Skip to main content

cuGraph SQL API

Algeon exposes NVIDIA RAPIDS cuGraph algorithms as SQL table functions over DataFusion SQL sessions, whether the session is embedded in a Rust process or served remotely through Flight SQL. Each cugraph_* function reads an edge relation, builds a GPU graph, runs an algorithm, and returns rows you can compose with ordinary SQL.

This section helps you choose a graph function, provide its edge relation, and understand its execution and reuse boundaries.

Use functions-only execution to keep scans and surrounding SQL on DataFusion CPU while graph algorithms run on GPU. The same page covers backend configuration and host staging limits.

Graph input and call shape​

Most functions share this positional shape; the ones that need extra inputs add them, so treat each function page's signature as authoritative:

cugraph_<algorithm>(table_name [, src_col, dst_col [, weight_col [, options_json]]])
  • table_name — an edge relation (a registered table or view of edges).
  • src_col / dst_col — endpoint columns; default to src / dst.
  • weight_col — optional edge weight column. Whether it affects results depends on the function's Weight column entry in the cheat sheet below.
  • options_json — a JSON string of algorithm and graph options.

For example, cugraph_bfs and cugraph_sssp take a source vertex as their second argument, and cugraph_personalized_pagerank requires all five arguments.

The relation name must resolve to a table or view registered in the session. That relation can be backed by the session's configured sources, including Parquet and Iceberg. See Integrating Algeon for source and session setup, and Graph Inputs and Construction for vertex-ID contracts, directedness, vertex renumbering, and edge normalization.

Functions​

Start with Browse functions to choose an algorithm by family or compare the generated catalog descriptors.

Discovery and validation​

Use Discover & Validate GPU Functions for the shared list, describe, validate, and execute workflow. The exact metadata response and validation-request schemas are in the GPU Function Catalog API.

Reuse in bounded servers​

A bounded Flight SQL server can retain constructed graphs for repeat calls with a strongly identified, eligible input. The current reusable path covers BFS without include_edges, PageRank, Jaccard, Sorensen, Overlap, and Cosine; other calls bypass the cache. Configure and observe it through Cache Design.

Next steps​