Jaccard
SQL function: cugraph_jaccard
Official cuGraph reference: C API
Compare explicit vertex pairs by dividing the size of their shared-neighbor intersection by the size of their neighbor union.
Signature
cugraph_jaccard(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
- candidate-pair columns must match the graph vertex domain; logical string graphs accept Utf8, LargeUtf8, or Utf8View independently per column
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 | 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 schema
| 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_jaccard('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.
Limitations & lifecycle
- 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 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_jaccard',
'{"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.