CALL { subquery }

Executes an inner query as a subquery.

Syntax

CALL {
  <inner_query>
}

Description

## Overview CALL { subquery } executes an enclosed Cypher query as a subquery within the outer query's execution context. The subquery can be correlated (referencing outer variables via WITH) or uncorrelated (independent of the outer query). This enables complex multi-stage computations within a single Cypher statement. In DeltaForge, CALL subqueries are executed by the Cypher engine as nested query plans. Each invocation of a correlated subquery receives one row of input from the outer query, executes the inner query, and returns the results to be joined with the outer row. Uncorrelated subqueries execute once and their result is broadcast to all outer rows. ## Behavior - Correlated subqueries must begin with `WITH <outer_variables>` to import variables from the outer scope. Only explicitly imported variables are accessible inside the subquery. - Uncorrelated subqueries do not reference outer variables and execute independently. Their results are cross-joined with the outer query's rows. - The subquery must end with a RETURN clause. The returned columns become available as variables in the outer query's subsequent clauses. - Subqueries can contain MATCH, WHERE, WITH, ORDER BY, LIMIT, SKIP, CALL (including nested subqueries), and aggregation functions. - Write operations (CREATE, SET, DELETE, MERGE, REMOVE) inside a CALL subquery make the outer query non-read-only. ## Limitations - The RETURN clause of the subquery defines the interface between inner and outer scopes. Variables not returned are not accessible in the outer query. - Deeply nested subqueries (subquery within subquery) increase planning and execution overhead. Flatten complex logic with WITH where possible. - Correlated subqueries execute once per outer row, which can be expensive for large outer result sets.

Examples

-- Correlated subquery: count neighbors per node
USE my_zone.my_schema.my_graph
MATCH (n:Employee)
CALL {
  WITH n
  MATCH (n)-[:mentor]->(m)
  RETURN count(m) AS mentee_count
}
RETURN n.name AS name, mentee_count
ORDER BY mentee_count DESC;

-- Uncorrelated subquery: compute a global metric
USE my_zone.my_schema.my_graph
CALL {
  MATCH (n)
  RETURN count(n) AS total_nodes
}
MATCH (a)-[]->(b)
RETURN a.name AS source, b.name AS target, total_nodes;

-- Subquery with aggregation and filtering
USE my_zone.my_schema.my_graph
MATCH (dept_node)
CALL {
  WITH dept_node
  MATCH (dept_node)-[r]->(peer)
  WHERE r.weight > 0.7
  RETURN count(peer) AS strong_connections
}
RETURN dept_node.name AS person, strong_connections
ORDER BY strong_connections DESC;

-- Algorithm inside a subquery
USE my_zone.my_schema.my_graph
CALL {
  MATCH (a)-[]->(b)
  RETURN a.name AS hub, count(b) AS degree
  ORDER BY degree DESC
  LIMIT 5
}
RETURN hub, degree;

Pitfalls

• Forgetting the WITH clause at the start of a correlated subquery causes the inner query to execute without access to outer variables, producing unexpected results or errors.
• Correlated subqueries execute once per outer row. If the outer MATCH produces 10,000 rows, the subquery runs 10,000 times. Use uncorrelated subqueries or aggregation in the outer query when possible to reduce execution count.
• Variable name collisions between the outer query and the subquery RETURN can shadow outer variables. Use distinct aliases to avoid ambiguity.
• CALL subqueries that contain mutations (CREATE, DELETE) execute those mutations for every outer row in a correlated context. Ensure the mutation logic is idempotent or carefully scoped.

See Also

• CALL
• WITH
• MATCH
• RETURN