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)

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_personalized_pagerank('target_edges', 'src', 'dst', NULL, '{"personalization_table":"ppr_seeds","personalization_vertex_col":"vertex","personalization_value_col":"value"}');

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		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	Damping factor: the probability that the random walk follows an outgoing edge instead of restarting. Higher values let distant structure influence scores more; lower values keep rank closer to the restart distribution.
epsilon	Float64	0.00001	> 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	100	min 1	Upper bound on PageRank iterations. If the bound is reached before epsilon is met, the scores computed so far are returned.
personalization_table	Utf8		required	Table containing personalized PageRank vertex weights.
personalization_value_col	Utf8		required; example "value"	Column in personalization_table holding each personalization vertex's relative restart weight; larger values pull more rank toward that vertex.
personalization_vertex_col	Utf8		required; example "vertex"	Column in personalization_table naming the vertices the random walk restarts at; vertices absent from the table receive no restart mass.

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

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