Design

This documentation covers Algeon's first integration, the DataFusion adapter. DataFusion keeps SQL parsing, logical planning, physical planning, catalogs, DataFrame APIs, and CPU execution. Algeon adds opt-in GPU execution on cuDF, SQL-visible cuGraph and cuVS algorithms, Iceberg/lakehouse source handling, and structured diagnostics around that DataFusion session. Throughout these pages, native means Algeon's GPU execution path, as opposed to DataFusion's CPU operators.

• For users: the GPU path is an implementation detail behind ordinary DataFusion or Flight SQL APIs.
• For developers: every native decision is local, reportable, and backed by an adapter or engine contract.
• Non-goals: Algeon is not a separate SQL engine, does not accept external serialized query plans, and does not run a single query across several GPUs.

Read this if

• Backend integrator: Start with Integration surfaces and Session wiring. Algeon fits inside your service boundary rather than replacing it.
• Flight SQL operator: Read Lakehouse and workspace boundary, then use server config, cache policy, and diagnostics as the deployment contract.
• Graph or vector SQL user: Jump to Specialized GPU functions. Discover and validate calls before running GPU work.
• Native contributor: Read Native Lowering & Final Plans, then use Crates and ownership and Where to change what to route code changes.

How a query runs

A query enters through a DataFusion API or the Flight SQL server and leaves as Arrow rows through that same interface. In between:

1. DataFusion plans. SQL parsing, catalog resolution, logical and physical planning are stock DataFusion. Algeon does not parse SQL; it works from the completed physical plan.
2. Algeon evaluates the plan as a GPU candidate. A physical optimizer rule recognizes whole relational plans whose operators, types, and semantics have an exact native mapping. Plans that are not selected stay on DataFusion and execute on CPU as if Algeon were absent; the reason is recorded in the PlanningReport. Every unified Iceberg scan keeps its executable CPU delegate alongside its native scan facts (the format-neutral description of the scan, such as files, schema, and pruning facts, that lowering hands to the engine).
3. A selected candidate is lowered to the DataFusion-free IR. The adapter translates the DataFusion ExecutionPlan tree into the planning crate's closed QueryPlan, then planning checks kernels, types, semantics, and scope for every node. Planning never estimates bytes.
4. Admission grants a memory cap on one device. When execution first needs the GPU, the runtime places the query on one compatible device and commits the service-configured cap as an immutable grant. Waiting is FIFO among capability-compatible requests; nothing overtakes and nothing is protected. EXPLAIN does not admit.
5. cuDF, cuGraph, and cuVS execute inside the cap. The query's allocator enforces the grant; an allocation beyond it fails with a typed allocation error at its source. A native attempt that fails after execution starts is terminal — it is not replayed on CPU.
6. Arrow batches return. Results flow back through the DataFusion ExecutionPlan wrapper, so callers see ordinary record batches, metrics, and errors. Composed GPU fragments can hand a GPU-resident frame to the next native consumer without a host round-trip.

cugraph_* and cuvs_* calls enter this flow as explicit GPU islands: they are planned as GraphAlgorithm and VectorAlgorithm nodes of the same IR and use the same admission and allocation path.

Three pages carry the details behind this flow:

• Native Lowering & Final Plans — the plan-time boundary: candidate recognition, the algeon_datafusion_native rule, baseline preservation, final-plan requirements, and planning evidence.
• Admission & Memory Governance — the runtime boundary: process-wide admission, per-device ledgers, immutable grants, and allocation enforcement shared by library and server modes.
• Cache Design — the data-reuse boundary: lakehouse object bytes, decoded cuDF sources, resident cuGraph graphs, eviction, and sizing.

Crates and ownership

Each layer depends only on the layers below it. Moving down the stack, a query loses DataFusion types (at the adapter), then Rust plan types (at the FFI boundary); moving up, results and errors gain structure at each step.

DataFusiondatafusion

Algeon consumes DataFusion physical-plan and ExecutionPlan APIs. SQL parsing, catalog resolution, and CPU execution remain upstream behavior.

The root workspace contains these crates. Default members are the adapter, workloads, and query-engine; the rest are built on request.

Crate	Path	Owns
algeon-datafusion	crates/algeon-datafusion/src/	The DataFusion adapter: optimizer rules, candidate recognition and lowering, ExecutionPlan wrappers, cuGraph and cuVS SQL functions, the GPU function catalog, Iceberg table providers, reports, and errors. The only crate that depends on DataFusion.
query-planning	crates/algeon-query-planning	The native IR (QueryPlan), optimizer, capability analysis, proof diagnostics, admission contracts, and compiled pipeline. No DataFusion or execution dependency.
query-runtime	crates/algeon-query-runtime	Attempt lifecycle, query service, device ledger, immutable grants, GPU caches, observation, and metrics.
query-engine	crates/algeon-query-engine	Native execution composition and the public facade that re-exports planning and runtime.
iceberg-catalog	crates/iceberg-catalog	DataFusion-free Iceberg catalog, snapshot, and scan-candidate contracts.
workloads	crates/workloads	Benchmark catalogs, fixtures, dataset discovery, and DataFusion registration.
server	crates/algeon-server	Private standalone binary/package shell for the Arrow Flight SQL service; implementation and library API belong to algeon-datafusion::server.
bench	crates/bench	Benchmark, report, triage, and stress binaries. Non-default member.
tools	crates/tools	Developer, operator, and explicit external-service E2E tools. Non-default member.
examples	crates/examples	Runnable embedding examples. Non-default member.
cudf, cudf-sys, rapids-interop	components/cudf	Safe Rust and FFI over libcudf and RMM, plus the shared RAPIDS interop types.
cugraph, cugraph-sys	components/cugraph	Safe Rust and FFI over libcugraph.
cuvs, cuvs-sys	components/cuvs	Safe Rust and FFI over libcuvs.

