GPU Function Catalog API

The unified GPU function catalog lets humans and agents discover every SQL-visible GPU function and dry-run a call without reading server source. It contains installed cuGraph and cuVS families; filter by provider for a provider-specific view.

For the task-oriented list, describe, validate, and execute workflow, use Discover & Validate GPU Functions. This page is the detailed API reference for the metadata functions and their response schemas.

Execution syntax remains provider-specific: cuGraph execution consumes a registered edge table/view name in its positional contract, while cuVS execution consumes parenthesized relation-valued subqueries. Metadata dry-run validation consistently uses registered named tables or views in its relation envelope and never evaluates arbitrary SQL from JSON.

gpu_list_functions

gpu_list_functions() takes no arguments and returns one row for each installed execution function. It does not list the three metadata functions themselves. Rows are ordered by function_name before ordinary SQL projection or filtering.

SELECT function_name, provider, available, summary
FROM gpu_list_functions()
WHERE provider IN ('cugraph', 'cuvs')
ORDER BY function_name;

Column	Arrow type	Nullable	Meaning
function_name	Utf8	no	Exact canonical execution-function name.
provider	Utf8	no	Implementation provider, such as cugraph or cuvs.
available	Boolean	no	Whether the function can be planned for GPU execution in this session and build.
unavailable_reason	Utf8	yes	Stable reason code when available=false.
signature	Utf8	no	Canonical SQL execution signature.
summary	Utf8	no	Short human-readable description.
relation_roles_json	Utf8	no	Ordered relation-role definitions as valid JSON.

available=true means the selected function is statically plannable. It does not reserve GPU memory, acquire runtime admission, inspect relation rows, or prove that an entire query is GPU-native. In particular, cuVS reports bounded_execution_unavailable for a bounded session until it has a lower-level peak-memory preflight contract.

gpu_describe_function(function_name)

gpu_describe_function takes one exact canonical execution-function name and returns one full descriptor row. It has no compact or verbose mode: project the columns you need. Provider-local short aliases are not accepted.

SELECT signature, options_schema_json, result_schemas_json
FROM gpu_describe_function('cuvs_brute_force_knn');

Column	Arrow type	Nullable	Meaning
function_name	Utf8	no	Exact canonical execution-function name.
provider	Utf8	no	Implementation provider.
available	Boolean	no	Current session/build planning availability.
unavailable_reason	Utf8	yes	Stable reason code when unavailable.
signature	Utf8	no	Canonical SQL execution signature.
summary	Utf8	no	Short human-readable description.
relation_roles_json	Utf8	no	Ordered relation-role definitions as valid JSON.
argument_descriptions_json	Utf8	no	Structured descriptions of non-relation arguments as valid JSON.
options_schema_json	Utf8	no	JSON schema for the execution function's options object.
result_schemas_json	Utf8	no	Generic/default and mode-dependent result schemas, including field semantics when available.
validation_request_schema_json	Utf8	no	JSON schema accepted by gpu_validate_call for this function.
examples_json	Utf8	no	Structured Quickstart, validation, and provider execution metadata.
limitations_json	Utf8	no	Known static and runtime limitations.

Every JSON column contains valid JSON. Empty objects and arrays are represented as {} and [], not SQL NULL.

gpu_validate_call(function_name, call_json)

gpu_validate_call takes an exact canonical execution-function name and a common versioned JSON envelope. The selected provider owns the meaning of relation roles and options, while the envelope consistently names function inputs.

SELECT *
FROM gpu_validate_call(
  'cuvs_kmeans',
  '{
    "schema_version":1,
    "relations":{"input":{"table":"embedding_vectors"}},
    "options":{"input":{"id":"item_id","vector":{"columns":["d0","d1"]}},"n_clusters":8}
  }'
);

Version 1 requires exactly these envelope fields:

• schema_version: integer 1.
• relations: object keyed by the descriptor-defined relation roles. Each relation currently has exactly one table field with a one-, two-, or three-part DataFusion table or view reference.
• options: object validated by the selected function.

Unknown envelope keys, relation roles, and option keys are rejected. The metadata path resolves named tables and views only; it does not accept arbitrary SQL in JSON. To dry-run a derived subquery, register it as a temporary view first.

Column	Arrow type	Nullable	Meaning
valid	Boolean	no	Whether the full static call is valid in this session.
error_code	Utf8	yes	Stable structured reason when invalid.
message	Utf8	no	Human-readable validation result.
function_name	Utf8	no	Canonical name, or the unresolved requested name.
relations_resolved	Boolean	no	Whether every required relation resolved.
normalized_call_json	Utf8	no	Versioned envelope after defaults and canonicalization.
output_schema_json	Utf8	no	Concrete output schema when it can be derived.
would_execute_gpu	Boolean	no	Whether this function call would target GPU execution after static planning.
details_json	Utf8	no	Structured per-relation and provider-specific validation facts.

A syntactically valid request for an unknown function or invalid execution call returns one structured invalid row. Wrong metadata-function arity and nonliteral metadata arguments are planning errors.

What validation does & does not do

Does: check that the function exists; resolve every required named relation; validate provider-owned relation bindings, columns, dtypes, dimensions, conditional arguments, and option values; apply defaults; and derive a concrete output schema when possible.

Does Not: scan relation rows, materialize Parquet, construct graphs, launch CUDA, allocate device memory, acquire query admission, or prove runtime facts such as source-vertex existence, vector uniformity, or evaluated relation cardinality.

would_execute_gpu is scoped to one selected function call. To check whether a whole query's planned path stays on the GPU, use GPU coverage validation.