Louvain

SQL function: cugraph_louvain

Official cuGraph reference: C API

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

Signature

cugraph_louvain(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_louvain('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

Option	Type	Default	Constraints	Description
max_level	UInt32	100	min 1	Maximum number of hierarchy levels (coarsening rounds) to run. Lowering it truncates the hierarchy earlier.
resolution	Float64	1	> 0	Resolution parameter (gamma) in the modularity formula. Higher values produce more, smaller communities; lower values produce fewer, larger ones.
threshold	Float64	1e-7	min 0	Minimum modularity gain: a vertex move is accepted, and a level continues, only while the gain exceeds this threshold. Larger values stop earlier with a coarser result.

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 Louvain community.
partition	Int64	no	Community identifier assigned by Louvain.

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

Examples

This example runs on the citation network demo dataset.

Compare citation communities against field labels

Two views select the 2010s AI literature — nodes by field-of-study label, edges where both endpoints qualify — and Louvain partitions it by citation structure alone. Cross-tabulating each community against primary_fos (with a window function to keep the top 3 labels per community) shows how closely the detected communities align with the assigned labels:

CREATE 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 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."partition" AS community, p.primary_fos, COUNT(*) AS n
  FROM cugraph_louvain('ai_edges', 'src', 'dst') c
  JOIN papers p ON p.paper_id = c.vertex
  GROUP BY c."partition", 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;

members	rn	primary_fos	n
10,684	1	Convolutional neural network	3,002
10,684	2	Object detection	2,467
10,684	3	Deep learning	2,247
6,707	1	Deep learning	2,168
6,707	2	Convolutional neural network	2,061
6,707	3	Feature extraction	778
5,118	1	Deep learning	1,591
5,118	2	Recurrent neural network	1,289
5,118	3	Convolutional neural network	714
3,960	1	Reinforcement learning	3,157
3,960	2	Artificial neural network	337
3,960	3	Deep learning	204

Louvain (1,960 communities over 38k papers) recovers recognizable subfield boundaries: a computer-vision community, a sequence-modeling community, and a reinforcement-learning community that is 80% one label. Note the quoted "partition", since the output column name is a SQL keyword. cugraph_leiden is a drop-in replacement with the same call shape.

Limits

No algorithm-specific limitations.

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_louvain',
  '{"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.