Core Number

SQL function: cugraph_core_number

Official cuGraph reference: C API

Assign each vertex the largest k for which it belongs to a k-core, where every vertex has degree at least k within that subgraph.

Signature

cugraph_core_number(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_core_number('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"	Which edges count toward a vertex's degree in the k-core decomposition: incoming (in), outgoing (out), or both (in_out).

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 whose core number is reported.
core_number	Int64	no	Largest k value for which the vertex belongs to the graph k-core.

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.

Find the densest citation core

Core number measures how deep a vertex sits in recursively denser subgraphs (with degree_type: "in_out", degree is in + out). Define the result as a workspace view, find the deepest shell, and list its members:

CREATE VIEW cores AS
SELECT vertex, core_number FROM cugraph_core_number('citation_edges', 'src', 'dst');

SELECT MAX(core_number) AS deepest,
       COUNT(*) FILTER (WHERE core_number = 70) AS members
FROM cores;

deepest	members
70	5,913

SELECT p.year, p.title
FROM cores c JOIN papers p ON p.paper_id = c.vertex
WHERE c.core_number = 70
ORDER BY p.n_citation DESC
LIMIT 6;

year	title
2004	Distinctive Image Features from Scale-Invariant Keypoints
2001	Random Forests
2011	LIBSVM: A library for support vector machines
1995	The Nature of Statistical Learning Theory
1995	Support-Vector Networks
1986	A Computational Approach to Edge Detection

The 70-core — 5,913 papers, each with at least 70 combined in/out edges to other members of the shell — is recognizably the machine-learning and computer-vision literature.

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