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.
Quickstart
The call below supplies edges from registered relation target_edges with canonical src and dst columns and may include weight, plus the registered relation ppr_seeds (the personalization relation with columns vertex, value). Substitute your own registered relations.
SELECT * FROM cugraph_personalized_pagerank(edges => (SELECT src, dst FROM target_edges), personalization => (SELECT vertex, value FROM ppr_seeds));
Inputs
Every relation is a named parenthesized SELECT subquery. The required edges role uses canonical src and dst columns; every role, its canonical columns, and their accepted Arrow types are listed under Relation arguments. Metadata validation resolves registered tables named in its JSON request.
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
Relation arguments
| Argument | Required | Columns | Description |
|---|---|---|---|
edges | yes |
| edge relation with canonical src and dst columns, plus optional weight and edge_id columns |
personalization | yes |
| personalization relation with vertex and numeric value columns |
Vertex columns of personalization must use the same vertex domain as edges: the integer type of src and dst, or any listed string type when the endpoints are strings. Every edge_id column must have the integer type of src and dst; string-keyed graphs accept no edge IDs.
Named value arguments
| Option | Type | Default | Constraints | Description |
|---|---|---|---|---|
alpha | number | 0.85 | min 0; max 1 | PageRank damping factor in [0, 1] |
epsilon | number | 0.00001 | > 0 | positive convergence tolerance |
max_iterations | integer | 100 | min 1; max 4294967295 | maximum iteration count, at least 1 |
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; run gpu_validate_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 seed view resolves BERT from its title and year (a 2019
conference record shares the title), and every later reference to the seed
reads that view. 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 OR REPLACE VIEW bert_seed AS
SELECT paper_id AS vertex, CAST(1.0 AS DOUBLE) AS value
FROM papers
WHERE title = 'BERT: Pre-training of Deep Bidirectional Transformers for Language Understanding'
AND year = 2018;
SELECT ROUND(r.value, 6) AS ppr, p.year, p.title
FROM cugraph_personalized_pagerank(
edges => (SELECT src, dst FROM citation_edges),
personalization => (SELECT vertex, value FROM bert_seed)) r
JOIN papers p ON p.paper_id = r.vertex
WHERE NOT EXISTS (SELECT 1 FROM bert_seed s WHERE s.vertex = r.vertex)
AND NOT EXISTS (SELECT 1 FROM citation_edges e JOIN bert_seed s ON s.vertex = e.src
WHERE 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 view, the exclusion of the seed itself, and the anti-join are all ordinary SQL composed around one GPU call.
Limits
No algorithm-specific limitations.
To dry-run validate relation metadata, column types, and options without execution, see gpu_validate_call.