PageRank

SQL function: cugraph_pagerank

Official cuGraph reference: C API

Rank vertices by the stationary probability of a damped random walk that follows outgoing edges.

Signature

cugraph_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_pagerank('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		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.

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

These examples run on the citation network demo dataset (4.9M papers, 45.6M src-cites-dst edges).

PageRank versus raw citation counts

PageRank over the full graph, joined back to paper metadata. Importance flows through citations, so a paper's score depends on who cites it, not only on how many do; on this dataset that lets papers with modest raw counts rank above papers with more, but shallower, citations.

SELECT p.title, p.year, p.n_citation, r.value AS pagerank
FROM cugraph_pagerank('citation_edges', 'src', 'dst') r
JOIN papers p ON p.paper_id = r.vertex
ORDER BY r.value DESC
LIMIT 5;

title	year	n_citation	pagerank
Finite automata and their decision problems	1959	1,401	0.00139
The Mathematical Theory of Communication	1949	48,327	0.00134
The reduction of two-way automata to one-way automata	1959	224	0.00126
The complexity of theorem-proving procedures	1971	4,592	0.00073
A mathematical theory of communication	1948	22,122	0.00066

In this run the first and third papers have modest raw counts (1,401 and 224 citations), but the papers citing them are themselves foundational results, and PageRank propagates that structure. The full call — 45.6M edges, GPU graph build, 4.1M scores, join, and sort — returned in about 1.5 s on the capture host; that is an observation from one run, not a performance figure.

Window functions over the result

The output of a cugraph_* function is a plain relation, so ROW_NUMBER() applies directly to it. This query finds where the paper that introduced PageRank ranks, by its own algorithm, among 4.9 million papers.

WITH ranked AS (
  SELECT vertex, value, ROW_NUMBER() OVER (ORDER BY value DESC) AS rank
  FROM cugraph_pagerank('citation_edges', 'src', 'dst'))
SELECT r.rank, p.title, p.year, r.value
FROM ranked r JOIN papers p ON p.paper_id = r.vertex
WHERE r.vertex = 2066636486;

rank	title	year	value
115	The anatomy of a large-scale hypertextual Web search engine	1998	0.000143

Rank #115 of 4,894,081 in this run.

SQL defines which graph the GPU sees

The first argument is any relation name, including a view. Joining the edge list to papers on both endpoints restricts the graph to citations within a chosen era, and PageRank then ranks the most important papers within that window — here, the pre-2000 literature.

CREATE VIEW edges_pre2000 AS
SELECT e.src, e.dst
FROM citation_edges e
JOIN papers ps ON ps.paper_id = e.src
JOIN papers pd ON pd.paper_id = e.dst
WHERE ps.year BETWEEN 1901 AND 2000 AND pd.year BETWEEN 1901 AND 2000;

SELECT p.year, p.title
FROM cugraph_pagerank('edges_pre2000', 'src', 'dst') r
JOIN papers p ON p.paper_id = r.vertex
ORDER BY r.value DESC
LIMIT 6;

year	title
1959	Finite automata and their decision problems
1959	The reduction of two-way automata to one-way automata
1949	The Mathematical Theory of Communication
1974	The Design and Analysis of Computer Algorithms
1958	Preliminary report: international algebraic language
1963	Machine perception of three-dimensional solids

Automata theory, information theory, the classic algorithms textbook, and the ALGOL report: the view's WHERE clause restricts the graph to one era, and the algorithm re-ranks the field within it.

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