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]]])

Relation inputs

The first positional argument names a registered edge table or view (the edges role). Parenthesized relation subqueries are not accepted; metadata validation uses the same registered name.

Vertex ID types

The edges relation declares the accepted vertex-ID domains. Numeric calls preserve the existing numeric schema. When logical string support is declared, Utf8, LargeUtf8, and Utf8View endpoint columns share one logical domain; their vertex-identity outputs are canonicalized to Utf8.

Domain	Accepted endpoint inputs	Output contract
Numeric edge endpoints	Int32, Int64	The numeric output schema is used for numeric calls.
Logical string edge endpoints	Utf8, LargeUtf8, Utf8View	Vertex identity columns are canonicalized to Utf8; scores, distances, counts, coordinates, and opaque labels remain numeric.

The native mapping type is Int64. Call-specific output schemas come 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

Scalar arguments & JSON 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 schema

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.

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.

Limitations & lifecycle

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

Validate before running

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.