Skip to main content

Louvain

UDTF: cugraph_louvain

Official cuGraph reference: C API

Build a hierarchy of communities by greedily moving vertices and aggregating partitions to maximize modularity.

Quickstart​

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

SELECT *
FROM cugraph_louvain(
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.

The vertex-ID types this UDTF accepts, the numeric types a per-call codebook maps to native ids, and its string-key limits are listed in Vertex ID support; the concrete call-specific schema comes from gpu_validate_call.

Arguments and options​

Relation arguments​

ArgumentRequiredColumnsDescription
edgesyes
  • 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; this algorithm ignores weight

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

Named value arguments​

OptionTypeDefaultConstraintsDescription
max_levelinteger100min 1; max 4294967295maximum hierarchy level, at least 1
resolutionnumber1> 0positive community resolution
thresholdnumber1e-7min 0non-negative convergence threshold

Graph construction options​

This UDTF requires directed=false (undirected/symmetric graph). All other graph construction options follow the shared defaults documented in Graph Construction Options.

Output​

ColumnTypeNullableDescription
vertexInt64|Utf8noVertex assigned to a Louvain community.
communityInt64noCommunity identifier assigned by Louvain.

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

Examples​

Do citation communities match the catalog's research fields?​

SQL selects papers from 2010 onward with one of ten AI primary_fos labels, keeps edges within that set and runs Louvain. It then counts the catalog labels within each returned community.

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;

WITH community_fos AS (
SELECT c.community, p.primary_fos, COUNT(*) AS n
FROM cugraph_louvain(edges => (SELECT src, dst FROM ai_edges)) c
JOIN papers p ON p.paper_id = c.vertex
GROUP BY c.community, p.primary_fos),
ranked AS (
SELECT SUM(n) OVER (PARTITION BY community) AS members,
ROW_NUMBER() OVER (PARTITION BY community ORDER BY n DESC) AS rn,
primary_fos,
n
FROM community_fos)
SELECT members, rn, primary_fos, n
FROM ranked
WHERE members > 2500 AND rn <= 3
ORDER BY members DESC, rn;

These are the five captured groups larger than 2,500 papers. The listed fields cover only part of each community.

Papers in groupThree most common catalog fields, with paper counts
7,172Convolutional neural network (2,698); Deep learning (2,527); Artificial neural network (869)
4,477Deep learning (1,332); Recurrent neural network (1,280); Artificial neural network (624)
4,260Image segmentation (1,919); Convolutional neural network (921); Deep learning (799)
3,859Reinforcement learning (3,129); Artificial neural network (279); Deep learning (226)
3,518Object detection (2,193); Convolutional neural network (467); Deep learning (342)

The query took 0.17 s.

The 7,172-paper community combines convolutional neural network and deep learning labels in similar numbers. The 3,859-paper community is dominated by reinforcement learning. Citation structure and catalog fields agree to different degrees across these groups.

An editor can examine disagreements before updating taxonomy categories, treating community IDs as local cluster assignments.

The capture records the query and all returned field counts.