Skip to main content

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.

UDTFNumeric endpoint typesNumeric types mapped by codebookLogical string endpoint typesCanonical string outputNative vertex id typeLogical side-input limitation
Betweenness CentralityInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
BFSInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs; string logical vertex-domain BFS rejects edges.edge_id and edge-id predicate relations
Core NumberInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
CosineInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs; candidate-pair columns must match the graph vertex domain; logical string graphs accept Utf8, LargeUtf8, or Utf8View independently per column
Degrees AllInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
ECGInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Edge Betweenness CentralityInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Eigenvector CentralityInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
ForceAtlas2Int32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
HITSInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
In Degrees AllInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
JaccardInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs; candidate-pair columns must match the graph vertex domain; logical string graphs accept Utf8, LargeUtf8, or Utf8View independently per column
K-CoreInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Katz CentralityInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
LeidenInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
LouvainInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Minimum Spanning TreeInt32, Int64Int64Utf8, LargeUtf8, Utf8ViewUtf8Int32edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Out Degrees AllInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
OverlapInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs; candidate-pair columns must match the graph vertex domain; logical string graphs accept Utf8, LargeUtf8, or Utf8View independently per column
PageRankInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Personalized PageRankInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
SorensenInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs; candidate-pair columns must match the graph vertex domain; logical string graphs accept Utf8, LargeUtf8, or Utf8View independently per column
Spectral Modularity MaximizationInt32, Int64Int64Utf8, LargeUtf8, Utf8ViewUtf8Int32edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
SSSPInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Strongly Connected ComponentsInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Triangle Count AllInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs
Weakly Connected ComponentsInt32, Int64NoneUtf8, LargeUtf8, Utf8ViewUtf8Int64edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs

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.

OptionTypeDefaultAllowed valuesDescription
directedBooleantrue base default; some algorithms default to falsetrue, falseWhether graph construction treats edges as directed.
renumberBooleantruetrue, falseWhether construction may renumber external vertex ids internally.
construction_policyUtf8python_cugraphpython_cugraph, raw_libcugraphEdge-list construction semantics used before calling libcugraph.

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.

PolicyBest useWhat happens
python_cugraphDefault for application SQL, notebooks, Python cuGraph parity checks, and edge tables that may contain duplicate or one-way undirected edges.Requests Python cugraph.Graph.from_cudf_edgelist(...)-compatible construction. Algeon inserts an EdgeNormalize step when the edge source is not already proven canonical.
raw_libcugraphPre-normalized edge tables, lower-level libcugraph parity checks, and performance-sensitive paths where duplicate/reverse-edge semantics are intentionally handled upstream.Skips Python-style EdgeNormalize and sends the edge list to the libcugraph-compatible graph builder. Null edge rows are still sanitized because libcugraph has no null-edge semantics.

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_cugraph means the SQL call requested Python-compatible construction semantics.
  • edge_normalize_inserted=true means Algeon will run a physical edge normalization step.
  • construction_policy=python_cugraph with edge_normalize_inserted=false means the optimizer proved the input is already canonical for the requested Python-compatible semantics.
  • distinct_edge_pairs=true means 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.