---
title: MATCH
url: https://nexyron.tech/docs/cypher/clauses/reading/match
description: Primary pattern matching clause that binds graph structure into variables.
---

# MATCH

## Generic Description

Primary pattern-matching clause that binds graph structure into variables.

Simple example:

```cypher
MATCH (p:Person)-[:KNOWS]->(q:Person) RETURN p, q
```

## Consumer-Level Explanation

Use `MATCH` when the query must primary pattern-matching clause that binds graph structure into variables 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

MATCH is the core graph-reading clause. It is where you describe the shape you want from the graph: isolated nodes, directed relationships, variable-length paths, path functions, or chained motifs. In practical use it is the clause that turns the graph from raw storage into a working set of rows.

What this clause is really for:

-   it defines one concrete stage in the Cypher row pipeline, so variables available before and after `MATCH` 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 `MATCH` 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

-   finding entities connected by a known relationship pattern
-   pulling anchor sets before aggregation or mutation
-   building recommendation or discovery queries from multi-hop traversals

## Real Limitations And Tradeoffs

-   pattern shape strongly influences row explosion and plan cost
-   broad unbounded expansions can become expensive quickly
-   MATCH alone does not preserve missing relationships; use OPTIONAL MATCH for outer-join-like behavior