The three query crates are DataFusion-free for two reasons. DataFusion's ExecutionPlan is an open trait that changes with DataFusion releases, while QueryPlan is a closed set of nodes the native stack fully controls, so lowering absorbs upstream change in one place. And each crate can be tested alone: planning tests pin IR and proof behavior without a runtime or executor, runtime tests pin grants and lifecycle without the engine, and engine contract tests exercise the whole native path without DataFusion in scope.

The current PlanNode variants are Source, Filter, Projection, Aggregate, Window, Sort, Limit, Join, Union, EdgeNormalize, GraphAlgorithm, and VectorAlgorithm.

Integration surfaces

Surface	Use it when	Primary owner
Embedded DataFusion backend	You already own the service API, auth, tenancy, and domain model. Install Algeon on a caller-owned SessionStateBuilder.	crates/algeon-datafusion/src/session.rs, crates/algeon-datafusion/src/backend.rs
Flight SQL service	You want a ready remote endpoint for notebooks, BI tools, agents, and non-Rust clients.	crates/algeon-server/
cuGraph SQL	You want graph algorithms as relations that can be joined, filtered, validated, and described from SQL.	crates/algeon-datafusion/src/cugraph_sql/
cuVS SQL	You want exact kNN, KMeans, and PCA over vector columns as relations.	crates/algeon-datafusion/src/cuvs_sql/
GPU function catalog	You want to list, describe, and validate the installed cugraph_* and cuvs_* functions before executing them.	crates/algeon-datafusion/src/gpu_functions/
Iceberg/lakehouse sources	You need Iceberg catalog tables to lower into native scan facts while workspace views stay mutable.	crates/algeon-datafusion/src/table_format/
Reports and errors	You need stable evidence for candidate selection, final plans, runtime, function validation, source access, and failures.	crates/algeon-datafusion/src/report.rs, crates/algeon-datafusion/src/native_report/, crates/algeon-datafusion/src/error.rs

The preferred embedded entry point is a process-scoped AlgeonGpuBackend. It installs the native optimizer and gives every installed session the same process-wide admission service and per-device memory ledger, so concurrent sessions draw from one GPU capacity authority (see Admission & Memory Governance). The cuGraph and cuVS lines require the matching feature; omit them for a pure relational session.

use datafusion::execution::SessionStateBuilder;
use algeon_datafusion::{
    backend::{GpuMemoryOwnership, AlgeonGpuBackend, AlgeonGpuDeviceConfig, AlgeonGpuDeviceProfile},
    cugraph_sql::CugraphSqlConfig,
    session::AlgeonSessionStateBuilderExt,
};

let device = AlgeonGpuDeviceConfig::new(AlgeonGpuDeviceProfile::new(0), GpuMemoryOwnership::WholeDeviceExclusive);
let backend = AlgeonGpuBackend::builder()
    .devices([device])
    .build()?;

let state = backend
    .install_on(SessionStateBuilder::new_with_default_features())?
    .try_with_cugraph_sql(CugraphSqlConfig::default())?
    .try_with_cuvs_sql()?
    .build();

Baseline preservation and requirements

Installing the relational optimizer preserves the executable DataFusion baseline. A candidate that is NotSupported or NotSelectedByCost is reported but does not turn an otherwise valid query into an error. A caller that needs the final plan to avoid DataFusion CPU execution configures a completed-plan requirement such as NoDataFusionCpu; that requirement evaluates the exact plan after native selection. The full boundary is described in Baseline preservation and final-plan requirements.

Feature gates

Feature	Adds
cugraph	cuGraph SQL algorithms and graph execution.
cuvs	cuVS SQL functions (cuvs_brute_force_knn, cuvs_kmeans, cuvs_pca) and their GPU execution.
iceberg	Iceberg catalogs and native scan integration.
nvml	Optional NVML device diagnostics.

algeon-datafusion exposes these DataFusion-specific features; the private server shell forwards them to the adapter and engine.

Specialized GPU functions

Graph and vector algorithms are SQL table functions. Both families are projected through the shared GPU function catalog, so gpu_list_functions, gpu_describe_function, and gpu_validate_call provide discovery and dry-run validation for every installed family without provider-specific metadata functions. The recommended workflow for either family is:

