Skip to content

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

@DavIvek

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
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions