GPU UDTF Catalog API
Three metadata UDTFs describe every cuGraph, cuVS and cuML UDTF installed in a session, so a client or an agent can find, understand and check a call without reading server source:
gpu_list_functions()lists the installed UDTFs and whether each one is executable in this build and session.gpu_describe_function(name)returns one UDTF's contract: signature, relation roles, option schema, result schemas, examples and limitations.gpu_validate_call(name, call_json)checks a concrete call against the schemas of named tables or views and the UDTF's options. It reads no data and runs nothing on the GPU.
Discover & Validate GPU UDTFs walks through the list, describe, validate and execute sequence. This page is the schema reference. Names are exact canonical UDTF names. Provider-local aliases are not accepted. Wrong metadata UDTF arity and nonliteral metadata arguments are planning errors.
gpu_list_functions
One row per installed UDTF, ordered by function_name, without the three
metadata UDTFs themselves. The catalog spans providers. Filter by provider
for the cugraph, cuvs or cuml subset.
SELECT function_name, provider, available, summary
FROM gpu_list_functions()
WHERE provider IN ('cugraph', 'cuvs', 'cuml')
ORDER BY function_name;
available=true covers the UDTF itself; the relational operators around it
are planned separately.
gpu_describe_function(function_name)
One full descriptor row for one UDTF. There is no compact mode. Project the columns you need.
SELECT signature, options_schema_json, result_schemas_json
FROM gpu_describe_function('cuvs_brute_force_knn');
The row carries the seven gpu_list_functions columns plus:
Every JSON column holds valid JSON. An empty object or array is {} or [],
never SQL NULL.
gpu_validate_call(function_name, call_json)
Static validation of one call. The envelope names registered tables or views by role; the selected UDTF owns the meaning of its roles and options.
SELECT *
FROM gpu_validate_call(
'cuvs_kmeans',
'{
"relations":{"input":{"table":"embedding_vectors"}},
"options":{"n_clusters":8}
}'
);
The envelope holds relations and options. relations is an object keyed by the
descriptor's relation roles, each with one table field holding a one-, two-
or three-part DataFusion table or view reference. options is an object the
UDTF validates. Unknown envelope keys, roles and option keys are rejected. The
envelope never carries SQL text: to validate a derived subquery, register it
as a temporary view first.
An unknown UDTF or an invalid call returns one row with valid=false. An
unavailable UDTF reports its unavailable_reason before anything else.
Otherwise the row lists, from one pass, every unresolved relation, every
option error and the relation schema errors that do not depend on a rejected
option. error_code and details_json describe the first. A check that depends on a rejected option,
such as a required option that failed its own check, runs once that option is
valid. details_json locates the first problem with path and, when present,
argument, relation_role and field.
A table function whose name starts with cugraph_, cuvs_, cuml_ or
gpu_ but names no installed function fails planning with object_not_found.
The message names the closest registered name when one is near enough and
points to gpu_list_functions(). A call to cugraph_page_rank fails with:
unknown GPU function cugraph_page_rank; closest registered name: cugraph_pagerank; gpu_list_functions() lists every installed function
Validation checks that the UDTF exists, resolves every required relation,
validates the relation bindings, columns, types, dimensions, conditional
arguments and option values, applies defaults, and derives the output schema
when it can. Source-vertex existence, vector uniformity and cardinality are
checked at execution, and an admitted call that exceeds its memory grant fails
there with an allocation error. would_execute_gpu covers this one call;
GPU coverage validation covers
the whole query.