Skip to main content

GPU table functions

A GPU UDTF returns a relation that can feed another SQL operator. Algeon binds its input subqueries into the DataFusion plan, executes the algorithm through the native engine and exposes its output columns to downstream consumers. The transfer contract specifies who owns the device buffers and when GPU work may read or release them.

An algorithm inside a query​

Assume registered relations citations(src, dst, citation_year) and papers(paper_id, field), with matching integer vertex IDs. This example filters the graph's edges before PageRank, filters the scores afterward, then joins paper metadata and aggregates by field:

WITH ranked AS (
SELECT vertex, value
FROM cugraph_pagerank(
edges => (
SELECT src, dst
FROM citations
WHERE citation_year >= 2020
),
alpha => 0.85
)
)
SELECT p.field, COUNT(*) AS paper_count, AVG(r.value) AS mean_pagerank
FROM ranked r
JOIN papers p ON p.paper_id = r.vertex
WHERE r.value > 0.0001
GROUP BY p.field;

The edge predicate changes the graph on which PageRank runs. The score predicate applies to its output. The same predicate placed before the algorithm would change the query's meaning. See the PageRank reference for a captured dataset example and the full argument contract.

Each SQL family registers a DataFusion RelationPlanner. Named relation arguments become logical plan children, including separate roles such as cuVS dataset and queries, or cuML training and predict. Extension planning creates the GPU execution nodes. Native lowering represents the operation as GraphAlgorithm, VectorAlgorithm or MlAlgorithm, with explicit inputs and a result schema. The compiled schedule contains the corresponding algorithm task.

The illustration below follows an uncached call with supported surrounding SQL selected for native execution. Separate native fragments can exchange GPU-resident results within the attempt. Each fragment has its own compiled schedule.

PageRank inside a SQL queryGPU UDTF execution flow for PageRank within a SQL query. The relational pipeline on the left filters edge columns in cuDF. A zero-copy read lease passes edge buffers to cuGraph for graph construction and PageRank. The result is copied in device memory into independently owned cuDF columns for downstream filtering, joining, and aggregation, while native graph memory is settled and freed.GPU VRAM · one admitted attempt · shared memory capRelational pipeline · cuDFAlgorithm runtime · cuGraph UDTFzero-copy read leasedevice memory copycopy complete1. Edge subquery (citations)WHERE citation_year >= 2020cuDF owns src, dst columnsPreparedTableExportBorrows the edge buffers.2. Graph constructionValidate column types and active rangesBuild CSR representation in VRAM3. PageRank kernelIterative power iteration on GPUOwns native vertex and score arrays4. UDTF result (ranked)to_dataframe → owned cuDF columnsvertex, value · SQL schema normalization5. Downstream SQLFilter: value > 0.0001Join: papers ON paper_id = vertexAggregate: GROUP BY fieldSettle and freeFree PageRank arrays; release read leaseReturn VRAM to query poolCapacity available for the hash join
Relational SQL operators (left) and the graph algorithm (right) share VRAM under one admission grant. Edge inputs are borrowed via a zero-copy read lease; algorithm results are copied into owned cuDF columns so native graph memory can be freed for downstream relational operators.

Execution mode determines the host boundaries. In functions_only, ordinary input subqueries and surrounding SQL execute on DataFusion CPU. Their Arrow batches require upload, and a CPU consumer requires host result materialization. A supported native consumer can continue from GPU columns without that intermediate round trip over PCIe.

From cuDF columns to a cuGraph result​

The cuDF frame retains ownership of its edge columns. Calling try_prepare_device_table_export() creates a PreparedTableExport containing the column layout, buffer ranges and device placement, together with producer readiness. The export also retains a shared owner of the frame. The preparation does not copy the edge values or transfer their allocation to cuGraph.

The cuGraph resource handle binds to the execution runtime's device, CUDA stream and memory resource. Before graph construction, a read lease orders consumer access after the producer's work. The import checks the selected column types, active ranges and null contract. Graph construction then creates its own representation, including renumbering when requested. The python_cugraph construction path can first copy edge columns into owned cuDF storage for normalization. These steps can allocate and copy within VRAM. Their precise semantics are covered by Graph Inputs and Construction.

For PageRank, the native result object owns its vertex and score arrays. to_dataframe(runtime) copies those arrays into independently owned cuDF columns on the same GPU. The result can then outlive the cuGraph result object. Result-schema normalization supplies the SQL-facing vertex and value columns, and the native consumer can apply its filter, join or aggregate to the resulting GpuDataFrame.

The PageRank result copy consumes device-memory bandwidth and temporarily requires both allocations. Because this boundary stays in VRAM, no host materialization occurs, but the graph preparation and result conversion still have measurable costs.

Ownership lasts through GPU completion​

Rust lifetimes protect the borrowed view during submission. CUDA operations can finish after a Rust call returns, so the interop contract also carries completion evidence. algeon-interop owns this contract. The cuDF adapters provide its CUDA implementation and expose the types through cudf::interop::contract.

