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.
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.
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.
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.
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.