Configuration

Nexus has three configuration owners. Keep them separate:

Surface	Configure with	Owns
Flight SQL process	ServerConfig, TOML, and environment variables	Listen address, admission, auth, source catalogs, and retention
Embedded GPU backend	NexusGpuBackend::builder()	Device ownership, capacity, queues, and final-plan requirements
DataFusion session	SessionConfig	DataFusion behavior and request-scoped planner evidence

This page covers the Flight SQL process. For an embedded Rust service, use DataFusion Session.

How server configuration is resolved

ServerConfig::from_env() starts with built-in defaults, reads the TOML file named by NEXUS_SERVER_CONFIG_FILE, and then applies environment overrides for matching scalar admission, native, and observability fields.

The TOML file accepts only [auth], [admission], [native], and [observability]. Unknown fields fail startup. cuGraph, Iceberg, and workspace settings use the environment; standard DataFusion settings come from its environment mapping or the embedded SessionConfig API.

Minimal GPU server

Every selected CUDA ordinal needs exactly one TOML device profile, even when all device-local values use their defaults:

# server.toml
[[admission.device_profiles]]
device_ordinal = 0

export NEXUS_SERVER_CONFIG_FILE="$PWD/server.toml"
export NEXUS_SERVER_GPU_DEVICES=0

flock /tmp/cudf-gpu.lock bash scripts/dev/run_server.sh

The profile above uses automatic device capacity, one active attempt, one source-work slot, no resident GPU cache, and engine-derived installation bounds. For a production deployment, set explicit limits only where the deployment needs them.

Admission

Environment variable	Default	Purpose
NEXUS_SERVER_BIND	0.0.0.0:50051	Flight SQL listen address
NEXUS_SERVER_LOG	info	Tracing filter
NEXUS_SERVER_CONFIG_FILE	unset	TOML overlay path
NEXUS_SERVER_STATEMENT_TICKET_TTL_SECS	300	How long an unconsumed Flight statement ticket may wait for DoGet
NEXUS_SERVER_GPU_DEVICES	0	Comma-separated CUDA ordinals
NEXUS_SERVER_ADMISSION_MAX_QUEUED_ATTEMPTS	64	Maximum queued admission waiters
NEXUS_SERVER_ADMISSION_MAX_QUEUE_WAIT_MS	30000	Maximum wait for a compatible device
NEXUS_SERVER_ADMISSION_MAX_OVERTAKES_PER_WAITER	4	Compatible-device bypass budget before waiter protection

The three queue values can also be placed under [admission] as max_queued_attempts, max_queue_wait_ms, and max_overtakes_per_waiter. Environment values win.

After device_ordinal, a profile accepts memory_limit_bytes, backend_reserve_bytes, attempt_floor_bytes, max_active_attempts, source_work_per_attempt, cache_cap_bytes, and the optional telemetry flag (install_telemetry). Configure stream_pool_size, worker_count, and lane_count together or omit all three. An explicit memory_limit_bytes requires an explicit backend_reserve_bytes: automatic capacity already bakes in driver headroom, but an explicit limit does not, so the reserve must be declared (0 is a valid, deliberate choice).

Selected ordinals and profile ordinals must match exactly. A profile outside NEXUS_SERVER_GPU_DEVICES, a missing profile, or a duplicate ordinal is an error. cache_cap_bytes = 0 (the default) installs no resident GPU cache.

Capabilities and memory ownership are not file settings. The shipped server binary declares WholeDeviceExclusive ownership for every selected ordinal; custom embedders must make that declaration through the Rust API.

Native execution

Native settings are accepted both under [native] and through the environment:

