Skip to content
NamiDB NamiDB

Reading data

NamiDB implements a strict subset of openCypher 9 plus GQL (ISO/IEC 39075:2024). Every LDBC SNB Interactive Complex Read query (IC01 through IC12) parses, plans, and runs end to end on top of this surface, so the read clauses below are well exercised in practice.

For the precise parser coverage and known gaps, see Supported subset. For the operator and function catalog, see Operators & functions.

MATCH

The basic pattern-matching clause. Variables in () bind nodes; variables in [] bind relationships.

MATCH (p:Person)
RETURN p.name

Patterns can chain through relationships:

MATCH (a:Person)-[:KNOWS]->(b:Person)
RETURN a.name AS a, b.name AS b

Multiple labels and inline property predicates:

MATCH (p:Person {name: 'Alice'})-[:KNOWS]->(friend:Person)
WHERE friend.age >= 18
RETURN friend.name

Variable-length relationship patterns (bounded):

MATCH (a:Person {name: 'Alice'})-[:KNOWS*1..3]->(reach:Person)
RETURN DISTINCT reach.name

WHERE

Filters bound rows. Supports comparison operators (=, <>, <, <=, >, >=), boolean operators (AND, OR, NOT), IN, IS NULL / IS NOT NULL, string predicates (STARTS WITH, ENDS WITH, CONTAINS), and property access (n.prop).

MATCH (p:Person)
WHERE p.age >= 18
  AND p.country IN ['US', 'CA', 'MX']
  AND p.name STARTS WITH 'A'
RETURN p.name, p.age

WHERE can appear after MATCH, OPTIONAL MATCH, or WITH. The optimizer pushes predicates down toward the storage layer so that bloom filters, fence pointers, and Parquet row-group pruning can skip work.

OPTIONAL MATCH

Like MATCH, but if the pattern fails to bind, columns from the optional pattern become NULL instead of dropping the row. Left-join semantics.

MATCH (p:Person)
OPTIONAL MATCH (p)-[:OWNS]->(car:Car)
RETURN p.name, car.model

WITH

Pipes intermediate results into the next clause. Use it to project before chaining another MATCH, to filter on an aggregation, or to break a query into stages.

MATCH (p:Person)-[:KNOWS]->(friend)
WITH p, count(friend) AS friend_count
WHERE friend_count > 5
RETURN p.name, friend_count
ORDER BY friend_count DESC

RETURN

Projects the final columns. Supports aliasing (AS), DISTINCT, expressions, and aggregations.

MATCH (p:Person)
RETURN DISTINCT p.country AS country, count(*) AS n
ORDER BY n DESC
LIMIT 10

Common shapes:

RETURN p                            -- whole node
RETURN p.name, p.age                -- properties
RETURN p.name AS name               -- aliased
RETURN p.first_name + ' ' + p.last  -- expression
RETURN count(*) AS n                -- aggregate

ORDER BY, SKIP, LIMIT

Sorting and paging. Chain on RETURN (or WITH).

MATCH (p:Person)
RETURN p.name, p.age
ORDER BY p.age DESC
SKIP 20
LIMIT 10

Multiple sort keys, mixed directions:

MATCH (p:Person)
RETURN p.country, p.age, p.name
ORDER BY p.country ASC, p.age DESC

Aggregations

The standard set: count(*), count(expr), sum, avg, min, max, collect.

MATCH (p:Person)-[:LIVES_IN]->(city:City)
RETURN city.name AS city,
       count(p)   AS people,
       avg(p.age) AS avg_age
ORDER BY people DESC

collect(expr) accumulates rows into a list, useful for shaping output:

MATCH (p:Person)-[:KNOWS]->(friend)
RETURN p.name, collect(friend.name) AS friends

DISTINCT works inside aggregates:

MATCH (p:Person)-[:LIVES_IN]->(city:City)
RETURN count(DISTINCT city) AS cities

EXISTS (subquery)

Tests whether a pattern exists, without materializing it. The optimizer decorrelates this into a hash semi-join (RFC-014) so it runs in a single pass.

MATCH (p:Person)
WHERE EXISTS {
  MATCH (p)-[:KNOWS]->(:Person {country: 'MX'})
}
RETURN p.name

UNWIND

Expands a list into rows. Useful for joining external data (parameters) into a pattern.

UNWIND $names AS name
MATCH (p:Person {name: name})
RETURN p.name, p.age

Plan inspection

Add EXPLAIN VERBOSE to any query to see the chosen plan, selectivity estimates, and per-operator cost annotations:

Terminal window
namidb explain --verbose \
  "MATCH (a:Person)-[:KNOWS]->(b) RETURN b ORDER BY b.id LIMIT 20"

Plan inspection touches the parser, lowerer, and optimizer but not storage, so it’s safe to run against a production namespace without I/O.

See the CLI page for the full explain flag reference.

What’s next