Skip to main content

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;
ColumnTypeMeaning
function_nameUtf8Canonical UDTF name.
providerUtf8cugraph, cuvs or cuml.
availableBooleanWhether the UDTF can be planned for GPU execution in this build and session.
unavailable_reasonUtf8Stable reason code, null when available. A UDTF whose build feature is off reports required_feature_disabled.
signatureUtf8Canonical SQL execution signature.
summaryUtf8One-line description.
relation_roles_jsonUtf8Ordered relation-role definitions.

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:

ColumnTypeMeaning
argument_descriptions_jsonUtf8Descriptions of the non-relation arguments.
options_schema_jsonUtf8JSON schema of the options object.
result_schemas_jsonUtf8Default and mode-dependent result schemas, with field semantics where available.
validation_request_schema_jsonUtf8JSON schema that gpu_validate_call accepts for this UDTF.
examples_jsonUtf8Quickstart, validation and execution examples.
limitations_jsonUtf8Known static and runtime limitations.

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.

ColumnTypeMeaning
validBooleanWhether the call is valid in this session.
error_codeUtf8Stable reason code of the first problem, null when valid.
messageUtf8valid, or every detected problem's message joined by ; .
function_nameUtf8Canonical name, or the unresolved requested name.
relations_resolvedBooleanWhether every required relation resolved.
normalized_call_jsonUtf8The envelope after defaults and canonicalization.
output_schema_jsonUtf8Concrete output schema when it can be derived.
would_execute_gpuBooleanWhether this call would target GPU execution after static planning.
details_jsonUtf8Per-relation and provider-specific validation facts.

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.