Skip to main content

Discover & Validate GPU UDTFs

Use this guide before adding a cuGraph, cuVS, or cuML UDTF to a query. It follows the same sequence for embedded sessions and Flight SQL: list what this build can run, inspect one UDTF's contract, validate the call statically, execute it, then check the complete query before production use.

This page shows the workflow only. For every returned column, JSON schema, and validation-envelope rule, see the GPU UDTF Catalog API.

1. List installed UDTFs​

Start with the UDTFs available in the current build and session. Filter by provider when you already know the workload:

SELECT function_name, provider, available, summary
FROM gpu_list_functions()
WHERE provider IN ('cugraph', 'cuvs', 'cuml')
ORDER BY function_name;
Example response
function_nameprovideravailablesummary
cugraph_betweenness_centralitycugraphtrueMeasure how often each vertex lies on shortest paths between other vertex pairs, exactly or from an explicit sample of source vertices.
cugraph_bfscugraphtrueVisit reachable vertices in increasing unweighted hop distance from one or more sources, returning distances and optional predecessors.
cugraph_core_numbercugraphtrueAssign each vertex the largest k for which it belongs to a k-core, where every vertex has degree at least k within that subgraph.
cugraph_cosinecugraphtrueCompare the neighbor vectors of explicit vertex pairs using cosine similarity, with optional edge-weight contributions.
cugraph_degrees_allcugraphtrueCount both incoming and outgoing edges for every vertex in the graph.
cugraph_ecgcugraphtrueStabilize community assignments by combining an ensemble of randomized Louvain partitions into a final consensus clustering.
cugraph_edge_betweenness_centralitycugraphtrueMeasure how often each edge lies on shortest paths between vertex pairs, exactly or from an explicit sample of source vertices.
cugraph_eigenvector_centralitycugraphtrueScore vertices by connections to other high-scoring vertices, using power iteration to find the dominant eigenvector.
cugraph_force_atlas2cugraphtruePlace vertices in two dimensions with a force-directed simulation that attracts connected vertices and repels vertices from one another.
cugraph_hitscugraphtrueCompute mutually reinforcing hub and authority scores: strong hubs point to strong authorities, and strong authorities are linked from strong hubs.
cugraph_in_degrees_allcugraphtrueCount incoming edges for every vertex in the graph.
cugraph_jaccardcugraphtrueCompare explicit vertex pairs by dividing the size of their shared-neighbor intersection by the size of their neighbor union.
cugraph_k_corecugraphtrueReturn the edges of the maximal subgraph whose vertices each have degree at least k within that subgraph.
cugraph_katz_centralitycugraphtrueScore vertices from the number of walks that reach them, attenuating longer walks and adding a baseline contribution.
cugraph_leidencugraphtrueFind modularity-based communities with a refinement step, and split each community into the connected components of its internal edges, so every returned community induces a connected subgraph.
cugraph_louvaincugraphtrueBuild a hierarchy of communities by greedily moving vertices and aggregating partitions to maximize modularity.
cugraph_minimum_spanning_treecugraphtrueSelect a minimum-total-weight acyclic edge set, producing a spanning tree for a connected graph or a spanning forest otherwise.
cugraph_out_degrees_allcugraphtrueCount outgoing edges for every vertex in the graph.
cugraph_overlapcugraphtrueCompare explicit vertex pairs by dividing their shared-neighbor count by the smaller of their two neighbor counts.
cugraph_pagerankcugraphtrueRank vertices by the stationary probability of a damped random walk that follows outgoing edges.
cugraph_personalized_pagerankcugraphtrueRank vertices with PageRank while biasing random-walk restarts toward explicitly weighted personalization vertices.
cugraph_sorensencugraphtrueCompare explicit vertex pairs as twice their shared-neighbor count divided by the sum of their neighbor counts.
cugraph_spectral_modularity_maximizationcugraphtruePartition vertices by running k-means on an embedding of the normalized graph Laplacian eigenvectors with the smallest eigenvalues. Modularity is not optimized directly.
cugraph_ssspcugraphtrueCompute minimum path distances and predecessors from one source vertex, using edges.weight or unit cost 1 when that field is omitted.
cugraph_strongly_connected_componentscugraphtrueLabel maximal directed subgraphs in which every vertex is reachable from every other vertex.
cugraph_triangle_count_allcugraphtrueCount the number of three-vertex cycles incident to every vertex in the graph.
cugraph_weakly_connected_componentscugraphtrueLabel maximal connected subgraphs after treating directed edges as undirected.
cuml_forest_predictcumlfalseScore Float32 rows with a pretrained XGBoost, LightGBM, or Treelite forest through nvForest.
cuml_hdbscancumltruecuML HDBSCAN fits density-based clusters and returns query-local labels and membership probabilities.
cuml_logistic_regressioncumltrueFit a query-local cuML logistic or softmax classifier and score independent rows.
cuml_random_forest_classifiercumltrueFit a query-local cuML random forest classifier and score independent rows.
cuml_random_forest_regressorcumltrueFit a query-local cuML random forest regressor and score independent rows.
cuml_tsvdcumltruecuML truncated SVD fits and transforms dense feature rows.
cuml_umapcumltruecuML UMAP fits a deterministic, query-local manifold embedding for dense feature rows.
cuvs_brute_force_knncuvstrueExact brute-force nearest-neighbor search over dense vectors.
cuvs_cagracuvstrueQuery-local graph approximate nearest-neighbor search.
cuvs_ivf_flatcuvstrueQuery-local inverted-file approximate nearest-neighbor search.
cuvs_ivf_pqcuvstrueQuery-local product-quantized inverted-file nearest-neighbor search.
cuvs_kmeanscuvstrueK-means clustering assignments for dense vector rows.
cuvs_pairwise_distancecuvstruePairwise distance or similarity for every x and y vector row.
cuvs_pcacuvstruePrincipal-component analysis transform for dense vector rows.
cuvs_top_kcuvstrueSelect the smallest or largest values in every dense vector row.

