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
Every edge_id column must have the integer type of src and dst; string-keyed graphs accept no edge IDs.
Named value arguments
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
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.
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.