UNWIND

Expands a list into individual rows.

Category: query-language

Syntax

UNWIND <list_expr> AS <variable>

Description

## Overview UNWIND takes a list expression and produces one output row per element, binding each element to the specified variable. It is the inverse of the collect() aggregation function. UNWIND is essential for transforming list-typed data into a tabular format that subsequent MATCH, CREATE, and RETURN clauses can process row by row. In DeltaForge, UNWIND operates on in-memory list values within the Cypher execution engine. The source list can originate from literal expressions, list-producing functions, collected aggregations, or list-typed columns from the underlying Delta tables. ## Behavior - UNWIND on an empty list produces zero output rows, effectively filtering out the current binding. - UNWIND on a NULL value produces zero output rows (same as empty list). - UNWIND preserves all existing bindings from preceding clauses. Each element of the list is paired with the full set of existing variable bindings. - Nested lists can be unwound with sequential UNWIND clauses to flatten multi-level structures. ## Limitations - UNWIND does not support unwinding maps directly. To iterate over map entries, use the keys() function to get the key list, then UNWIND the keys. - Very large lists (millions of elements) can cause memory pressure when unwound, since each element produces a full row with all existing bindings.

Parameters

Name	Type	Description
`list_expr`		Specifies the list expression to expand into rows. Accepts literal lists, list-producing functions (collect, range, keys, labels), list comprehensions, and property references that return list-typed values.
`variable`		Specifies the variable name to bind each element of the list. This variable is available in subsequent clauses.

Examples

-- Expand a literal list into rows
UNWIND [1, 2, 3] AS x
RETURN x;

-- Expand a property that contains a list
USE my_zone.my_schema.my_graph
MATCH (n:Employee)
UNWIND n.skills AS skill
RETURN skill, count(*) AS frequency
ORDER BY frequency DESC;

-- Use UNWIND with range() to generate a sequence
UNWIND range(1, 10) AS i
RETURN i, i * i AS square;

-- Flatten a collected list back into rows
USE my_zone.my_schema.my_graph
MATCH (a)-[]->(b)
WITH a, collect(b.name) AS contacts
UNWIND contacts AS contact_name
RETURN a.name AS person, contact_name;

-- UNWIND for batch node creation
USE my_zone.my_schema.my_graph
UNWIND [{name: 'Sensor_A', type: 'temp'}, {name: 'Sensor_B', type: 'humidity'}] AS props
CREATE (n:Sensor) SET n += props;

Pitfalls

UNWIND on NULL or an empty list silently produces zero rows, which can eliminate the entire result set. Check for NULL/empty lists before UNWIND if row preservation is important.
Unwinding a collected list immediately after collecting it (collect then UNWIND) produces the original rows but loses the grouping context. This pattern is useful for reshaping data but adds overhead.
UNWIND creates a cross product when combined with other bindings. Unwinding a list of N elements on a result set of M rows produces N*M rows. Be aware of the cardinality explosion.
UNWIND does not deduplicate elements. If the source list contains duplicates, the output will contain duplicate rows. Use DISTINCT in a subsequent WITH or RETURN to deduplicate.