Skip to content

GQL_PROFILE_STATEMENT.md

Latest commit

 

History

History
119 lines (100 loc) · 6.42 KB

GQL_PROFILE_STATEMENT.md

File metadata and controls

119 lines (100 loc) · 6.42 KB
Raw

Grust GQL/Cypher — Profile Statement

This is the precise, backed statement of Grust's own GQL/Cypher feature catalog. It began as the terminal deliverable of the GQL completion goal (U16) with Full39075 as a candidate internal profile. The completion goal (docs/GQL_FULL39075_GOAL.md, F1–F11) implemented every remaining catalogued feature, so Full39075 is the realized Grust profile, backed feature-by-feature against the machine-readable manifest (grust_cypher::gql::feature_manifest), not by prose.

The profile name does not claim complete ISO/IEC 39075 conformance, formal certification, or uniform execution on every backend. The manifest is a scoped Grust catalog, and the reference executor, pushdown engines, native escape hatches, and storage adapters have intentionally different capabilities.

Source of truth: the GqlFeature manifest in crates/grust-cypher/src/gql.rs. This document must agree with it; the test gql::tests::full_profile_claim_is_backed fails if the scoped-out set below drifts from the manifest.

Profiles (nested)

GqlConformanceProfile, narrowest → widest:

  1. StrictWrite — the original strict writable-Cypher surface (the 327-test floor): explicit-id CREATE/MERGE/DELETE/SET/REMOVE, resolved-endpoint edge writes, literal-only assignments, structured rejections.
  2. PortableGql — StrictWrite plus the portable read core, expression engine, aggregates/RETURN, read pushdown, the type-system values, procedures, CALL { … } subqueries, transaction surface, and the U10b write widenings.
  3. Full39075 — the widest Grust catalog profile: PortableGql plus index and graph-type DDL metadata, catalog metadata, named graph selection, session control, first-class path and graph values, table-valued functions, shortest-path matching, and backend-native passthrough. This is the realized profile today.

Realized profile (today): Full39075

72 of 77 Grust-catalogued features are Supported (implemented + tested); the remaining 5 are intentional rejections. By family (run support_summary() for the live list): parser/semantics, resolved writes, broad matched writes, row-producing relationship writes, returning & aggregates, predicates & expressions (incl. the list binding forms reduce, list comprehensions and general any/all/none/single, evaluated by the reference; pushdown declines them), read-only matching, path matching (incl. shortestPath / allShortestPaths), query composition (incl. CALL { … } subqueries), type system (temporal/duration/decimal/path/graph incl. arithmetic, ordering, and stable serialization where applicable), constraints and index metadata, graph type metadata, catalog metadata, named graph selection, transactions (control surface, capability reporting, and atomic batch execution on transactional stores), session state commands, catalog procedures and table-valued functions, backend-native passthrough.

Counts: supported 72 · rejected 5 · planned 0 · future 0 · total 77.

Scoped OUT of the profile: intentional rejections (5)

These are the only non-Supported manifest entries. They are required rejections in the strict surface (pinned by tests) — correctness guards, not missing features:

  • reject-create-node-without-explicit-identity (unless GenerateForCreate)
  • reject-merge-without-explicit-identity
  • reject-unresolved-edge-endpoint-write
  • reject-non-literal-assignment-value
  • reject-trailing-node-creation-after-row-producing-edge

How the claim is backed

  • Manifest — every feature has a status + min-profile + summary; is_supported_in drives profile membership.
  • full_profile_claim_is_backed — pins the scoped-out set (exactly the five rejections) to this document.
  • Conformance corpora — tests/gql/portable_read.json, tests/golden/write_golden.json (byte-identical write plans), tests/golden/write_corpus.json, plus the grust-turso differential read-pushdown oracle.
  • Test floor — the current grust-cypher library and integration suites must stay green; the original 327 strict-write cases remain a historical non-regression floor.

Honest scope notes (within Supported)

The realized profile claims exactly what the summaries in the manifest say, no more. It is not an exhaustive clause-by-clause model of the ISO standard. Notable deliberate scopings:

  • CALL { … } subqueries use correlated import-all scoping (the subquery sees the outer row's bindings); RETURN * inside a subquery is a structured rejection.
  • shortestPath / allShortestPaths cover a single relationship segment over minimal-length simple paths.
  • Index/graph-type DDL and catalog metadata are portable, caller-owned metadata; physical/native index creation remains backend-specific and is reported through backend capability flags.
  • Native passthrough (NativeQuery) is an explicit escape hatch outside portable conformance: no portable semantics are claimed for passthrough text.

Per-backend conformance

The executing-Cypher set is Memory (reference), Sail (writes + read pushdown), Turso (writes + read pushdown + the differential oracle), and PostgreSQL (writes incl. atomic transaction batches + read pushdown over the universal tables, proven by the gated live differential suite — grust-postgres-core/tests/pg_cypher_live.rs, run with a reachable PostgreSQL via GRUST_PG_URL). The pushed read subset (see docs/GQL_PUSHDOWN2_GOAL.md) covers node/segment/var-length patterns, UNION, OPTIONAL MATCH, multi-pattern MATCH, the WITH horizon, catalog procedures, TVF row sources, CALL { … } subqueries (uncorrelated and correlated-WHERE), and endpoint-only shortest paths — with SQLite-gated leaves falling back to the reference on Spark, and the RETURN projection always running through the shared reference so pushed results match it by construction. Postgres-PGQ wraps the executing Postgres core store but does not yet delegate the executor surface; Falkor and Surreal are native-graph backends (backend-native Cypher / SurrealQL passthrough via run_native_cypher / run_native_surrealql); Helix/Ladybug are internal (publish=false); CocoIndex is a sync target. See GqlBackend::descriptor() and backend_manifest() for the honest per-backend capability flags (including native_passthrough languages and the W3 cross-variable correlated update, which only the Memory reference executes).