StateStorage owner and ordering
Prepared exportThe producer still owns the allocation. The description records its layout and readiness, and can retain a shared producer owner.
Active read leaseThe consumer stream is ordered after producer readiness, using a CUDA event when needed. The lease bounds access to the export.
Read submittedcomplete() records completion after the consumer's reads. A pending LeaseCompletion retains its witness and producer owner until those reads finish.
Owner releaseExplicit synchronization or destruction settles the pending completion before releasing its retained owner. The allocation remains live while other owners still use it.

complete() can return while the GPU is still reading. A cuGraph graph can retain the pending input completion, allowing construction to return without an immediate host wait on that lease. Graph parking settles these input completions before the graph enters a reusable cache. An export without a retained owner requires synchronization before lease completion returns.

The cleanup paths cover early returns as well. A dropped incomplete read lease invokes the backend completion fallback; a dropped pending LeaseCompletion waits on its witness. If that wait fails, the retained owner is deliberately leaked because queued reads may still reference it. Attempt cleanup and device capacity reuse follow the completion and release contract.

Active cuGraph, cuVS and cuML resources are bound to their runtime context. Their Rust wrappers restrict transfer between threads. The engine creates them inside the attempt's execution job on an algeon-gpu-{d} worker, and a !Send handle cannot leave that job. ParkedGraph (Send + !Sync) is the form that moves between attempts. A graph prepared for cache transfer uses ParkedGraph with a completion event. When an attempt resumes it on its stream, that event establishes the dependency before algorithm execution.

cuVS and cuML layouts and result ownership​

Columnar SQL input and an algorithm's matrix layout can differ. The supported element types, null checks and shape checks are part of the library boundary. For list vectors, Algeon validates the active offsets and common vector dimension before exposing a tensor view.

BoundarycuGraphcuVScuML
Algorithm inputEdge columns become a constructed graph. Normalization and renumbering can create additional storage.Separate feature columns are packed into a dense matrix. Supported, validated list children can be borrowed as tensors when the runtime binding matches. Other paths copy or pack.SQL execution packs feature relations into the matrix layout required by the operation, such as column-major TSVD or row-major prediction input.
Result to cuDFPageRank copies cuGraph-owned result arrays into cuDF columns on the device.Runtime-owned output buffers can be consumed as cuDF columns without copying that allocation. Relational assembly can still gather IDs, sort or create other columns.Validated runtime-owned output buffers can become cuDF columns. Matrix unpacking and output ID assembly can require further device work.
Algorithm stateAn eligible constructed graph can use the server's accounted graph cache.SQL indexes and fitted transforms are local to one query execution. There is no persistent SQL vector-index cache.Fitting UDTFs release their model after the call. Forest inference binds an imported model. SQL does not expose a reusable fitted-model cache.

kNN output assembly maps neighbor ordinals back to relation IDs and orders the returned neighbors on the GPU. A cuML prediction retains its model and feature matrix through the native read lifetime, even though the output becomes a separate relation.

The input contracts are documented in Vector Inputs and ML Inputs. The API references describe cuVS index lifetimes and cuML model lifetimes.

Resident results and the query memory cap​

For an uncached UDTF, graph workspaces, packed matrices and algorithm outputs allocate through the query domain under the attempt's immutable grant, alongside relational intermediate buffers. cuML pool streams also allocate within that domain and share the query memory limit.

Reusable cached graphs have separate device-ledger charges. On a cache hit, the attempt stream synchronizes with the parked graph, while algorithm workspaces and outputs allocate under the borrowing attempt. Graph insertion copies edges into the cache allocation scope, constructs the graph, and copies the algorithm result into the attempt domain. The Memory and query lifetime page governs device buffer leases, column-level identity tracking and ledger charges.

Shared relational subplans across GPU function inputs and query roots (including inlined CTEs) follow Shared resident subplans. Edge inputs that filter one DISTINCT CTE by period, and a root aggregate over all of that CTE, read one producer when the root's copy scans the row groups both periods select; each reader filters the producer's output by its own period. Separate graph invocations that read an identical edge relation build separate graph instances.

One evaluation for each call site​

The relation planner gives each SQL call of a GPU function an invocation identity. DataFusion copies a CTE or view at every reference, and each copy keeps that identity, while two calls with identical text receive different ones. Within one query execution, the references of one call read a single evaluation. A function in the reproducibility table then returns one relation to every reader, apart from the separate evaluations listed below.

Inside a composed island, the first occurrence to run computes the GPU-resident result. Later occurrences read that result and skip their own input subplans. The handle stays under the attempt's grant until the final reader completes. A result option pushed into one occurrence, such as a LIMIT absorbed by a cuGraph producer, changes the relation that occurrence computes and gives it a separate evaluation.

