Personalized PageRank

SQL function: cugraph_personalized_pagerank

Official cuGraph reference: C API

Rank vertices with PageRank while biasing random-walk restarts toward explicitly weighted personalization vertices.

Signature

cugraph_personalized_pagerank(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		optional edge weight column for graph construction when supported by the algorithm; semantic effect: edge weights affect algorithm results when provided

JSON options

Option	Type	Default	Constraints	Description
alpha	Float64	0.85	min 0; max 1
epsilon	Float64	0.00001	> 0
max_iterations	UInt32	100	min 1
personalization_table	Utf8		required	Table containing personalized PageRank vertex weights.
personalization_value_col	Utf8		required; example "value"
personalization_vertex_col	Utf8		required; example "vertex"

Graph construction options

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

Output schema

Column	Type	Nullable	Description
vertex	Int64|Utf8	no	Vertex receiving the PageRank score.
value	Float64	no	PageRank 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.

Biased walk filtered by an anti-join

Personalized PageRank biases the walk toward seed vertices supplied by a relation. Seeding on BERT ranks the papers its citation neighborhood returns to most often. The rows of interest are the ones BERT does not already cite: a NOT EXISTS anti-join against the edge table removes the direct references, leaving the indirect ancestry:

CREATE VIEW bert_seed AS
SELECT CAST(2896457183 AS BIGINT) AS vertex, CAST(1.0 AS DOUBLE) AS value;

SELECT ROUND(r.value, 6) AS ppr, p.year, p.title
FROM cugraph_personalized_pagerank('citation_edges', 'src', 'dst', NULL,
       '{"personalization_table":"bert_seed",
         "personalization_vertex_col":"vertex",
         "personalization_value_col":"value"}') r
JOIN papers p ON p.paper_id = r.vertex
WHERE r.vertex <> 2896457183
  AND NOT EXISTS (SELECT 1 FROM citation_edges e
                  WHERE e.src = 2896457183 AND e.dst = r.vertex)
ORDER BY r.value DESC
LIMIT 8;

ppr	year	title
0.003127	1983	A Maximum Likelihood Approach to Continuous Speech Recognition
0.002984	2003	A neural probabilistic language model
0.002392	1997	Long short-term memory
0.002358	2014	Adam: A Method for Stochastic Optimization
0.002344	1990	A statistical approach to machine translation
0.001988	1993	Building a large annotated corpus of English: the penn treebank
0.001923	1975	Design of a linguistic statistical decoder for the recognition of continuous speech
0.001872	2006	The PASCAL Recognising Textual Entailment Challenge

BERT never cites Jelinek's 1975–1983 speech-decoding papers, statistical machine translation, or the Penn Treebank, yet the walk reaches them two or three references deep. The seed table, the exclusion of the seed itself, and the anti-join are all ordinary SQL composed around one GPU call.

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_personalized_pagerank',
  '{"schema_version":1,"relations":{"edges":{"table":"target_edges"}},"options":{"src_col":"src","dst_col":"dst","personalization_table":"ppr_seeds","personalization_vertex_col":"vertex","personalization_value_col":"value"}}'
);

See GPU Function Catalog API for the full gpu_validate_call contract.