Graph Inputs and Construction
Every cugraph_* UDTF builds a GPU graph from an edge relation. Before
choosing algorithm-specific options, establish two parts of the graph input
contract:
- the vertex-ID domain carried by the source and destination columns;
- the construction semantics applied to the edge rows.
The concrete UDTF descriptor remains authoritative when an algorithm narrows either part of this shared contract.
Vertex ID support by UDTF
This matrix is generated from each UDTF descriptor’s structured edges.vertex_id_contract. It is the authoritative overview of numeric endpoint inputs, the numeric types a per-call codebook maps to native ids, logical string endpoint inputs, canonical string output, the native vertex id type, and side-input limitations.
Logical string input means any Utf8, LargeUtf8, or Utf8View edge endpoint. The physical string types may be mixed within one graph call. Vertex-identity outputs use the declared canonical string type. A per-call codebook maps string vertices, and numeric vertices the native graph cannot index, to dense native ids and decodes results back to the input vertex type.
Use gpu_describe_function for the full descriptor and gpu_validate_call for the concrete call-specific schema and side-input validation.
Vertex codebook
cugraph_spectral_modularity_maximization and cugraph_minimum_spanning_tree
run their native algorithms on Int32 vertex ids. Both accept Int32, Int64 and
string vertex columns. For Int64 and string vertices, the call maps each
distinct vertex to a dense Int32 id before the native algorithm runs and
decodes the returned ids to the input vertex type, so the SQL needs no mapping
table. The distinct vertex count must fit in Int32.
Construction options
Every cugraph_* UDTF accepts these shared named value arguments alongside
any algorithm-specific values. They control how the GPU graph is built from the
edge relation.
Per-algorithm option defaults can differ. directed defaults to false for
weakly connected components, triangle count, core number, k-core, minimum
spanning tree, spectral modularity maximization, and ForceAtlas2. The default
shown on each UDTF's page and from gpu_validate_call is authoritative
for that UDTF.
Construction policy
construction_policy is a graph-ingress choice, not an algorithm choice. It
decides whether Algeon should first make the SQL edge relation match
Python cuGraph edge-list construction semantics, or pass the relation directly
to the lower-level libcugraph construction path.
Use python_cugraph unless you have a specific reason to bypass Python-style
edge normalization.
For SQL calls, both policies still use simple graph properties selected by
directed. There is no SQL multigraph option.
What python_cugraph normalizes
When normalization is required, Algeon rewrites the edge list before graph construction:
directed=true: duplicate directed(src, dst)pairs are collapsed.directed=false: reverse(dst, src)rows are added, then duplicate directed pairs are collapsed.- weighted duplicate conflicts are shape-specific: directed weighted graphs keep
the last row in stable input order for each
(src, dst)pair; undirected weighted graphs keep the minimum weight after reverse-edge expansion.
Edge normalization and null handling
The optimizer may skip the physical EdgeNormalize operator even when the
selected policy is python_cugraph, but only when it can prove the input edge
source is already canonical for the requested directed and edge-column shape.
With either construction policy, source and destination nulls are not valid graph edges and are dropped before libcugraph receives the edge list. Null weights or edge ids only drop rows when the planned algorithm consumes that column.
How to set it
Leave the option unset to use the default python_cugraph policy:
SELECT *
FROM cugraph_pagerank(edges => (SELECT src, dst FROM edges));
Override one call when the edge relation is already prepared for raw libcugraph-style construction:
SELECT *
FROM cugraph_pagerank(
edges => (SELECT src, dst, weight FROM canonical_edges),
construction_policy => 'raw_libcugraph'
);
On the standalone Flight SQL server, set a process default with
ALGEON_SERVER_CUGRAPH_CONSTRUCTION_POLICY. A per-call named value still wins:
ALGEON_SERVER_CUGRAPH_CONSTRUCTION_POLICY=raw_libcugraph target/release/algeon_server
Verify the planned path
Use EXPLAIN when the distinction matters:
EXPLAIN
SELECT *
FROM cugraph_louvain(
edges => (SELECT src, dst, weight FROM edges),
directed => false,
construction_policy => 'python_cugraph'
);
Look for both fields in the physical plan:
construction_policy=python_cugraphmeans the SQL call requested Python-compatible construction semantics.edge_normalize_inserted=truemeans Algeon will run a physical edge normalization step.construction_policy=python_cugraphwithedge_normalize_inserted=falsemeans the optimizer proved the input is already canonical for the requested Python-compatible semantics.
Reuse algorithm results
A view stores a query definition. Each later query that reads it executes the
algorithm again.
Community partitions and layout coordinates can change between executions.
The reproducibility section
lists which functions repeat. Use CREATE OR REPLACE TABLE ... AS when later
queries need results from one execution, as in the
SCC example.
CTAS executes the query and collects its results into a DataFusion MemTable
in host RAM. A later GPU query uploads the required data again. These result
tables last until the server stops and leave the source Parquet files unchanged.
Include materialization and result collection in end-to-end timing.