Summary
The "Supported GQL Query Features" matrix in
reference.mdx
(and the per-connector mirrors in connect/postgres.mdx, connect/mysql.mdx,
connect/duckdb.mdx) is too thin to actually answer the question users
arrive with: "will my query work?"
A ✓ in the matrix answers "does this word exist in the supported set" —
not "does my query work." Two examples of where readers get stuck today:
collect() / collect_list() (aggregate) is marked ✓ on both backend
categories. It doesn't say whether WITH collect(n) AS xs ... is allowed
(it is) vs. only RETURN collect(n) (also is) — readers have to try and
see, or read the source.
Quantified path (){m,n} — bounded is ✓ on SQL, but with implicit
caveats: MATCH p = (...){m,n}(...) (path binding) is not supported,
and that's buried in the "Known limitations" section as a separate bullet.
A reader checking the matrix and trying MATCH p = (a){1,3}(b) will get
an error and think the matrix is wrong.
The matrix tries to be exhaustive but is shaped against syntax surface area
rather than what a user actually composes into a query. The result is
both factually correct and operationally misleading.
Proposal
Replace the single exhaustive matrix with three narrower, intent-driven
sections:
1. Works-everywhere baseline
Concrete examples of MATCH-WHERE-RETURN-WITH-aggregate-UNION patterns
that work identically on every supported backend. Each example is a real
GQL query the reader can paste, not just a feature name with a checkmark.
MATCH (n:Label)-[r:REL]->(m:Label)
WHERE n.field > 10
WITH n, count(*) AS hits
RETURN n.name, hits
ORDER BY hits DESC
LIMIT 10;
A reader scanning this section gets immediate confidence about the
boring 80% of their workload.
2. Advanced capabilities by use case
Group by what the user is trying to do, not by syntax category:
- Graph traversal — paths, variable-length, shortest path
- Aggregation —
WITH count(...) grouping, collect() materialization
- Mutations —
INSERT, DELETE, SET, REMOVE
- Set operations —
UNION, INTERSECT, EXCEPT
Each use-case block: what works on which backends, with an example for
each supported shape and a link to the connector page for backend-specific
notes.
3. Limitations page (separate)
Convert "Known limitations" from a bulleted afterthought into a dedicated
sub-page where each entry follows some fixed shape.
Summary
The "Supported GQL Query Features" matrix in
reference.mdx(and the per-connector mirrors in
connect/postgres.mdx,connect/mysql.mdx,connect/duckdb.mdx) is too thin to actually answer the question usersarrive with: "will my query work?"
A
✓in the matrix answers "does this word exist in the supported set" —not "does my query work." Two examples of where readers get stuck today:
collect() / collect_list() (aggregate)is marked ✓ on both backendcategories. It doesn't say whether
WITH collect(n) AS xs ...is allowed(it is) vs. only
RETURN collect(n)(also is) — readers have to try andsee, or read the source.
Quantified path (){m,n} — boundedis ✓ on SQL, but with implicitcaveats:
MATCH p = (...){m,n}(...)(path binding) is not supported,and that's buried in the "Known limitations" section as a separate bullet.
A reader checking the matrix and trying
MATCH p = (a){1,3}(b)will getan error and think the matrix is wrong.
The matrix tries to be exhaustive but is shaped against syntax surface area
rather than what a user actually composes into a query. The result is
both factually correct and operationally misleading.
Proposal
Replace the single exhaustive matrix with three narrower, intent-driven
sections:
1. Works-everywhere baseline
Concrete examples of MATCH-WHERE-RETURN-WITH-aggregate-UNION patterns
that work identically on every supported backend. Each example is a real
GQL query the reader can paste, not just a feature name with a checkmark.
A reader scanning this section gets immediate confidence about the
boring 80% of their workload.
2. Advanced capabilities by use case
Group by what the user is trying to do, not by syntax category:
WITH count(...)grouping,collect()materializationINSERT,DELETE,SET,REMOVEUNION,INTERSECT,EXCEPTEach use-case block: what works on which backends, with an example for
each supported shape and a link to the connector page for backend-specific
notes.
3. Limitations page (separate)
Convert "Known limitations" from a bulleted afterthought into a dedicated
sub-page where each entry follows some fixed shape.