Katz Centrality

SQL function: cugraph_katz_centrality

Official cuGraph reference: C API

Score vertices from the number of walks that reach them, attenuating longer walks and adding a baseline contribution.

Signature

cugraph_katz_centrality(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_katz_centrality('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
alpha	Float64	0.01	max 1; > 0	Attenuation factor applied per path length; larger values let longer paths contribute more. cuGraph requires alpha below the inverse of the graph's largest eigenvalue for the iteration to converge.
beta	Float64	1	> 0	Constant added to every vertex's score in each iteration. One scalar applies to all vertices; per-vertex betas are not exposed.
epsilon	Float64	0.000001	> 0	Convergence tolerance: iteration stops once the L1 sum of score changes between consecutive iterations is below the vertex count multiplied by epsilon. Smaller values tighten convergence and may need more iterations.
max_iterations	UInt32	1000	min 1	Upper bound on Katz iterations.

Graph construction options

Graph construction follows the shared defaults (directed=true, renumbering, python_cugraph policy) documented in Graph Construction Options.

Output

Column	Type	Nullable	Description
vertex	Int64|Utf8	no	Vertex receiving the Katz centrality score.
value	Float64	no	Katz centrality score for the vertex.

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.

alpha decides how deep credit flows

Katz centrality counts all incoming walks, discounting a walk of length n by alpha^n. At the default alpha (0.01) long chains contribute almost nothing and the ranking is nearly in-degree. Raising alpha to 0.05 shifts credit to papers whose citers are themselves heavily cited, transitively — window functions over the two results make the shift visible as rank movement:

WITH katz AS (
  SELECT vertex, ROW_NUMBER() OVER (ORDER BY value DESC) AS katz_rank
  FROM cugraph_katz_centrality('citation_edges', 'src', 'dst', NULL,
                               '{"alpha": 0.05}')),
deg AS (
  SELECT vertex, in_degree, ROW_NUMBER() OVER (ORDER BY in_degree DESC) AS degree_rank
  FROM cugraph_in_degrees_all('citation_edges', 'src', 'dst'))
SELECT p.title, p.year, k.katz_rank, d.degree_rank, d.in_degree
FROM katz k
JOIN deg d ON d.vertex = k.vertex
JOIN papers p ON p.paper_id = k.vertex
WHERE k.katz_rank <= 8
ORDER BY k.katz_rank;

title	year	katz_rank	degree_rank	in_degree
Distinctive Image Features from Scale-Invariant Keypoints	2004	1	1	22,892
The Nature of Statistical Learning Theory	1995	2	6	14,508
Histograms of oriented gradients for human detection	2005	3	9	13,768
Object recognition from local scale-invariant features	1999	4	58	6,300
New Directions in Cryptography	1976	5	69	6,007
The Design and Analysis of Computer Algorithms	1974	6	103	5,168
A Computational Approach to Edge Detection	1986	7	24	9,069
A method for obtaining digital signatures and public-key cryptosystems	1978	8	50	6,580

The risers are the foundations: New Directions in Cryptography climbs from in-degree rank #69 to Katz rank #5 and the RSA paper from #50 to #8, because the papers citing them anchor entire downstream literatures. Katz is the natural choice on citation-style graphs — near-acyclic structure starves eigenvector centrality, while the beta base score keeps every vertex non-zero here. Convergence requires alpha below the reciprocal of the graph's largest eigenvalue: pushing it too high fails with a convergence error rather than returning partial scores.

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