available=true means the UDTF can be planned for GPU execution in this build and session. It does not prove that a surrounding query runs entirely on the GPU. Step 5 covers that. cuVS UDTFs require the cuvs feature, and cuml_forest_predict requires a models root.

2. Describe the selected UDTF​

Retrieve the canonical signature, relation roles, option schema, output schema, and lifecycle limits before constructing a call:

SELECT signature, relation_roles_json, options_schema_json, result_schemas_json, limitations_json
FROM gpu_describe_function('cugraph_pagerank');
Example response
{
"signature": "cugraph_pagerank(edges => (relation subquery), directed => value, renumber => value, construction_policy => value, alpha => value, epsilon => value, max_iterations => value)",
"relation_roles_json": [
{
"name": "edges",
"required": true,
"description": "edge relation with canonical src and dst columns, plus optional weight and edge_id columns",
"fields": [
{
"name": "src",
"required": true,
"type": "vertex_id",
"data_types": [
"Int32",
"Int64",
"Utf8",
"LargeUtf8",
"Utf8View"
],
"description": "source vertex identifier"
},
{
"name": "dst",
"required": true,
"type": "vertex_id",
"data_types": [
"Int32",
"Int64",
"Utf8",
"LargeUtf8",
"Utf8View"
],
"description": "destination vertex identifier"
},
{
"name": "weight",
"required": false,
"type": "numeric",
"data_types": [
"Float32",
"Float64"
],
"description": "optional edge weight"
},
{
"name": "edge_id",
"required": false,
"type": "integer_edge_id",
"data_types": [
"Int32",
"Int64"
],
"description": "optional edge identifier"
}
],
"vertex_id_contract": {
"numeric_endpoint_types": [
"Int32",
"Int64"
],
"mapped_numeric_endpoint_types": [],
"logical_string_endpoint_types": [
"Utf8",
"LargeUtf8",
"Utf8View"
],
"logical_string_output_type": "Utf8",
"native_logical_mapping_type": "Int64",
"edge_id_supported_for_logical_string": false,
"call_specific_authority": "gpu_validate_call"
}
}
],
"options_schema_json": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "cugraph_pagerank value arguments",
"description": "Named cuGraph value arguments. Relation fields are derived from resolved relation schemas.",
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"directed": {
"type": "boolean",
"default": true,
"description": "whether the edge relation is directed; some algorithms require false or true"
},
"renumber": {
"type": "boolean",
"default": true,
"description": "whether to renumber vertex identifiers during graph construction"
},
"construction_policy": {
"type": "string",
"enum": [
"python_cugraph",
"raw_libcugraph"
],
"default": "python_cugraph",
"description": "graph construction policy"
},
"alpha": {
"type": "number",
"minimum": 0,
"maximum": 1,
"default": 0.85,
"description": "PageRank damping factor in [0, 1]"
},
"epsilon": {
"type": "number",
"minimum": 0,
"default": 0.00001,
"description": "convergence tolerance; 0 runs all max_iterations iterations"
},
"max_iterations": {
"type": "integer",
"minimum": 1,
"maximum": 4294967295,
"default": 100,
"description": "maximum iteration count, at least 1"
}
}
},
"result_schemas_json": {
"default_schema": "default",
"schemas": {
"default": {
"fields": [
{
"name": "vertex",
"data_type": "Int64|Utf8",
"nullable": false
},
{
"name": "value",
"data_type": "Float64",
"nullable": false
}
]
}
},
"call_specific_authority": "gpu_validate_call",
"note": "Generic registry schemas; run gpu_validate_call for the concrete table-specific output schema.",
"field_descriptions": [
{
"name": "vertex",
"description": "Vertex receiving the PageRank score."
},
{
"name": "value",
"description": "PageRank score for the vertex."
}
]
},
"limitations_json": [
"dry-run validates table resolution, column presence, static dtypes, and options only",
"dry-run does not scan edge data, construct a graph, or prove source-vertex existence",
"calls without an edge weight column repeat between runs; with one, scores can differ in the last digits because out-weight sums accumulate with floating-point atomics"
]
}

