[Feature Request]: Implement SQL:2023 SQL/PGQ property graphs over relational tables

## Is there an existing issue for the same feature request?

- [x] Searched open and closed MatrixOne issues for SQL/PGQ, PGQ, property graph and graph query; no matching feature issue found.

## Problem and motivation

Applications currently have to express domain relationships repeatedly through joins. Add a standards-oriented graph query interface over existing MatrixOne relational data, so relationship-oriented queries compose with ordinary SQL without duplicating data into another graph database.

Motivating article: [From Joins to Graph Edges: SQL/PGQ in PostgreSQL 19](https://dev.to/franckpachot/from-joins-to-graph-edges-sqlpgq-in-postgresql-19-2doo).

**Standards/product status checked on 2026-09-05:** SQL/PGQ is ISO/IEC 9075-16:2023, part of SQL:2023. Oracle Database 23ai implements SQL property graphs and GRAPH_TABLE. PostgreSQL 19 implements a basic subset; its current documentation still identifies 19 as a development/beta version, not a generally supported stable release. Neither vendor precedent implies complete SQL/PGQ conformance. SQL/PGQ is not Oracle PGQL, Cypher, or the separate GQL standard.

## Feature and first-principles contract

Introduce `CREATE PROPERTY GRAPH`, `DROP PROPERTY GRAPH`, and `GRAPH_TABLE (... MATCH ... COLUMNS (...))` as a logical graph mapping and query interface over relational tables.

**Invariant:** for every supported pattern, graph results must agree with its defined relational semantics on the same transaction snapshot, including row multiplicity, NULL handling, element identity, labels and edge direction. Base tables remain the source of truth. The first milestone must not require graph-data copies, asynchronous synchronization or a second transaction domain.

The primary initial benefit is expressiveness/composability, **not an assumed execution speedup over equivalent joins**.

### Proposed MVP (subject to design approval)

- Persistent graph metadata: vertex/edge table aliases, explicit keys including composite keys, source/destination references, labels and explicitly exposed properties. Allow a base table to play both vertex and edge roles through distinct aliases.
- Fixed-length patterns: vertex-only, one-hop and explicitly written multi-hop paths; named/anonymous elements, label matching, direction, property predicates and projected properties.
- `GRAPH_TABLE` as a composable FROM item: outer joins to ordinary tables, filtering, aggregation, ordering and limit through existing SQL operators. Publish the exact supported surface rather than claiming the whole standard.
- DDL lifecycle, dependency management, metadata inspection/export and documented privilege rules must ship with the query feature, not be left as cleanup work.
- Explicitly reject unsupported constructs. Variable-length/quantified paths, shortest paths, path values/analytics, graph mutation syntax and a dedicated graph storage/index engine are follow-up design topics, not MVP commitments.

Illustrative target (to be validated against the selected standards subset and MO naming rules):

```sql
CREATE PROPERTY GRAPH org_graph
VERTEX TABLES (
employee KEY (id) LABEL person PROPERTIES (name)
)
EDGE TABLES (
employee AS reports KEY (id)
SOURCE KEY (id) REFERENCES employee (id)
DESTINATION KEY (manager_id) REFERENCES employee (id)
LABEL reports_to NO PROPERTIES
);

SELECT * FROM GRAPH_TABLE (
org_graph
MATCH (e IS person WHERE e.name = 'Alice')
-[IS reports_to]->(m IS person)
COLUMNS (m.name AS manager_name)
);
```

The simple case should match a hand-written employee self-join, without requiring a separate relationship table.

## Implementation direction and required design decisions

**Design first:** this crosses parser, planner, persisted catalog and execution/DDL boundaries. Produce a versioned design document, review its exact revision, and resolve blockers before implementation. This issue is a planning brief, not an approved design.

Preferred starting hypothesis: parse to a typed graph AST, bind graph metadata and element identity, lower fixed-length patterns to existing relational plan nodes, then reuse optimizer/distributed execution. Do not implement by string-building SQL or hiding the graph behind an opaque table function that prevents optimization. Compare this with (1) continuing with views/manual joins and (2) introducing dedicated traversal operators/storage; justify the MVP choice and when an alternative would become necessary.

Initial local reconnaissance at `8b0a5ff873824737e2c89c19876460a3073de40d` found no SQL/PGQ/GRAPH_TABLE/property-graph matches in `pkg/sql` or `pkg/catalog`; this is not an exhaustive proof of absence on latest main. Recheck current main before design. Likely owners: `pkg/sql/parsers/dialect/mysql/mysql_sql.y`, `pkg/sql/parsers/tree`, `pkg/sql/plan` (including DDL binding), `pkg/catalog`, frontend DDL/privilege handling and existing relational execution paths. Reuse established catalog/DDL mechanisms rather than preselecting a new metadata framework.

The design must settle:

1. Standard feature matrix and MO dialect compatibility, including keywords/identifier quoting, type coercion/collation, property-name ambiguity, multiple labels and label-to-table expansion.
2. Identity and multiplicity: composite keys, uniqueness requirements, repeated variables, parallel edges, cycles, self-loops and bidirectional matches. No blanket DISTINCT to conceal incorrect duplicate generation.
3. NULL/dangling endpoints and constraints: specify behavior under supported graph semantics; do not assume a declared foreign key is always required, or that every deployment enforces it. Reject unsupported key/constraint configurations explicitly.
4. Catalog ownership, atomic graph creation/drop, base table/column rename/drop/type change, prepared-plan invalidation, cross-CN visibility, restart, backup/restore and mixed-version/upgrade behavior. Dropping a graph must not delete underlying tables.
5. Graph/base-table privilege checks and account/database scoping consistent with MO object semantics.

## Performance and unhappy-path requirements

- Preserve predicate/projection pushdown, join reordering, statistics and existing index/distribution choices wherever semantics permit. EXPLAIN must make the resulting access paths visible.
- Cost model must include label expansion, join cardinality, high-degree/skewed vertices, intermediate rows, network exchange, memory and planning time. Fixed path length does not bound result cardinality. Avoid Cartesian expansion of impossible label/table combinations and full-graph loading.
- Benchmark against equivalent hand-written SQL using identical data, snapshot, topology and settings: selective one-hop, two/three-hop, skew/high fan-out, multi-label and composite-key cases. Report latency, planning time, peak memory, scanned/intermediate rows and network volume. Define acceptable overhead before implementation; investigate regressions instead of assuming the same syntax means the same plan.
- Reuse cancellation, memory accounting and spill/resource-limit behavior. Invalid definitions, bind failures, concurrent schema changes, failed/rolled-back DDL and query cancellation must produce clear errors with no partial published graph, stale usable plan, leaked resources or unbounded background work.
- Any later recursive traversal needs its own semantics, termination/resource budget and cycle handling design; never add recursion merely to make syntax parse.

## Delivery / acceptance checklist

- [ ] Approved versioned design and explicit supported/unsupported SQL/PGQ matrix.
- [ ] Parser/binder/catalog tests plus executable end-to-end SQL BVT for graph create/query/drop.
- [ ] Independent result oracle: graph queries versus manually authored relational queries, preserving multisets rather than comparing only counts; differential checks against pinned vendor versions only for agreed common semantics.
- [ ] Minimal deterministic counterexamples: NULL endpoints/properties, duplicate projected values, parallel edges, self-loops/cycles, repeated variables, composite keys, invalid references, ambiguous labels/properties and unsupported paths.
- [ ] Lifecycle coverage: base DML visibility under MO transaction semantics, schema invalidation, failed DDL, restart/restore and account scoping; no orphan metadata or deletion of base data.
- [ ] Cancellation/resource-exhaustion tests and plan/performance evidence for single-CN and distributed execution where the plan reaches those paths.
- [ ] User documentation, compatibility limitations and rollout/upgrade guidance; link implementation PRs here.

## Primary references

- [PostgreSQL 19 property graph model](https://www.postgresql.org/docs/19/ddl-property-graphs.html)
- [CREATE PROPERTY GRAPH syntax and ISO/IEC 9075-16 conformance](https://www.postgresql.org/docs/19/sql-create-property-graph.html)
- [GRAPH_TABLE and graph patterns](https://www.postgresql.org/docs/19/queries-graph.html)
- [PostgreSQL 19 unsupported SQL:2023 features](https://www.postgresql.org/docs/19/unsupported-features-sql-standard.html)
- [Oracle Database 23ai and the SQL/PGQ standard](https://blogs.oracle.com/database/property-graphs-in-oracle-database-23ai-the-sql-pgq-standard)
- [Oracle: SQL/PGQ versus PGQL](https://blogs.oracle.com/database/querying-graphs-with-sql-and-pgql-what-is-the-difference)