TOML field	Environment variable	Default
max_source_chunk_bytes	NEXUS_SERVER_NATIVE_MAX_SOURCE_CHUNK_BYTES	64 MiB
max_row_groups_per_chunk	NEXUS_SERVER_NATIVE_MAX_ROW_GROUPS_PER_CHUNK	1
max_retry_attempts	NEXUS_SERVER_NATIVE_MAX_RETRY_ATTEMPTS	3
max_source_reads_in_flight	NEXUS_SERVER_NATIVE_MAX_SOURCE_READS_IN_FLIGHT	2
source_chunk_planning_mode	NEXUS_SERVER_NATIVE_SOURCE_CHUNK_PLANNING_MODE	conservative
statistical_aggregate_execution_mode	NEXUS_SERVER_NATIVE_STATISTICAL_AGGREGATE_EXECUTION_MODE	datafusion_exact_host_welford
final_plan_requirement	NEXUS_SERVER_FINAL_PLAN_REQUIREMENT	unset

source_chunk_planning_mode also accepts local_parquet_throughput. Statistical aggregates can use gpu_native_tolerant when exact DataFusion Welford bits are not required. The only final-plan requirement is no_datafusion_cpu.

Native settings carry no device-budget planning placeholder. Device capacity is owned solely by the ordinal-keyed [[admission.device_profiles]] entries. max_source_chunk_bytes and max_row_groups_per_chunk are independent: each defaults to the engine default (64 MiB / 1) when unset, and setting one no longer requires the other.

Authentication

Authentication is TOML-only and defaults to disabled. Use that default only on a trusted local network. Static Basic credentials can be exchanged for server-issued bearer tokens:

[auth.mode]
kind = "basic_bearer"
token_ttl_secs = 3600

[[auth.mode.users]]
username = "alice"
password_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."

token_ttl_secs is required and must be greater than zero; non-expiring bearer tokens are not supported. password_hash must be a valid Argon2 PHC string; plaintext is rejected. Usernames must be unique.

Runtime observation retention

The defaults retain bounded per-query records and sealed reports. Change them only when the service's traffic and exporter behavior require a different budget:

TOML field under [observability]	Environment override	Default
per_query_max_records	NEXUS_SERVER_OBSERVABILITY_PER_QUERY_MAX_RECORDS	65536
per_query_max_bytes	NEXUS_SERVER_OBSERVABILITY_PER_QUERY_MAX_BYTES	8 MiB
active_logical_capture_max_bytes	NEXUS_SERVER_OBSERVABILITY_ACTIVE_LOGICAL_CAPTURE_MAX_BYTES	1 GiB
global_sealed_max_count	NEXUS_SERVER_OBSERVABILITY_GLOBAL_SEALED_MAX_COUNT	1024
global_sealed_max_bytes	NEXUS_SERVER_OBSERVABILITY_GLOBAL_SEALED_MAX_BYTES	1 GiB
sealed_ttl_secs	NEXUS_SERVER_OBSERVABILITY_SEALED_TTL_SECS	3600
shutdown_grace_secs	NEXUS_SERVER_OBSERVABILITY_SHUTDOWN_GRACE_SECS	30

All values must be greater than zero.

GPU SQL functions

cuGraph registration is controlled by these settings:

Variable	Default	Purpose
NEXUS_SERVER_CUGRAPH_ENABLED	true	Register the cugraph_* SQL frontend
NEXUS_SERVER_CUGRAPH_CONSTRUCTION_POLICY	python_cugraph	python_cugraph or raw_libcugraph

The construction-policy override is rejected when NEXUS_SERVER_CUGRAPH_ENABLED is false. A binary without the cugraph feature can still expose the frontend, but execution returns a structured required_feature_disabled error. Per-call options_json overrides these defaults; see Graph Inputs and Construction.

cuVS has no enable variable. Nexus installs its metadata and relation-aware planner with the backend; execution availability is described in cuVS SQL API.

Iceberg and workspace

Iceberg server configuration activates when a catalog, storage, or cache setting below is present and requires the iceberg Cargo feature. Start with the Local Iceberg E2E for a reproducible REST catalog.

Common settings are:

