HITS

SQL function: cugraph_hits

Official cuGraph reference: C API

Compute mutually reinforcing hub and authority scores: strong hubs point to strong authorities, and strong authorities are linked from strong hubs.

Signature

cugraph_hits(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		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
epsilon	Float64	0.00001	> 0
max_iterations	UInt32	100	min 1
normalize	Boolean	false

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 HITS scores.
hub_score	Float64	no	HITS hub score for the vertex.
authority_score	Float64	no	HITS authority 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.

Hubs versus authorities

HITS returns two scores per vertex in one pass. In a citation graph they separate two kinds of importance that PageRank blends: a hub cites many authorities (typically a survey), and an authority is cited by many hubs (typically a foundational result). One call feeds two ORDER BY clauses:

SELECT p.year, p.n_references, p.title
FROM cugraph_hits('citation_edges', 'src', 'dst') h
JOIN papers p ON p.paper_id = h.vertex
ORDER BY h.hub_score DESC
LIMIT 4;

year	n_references	title
2019	292	Deep Learning for Generic Object Detection: A Survey
2018	276	Deep Learning for Generic Object Detection: A Survey.
2015	299	Recent Advances in Convolutional Neural Networks
2019	211	Object Detection With Deep Learning: A Review

SELECT p.year, p.n_citation, p.title
FROM cugraph_hits('citation_edges', 'src', 'dst') h
JOIN papers p ON p.paper_id = h.vertex
ORDER BY h.authority_score DESC
LIMIT 4;

year	n_citation	title
2004	35,541	Distinctive Image Features from Scale-Invariant Keypoints
2014	18,029	VERY DEEP CONVOLUTIONAL NETWORKS FOR LARGE-SCALE IMAGE RECOGNITION
2012	16,802	ImageNet Classification with Deep Convolutional Neural Networks
2005	19,433	Histograms of oriented gradients for human detection

The top hubs are titled "Survey" and "Review"; the top authorities are SIFT, VGG, AlexNet, and HOG. The mutually reinforcing definition places both lists in the field with the densest hub/authority structure — computer vision — without any field labels supplied as input.

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