Betweenness Centrality

UDTF: cugraph_betweenness_centrality

Official cuGraph reference: C API

Measure how often each vertex lies on shortest paths between other vertex pairs, exactly or from an explicit sample of source vertices.

Quickstart

The call below supplies edges from registered relation target_edges with canonical src and dst columns and may include weight. Substitute your own registered relations.

SELECT *
FROM cugraph_betweenness_centrality(
  edges => (SELECT src, dst FROM target_edges)
);

Inputs

Every relation is a named parenthesized SELECT subquery. The required edges role uses canonical src and dst columns; every role, its canonical columns, and their accepted Arrow types are listed under Relation arguments. Metadata validation resolves registered tables named in its JSON request.

Endpoint columns accept numeric Int32, Int64 vertex IDs or logical string Utf8, LargeUtf8, Utf8View vertex IDs; string vertex-identity outputs are canonicalized to Utf8 (native mapping Int64) while scores, distances, counts, coordinates, and opaque labels stay numeric. The shared vertex-ID contract is summarized in Vertex ID support; the concrete call-specific schema comes from gpu_validate_call.

Logical string side-input limitations:

• edge ID columns and edge-ID predicate side inputs are not supported for logical string graphs

Arguments and options

Relation arguments

Argument	Required	Columns	Description
edges	yes	src, dst: Int32, Int64, Utf8, LargeUtf8, Utf8View weight (optional): Float32, Float64 edge_id (optional): Int32, Int64	edge relation with canonical src and dst columns, plus optional weight and edge_id columns

Every edge_id column must have the integer type of src and dst; string-keyed graphs accept no edge IDs.

Named value arguments

Option	Type	Default	Constraints	Description
exact_vertex_threshold	integer	100000	min 0; max 18446744073709552000	vertex count threshold for exact betweenness
include_endpoints	boolean	false		whether betweenness includes endpoints
k	integer|null	null	min 1; max 18446744073709552000	optional sample count, at least 1
normalized	boolean	true		whether centrality scores are normalized
seeds	array|null	null		optional non-empty homogeneous seed vertex array

Graph construction options

Graph construction follows the shared defaults (directed=true, renumbering, python_cugraph policy) documented in Graph Construction Options.

Output

Column	Type	Nullable	Description
vertex	Int64|Utf8	no	Algorithm result column.
value	Float64	no	Algorithm result column.

These are generic descriptor schemas; run gpu_validate_call to get the concrete, table-specific output schema.

Examples

This example runs on the citation network demo dataset.

Which papers connect the most citation routes across AI research?

A paper can connect many shortest citation routes without having the largest citation count. This query ranks papers by betweenness in a selected 2010s AI subgraph.

CREATE OR REPLACE VIEW ai_nodes AS
SELECT paper_id FROM papers
WHERE year >= 2010 AND primary_fos IN (
  'Deep learning', 'Artificial neural network', 'Convolutional neural network',
  'Recurrent neural network', 'Natural language processing',
  'Reinforcement learning', 'Image segmentation', 'Feature extraction',
  'Object detection', 'Speech recognition');

CREATE OR REPLACE VIEW ai_edges AS
SELECT e.src, e.dst
FROM citation_edges e
JOIN ai_nodes a ON a.paper_id = e.src
JOIN ai_nodes b ON b.paper_id = e.dst;

SELECT p.title, p.year, p.primary_fos, CAST(b.value AS BIGINT) AS betweenness
FROM cugraph_betweenness_centrality(
  edges => (SELECT src, dst FROM ai_edges), normalized => false) b
JOIN papers p ON p.paper_id = b.vertex
ORDER BY b.value DESC
LIMIT 6;

title	year	primary_fos	betweenness
Deep learning in neural networks	2015	Deep learning	1,107,737
Rich Feature Hierarchies for Accurate Object Detection and Semantic Segmentation	2014	Object detection	1,053,439
ImageNet Large Scale Visual Recognition Challenge	2015	Object detection	551,884
Squeeze-and-Excitation Networks	2017	Convolutional neural network	535,545
SqueezeNet: AlexNet-level accuracy with 50x fewer parameters and <0.5MB model size	2017	Deep learning	503,771
Regionlets for Generic Object Detection	2013	Object detection	475,746

With normalized: false, each paper's score sums its share of shortest paths across source-target pairs in this subgraph. The query casts the score to BIGINT for display. This ranks papers by their role in citation routes, a different measure from citation volume.

For sampling options on larger graphs, see the Betweenness Centrality UDTF reference.

Limits

No algorithm-specific limitations.

To dry-run validate relation metadata, column types, and options without execution, see gpu_validate_call.