Graph Inputs and Construction

Every cugraph_* function 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 function descriptor remains authoritative when an algorithm narrows either part of this shared contract.

Vertex ID support by function

This matrix is generated from each function descriptor’s structured edges.vertex_id_contract. It is the authoritative overview of numeric endpoint inputs, logical string endpoint inputs, canonical string output, side-input limitations, and legacy Int32-only dispatch.

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. Numeric endpoint requirements remain function-specific and are not widened by logical string support.

Function	Numeric endpoint types	Logical string endpoint types	Canonical string output	Logical side-input limitation	Legacy Int32-only
Betweenness Centrality	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
BFS	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs; string logical vertex-domain BFS rejects edge_id_col, include_edge_ids_*, and include_edge_id_col	No
Core Number	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Cosine	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge 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	No
Degrees All	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
ECG	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Edge Betweenness Centrality	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Eigenvector Centrality	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
ForceAtlas2	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
HITS	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
In Degrees All	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Jaccard	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge 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	No
K-Core	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Katz Centrality	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Leiden	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Louvain	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Minimum Spanning Tree	Int32	Not supported	—	Not applicable	Yes
Out Degrees All	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Overlap	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge 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	No
PageRank	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Personalized PageRank	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Sorensen	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge 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	No
Spectral Modularity Maximization	Int32	Not supported	—	Not applicable	Yes
SSSP	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Strongly Connected Components	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Triangle Count All	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No
Weakly Connected Components	Int32, Int64	Utf8, LargeUtf8, Utf8View	Utf8	edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs	No

Use gpu_describe_function for the full descriptor and gpu_validate_call for the concrete call-specific schema and side-input validation.

Construction options

Every cugraph_* function accepts these shared options inside options_json, alongside any algorithm-specific options. They control how the GPU graph is built from the edge relation.

Option	Type	Default	Allowed values	Description
directed	Boolean	true base default; some algorithms default to false	true, false	Whether graph construction treats edges as directed.
renumber	Boolean	true	true, false	Whether construction may renumber external vertex ids internally.
construction_policy	Utf8	python_cugraph	python_cugraph, raw_libcugraph	Edge-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 function's page and from gpu_validate_call is authoritative for that function.

Construction policy

construction_policy is a graph-ingress choice, not an algorithm choice. It decides whether DataFusion Nexus 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.

Policy	Best use	What happens
python_cugraph	Default 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. DataFusion Nexus inserts an EdgeNormalize step when the edge source is not already proven canonical.
raw_libcugraph	Pre-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. The difference is whether Nexus performs the Python-compatible edge normalization before the raw graph build.

What python_cugraph normalizes

When normalization is required, Nexus 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 actually consumes that column.

How to set it

Leave the option unset to use the default python_cugraph policy:

SELECT *
FROM cugraph_pagerank('edges', 'src', 'dst');

Override one call when the edge relation is already prepared for raw libcugraph-style construction:

SELECT *
FROM cugraph_pagerank(
  'canonical_edges',
  'src',
  'dst',
  'weight',
  '{"construction_policy":"raw_libcugraph"}'
);

On the standalone Flight SQL server, set a process default with NEXUS_SERVER_CUGRAPH_CONSTRUCTION_POLICY. Per-call options_json still wins:

NEXUS_SERVER_CUGRAPH_CONSTRUCTION_POLICY=raw_libcugraph \
NEXUS_SERVER_CUGRAPH_ENABLED=true \
flock /tmp/cudf-gpu.lock bash scripts/dev/run_server.sh

Verify the planned path

Use EXPLAIN when the distinction matters:

EXPLAIN
SELECT *
FROM cugraph_louvain(
  'edges',
  'src',
  'dst',
  'weight',
  '{"directed":false,"construction_policy":"python_cugraph"}'
);

Look for both fields in the physical plan:

• construction_policy=python_cugraph means the SQL call requested Python-compatible construction semantics.
• edge_normalize_inserted=true means Nexus 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.
• construction_policy=raw_libcugraph with edge_normalize_inserted=false means the call bypasses Python-style normalization.