References that cross into DataFusion operators as host Arrow share one evaluation as well. The first reference that DataFusion polls runs the function, and every reference replays the retained batches; the attempt manifest records one host occurrence for them. The batches stay in host memory until the last reference finishes and count against the DataFusion memory pool when host output accounting is enabled.

A composed island and the host boundaries keep separate results. When one reference is read inside an island and another crosses into DataFusion, or two islands each read a reference, the call runs once in each of them. Separate queries, including repeated executions of one prepared statement, evaluate it again.

Reproducibility​

Two runs of the same query on the same data, options and GPU return the same relation for some GPU functions and different relations for others. Several cuGraph, cuVS and cuML kernels add floating-point values with atomic operations, or let the first thread to arrive decide a tie. The order of those operations changes between runs, and Algeon adds no ordering to them. A seed option fixes the random draws of an algorithm and leaves the accumulation order of atomic operations unconstrained.

FunctionSeed optionBetween runs
cugraph_force_atlas2seed: initial positionsCoordinates differ in every run, because force accumulation uses atomics.
cugraph_spectral_modularity_maximizationseed: Lanczos start vector and k-means initializationThe partition can differ with the same seed, because k-means centroid sums use atomics.
cugraph_ecgseed: initial community labels of each Louvain passIdentical communities are not guaranteed.
cugraph_leidenseed: random choices in the refinement stepIdentical communities are not guaranteed; community identifiers are arbitrary integers.
cugraph_bfsnoneDistances repeat. The predecessor of a vertex with several shortest-path parents can differ.
cugraph_ssspnoneDistances and predecessors repeat. Which of several equal-cost parents becomes the predecessor is unspecified.
cugraph_hitsnoneScores differ in the last digits, because the hub update uses atomics.
cugraph_pagerank, cugraph_personalized_pageranknoneIdentical without an edge weight column. With edge weights, scores differ in the least significant digits due to floating-point atomic additions.
cuvs_kmeansnone (the native seed is fixed at 0)Cluster sizes differ slightly, because centroid sums use atomics.
cuvs_cagra, cuvs_ivf_flat, cuvs_ivf_pqnoneNeighbors and distances differ slightly, because index construction uses atomics.
cuvs_brute_force_knnnoneDistances repeat. Neighbors tied at the k-th distance can differ.
cuvs_top_knoneThe positions chosen among values tied across rank k are unspecified.
cuml_logistic_regressionnoneCoefficients and scores differ slightly, because the loss reduction uses atomics.
cuml_random_forest_classifierseed: bootstrap rows and feature subsetsThe same seed, input row order and GPU grow the same forest.
cuml_random_forest_regressorseed: bootstrap rows and feature subsetsNot guaranteed to be bit-identical, because regression histograms use floating-point atomics.
cuml_umaprandom_state: spectral initialization, edge shuffle and negative samplingRuns in cuML's deterministic mode and is expected to repeat.
cuml_forest_predictnoneIdentical for the same model file, input row order and GPU. Inference draws no random numbers.

Connected-component labels (the minimum vertex ID of each component), degrees, triangle counts and core numbers involve no floating-point accumulation and repeat. The similarity functions cugraph_jaccard, cugraph_sorensen, cugraph_overlap and cugraph_cosine contain no atomic accumulation. None of the remaining functions has a seed option (the seeds argument of the betweenness functions lists source vertices and draws no random numbers).

Floating-point results from atomic reductions require tolerance comparisons rather than bitwise equality. Community and cluster identifiers are arbitrary integers; validation checks partition membership rather than label values.

The table compares separate executions. Within one query, the references of one CTE or view read one evaluation and agree with each other, except where that section lists separate evaluations. Two calls written separately with the same arguments are two evaluations and can disagree. To preserve non-deterministic results across queries, materialize the relation using CREATE TABLE ... AS (Reuse algorithm results).

A seed fixes random draws over one row order. Without a top-level ORDER BY, the row order of an input subquery can change between runs, thereby shifting seeded results as well. See Input order and Relation identity.

Observe the boundaries​

Use the plan and runtime artifacts to distinguish native composition from host boundaries.

Graph runtime rows include gpu_resident_input_handoffs, host_to_device_uploads and device_to_host_materializations. These counters describe input and output boundaries; a resident handoff does not prove the absence of device copies during normalization or result conversion. PageRank's algorithm_metadata records iteration count and convergence information.

cuVS operator stages separate vector_pack, vector_native and vector_assemble; cuML uses ml_pack, ml_native and ml_assemble. Stage identity includes the algorithm, relation role where applicable, and runtime binding. The pack stage also records matrix layout and dimension. A pack stage can cover validation and a borrowed tensor view, so its output bytes alone do not establish the number of bytes copied.

Elapsed counters measure host scopes around execution and library calls. CUDA work can complete after its submitting scope returns, and a task that consumes streamed input can include upstream execution in its elapsed time. Stage counters and graph runtime rows therefore do not establish exclusive kernel durations. Use the statement's elapsed time for end-to-end comparisons and a GPU profiler to attribute time to individual kernels.