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]]])

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_hits('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		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	Convergence tolerance on the summed change in hub scores between consecutive iterations. Smaller values tighten convergence and may need more iterations.
max_iterations	UInt32	100	min 1	Upper bound on HITS iterations.
normalize	Boolean	false		When true, the final hub and authority score arrays are each scaled to L1 norm 1.0 before being 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 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.

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