Configuration

Algeon 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	AlgeonGpuBackend::builder()	Device ownership, capacity, queues, and execution mode
DataFusion session	SessionConfig	Standard DataFusion behavior (catalogs, batch size, target partitions)

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 ALGEON_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 ALGEON_SERVER_CONFIG_FILE="$PWD/server.toml"
export ALGEON_SERVER_GPU_DEVICES=0

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

The profile above uses automatic device capacity, two active attempts, 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
ALGEON_SERVER_BIND	0.0.0.0:50051	Flight SQL listen address
ALGEON_SERVER_LOG	info	Tracing filter
ALGEON_SERVER_CONFIG_FILE	unset	TOML overlay path
ALGEON_SERVER_STATEMENT_TICKET_TTL_SECS	300	How long an unconsumed Flight statement ticket may wait for DoGet
ALGEON_SERVER_GPU_DEVICES	0	Comma-separated CUDA ordinals
ALGEON_SERVER_ADMISSION_MAX_QUEUED_ATTEMPTS	64	Maximum queued admission waiters
ALGEON_SERVER_ADMISSION_MAX_QUEUE_WAIT_MS	30000	Maximum wait for a compatible device

The two queue values can also be placed under [admission] as max_queued_attempts and max_queue_wait_ms. Environment values win. Admission is FIFO among capability-compatible waiters; there is no overtaking or protected-waiter setting.

After device_ordinal, a profile accepts memory_limit_bytes, backend_reserve_bytes, default_query_limit_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 ALGEON_SERVER_GPU_DEVICES, a missing profile, or a duplicate ordinal is an error. cache_cap_bytes = 0 (the default) installs no resident GPU cache. default_query_limit_bytes is the immutable cap granted to a query unless an embedding caller supplies an explicit cap. It must be positive and no larger than the device's managed capacity; planner memory estimates do not resize it.

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

Execution mode

The default is native_preferred. To keep ordinary SQL on DataFusion CPU and use the GPU only for explicit cuGraph and cuVS functions, add this to the server TOML alongside its device profiles:

[native]
execution_mode = "functions_only"

Or override it through the environment:

export ALGEON_SERVER_EXECUTION_MODE=functions_only

Accepted values are native_preferred, functions_only, and native_required. See Choose an execution mode for their behavior, composition boundaries, host staging limits, and embedded Rust configuration. This is backend policy, not a SQL SET option. Function features, registration, device profiles, and GPU admission are still required.

Native settings

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

TOML field	Environment variable	Default
execution_mode	ALGEON_SERVER_EXECUTION_MODE	native_preferred
max_source_chunk_bytes	ALGEON_SERVER_NATIVE_MAX_SOURCE_CHUNK_BYTES	64 MiB
max_row_groups_per_chunk	ALGEON_SERVER_NATIVE_MAX_ROW_GROUPS_PER_CHUNK	1
max_retry_attempts	ALGEON_SERVER_NATIVE_MAX_RETRY_ATTEMPTS	3
max_source_reads_in_flight	ALGEON_SERVER_NATIVE_MAX_SOURCE_READS_IN_FLIGHT	2
source_chunk_planning_mode	ALGEON_SERVER_NATIVE_SOURCE_CHUNK_PLANNING_MODE	conservative
statistical_aggregate_execution_mode	ALGEON_SERVER_NATIVE_STATISTICAL_AGGREGATE_EXECUTION_MODE	gpu_native_tolerant
final_plan_requirement	ALGEON_SERVER_FINAL_PLAN_REQUIREMENT	unset

source_chunk_planning_mode also accepts local_parquet_throughput.

statistical_aggregate_execution_mode controls the stddev and var aggregate family. The default, gpu_native_tolerant, keeps them on the GPU, but its results are not guaranteed to match DataFusion exactly: floating-point bits can differ, and precision degrades when values are large relative to their spread. Set datafusion_exact_host_welford when results must match DataFusion. That mode copies the aggregate input to host memory, and a query whose group keys or other aggregates in the same GROUP BY it cannot evaluate exactly is not rewritten to native execution.