1. gpu_list_functions() to discover enabled functions, filtering with WHERE provider = 'cugraph' or 'cuvs' for one family.
2. gpu_describe_function('<fn>') to inspect the fixed descriptor, including signatures, options, schemas, examples, and limitations.
3. gpu_validate_call('<fn>', '<call_json>') to check a versioned envelope containing named relations and options without scanning inputs or launching CUDA.
4. Execute the function once validation returns valid = true.

cuGraph SQL path

With --features cugraph, every graph execution function in CUGRAPH_OPERATION_REGISTRY is available as a cugraph_* table function:

SELECT * FROM cugraph_pagerank('edges', 'src', 'dst')
ORDER BY value DESC;

Arrows show where the edge data moves: from SQL arguments to a GPU frame, then into a typed graph, then back to the caller as rows. Inside the shaded region the data stays on one device and stream; a value crosses to host memory only at the ends of the path.

cugraph_*()crates/algeon-datafusion/src/cugraph_sql/table_function.rs · crates/algeon-datafusion/src/cugraph_sql/exec/

CugraphAlgoTableProvider parses SQL arguments, resolves the edge relation in the DataFusion catalog, creates the physical edge-source plan, and returns CugraphAlgoExec. The metadata functions expose the same registry for humans and agents.

cuGraph shares the native cuDF runtime, metrics, memory cap, and structured error handling; it is not a separate service boundary. The function reference lives in cuGraph SQL API.

cuVS SQL path

With --features cuvs, cuvs_brute_force_knn, cuvs_kmeans, and cuvs_pca run on the GPU once the session installs cuVS SQL (try_with_cuvs_sql(); the Flight SQL server installs it on every session it builds) and a AlgeonGpuBackend is present. They follow the cuGraph path with one difference: instead of an edge relation, they take vector relations that the adapter lowers to a VectorAlgorithm node, and the engine executes that node through the cuvs component inside the same admitted memory cap. Each call builds the index, model, or transform it needs for that statement; there is no cross-statement cache of vector artifacts. See cuVS SQL API for the execution conditions and function reference.

Lakehouse and workspace boundary

Iceberg catalogs are source catalogs. They are not the mutable workspace. Algeon keeps these concerns separate:

• Iceberg and Glue/REST metadata resolve to adapter-owned table providers and format-neutral scan facts.
• Interactive DDL such as CREATE VIEW belongs in a mutable DataFusion workspace, including graph edge views built over source tables.
• The Flight SQL server can expose a workspace overlay so users get short names without teaching a read-only Iceberg catalog to accept views.

Set ALGEON_ICEBERG_FOOTER_PRUNING=true to let native object-store scans use Parquet footers for safe static and dimension-derived row-group pruning before execution.

Iceberg/Glue/S3 is designed behind --features iceberg; the feature is held out of the current release until iceberg-rust 0.12 is available and validated. Tests must not require a real AWS account.

Where to change what

For contributors, the ownership table above is the routing rule: DataFusion types stop at the adapter, plan and proof semantics live in planning, resource decisions live in runtime, execution composition lives in the engine, and missing GPU capability is added in the component crates rather than worked around above them. The table below maps common changes to their home and the contract each one must keep stable.

If you are changing...	Home	Keep stable
Which DataFusion physical shapes lower natively	crates/algeon-datafusion/src/native/normalize.rs, crates/algeon-datafusion/src/native/lowering/, crates/algeon-datafusion/src/native/validate*	PlanningReport, CandidateOutcome, CapabilityReason, rule names, final-plan requirements
Native IR, optimizer, capability, proof, or compiled-pipeline semantics	crates/algeon-query-planning/src/{plan,expr,source,optimizer,capability,admission,pipeline}/	One proof path and structured planning diagnostics; no family-name shortcuts
Attempt lifecycle, device admission, grants, cache, observation, or metrics	crates/algeon-query-runtime/src/{attempt,runtime,observability,metrics}/	One ledger, immutable grants, and runtime observation projections
Native execution semantics or planning/runtime composition	crates/algeon-query-engine/src/exec/	Engine execution contracts and facade compatibility
cuGraph or cuVS SQL behavior	crates/algeon-datafusion/src/cugraph_sql/, crates/algeon-datafusion/src/cuvs_sql/, crates/algeon-datafusion/src/gpu_functions/, crates/algeon-query-engine/src/exec/graph_algorithm/	Metadata column order and validation output
Iceberg/source behavior	crates/algeon-datafusion/src/table_format/, crates/iceberg-catalog-catalog/, server workspace configuration	Source diagnostics and credential-safe error facts
GPU memory, streams, source readers, or graph/vector interop	components/cudf, components/cugraph, components/cuvs	Component crate APIs and FFI error mapping
Public diagnostics	crates/algeon-datafusion/src/native_report/schema.rs, crates/algeon-datafusion/src/native_exec/metrics/, crates/algeon-datafusion/src/error.rs	TSV headers, metric names, ErrorCodes

Cache-specific routing is on Cache Design; lowering extension steps are on Extending native lowering. The Glossary defines the terms used across these pages.