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]]])

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_k_core('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
degree_type	Utf8	"in_out"	one of "in", "out", "in_out"	Degree direction used by the underlying core-number computation: incoming (in), outgoing (out), or both (in_out).
k	UInt32	2	min 1	Order of the core to extract: vertices whose core number is below k are dropped along with their edges.

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

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_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.