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
A call whose vertex type the native algorithm cannot index maps each distinct
vertex to a dense id of the native vertex id type in the table above, runs the
algorithm on those ids and decodes the returned ids to the input vertex type,
so the SQL needs no mapping table. String vertices are mapped for every
algorithm. cugraph_spectral_modularity_maximization and
cugraph_minimum_spanning_tree run on Int32 ids, so they also map Int64
vertices, and their distinct vertex count must fit in Int32.
The mapping keeps the edge relation resident with both endpoint columns, builds the distinct vertex set from both endpoints and joins the edge relation to it once per endpoint. Peak device memory for a string-vertex call grows with the string bytes of the edge relation and is several times the peak of the same graph with Int64 vertex ids. When such a call exceeds the query memory grant, assign Int64 surrogate ids in the edge subquery, for example by joining the edges to a vertex table, and join the algorithm output back to the strings.
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.
The planner proves that each (src, dst) pair appears once when the edge
relation groups on src and dst (SELECT DISTINCT src, dst or
GROUP BY src, dst), or reads one complete Parquet file whose footer carries
the algeon.graph.simple_directed_edge_topology certificate. With that proof
an unweighted directed => true call is canonical and EdgeNormalize is
skipped. A weighted directed => true call keeps the step, which then has
nothing to deduplicate.
A directed => false call still needs the reversed edges, so EdgeNormalize
stays in the plan and receives the proof. At run time it reads the minimum and
maximum of src and dst. When the two ranges do not overlap, as in a
user-to-item graph whose user ids are offset past the item ids, a reversed
edge cannot repeat an input edge, and the step appends the reversed edges
without deduplicating. Overlapping ranges, or a relation without the proof,
take the full deduplication.
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 these 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.distinct_edge_pairs=truemeans the planner proved that each(src, dst)pair appears once.
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.