Flight SQL Server

Run the standalone server when clients need a remote Arrow Flight SQL endpoint instead of an embedded Rust API. It builds one shared GPU backend, installs the cuVS SQL functions on every session (and the cuGraph functions when enabled in its configuration), and serves ordinary Arrow results to any ADBC or Flight SQL client. Its embeddable implementation and public API live in algeon_datafusion::server; crates/algeon-server is the private standalone launcher.

Build and start

Build the server package and its algeon_server binary:

cargo build --release -p server --all-features --bin algeon_server

Every selected GPU needs an explicit device profile. For a single-GPU local server, create server.toml in the repository root:

[[admission.device_profiles]]
device_ordinal = 0

Then start the server on localhost. The development helper enables its local Iceberg defaults unless ALGEON_RUN_SERVER_ICEBERG=0 is set:

export ALGEON_SERVER_CONFIG_FILE="$PWD/server.toml"
export ALGEON_SERVER_BIND=127.0.0.1:50051
export ALGEON_RUN_SERVER_ICEBERG=0

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

From another terminal, verify the endpoint with the repository client:

cargo run -p tools --all-features -- \
  flight-sql-query http://127.0.0.1:50051 "SELECT 1 AS one"

The expected result is a column named one containing 1. Authentication is disabled by default, so keep this setup on a trusted local interface. See Configuration before exposing the endpoint or selecting more GPUs.

To keep ordinary SQL on DataFusion CPU while explicit cuGraph and cuVS calls run on GPU, set ALGEON_SERVER_EXECUTION_MODE=functions_only before startup. The default is native_preferred; see Execution mode for all three modes and their TOML equivalents.

Start the citation demo server

The graph examples use an Iceberg REST catalog backed by RustFS. Start the fixture, load the citation network, and reuse the server.toml profile above:

docker compose -f fixture/iceberg-local/docker-compose.yml up -d
fixture/fixture.sh iceberg rest load \
  --workload citation_network \
  --load-mode add-files

export ALGEON_SERVER_CONFIG_FILE="$PWD/server.toml"
export ALGEON_RUN_SERVER_ICEBERG=1
export ALGEON_SERVER_CUGRAPH_ENABLED=true
export ALGEON_SERVER_BIND=127.0.0.1:50051
export DATAFUSION_CATALOG_DEFAULT_CATALOG=datafusion
export DATAFUSION_CATALOG_DEFAULT_SCHEMA=public
export ALGEON_ICEBERG_CATALOG_KIND=rest
export ALGEON_ICEBERG_CATALOG_NAME=lake
export ALGEON_ICEBERG_NAMESPACE=citation_network
export ALGEON_ICEBERG_WAREHOUSE=s3://lakehouse/warehouse
export ALGEON_ICEBERG_REST_URI=http://localhost:8181
export ALGEON_ICEBERG_S3_ENDPOINT=http://localhost:9000
export ALGEON_ICEBERG_S3_REGION=us-east-1
export ALGEON_ICEBERG_S3_PATH_STYLE=true
export ALGEON_ICEBERG_S3_ACCESS_KEY_ID=algeonadmin
export ALGEON_ICEBERG_S3_SECRET_ACCESS_KEY=algeonadmin
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,citation_edges_by_dst,papers,paper_authors,paper_fos

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

The startup snapshot should report iceberg_enabled=true, cugraph_enabled=true, and a non-zero cugraph_registry_algorithm_count. The demo dataset page lists the available tables.

Connect with ADBC

Use an Apache Arrow ADBC Flight SQL driver from application code. The Python DB-API wrapper requires both the Flight SQL driver and PyArrow:

python -m pip install adbc-driver-flightsql pyarrow

from adbc_driver_flightsql import dbapi


with dbapi.connect(uri="grpc://127.0.0.1:50051") as conn:
    with conn.cursor() as cur:
        cur.execute("SELECT 1 AS one")
        result = cur.fetch_arrow_table()

The same endpoint works with other ADBC language bindings. Keep pooling, timeouts, authentication, and result conversion in the client service.

Use an interactive client

Choose either client for an interactive session.

DataBow

databow exercises the ADBC driver path:

databow --driver flightsql --uri grpc://127.0.0.1:50051

arrow_cli

arrow_cli connects directly over Flight SQL:

arrow_cli --host 127.0.0.1 --port 50051 --timeout 120

Flight SQL accepts ordinary DataFusion SET statements, but rejects SET algeon_datafusion.*; server resource policy comes from ServerConfig. GPU execution requires a CUDA-capable host and the runtime libraries for the enabled Cargo features. In the default mode, relational candidates the server does not select for GPU execution stay in DataFusion; a failure after GPU execution starts is returned as a structured error and is not replayed on CPU. Use EXPLAIN GPU (see GPU Coverage Validation) to see which parts of a query will run on the GPU.