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