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.

Signature

cugraph_k_core(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

Option	Type	Default	Constraints	Description
degree_type	Utf8	"in_out"	one of "in", "out", "in_out"
k	UInt32	2	min 1

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
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; validate the 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 TABLE kcore30 AS
SELECT src, dst FROM cugraph_k_core('citation_edges', 'src', 'dst', NULL, '{"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). Note also that this per-direction floor is a stricter condition than cugraph_core_number's in_out degree, which sums the two directions.

Chain it into the next algorithm

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

SELECT p.year, p.title
FROM cugraph_pagerank('kcore30', 'src', 'dst') 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

Limitations & lifecycle

No algorithm-specific limitations.

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