Integration

Algeon executes GPU plans through Apache DataFusion APIs while preserving standard SQL queries, DataFrame interfaces, and Arrow record batches. Embed Algeon in a Rust service, or connect remote clients through Arrow Flight SQL. Throughout these docs, "native" denotes Algeon's GPU execution path.

Surface	Use it when	Start here
DataFusion session	The hosting Rust service manages request dispatch, session lifecycles, authentication, multi-tenancy, and result formatting.	DataFusion Session
Flight SQL server	Remote clients, notebooks, analytics agents, or non-Rust services query Algeon via Arrow Flight SQL.	Flight SQL server

The session and server APIs use the same GPU backend. By default, Algeon selects supported relational SQL for cuDF execution. Setting functions_only keeps ordinary SQL on DataFusion CPU while explicit GPU UDTFs run on the GPU; native_required rejects plans containing DataFusion CPU execution. See Choose an execution mode.

The cugraph, cuvs, and cuml features make the matching UDTFs executable; see Dependencies.

Iceberg support

A server built with the iceberg feature registers each [[iceberg.catalogs]] entry as a DataFusion catalog. Two catalog kinds connect: Iceberg REST catalogs that need no SigV4 request signing, such as iceberg-rest-fixture, Polaris and Lakekeeper (authentication none, OAuth2 client credentials or a bearer token), and AWS Glue with the default AWS credential chain. Glue's Iceberg REST endpoint and S3 Tables REST require SigV4, which iceberg-rust does not implement, so they are not supported. GCP catalogs are out of scope.

Data files must be in S3. Native scans read them with KvikIO through the server's [s3] table, and the catalog's metadata files (table metadata, manifest lists and manifests) are read through iceberg-rust's FileIO with the endpoint, region and path style of the same table, which [[iceberg.catalogs]] therefore requires. A loaded table whose FileIO endpoint differs from [s3], or whose region or path style differs when both sides set one, fails with iceberg_storage_properties_mismatch. Credentials a catalog returns for a table are neither requested nor used. An embedded session uses AlgeonNativeExecutionConfig::with_s3_storage.

Access is read-only. Every scan loads the table again and plans its current snapshot; there is no time-travel syntax and no metadata table. A table without a snapshot scans as empty. Namespaces and table names are listed once, at server startup, and only single-level namespaces appear. A query loads a table by name, so a table created after startup can be queried but is missing from the listings.

Filters convert to Iceberg predicates that prune manifests and data files. DataFusion keeps every filter in a FilterExec above the scan, so a filter that does not convert only loses pruning. The scan is a standard Parquet DataSourceExec with one whole-file entry per data file, the exact row count from the manifest, and each footer placed in the session's file metadata cache. Native lowering therefore sees a multi-object s3:// Parquet scan (see Object storage and libcurl). String and binary columns use the view types that a ListingTable infers. Columns bind by name, after a per-file check that name and Iceberg field id (or the table's name mapping) select the same column.

Rejected table features

A snapshot that a Parquet scan would read incorrectly fails with unsupported_table_feature; the error page lists its metadata. The checks run in the provider's scan before native lowering, so they apply in every execution mode, and no CPU fallback exists.

reason	Raised when
iceberg_delete_files	A data file of the snapshot has delete files attached.
iceberg_field_id_mismatch	In a file that carries field ids, a column's name and its field id select different file columns, as after a rename.
iceberg_missing_field_ids	A file has no field ids and the table has no default name mapping, or the mapping resolves a column to another name than the file uses.
iceberg_partition_column_absent	A file lacks an identity-partition column, whose value Iceberg keeps only in partition data.
iceberg_required_column_absent	A file lacks a required column. A missing optional column reads as null.
iceberg_encrypted_file	A data file has encryption key metadata.
iceberg_non_parquet_file	A data file is not Parquet.
iceberg_multiple_buckets	The data files left after pruning span more than one bucket.
iceberg_unsupported_location_scheme	A data file location is not s3://, s3a:// or s3n://. file:// locations are read from local disk.
iceberg_storage_properties_mismatch	The table's FileIO storage properties disagree with [s3], as described above.
iceberg_column_type_mismatch	A file stores a projected column with another type than the table declares, as after an int to long promotion. String and binary widths and dictionary encoding count as the same type.

Catalog and storage failures keep the existing codes. A missing namespace or table is object_not_found. Credential and access failures from the catalog or metadata storage are source_unauthenticated or source_access_denied. A retryable failure is source_temporary_failure, and any other is source_dependency_failure. A table schema that changes between name resolution and the scan fails with source_temporary_failure; a data file whose size differs from its manifest entry fails with source_dependency_failure.

Common flow

1. Build the native libraries and the Rust stack with the features required for the deployment, following Build & Test. Every surface below starts from that build.
2. Select an entry point. Embed a DataFusion session in a Rust service or start the Flight SQL server for remote clients. In each case, declare the GPUs the process may use before running queries. Server-side settings are documented in Configuration.
3. Provide tables. In an embedded session, register tables as in plain DataFusion (CREATE EXTERNAL TABLE ... STORED AS PARQUET or register_parquet). See Execute one attempt per query. The server reads Parquet tables that clients register with CREATE EXTERNAL TABLE, as in the citation table registration. When using cugraph_*, cuvs_*, or cuml_* UDTFs, list and validate installed calls with Discover & Validate GPU UDTFs.
4. Verify whether a query runs on the GPU. Before shipping a query, inspect its planned execution path and the reason for any part that remains on the CPU using GPU coverage validation: algeon_explain_coverage in embedded SQL, EXPLAIN GPU through Flight SQL, or validate_query in Rust. With the default native_preferred mode, relational candidates not selected for GPU execution stay in DataFusion.
5. Handle failures. A GPU execution failure returns an error with a stable code, kind, and status. At the application boundary, inspect errors that carry a typed Algeon identity and keep standard handlers for ordinary DataFusion failures. See Handling Errors. Queries that cannot acquire GPU execution capacity within configured deadlines return service_overloaded backpressure; eligible waiters are served in first-in, first-out order.