Weakly Connected Components

SQL function: cugraph_weakly_connected_components

Official cuGraph reference: C API

Label maximal connected subgraphs after treating directed edges as undirected.

Signature

cugraph_weakly_connected_components(table_name [, src_col, dst_col [, weight_col [, options_json]]])

Quickstart

The call below expects a registered edge table or view target_edges with endpoint columns src and dst. Substitute your own registered relations.

SELECT * FROM cugraph_weakly_connected_components('target_edges');

Inputs

table_name must be a registered edge table or view (the edges role); parenthesized subqueries are not accepted, and metadata validation resolves the same registered name.

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

Positional scalar arguments

src_col and dst_col name the edge endpoint columns; both are optional and default to src and dst.

Argument	Type	Required	Default	Notes
weight_col	Utf8|null	no		accepted as an edge-column binding; native algorithm execution does not consume weights; semantic effect: none for this algorithm

JSON options

This function has no algorithm-specific options.

Graph construction options

This function builds an undirected graph by default (directed=false); all other graph construction options follow the shared defaults documented in Graph Construction Options.

Output

Column	Type	Nullable	Description
vertex	Int64|Utf8	no	Vertex assigned to a weakly connected component.
label	Int64	no	Weakly connected component identifier for the vertex: the minimum vertex id in the component, stable across runs.

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

Examples

These examples run on the citation network demo dataset.

Measure the largest connected component

WCC requires directed: false. Of the 4.15M papers that have at least one edge, 99.4% form a single giant component:

WITH comp AS (
  SELECT label, COUNT(*) AS members
  FROM cugraph_weakly_connected_components('citation_edges', 'src', 'dst', NULL,
                                           '{"directed":false}')
  GROUP BY label)
SELECT COUNT(*) AS components, MAX(members) AS giant, SUM(members) AS vertices
FROM comp;

components	giant	vertices
9,751	4,123,602	4,146,772

Snapshot first, then examine the isolated components

Component labels are assigned per execution, so a query that scans the algorithm twice can join mismatched labels. Materialize one run in the mutable datafusion.public workspace, then summarize the largest components outside the giant one — one row per component, represented by its most-cited member.

-- Local workspace snapshot; this does not write to lake.citation_network.
CREATE TABLE wcc_snapshot AS
SELECT vertex, label
FROM cugraph_weakly_connected_components('citation_edges', 'src', 'dst', NULL,
                                         '{"directed":false}');

WITH sizes AS (
  SELECT label, COUNT(*) AS members FROM wcc_snapshot
  GROUP BY label ORDER BY members DESC LIMIT 3 OFFSET 1),
detail AS (
  SELECT s.members, p.year, p.venue, p.title,
         ROW_NUMBER() OVER (PARTITION BY s.label ORDER BY p.n_citation DESC) AS rn
  FROM sizes s
  JOIN wcc_snapshot c ON c.label = s.label
  JOIN papers p ON p.paper_id = c.vertex)
SELECT members, year, venue, title
FROM detail WHERE rn = 1
ORDER BY members DESC;

members	year	venue	title
39	2008	IEICE Transactions on Electronics	Motion of Break Arcs Driven by External Magnetic Field…
25	2013	IEICE Electronics Express	Cavity-resonator-integrated guided-mode resonance filter…
21	2015	Symmetry	Inflationary Cosmology in Modified Gravity Theories

The three largest isolated components are a 39-paper cluster on electrical-contact arc discharge, a 25-paper photonics/electromagnetics cluster, and a 21-paper modified-gravity cosmology cluster — each citing only itself. Communities that publish outside the corpus's main subject areas appear as disconnected components in the graph.

Limits

• cuGraph requires directed=false so the graph is constructed as an undirected/symmetric view

Validate the call

Dry-run validation checks registered relation metadata, column presence, static dtypes, and options only; it does not scan edge data, construct a graph, or prove source-vertex existence:

SELECT * FROM gpu_validate_call(
  'cugraph_weakly_connected_components',
  '{"schema_version":1,"relations":{"edges":{"table":"target_edges"}},"options":{"src_col":"src","dst_col":"dst"}}'
);

See GPU Function Catalog API for the full gpu_validate_call contract.