Skip to main content

Discover & Validate GPU Functions

Use this guide before adding a cuGraph or cuVS function to a query. It follows the same sequence for embedded sessions and Flight SQL: list what this build can run, inspect one function's contract, validate the call statically (no data is read and nothing runs on the GPU), 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 Function Catalog API.

1. List installed functions​

Start with the functions 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')
ORDER BY function_name;

available=true means the function can be planned for GPU execution in this build and session; cuVS functions require the cuvs feature. It does not reserve GPU memory, inspect relation rows, or prove that a surrounding query runs entirely on the GPU. Memory is decided at execution: the call runs inside its granted cap and fails with an allocation error if it exceeds it.

2. Describe the selected function​

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');

Function names are exact canonical names. The returned descriptor is useful when a client or agent needs to construct SQL dynamically, while the provider function 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',
  '{
    "schema_version":1,
    "relations":{"edges":{"table":"analytics.edges"}},
    "options":{"src_col":"src","dst_col":"dst","weight_col":"weight"}
  }'
);

This is static validation: it checks the named tables' or views' schemas and the options, reads no data, and runs nothing on the GPU (no rows scanned, no subquery run, no device memory allocated, no kernel launched). Only registered tables or views resolve; register a derived relation as a temporary view when it needs validation.

4. Execute with the provider's relation syntax​

The catalog workflow is shared, but execution SQL intentionally differs:

  • cuGraph passes a registered edge table or view by its positional name, such as cugraph_pagerank('edges', 'src', 'dst').
  • cuVS passes each relation as a parenthesized SELECT subquery, such as cuvs_kmeans((SELECT item_id, d0, d1 FROM embeddings), '<options-json>').

Use the cuGraph Functions and cuVS Functions pages for each function's signature, input contract, outputs, and lifecycle.

5. Check whole-query GPU coverage​

gpu_validate_call covers one selected function 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.