K-Core

SQL function: cugraph_k_core

Official cuGraph reference: C API

Return the edges of the maximal subgraph whose vertices each have degree at least k within that subgraph.

Quickstart

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

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

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

Relation arguments

Argument	Required	Columns	Description
edges	yes	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

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

Named value arguments

Option	Type	Default	Constraints	Description
degree_type	string	"in_out"	one of "in", "out", "in_out"	degree direction
k	integer	2	min 1; max 4294967295	k-core degree threshold, at least 1

Graph construction options

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

Output

Column	Type	Nullable	Description
src	Int64|Utf8	no	Source vertex of an edge retained in the k-core subgraph.
dst	Int64|Utf8	no	Destination vertex of an edge retained in the k-core subgraph.

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

Examples

These examples run on the citation network demo dataset.

Extract the citation backbone and audit it with SQL

Unlike most functions here, cugraph_k_core returns edges, not scores: the subgraph where every remaining vertex keeps at least k in-edges and k out-edges. Because the output is reused as an edge relation, materialize it in the local workspace; plain SQL can then verify the contract it guarantees:

-- Local workspace materialization; this does not write to lake.citation_network.
CREATE OR REPLACE TABLE kcore30 AS
SELECT src, dst
FROM cugraph_k_core(edges => (SELECT src, dst FROM citation_edges), k => 30);

WITH deg AS (
  SELECT v, SUM(o) AS outd, SUM(i) AS ind
  FROM (SELECT src AS v, 1 AS o, 0 AS i FROM kcore30
        UNION ALL
        SELECT dst AS v, 0 AS o, 1 AS i FROM kcore30) u
  GROUP BY v)
SELECT COUNT(*) AS vertices, MIN(outd) AS min_out, MIN(ind) AS min_in
FROM deg;

vertices	min_out	min_in
33,389	30	30

45.6M edges reduce to a 33k-vertex backbone of papers that both cite and are cited heavily, and the audit confirms every vertex meets the k=30 floor in both directions.

The k-core edge list comes back symmetrized: each undirected core edge appears in both directions (2,043,052 rows here, i.e. ~1.0M undirected edges), which is why the in and out floors match. Both functions count a paper's distinct citation neighbors, so this backbone is the set of papers whose core number is at least 30.

Chain it into the next algorithm

The materialized backbone is itself a valid edge relation, so it can feed another cugraph_* call, forming a two-stage GPU pipeline connected through a local workspace table name:

SELECT p.year, p.title
FROM cugraph_pagerank(edges => (SELECT src, dst FROM kcore30)) r
JOIN papers p ON p.paper_id = r.vertex
ORDER BY r.value DESC
LIMIT 5;

year	title
2004	Distinctive Image Features from Scale-Invariant Keypoints
2014	VERY DEEP CONVOLUTIONAL NETWORKS FOR LARGE-SCALE IMAGE RECOGNITION
2005	Histograms of oriented gradients for human detection
2009	ImageNet: A large-scale hierarchical image database
2016	Deep Residual Learning for Image Recognition

Limits

No algorithm-specific limitations.

To dry-run validate relation metadata, column types, and options without execution, see gpu_validate_call.