---
title: UNWIND
url: https://nexyron.tech/docs/cypher/clauses/reading/unwind
description: Use UNWIND when the query must expands a list into one row per element and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit be
---

# UNWIND

## Generic Description

Expands a list into one row per element.

Simple example:

```cypher
UNWIND [1,2,3] AS n RETURN n
```

## Consumer-Level Explanation

Use `UNWIND` when the query must expands a list into one row per element and the planner needs to see that operation as part of the Cypher row pipeline. Keep the clause explicit because it controls row grain, variable scope, and what later clauses are allowed to reference.

## More Detailed Explanation

UNWIND is one of the bridges between document/list-style data and graph-style querying. It turns an in-memory list or collected set into row form so that normal graph or analytic operations can continue. It is essential for bulk parameter ingestion and semi-structured payload normalization.

What this clause is really for:

-   it defines one concrete stage in the Cypher row pipeline, so variables available before and after `UNWIND` must be clear
-   it should make graph structure, temporal filters, document payload shaping, or procedure output explicit instead of relying on client-side interpretation
-   planner tooling depends on this clause boundary to know row grain, variable scope, and whether later expressions are reads, writes, schema operations, or projections

## Advanced Example

This example keeps `UNWIND` inside a complete query pipeline so the clause boundary, visible variables, and returned row shape are clear to planner tooling.

```cypher
MATCH (u:User)-[e:VIEWED]->(d:Document)
TIME e.ts BETWEEN datetime('2025-01-01T00:00:00Z') AND datetime('2025-02-01T00:00:00Z')
WITH u, e, d,
     date_trunc('day', e.ts) AS day_bucket,
     properties(d) AS doc_map,
     unpivot(properties(d.metadata)) AS metadata_rows,
     cosine_similarity(vector(properties(d).embedding), vector([0.22, 0.18, 0.44])) AS score
RETURN u.user_id, d.title, day_bucket, keys(doc_map) AS doc_keys, metadata_rows, score
ORDER BY score DESC
LIMIT 15
```

## Real Use Cases

-   bulk create/update flows from array parameters
-   turning nested metadata arrays into row pipelines
-   post-aggregation expansion after collect or comprehension

## Real Limitations And Tradeoffs

-   large lists create large row sets immediately
-   list order can matter if later logic assumes stable sequencing
-   it can hide data-volume issues if used on wide collected payloads