Skip to content

MemGQL: restructure reference.mdx feature matrix to answer 'will my query work?' #1643

Description

@DavIvek

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
  • AggregationWITH count(...) grouping, collect() materialization
  • MutationsINSERT, DELETE, SET, REMOVE
  • Set operationsUNION, 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions