Cosine

SQL function: cugraph_cosine

Official cuGraph reference: Python API

Compare the neighbor vectors of explicit vertex pairs using cosine similarity, with optional edge-weight contributions.

Signature

cugraph_cosine(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, plus the registered relation candidate_pairs (the vertex_pairs side input with columns first, second). Substitute your own registered relations.

SELECT * FROM cugraph_cosine('target_edges', 'src', 'dst', NULL, '{"vertex_pairs_table":"candidate_pairs","first_vertex_col":"first","second_vertex_col":"second"}');

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
• candidate-pair columns must match the graph vertex domain; logical string graphs accept Utf8, LargeUtf8, or Utf8View independently per column

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
first_vertex_col	Utf8		required; column of vertex_pairs_table; type ref vertex_pairs_domain	First endpoint column in vertex_pairs_table.
second_vertex_col	Utf8		required; column of vertex_pairs_table; type ref vertex_pairs_domain	Second endpoint column in vertex_pairs_table.
vertex_pairs_table	Utf8		required; side input (vertex_pairs, cols: first_vertex_col, second_vertex_col)	Table or view containing the explicit candidate vertex pairs.

Graph construction options

This function requires directed=false (undirected/symmetric graph); all other graph construction options follow the shared defaults documented in Graph Construction Options.

Output

Column	Type	Nullable	Description
first	Int64|Utf8	no	First vertex from the explicit candidate-pair relation.
second	Int64|Utf8	no	Second vertex from the explicit candidate-pair relation.
similarity	Float64	no	Similarity coefficient for the explicit candidate pair.

These are generic descriptor schemas; validate the call to get the concrete, table-specific output schema.

Examples

Canonical call shape using target_edges as the edge table:

SELECT * FROM cugraph_cosine('target_edges', 'src', 'dst', NULL, '{"vertex_pairs_table":"candidate_pairs","first_vertex_col":"first","second_vertex_col":"second"}')

Use the same shape with your registered edge table or view; configure algorithm and graph options through options_json as described above.

Limits

• similarity is explicit-pair only; all-pairs candidate generation and all-pairs top-k search are not exposed
• options_json must name vertex_pairs_table, first_vertex_col, and second_vertex_col
• candidate-pair columns must match the graph vertex domain; logical string graphs accept Utf8, LargeUtf8, or Utf8View independently per column
• null candidate-pair values are rejected at execution and are never dropped
• candidate pairs are a multiset: duplicate, reversed, and self pairs remain distinct output rows
• result rows have no global ordering; use ORDER BY when order is required
• providing weight_col selects weighted similarity; omitting it selects unit-weight similarity
• cuGraph requires directed=false so the graph is constructed as an undirected/symmetric view

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_cosine',
  '{"schema_version":1,"relations":{"edges":{"table":"target_edges"}},"options":{"src_col":"src","dst_col":"dst","vertex_pairs_table":"candidate_pairs","first_vertex_col":"first","second_vertex_col":"second"}}'
);

See GPU Function Catalog API for the full gpu_validate_call contract.