CALL

Invokes a procedure with an optional per-CALL device hint and YIELD for result columns.

Category: query-language

Syntax

CALL <procedure>(<args>) [ON GPU [THRESHOLD <n>] | ON CPU] [YIELD <items>]

Description

## Overview CALL invokes a registered procedure and optionally yields specific columns from its result. In DeltaForge, CALL is the primary mechanism for executing graph algorithms (PageRank, betweenness centrality, community detection, shortest path, and others) on graphs backed by Delta tables. Procedures operate on the full graph topology loaded into the CSR representation. The YIELD clause controls which output columns are bound as variables for use in subsequent RETURN, WITH, or WHERE clauses. This allows selective projection of algorithm results and enables chaining algorithm output with further Cypher processing. ## Behavior - Procedure arguments are typically passed as a map literal (e.g., `{dampingFactor: 0.85}`). The available parameters vary by procedure. Consult the algorithm documentation for supported options. - YIELD binds procedure output columns as variables in the query scope. Subsequent RETURN or WITH clauses can reference these variables. - Graph algorithm procedures (algo.*) execute on the CSR graph loaded from the graph definition specified by the preceding USE clause. The algorithm runs on the full graph topology. - When ON GPU is specified and the graph exceeds the minimum threshold, GPU-accelerated algorithms (algo.pageRank, algo.betweenness, algo.connectedComponents, algo.louvain, algo.triangleCount) execute on the GPU via wgpu compute shaders. The device hint can be written either as a query-level prefix (ON GPU placed after USE, applying to the whole query) or as a per-CALL suffix placed after the argument list (CALL algo.pageRank(...) ON GPU THRESHOLD n). The per-CALL suffix binds the device to the procedure it follows and overrides the query-level hint for that single invocation, which keeps the hint next to the algorithm it controls instead of detached at the top of the statement. Non-accelerated algorithms (algo.degree, algo.closeness, algo.shortestPath, algo.bfs, algo.dfs, algo.mst, algo.knn, algo.similarity, algo.scc) always run on CPU regardless of the hint. - The engine silently falls back to CPU when the graph node count is below THRESHOLD, no GPU accelerator is registered, or the GPU path reports an error. Output is identical on either device. - Procedure results are materialized as Arrow RecordBatches, enabling seamless integration with downstream Cypher clauses or the cypher() table function for SQL interop. ## Limitations - Only built-in procedures are available. User-defined procedures are not currently supported. - Algorithm procedures operate on the entire graph; per-subgraph execution requires filtering via MATCH before or after the CALL. - Weighted algorithms require a weight column in the edge table, specified via the graph definition or the procedure arguments.

Parameters

Name	Type	Description
`procedure`		Specifies the fully qualified procedure name using dot notation (e.g., algo.pageRank, algo.louvain, db.labels). The procedure must be registered in the engine's procedure catalog.
`arguments`		Specifies the arguments to pass to the procedure. Most graph algorithm procedures accept a single map argument with named options (e.g., {dampingFactor: 0.85, iterations: 20}). Some procedures accept no arguments.
`device`		Optional per-CALL execution device hint placed immediately after the argument list and before YIELD: ON GPU [THRESHOLD <n>] or ON CPU. It binds the device to the procedure invocation it follows and overrides any query-level ON GPU hint for this single CALL. When omitted, the CALL inherits the query-level hint (CPU by default). THRESHOLD <n> sets the minimum graph node count below which the engine falls back to CPU.
`yield_items`		Specifies which columns from the procedure result to bind as variables. Each YIELD item is a column name optionally aliased with AS. When YIELD is omitted, all result columns are available.

Examples

-- Run PageRank with custom parameters
USE my_zone.my_schema.my_graph
CALL algo.pageRank({dampingFactor: 0.85, iterations: 20})
YIELD node_id, score, rank
RETURN node_id, score, rank
ORDER BY score DESC;

-- Run Louvain community detection
USE my_zone.my_schema.my_graph
CALL algo.louvain({resolution: 1.0})
YIELD node_id, community_id
RETURN community_id, count(*) AS size
ORDER BY size DESC;

-- Compute betweenness centrality
USE my_zone.my_schema.my_graph
CALL algo.betweenness()
YIELD node_id, centrality, rank
RETURN node_id, centrality, rank
ORDER BY centrality DESC;

-- Shortest path between two nodes
USE my_zone.my_schema.my_graph
CALL algo.shortestPath({source: 1, target: 33})
YIELD source, target, distance, path
RETURN source, target, distance;

-- Degree centrality
USE my_zone.my_schema.my_graph
CALL algo.degree()
YIELD node_id, in_degree, out_degree, total_degree
RETURN node_id, in_degree, out_degree, total_degree
ORDER BY total_degree DESC;

-- K-nearest neighbors
USE my_zone.my_schema.my_graph
CALL algo.knn({node: 1, k: 5})
YIELD neighbor_id, similarity, rank
RETURN neighbor_id, similarity, rank
ORDER BY rank;

Pitfalls

Omitting YIELD causes all procedure output columns to be available, but column names must be known to reference them. Always use YIELD for clarity and to avoid ambiguity.
Algorithm parameters (dampingFactor, iterations, resolution) have defaults that may not suit all use cases. Check the algorithm documentation for default values and tune parameters for your graph size and density.
CALL algo.shortestPath requires source and target node IDs, not variable references. The IDs must correspond to the id column in the node Delta table.
Procedure execution time scales with graph size. Running PageRank or Louvain on graphs with millions of edges may take significant time. Use ON GPU for large graphs when GPU acceleration is available, but remember that algorithms outside the GPU-accelerated set (PageRank, betweenness, connected components, Louvain, triangle count) always run on CPU regardless of the hint.