UDTF names are exact canonical names. The returned descriptor is useful when a client or agent needs to construct SQL dynamically, while the provider UDTF pages explain the same contract in task-specific terms.

3. Validate a concrete call​

Validate registered relation metadata and the provider-owned options before execution:

SELECT *
FROM gpu_validate_call(
'cugraph_pagerank',
'{
"relations":{"edges":{"table":"analytics.edges"}},
"options":{"alpha":0.9,"directed":true}
}'
);
Example response · valid call
{
"valid": true,
"error_code": null,
"message": "valid",
"function_name": "cugraph_pagerank",
"relations_resolved": true,
"normalized_call_json": {
"relations": {
"edges": {
"table": "analytics.edges"
}
},
"options": {
"directed": true,
"renumber": true,
"construction_policy": "python_cugraph",
"alpha": 0.9,
"epsilon": 0.00001,
"max_iterations": 100
}
},
"output_schema_json": {
"fields": [
{
"name": "vertex",
"data_type": "Int64",
"nullable": false
},
{
"name": "value",
"data_type": "Float64",
"nullable": false
}
]
},
"would_execute_gpu": true,
"details_json": {
"edges": {
"table": "analytics.edges",
"resolved": true,
"schema": {
"fields": [
{
"name": "src",
"data_type": "Int64",
"nullable": true
},
{
"name": "dst",
"data_type": "Int64",
"nullable": true
}
]
},
"src_dtype": "Int64",
"dst_dtype": "Int64"
}
}
}

