MATCH

Pattern matching clause -- finds nodes and relationships in the graph.

Category: query-language

Syntax

MATCH <pattern> [WHERE <predicate>]

Description

## Overview MATCH is the primary read clause in DeltaForge's Cypher query engine. It searches for patterns of nodes and relationships within a graph that has been constructed from Delta tables registered as graph sources. Each MATCH clause defines a structural pattern, and the engine finds all subgraphs that satisfy that pattern within the underlying CSR (Compressed Sparse Row) graph representation. The graph is loaded from Delta tables at query time (or served from an in-memory cache when available). Node and edge properties are resolved from the originating Delta table columns, which means MATCH operates over real analytical data rather than a separate graph store. ## Behavior - The engine converts the pattern into index lookups on the CSR adjacency structure. Single-hop patterns use direct neighbor iteration; variable-length paths use bounded BFS/DFS depending on the depth range specified. - When a WHERE clause accompanies MATCH, predicate pushdown filters nodes and edges as early as possible during traversal, reducing intermediate result size. - Label filtering restricts traversal to edges whose relationship type column matches the specified label (e.g., `-[:mentor]->`). Multiple labels on a relationship are treated as OR. - Inline property maps in node patterns (e.g., `{name: 'Alice'}`) are evaluated as equality predicates during pattern matching, equivalent to a WHERE clause. - DeltaForge supports the openCypher pattern predicate syntax (`WHERE NOT (n)-->()`) for existence and non-existence checks during filtering. ## GPU Execution - Single-hop expansion is GPU-accelerable. Appending `ON GPU [THRESHOLD <n>]` to a MATCH clause, or specifying ON GPU at the query level, dispatches the expansion kernel to a wgpu-backed compute shader that runs on DirectX 12, Vulkan, or Metal GPUs. - The per-MATCH ON GPU hint overrides any query-level device hint for that single clause. Multi-hop patterns reuse the GPU expansion kernel hop by hop. - The engine falls back to CPU transparently when the graph node count is below THRESHOLD, when no GPU accelerator is registered, or when the GPU path returns no result (e.g., driver error). CPU and GPU outputs are semantically identical. - GPU expansion returns topology (source, destination, edge indices, weight). Property materialization for RETURN and WHERE still runs on CPU. Returning bare variables (`RETURN a, r, b`) forces full property propagation and often dominates runtime for large result sets. ## Limitations - Variable-length paths without an upper bound (`-[*]->`) are internally capped at a configurable maximum hop count to prevent runaway traversals on large graphs. - MATCH does not support pattern quantifiers (path patterns with `+` or `{n,m}` syntax from newer GQL proposals). Use explicit variable-length paths instead. - All graph data must originate from Delta tables registered in a graph definition; ad-hoc table references inside MATCH are not supported.

Parameters

Name	Type	Description
`pattern`		Specifies the node and relationship pattern to search for in the graph. Accepts node patterns, relationship patterns, variable-length paths, and path function wrappers such as shortestPath.
`predicate`		Filters matched results using a boolean expression. Supports property comparisons, logical operators (AND, OR, NOT, XOR), list membership (IN), string predicates (STARTS WITH, ENDS WITH, CONTAINS), and pattern predicates such as WHERE NOT (n)-->().

Examples

-- Browse all nodes in the graph
USE my_zone.my_schema.my_graph
MATCH (n)
RETURN n.name AS name, n.department AS department
ORDER BY n.name;

-- Filter nodes by label and property
USE my_zone.my_schema.my_graph
MATCH (n:Employee)
WHERE n.active = true AND n.level IN ['L3', 'L4', 'L5']
RETURN n.name AS name, n.level AS level
ORDER BY n.level DESC;

-- Traverse one-hop relationships with edge type filter
USE my_zone.my_schema.my_graph
MATCH (mentor)-[r:mentor]->(mentee)
RETURN mentor.name AS mentor, mentee.name AS mentee, r.weight AS bond_strength
ORDER BY r.weight DESC;

-- Multi-hop traversal: find 2-hop advisor chains
USE my_zone.research_network.research_network
MATCH (a)-[:advisor]->(b)-[:advisor]->(c)
WHERE a <> c
RETURN a.name AS senior, b.name AS middle, c.name AS junior
ORDER BY a.name;

-- Variable-length path: reachability within 3 hops
USE my_zone.my_schema.my_graph
MATCH (a)-[*1..3]->(b)
WHERE a.id = 1 AND a <> b
RETURN DISTINCT b.name AS reachable, b.department AS dept
ORDER BY b.name;

-- Negative pattern: find isolated nodes with no outgoing edges
USE my_zone.research_network.research_network
MATCH (n)
WHERE NOT (n)-->()
RETURN n.name AS name, n.department AS department;

Pitfalls

Cartesian products occur silently when a MATCH clause contains multiple disconnected patterns (e.g., `MATCH (a), (b)`), because the engine returns the cross product of all matched nodes. Connect patterns with relationships or use separate MATCH clauses with WITH to control cardinality.
Variable-length paths with wide ranges (e.g., `*1..10`) on dense graphs can produce exponential intermediate results. Narrow the hop range or add WHERE filters to constrain the search space.
Omitting a USE clause causes the query to fail because no graph context is established. Always prefix Cypher queries with `USE <zone>.<schema>.<graph>` to specify the target graph definition.
Pattern predicates like `WHERE NOT (n)-->()` perform a full neighbor scan per candidate node. On high-degree nodes this can be expensive; consider filtering by label or property first to reduce the candidate set.
GPU MATCH with bare variable RETURN (RETURN a, r, b) triggers full CPU-side property propagation that often dominates runtime. Return specific properties (RETURN a.id, r.weight) or materialize topology into a temp table and JOIN properties back via SQL to avoid the pointer scan.
Per-MATCH ON GPU overrides a query-level hint, not the other way around. Placing ON GPU on a single MATCH leaves other clauses in the same query on CPU unless they carry their own hint.