The only final-plan requirement is no_datafusion_cpu. Used alone, it has the same effect as execution_mode = "native_required". If both fields are set, they must agree: combining it with native_preferred or functions_only fails startup.

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	ALGEON_SERVER_OBSERVABILITY_PER_QUERY_MAX_RECORDS	65536
per_query_max_bytes	ALGEON_SERVER_OBSERVABILITY_PER_QUERY_MAX_BYTES	8 MiB
active_logical_capture_max_bytes	ALGEON_SERVER_OBSERVABILITY_ACTIVE_LOGICAL_CAPTURE_MAX_BYTES	1 GiB
global_sealed_max_count	ALGEON_SERVER_OBSERVABILITY_GLOBAL_SEALED_MAX_COUNT	1024
global_sealed_max_bytes	ALGEON_SERVER_OBSERVABILITY_GLOBAL_SEALED_MAX_BYTES	1 GiB
sealed_ttl_secs	ALGEON_SERVER_OBSERVABILITY_SEALED_TTL_SECS	3600
shutdown_grace_secs	ALGEON_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
ALGEON_SERVER_CUGRAPH_ENABLED	true	Register the cugraph_* SQL frontend
ALGEON_SERVER_CUGRAPH_CONSTRUCTION_POLICY	python_cugraph	python_cugraph or raw_libcugraph

The construction-policy override is rejected when ALGEON_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. The server installs cuVS SQL on every session it builds; the cuvs feature decides whether the functions execute or return a structured required_feature_disabled error. See cuVS execution.

Iceberg and workspace

Iceberg server configuration activates when a catalog, storage, or cache setting below is present and requires the iceberg Cargo feature. That feature is held out of the current release while the project waits for the upstream iceberg-rust 0.12 release and compatibility validation. Start with the Local Iceberg E2E for a reproducible REST catalog.

Common settings are:

Variable	Requirement
ALGEON_ICEBERG_CATALOG_KIND	Required when Iceberg settings are present; glue or rest
ALGEON_ICEBERG_CATALOG_NAME	DataFusion catalog name; defaults to the selected backend name
ALGEON_ICEBERG_NAMESPACE	Required namespace exposed to SQL
ALGEON_ICEBERG_WAREHOUSE	Required warehouse URI
ALGEON_ICEBERG_TABLES	Optional alias=table preload list; otherwise tables resolve lazily
ALGEON_ICEBERG_SCAN_PLANNING_TIMEOUT_SECS	Planning timeout; default 60

REST catalogs require ALGEON_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 ALGEON_ICEBERG_S3_ENDPOINT, ALGEON_ICEBERG_S3_REGION, and ALGEON_ICEBERG_S3_PATH_STYLE. Choose either static ALGEON_ICEBERG_S3_ACCESS_KEY_ID / ALGEON_ICEBERG_S3_SECRET_ACCESS_KEY credentials or ALGEON_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 ALGEON_LAKEHOUSE_CACHE_ROOT, ALGEON_LAKEHOUSE_CACHE_READ, ALGEON_LAKEHOUSE_CACHE_POLICY, and ALGEON_LAKEHOUSE_CACHE_MAX_BYTES; cache policy is disabled, read_through, or fill_before_read. ALGEON_LAKEHOUSE_CACHE_READ accepts only enabled or disabled. ALGEON_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 ALGEON_ICEBERG_FOOTER_PRUNING are process/source flags rather than ServerConfig fields; set them before process startup. ALGEON_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 ALGEON_SERVER_WORKSPACE_CATALOG=datafusion
export ALGEON_SERVER_WORKSPACE_SCHEMA=public
export ALGEON_SERVER_WORKSPACE_BACKING_CATALOG=lake
export ALGEON_SERVER_WORKSPACE_BACKING_SCHEMA=citation_network
export ALGEON_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 session configuration

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.

Native execution policy is owned solely by the server configuration ([native] TOML options and ALGEON_SERVER_NATIVE_* environment variables) or the embedded AlgeonGpuBackendBuilder. Algeon registers no session configuration extensions; DataFusion sessions carry standard DataFusion configuration only. SQL statements attempting SET algeon_datafusion.* fail with an unrecognized configuration key error.