Design

DataFusion Nexus is a DataFusion-native integration layer. DataFusion keeps SQL parsing, logical planning, physical planning, catalogs, DataFrame APIs, and CPU execution. Nexus adds opt-in cuDF execution, SQL-visible cuGraph algorithms, Iceberg/lakehouse source handling, and structured diagnostics around that DataFusion session.

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

Read this if

• Backend integrator: Start with Integration surfaces and Session wiring. Nexus should fit inside your service boundary, not replace it.
• Flight SQL operator: Read Lakehouse and workspace boundary, then use server config, cache policy, and diagnostics as the deployment contract.
• Graph SQL user: Jump to cuGraph SQL path. Discover and validate calls before running GPU graph work.
• Native contributor: Read Native Lowering & Final Plans, then use Layering and ownership and Developer checklist to route code changes.

The design contract

• DataFusion stays in charge: SQL, catalogs, physical planning, and the executable baseline remain stock DataFusion. Every unified Iceberg scan keeps an executable upstream CPU delegate alongside its optional native scan facts (the format-neutral description of the scan that lowering hands to the engine).
• The adapter translates: src/ recognizes whole relational DataFusion physical plans as native candidates, lowers a selected candidate into QueryPlan, and exposes reports.
• The engine owns native execution: crates/nexus-query-engine has no DataFusion dependency. It owns the IR, capability analysis, execution-time context, and executor.
• RAPIDS capability belongs below: Missing GPU APIs, memory hooks, device interop, graph, or vector contracts belong in the components/cudf / components/cugraph / components/cuvs crates, not adapter workarounds.

Integration surfaces

Surface	Use it when	Primary owner
Embedded DataFusion backend	You already own the service API, auth, tenancy, and domain model. Install Nexus on a caller-owned SessionStateBuilder.	src/session.rs
Flight SQL service	You want a ready remote endpoint for notebooks, BI tools, agents, and non-Rust clients.	crates/nexus-server/
cuGraph SQL	You want graph algorithms as relations that can be joined, filtered, validated, and described from SQL.	src/cugraph_sql/
Iceberg/lakehouse sources	You need Iceberg catalog tables to lower into native table-format scan facts while workspace views stay mutable.	src/table_format/
Reports and errors	You need stable evidence for candidate selection, final plans, runtime, graph validation, source access, and failures.	src/report.rs, src/native_report/, src/error.rs

The preferred embedded entry point is a process-scoped NexusGpuBackend. 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 line is available only when the crate is built with --features cugraph; omit it for a pure relational session.

use datafusion::execution::SessionStateBuilder;
use datafusion_nexus::{
    backend::{GpuMemoryOwnership, NexusGpuBackend, NexusGpuDeviceProfile},
    cugraph_sql::CugraphSqlConfig,
};

let backend = NexusGpuBackend::builder()
    .device_profiles([NexusGpuDeviceProfile::new(0)])
    .device_memory_ownership([(0, GpuMemoryOwnership::WholeDeviceExclusive)])
    .build()?;

let state = backend
    .install_on_with_cugraph_sql(
        SessionStateBuilder::new_with_default_features(),
        CugraphSqlConfig::default(),
    )?
    .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 bindings and vector-function planning.
iceberg	Iceberg catalogs and native scan integration.
nvml	Optional NVML device diagnostics.

The server's features with the same names forward these adapter and engine capabilities into nexus-server.

The nexus-server package owns the Arrow Flight SQL service, protocol handshake, cancellation, admission, workspace, and diagnostics.

Native Lowering and Admission

Three deep contracts sit behind this overview, each on its own page:

• Native Lowering & Final Plans — the plan-time boundary: the relational acceleration path, the datafusion_nexus_native rewrite rule and its surrounding session hooks, baseline preservation, final-plan requirements, and the plan-shape admission evidence developers assert against (PlanningReport, engine capability analysis, and bounded-controller report projections).
• Admission & Memory Governance — the runtime boundary: process-wide query admission, immutable device grants, and the per-device resource controller shared by library and server modes.
• Cache Design and Use — the persistent data-reuse boundary: lakehouse object bytes, decoded cuDF sources, resident cuGraph graphs, eviction, sizing, and diagnostics.