This is static validation: it checks the named tables' or views' schemas and the options, reads no data, and runs nothing on the GPU. Only registered tables or views resolve, and each one must already expose the role's canonical columns (src/dst for cuGraph edges, id plus feature columns for cuVS relations). A call whose relation aliases, filters, joins, or reads a CTE is not represented by this envelope. Run EXPLAIN GPU on the final SQL instead, or register that derived relation as a view and validate the view.

A rejected call also returns one row:

SELECT *
FROM gpu_validate_call(
'cugraph_pagerank',
'{
"relations":{"edges":{"table":"analytics.follows"}},
"options":{"alpha":0.9,"max_iter":50,"tol":0.0001}
}'
);
Example response · rejected call
{
"valid": false,
"error_code": "unknown_option",
"message": "unknown option 'max_iter' for cugraph_pagerank. Did you mean 'max_iterations'? Valid options: directed, renumber, construction_policy, alpha, epsilon, max_iterations.; unknown option 'tol' for cugraph_pagerank. Valid options: directed, renumber, construction_policy, alpha, epsilon, max_iterations.; cuGraph edge child is missing canonical source column 'src'",
"function_name": "cugraph_pagerank",
"relations_resolved": true,
"normalized_call_json": {
"relations": {
"edges": {
"table": "analytics.follows"
}
},
"options": {
"alpha": 0.9,
"max_iter": 50,
"tol": 0.0001
}
},
"output_schema_json": {},
"would_execute_gpu": false,
"details_json": {
"edges": {
"table": "analytics.follows",
"resolved": true,
"schema": {
"fields": [
{
"name": "follower_id",
"data_type": "Int64",
"nullable": true
},
{
"name": "followee_id",
"data_type": "Int64",
"nullable": true
}
]
}
},
"path": "options.max_iter",
"argument": "max_iter"
}
}

message lists every problem found in one pass. error_code and details_json locate the first.

4. Execute with the provider's relation syntax​

While the discovery and validation interfaces are identical across providers, execution syntax reflects each library's relation roles:

  • cuGraph passes graph topologies via named relation subqueries (e.g., edges => (SELECT src, dst FROM edges)).
  • cuVS and cuML pass vector and training relations as named subqueries alongside scalar options (e.g., input => (SELECT ...), k => 10).

Use the cuGraph UDTFs, cuVS UDTFs, and cuML UDTFs pages for each UDTF's signature, input contract, outputs, and lifecycle.

5. Check whole-query GPU coverage​

gpu_validate_call covers one selected UDTF call. It does not inspect DataFusion operators, sources, or host boundaries feeding and consuming that call. Before shipping a composed query, use GPU coverage validation to check the final planned path.

6. The sequence on a recorded session​

A session over the MerRec dataset followed this sequence through Flight SQL to investigate which brands moved toward Barbie's audience after the July 2023 film.

StepPurposeOutcomeElapsed
1Which graph functions can rank brands around a seed?rows4 ms
2What does personalized PageRank take, and what does it return?rows3 ms
3Which vertex is Barbie? Look up the brand id to seed fromrows496 ms
4Before spending GPU time: will the whole query run on the GPU?rows102 ms
5Run it: which brands moved toward Barbie's audience after the July release?rows2,081 ms

Each step ran once, in a replay over Arrow Flight SQL against a freshly started release server in native_required mode, with the MerRec Parquet files in the page cache.

Step 2 read the descriptor with result_schemas_json, and the call in step 5 named its personalization and output columns correctly on the first attempt. The edge relation joins two tables under a date filter, which gpu_validate_call does not cover (section 3), and step 4 checked the composed query with EXPLAIN GPU instead. It reported the whole query on the GPU with no host boundary. The query itself ran four graph calls over 1.27 billion events; the result and its control seeds are on the MerRec page.

Two calls sent after the session show what the planner returns when a column name is wrong. One kept the source table's column names in the personalization relation, and one selected an output column the function does not produce. Each was rejected before any row was read:

cuGraph side-input child is missing canonical column 'vertex'
No field named score. Valid fields are vertex, value.