Variable	Requirement
NEXUS_ICEBERG_CATALOG_KIND	Required when Iceberg settings are present; glue or rest
NEXUS_ICEBERG_CATALOG_NAME	DataFusion catalog name; defaults to the selected backend name
NEXUS_ICEBERG_NAMESPACE	Required namespace exposed to SQL
NEXUS_ICEBERG_WAREHOUSE	Required warehouse URI
NEXUS_ICEBERG_TABLES	Optional alias=table preload list; otherwise tables resolve lazily
NEXUS_ICEBERG_SCAN_PLANNING_TIMEOUT_SECS	Planning timeout; default 60

REST catalogs require NEXUS_ICEBERG_REST_URI. Glue requires AWS_REGION or AWS_DEFAULT_REGION; backend-specific prefix, token, catalog-handle, ID, and endpoint variables are optional.

S3-compatible storage uses NEXUS_ICEBERG_S3_ENDPOINT, NEXUS_ICEBERG_S3_REGION, and NEXUS_ICEBERG_S3_PATH_STYLE. Choose either static NEXUS_ICEBERG_S3_ACCESS_KEY_ID / NEXUS_ICEBERG_S3_SECRET_ACCESS_KEY credentials or NEXUS_ICEBERG_S3_CREDENTIAL_SOURCE=default_chain; combining them is rejected. For Glue with remote KvikIO reads, set both AWS_REGION and AWS_DEFAULT_REGION to the same region.

The optional persistent byte cache is separate from GPU memory. Configure it with NEXUS_LAKEHOUSE_CACHE_ROOT, NEXUS_LAKEHOUSE_CACHE_READ, NEXUS_LAKEHOUSE_CACHE_POLICY, and NEXUS_LAKEHOUSE_CACHE_MAX_BYTES; cache policy is disabled, read_through, or fill_before_read. NEXUS_LAKEHOUSE_CACHE_READ accepts only enabled or disabled. NEXUS_LAKEHOUSE_CACHE_MAX_BYTES is required whenever a cache root is configured with a filling policy (read_through or fill_before_read). KVIKIO_COMPAT_MODE=ON|OFF|AUTO and NEXUS_ICEBERG_FOOTER_PRUNING are process/source flags rather than ServerConfig fields; set them before process startup. NEXUS_ICEBERG_FOOTER_PRUNING accepts only true, false, 1, or 0 — any other value is a startup/planning error, not a silent false.

Use a workspace overlay when the source catalog is read-only but interactive DDL should remain local:

export NEXUS_SERVER_WORKSPACE_CATALOG=datafusion
export NEXUS_SERVER_WORKSPACE_SCHEMA=public
export NEXUS_SERVER_WORKSPACE_BACKING_CATALOG=lake
export NEXUS_SERVER_WORKSPACE_BACKING_SCHEMA=citation_network
export NEXUS_SERVER_WORKSPACE_BACKING_ALIASES=citation_edges,papers,paper_authors

The backing catalog and schema must be set together. Catalog/schema default to datafusion.public, and omitting the aliases exposes every backing table.

DataFusion and Nexus session keys

The server builds DataFusion's SessionConfig with SessionConfig::from_env(). Common keys include DATAFUSION_EXECUTION_BATCH_SIZE, DATAFUSION_EXECUTION_TARGET_PARTITIONS, DATAFUSION_CATALOG_DEFAULT_CATALOG, and DATAFUSION_CATALOG_DEFAULT_SCHEMA.

Nexus session options are registered later by the optimizer install; they are not loaded from DATAFUSION_NEXUS_* environment variables. Direct optimizer installs expose six session-scoped native fields as datafusion_nexus.native.<field>: max_source_chunk_bytes, max_row_groups_per_chunk, max_retry_attempts, max_source_reads_in_flight, source_chunk_planning_mode, and statistical_aggregate_execution_mode. final_plan_requirement has no session-key projection. Backend-managed sessions freeze those keys because the shared backend owns admission policy.

The one mutable planner-evidence key is datafusion_nexus.request.graph_raw_input_edges, which accepts a positive edge count or none. Flight SQL rejects SET datafusion_nexus.*; configure Flight through the server surface instead.