Layering and ownership

The important boundary is not "host versus GPU"; it is DataFusion's open ExecutionPlan trait versus the engine's closed, owned QueryPlan IR.

DataFusiondatafusion

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

Why two crates (datafusion-nexus & nexus-query-engine)

The split is structural, not cosmetic. nexus-query-engine deliberately consumes a closed, owned QueryPlan instead of DataFusion's open ExecutionPlan trait.

• DataFusion's physical trait changes with DataFusion releases; the engine's IR remains a stable native execution contract.
• Physical planning has already decided aggregate modes, partitioning, projection pushdown, join shape, and scan facts. Native lowering needs those decisions.
• Engine tests can pin capability analysis, immutable-grant behavior, reservation behavior, and executor semantics without DataFusion in scope.
• Non-DataFusion frontends can construct the same native IR directly.

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

Placement rules

Change	Correct home	Contract to update
Support a new DataFusion physical shape	src/native/normalize.rs, src/native/lowering/, src/native/validate*	Planning reports, candidate outcomes, and final-plan requirements
Add native IR or executor behavior	crates/nexus-query-engine/src/plan, expr, source, exec, runtime	Engine contract tests and metrics
Admit a bounded compiled shape	crates/nexus-query-engine/src/admission, capability, pipeline	Capability evidence, immutable grants, and bounded-controller report projections; no family-name shortcuts
Improve GPU memory, streams, source readers, or graph interop	cudf, cugraph, rapids-interop crates	Binding crate API and FFI error mapping
Change public evidence	src/native_report/, src/native_exec/metrics/, src/error.rs	Public surface schema/version constants

cuGraph SQL path

With --features cugraph, graph algorithms are SQL table functions. The SQL surface projects every graph execution function from CUGRAPH_OPERATION_REGISTRY through the shared GPU catalog. gpu_list_functions, gpu_describe_function, and gpu_validate_call provide discovery and dry-run validation for every installed GPU family without adding provider-specific metadata functions.

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

cuGraph is not a separate service boundary. It is a table-function execution path that shares the native cuDF runtime, metrics, memory policy, and structured error handling.

cugraph_*()src/cugraph_sql/table_function.rs · 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 UDTFs expose the same registry for humans and agents.

For callers, the recommended workflow is:

1. gpu_list_functions() to discover enabled functions, using WHERE provider = 'cugraph' for a graph-only inventory.
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 edges or launching CUDA.
4. Execute the cugraph_* function once validation returns valid = true.

The detailed function reference lives in cuGraph SQL API.

Lakehouse and workspace boundary

Iceberg catalogs are source catalogs. They are not the mutable workspace. Nexus 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 NEXUS_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 feature-gated behind --features iceberg; tests must not require a real AWS account.

Developer checklist

Use this page as the routing table before changing behavior:

If you are changing...	Inspect first	Keep stable
Native rewrite coverage	src/native/normalize.rs, src/native/lowering/, src/native/validate*	PlanningReport, CandidateOutcome, CapabilityReason, rule names
Native execution semantics	crates/nexus-query-engine/src/admission/, capability/, pipeline/, exec/, runtime/	Immutable-grant reservation evidence and retained report projections
cuGraph SQL behavior	src/cugraph_sql/types.rs, parser.rs, exec/, src/gpu_functions/, engine exec/graph_algorithm/	Metadata column order and validation output
Iceberg/source behavior	src/table_format/, src/table_format/iceberg/, server workspace configuration	Source diagnostics and credential-safe error facts
Public diagnostics	src/native_report/schema.rs, src/native_exec/metrics/, src/error.rs	TSV headers, metric names, ErrorCodes

Authoritative references

• Glossary for one-line definitions of the terms used across these pages.
• cuGraph SQL API for callable graph algorithms and validation metadata.
• Cargo.toml for feature gates and dependency declarations.
• src/native_report/schema.rs, src/native_exec/metrics/, and src/error.rs for stable report, metric, and error contracts.