MemGQL: connectors + schema-graph model docs

pages/memgraph-zero/memgql/_meta.ts

@@ -3,6 +3,7 @@ export default {
   "use-cases": "Use Cases",
   "features": "Features",
   "connect": "Connect",
+  "schema-file": "Schema File",
   "multiple-graphs": "Multiple Graphs",
   "complete": "Docker Compose",
   "reference": "Reference",

pages/memgraph-zero/memgql/changelog.mdx

@@ -5,11 +5,38 @@ description: MemGQL release notes
 
 # MemGQL Changelog
 
-## MemGQL v0.7.1 - July 19th, 2026
+## MemGQL v0.8.0 - July 19th, 2026
 
 ### ✨ New features & Improvements
 
--
+### ⚠️ Breaking changes
+
+- **New graph model: connectors + schema graphs.** A **connector** is now a pure
+  connection and a **graph** is a mapping (`vertices` + `edges`) laid over one or
+  more connectors. Register a connection with `ADD CONNECTOR`, then define a graph
+  with `CREATE GRAPH <name> FROM '<json>'` / `FROM FILE '<path>'`, or boot the
+  whole catalog from a single [`--schema`](/memgraph-zero/memgql/schema-file) file.
+- **New mapping format.** Mappings use `vertices` / `edges` with
+  `mappedTableSource` (relational) or `mappedGraphSource` (native), `metaFields`
+  (`id` / `from` / `to`), and `attributes`. The legacy `nodes` / `edges` format
+  (`id_column`, `source_label`, `rel_type`) is no longer accepted; loading it
+  raises an actionable error pointing at the new format.
+- **Removed statements.** `ADD GRAPH … ON CONNECTOR`, `UNADD GRAPH`,
+  `ALTER GRAPH SET CONNECTOR / GRAPH / MAPPING`, `ADD MAPPING` / `DROP MAPPING`,
+  and the connection-scoped `CONNECT … AS`, `DISCONNECT`, `USE CONNECTION`, and
+  `SET DEFAULT CONNECTION` are gone. Register connectors + graphs instead and
+  query by graph name (`USE <graph>`) or let routing pick the graph.
+
+### ✨ New features & Improvements
+
+- **Query graphs without `USE`.** [Schema-based routing](/memgraph-zero/memgql/multiple-graphs#routing)
+  infers the target graph from the labels, relationship types, and declared
+  properties a query mentions; ambiguity is an actionable error. Explicit
+  `USE <graph>` remains the override.
+- **Caching engages under routing.** A cache-enabled graph is populated
+  and served whether a part is pinned with `USE` or routed by label. Re-issuing
+  `ALTER GRAPH … SET CACHE` now drops stale fragments, so re-pointing the cache
+  can't serve a stale result.
 
 ## MemGQL v0.7.0 - July 5th, 2026
 
@@ -64,7 +91,7 @@ description: MemGQL release notes
   RETURN e.name, i.total;
   ```
   Previously this join had to be spelled as `WHERE i.employee_id = e.id`. Works
-  USE-free (each part routes by its own labels) and with multiple keys
+  without `USE` (each part routes by its own labels) and with multiple keys
   (`{country: o.country, city: o.city}`).
 - **SQL Server connector.** New `sqlserver` connector type (aliases: `mssql`,
   `sql_server`, `sql-server`) translates GQL to T-SQL. The driver is
@@ -99,12 +126,12 @@ description: MemGQL release notes
 
 ### ✨ New features & Improvements
 
-- **Schema-based routing (USE-free queries).** In `multi` mode, queries no
+- **Schema-based routing.** In `multi` mode, queries no
   longer need a `USE <graph>` clause — the engine infers the backend from the
   query's schema signals (labels, rel-types, properties) against a unified schema
   index, built from mappings for SQL backends and live introspection for Cypher
 	backends. Routing is strict: exactly one candidate routes, zero or multiple
-	hard-error with the fix; explicit `USE` always wins. USE-free federated
+	hard-error with the fix; explicit `USE` always wins. Routed federated
 	`JOIN` and `UNION` work too, and writes route on a unique candidate. Two new
 	statements expose the index: **`SHOW SCHEMA [FOR <graph>]`** and **`REFRESH
 	SCHEMA`**. Identifier matching is now **exact** engine-wide. **Still gated

pages/memgraph-zero/memgql/complete.mdx

@@ -50,7 +50,7 @@ docker network create memgql-net
 MemGQL needs a graph mapping to translate graph patterns into SQL. Create
 these two files next to your `docker-compose.yml`:
 
-**`pg_init.sql`** — creates the relational tables:
+**`pg_init.sql`** creates the relational tables:
 
 ```sql
 CREATE TABLE users (
@@ -60,36 +60,52 @@ CREATE TABLE users (
 );
 
 CREATE TABLE friend_of (
+    id SERIAL PRIMARY KEY,
     user_id INTEGER NOT NULL REFERENCES users(id),
     friend_id INTEGER NOT NULL REFERENCES users(id),
-    PRIMARY KEY (user_id, friend_id)
+    UNIQUE (user_id, friend_id)
 );
 ```
 
-**`pg_mapping.json`** — tells MemGQL how tables map to graph labels:
+**`pg_mapping.json`** is a graph mapping body (`vertices` + `edges`) that maps the
+tables to graph labels on the `pg` connector:
 
 ```json
 {
-  "nodes": [
+  "vertices": [
     {
       "label": "User",
-      "table": "users",
-      "id_column": "id",
-      "properties": {
-        "name": "name",
-        "email": "email"
-      }
+      "mappedTableSource": {
+        "connector": "pg",
+        "table": "users",
+        "metaFields": {
+          "id": "id"
+        }
+      },
+      "attributes": [
+        {
+          "name": "name"
+        },
+        {
+          "name": "email"
+        }
+      ]
     }
   ],
   "edges": [
     {
-      "rel_type": "FRIEND_OF",
-      "table": "friend_of",
-      "id_column": "id",
-      "source_column": "user_id",
-      "target_column": "friend_id",
-      "source_label": "User",
-      "target_label": "User"
+      "label": "FRIEND_OF",
+      "from": "User",
+      "to": "User",
+      "mappedTableSource": {
+        "connector": "pg",
+        "table": "friend_of",
+        "metaFields": {
+          "id": "id",
+          "from": "user_id",
+          "to": "friend_id"
+        }
+      }
     }
   ]
 }
@@ -136,10 +152,8 @@ services:
       - -c
       - |
         echo "ADD CONNECTOR mg TYPE memgraph URI 'memgraph:7687' GRAPH memgraph;" | mgconsole --host memgql --port 7688 &&
-        echo "CONNECT mg AS mg_conn;" | mgconsole --host memgql --port 7688 &&
-        echo "ADD MAPPING pg_social FROM '/mappings/pg_mapping.json';" | mgconsole --host memgql --port 7688 &&
-        echo "ADD CONNECTOR pg TYPE postgres URI 'host=postgres user=postgres password=postgres dbname=postgres' MAPPING pg_social;" | mgconsole --host memgql --port 7688 &&
-        echo "CONNECT pg AS pg_conn;" | mgconsole --host memgql --port 7688 &&
+        echo "ADD CONNECTOR pg TYPE postgres URI 'host=postgres user=postgres password=postgres dbname=postgres';" | mgconsole --host memgql --port 7688 &&
+        echo "CREATE GRAPH social FROM FILE '/mappings/pg_mapping.json';" | mgconsole --host memgql --port 7688 &&
         echo "MemGQL bootstrap complete."
     depends_on:
       memgql:
@@ -248,21 +262,29 @@ docker compose ps
 
 You should see all eight services running: `memgraph`, `memgql`, `memgql-init`,
 `lab`, `postgres`, `memgql-mcp`, and `structured2graph`. The `memgql-init`
-container registers both connectors and exits — this is expected.
+container registers both connectors and exits; this is expected.
 
 ## 5. Connect with mgconsole
 
 ```bash
 mgconsole --port 7688
 ```
 
-Both the Memgraph and PostgreSQL connectors are already registered and
-connected by the `memgql-init` service. You can start querying right away.
+The `mg` and `pg` connectors and the `social` graph (over PostgreSQL) are
+already registered by the `memgql-init` service. We add the native Memgraph
+graph below, then query each by its labels: routing picks the graph, so no
+`USE` is required.
 
 ### Seed Memgraph with developers
 
+Register a native graph over the Memgraph connector, then insert developers (the
+`Developer` label routes to `dev`):
+
 ```gql
-SET DEFAULT CONNECTION mg_conn;
+CREATE GRAPH dev FROM '{
+  "vertices": [ { "label": "Developer", "mappedGraphSource": { "connector": "mg" } } ],
+  "edges":    [ { "label": "FOLLOWS", "from": "Developer", "to": "Developer", "mappedGraphSource": { "connector": "mg" } } ]
+}';
 ```
 
 ```gql
@@ -289,11 +311,7 @@ MATCH (a:Developer)-[:FOLLOWS]->(b:Developer) RETURN a.name, b.name;
 
 ### Seed PostgreSQL with users
 
-Switch to the PostgreSQL connection and insert users:
-
-```gql
-SET DEFAULT CONNECTION pg_conn;
-```
+Insert users; the `User` label routes to the `social` graph (PostgreSQL):
 
 ```gql
 INSERT (alice:User {name: "Alice", email: "alice@example.com"});
@@ -321,25 +339,20 @@ MATCH (u:User)-[:FRIEND_OF]->(f:User) RETURN u.name, f.name;
 
 ### Query across both backends
 
-Each connection is queried independently — MemGQL routes the query to
-the right backend based on the `USE CONNECTION` clause:
-
 ```gql
-USE CONNECTION mg_conn
-  MATCH (d:Developer)-[:FOLLOWS]->(f:Developer)
+MATCH (d:Developer)-[:FOLLOWS]->(f:Developer)
   RETURN d.name AS source, "FOLLOWS" AS rel, f.name AS target;
 ```
 
 ```gql
-USE CONNECTION pg_conn
-  MATCH (u:User)-[:FRIEND_OF]->(f:User)
+MATCH (u:User)-[:FRIEND_OF]->(f:User)
   RETURN u.name AS source, "FRIEND_OF" AS rel, f.name AS target;
 ```
 
 ## 6. Open Memgraph Lab
 
 Open [http://localhost:3000](http://localhost:3000) in a browser.
-Lab is pre-configured to connect to MemGQL on port 7688 — click
+Lab is pre-configured to connect to MemGQL on port 7688; click
 **Quick Connect** and start exploring visually.
 
 ## 7. Create mappings with structured2graph

pages/memgraph-zero/memgql/connect.mdx

@@ -17,4 +17,4 @@ description: MemGQL connector details and configuration.
 
 ## Multi-Connector
 
-Connect to multiple backends simultaneously. See the [Quick Start](/memgraph-zero/memgql/quick-start#multi-connection-mode) for details.
+Connect to multiple backends simultaneously. See the [Quick Start](/memgraph-zero/memgql/quick-start#connecting-your-data-with-a-schema-file) for details.

pages/memgraph-zero/memgql/connect/duckdb.mdx

@@ -90,7 +90,7 @@ For environment variables, see [Reference](../reference.mdx#duckdb-duckdb).
 | Typed edge `(a)-[r:R]->(b)`                   | ✓      |
 | Untyped edge `()-[]->(b)`                     | ✗      |
 | `UNION` / `UNION ALL` / `UNION DISTINCT`      | ✓      |
-| Quantified path `(){m,n}` — bounded           | ✓      |
+| Quantified path `(){m,n}` (bounded)           | ✓      |
 | Whole-node `RETURN n` / whole-rel `RETURN r`  | ✓      |
 | Map projections `RETURN n {.a, .b}`           | ✓      |
 | `IN` list membership `WHERE x IN [...]`       | ✓      |
@@ -106,11 +106,11 @@ For environment variables, see [Reference](../reference.mdx#duckdb-duckdb).
 | `SET` / `REMOVE` (property update / delete)   | ✗      |
 | `DETACH DELETE`                               | ✗      |
 | `INTERSECT` / `EXCEPT`                        | ✗      |
-| Quantified path `(){m,}` — unbounded          | ✗      |
+| Quantified path `(){m,}` (unbounded)          | ✗      |
 | Shortest-path (`ALL SHORTEST` / `SHORTEST k`) | ✗      |
 
 ## Known limitations
 
 - **Unbounded variable-length paths** (`()-[*]->()`) are rejected. Bound the depth (`{1,5}`) or run the query against a Cypher backend.
 - **`FOR x IN [...]` (UNWIND-style)** is rejected with an actionable error. Cypher backends (Memgraph, Neo4j) handle this syntax natively.
-- **Path variables on variable-length patterns** — `MATCH p = (a){1,3}(b) RETURN p` is not supported. Drop the `p =` binding (or query a Cypher backend) and `RETURN` the individual nodes / edges instead.
+- **Path variables on variable-length patterns**: `MATCH p = (a){1,3}(b) RETURN p` is not supported. Drop the `p =` binding (or query a Cypher backend) and `RETURN` the individual nodes / edges instead.

pages/memgraph-zero/memgql/connect/iceberg.mdx

@@ -13,7 +13,7 @@ Iceberg tables, and both fully qualify table references as
 
 | Connector        | `CONNECTOR_TYPE` | Execution                                                                 | Writes |
 |------------------|------------------|---------------------------------------------------------------------------|--------|
-| Direct (native)  | `iceberg-direct` | Native, in-process — reads Iceberg as Arrow directly from object storage  | ❌ read-only |
+| Direct (native)  | `iceberg-direct` | Native, in-process; reads Iceberg as Arrow directly from object storage   | ❌ read-only |
 | Trino            | `iceberg`        | GQL → Trino-dialect SQL, executed by a Trino engine                       | ✓ |
 
 **Which one should you use?**
@@ -28,7 +28,7 @@ Iceberg tables, and both fully qualify table references as
   fully contained in one Iceberg catalog**, or when you need writes. Trino
   executes joins, pruning, and aggregation server-side.
 
-Both connectors accept the same mapping file unchanged — a mapping written for
+Both connectors accept the same mapping file unchanged; a mapping written for
 one works against the other.
 
 ---
@@ -41,7 +41,7 @@ in-process** graph execution on Iceberg. It uses the
 [`iceberg-catalog-rest`](https://crates.io/crates/iceberg-catalog-rest) Rust
 crates to talk to the Iceberg REST Catalog and read table data as Apache Arrow
 record batches directly from object storage. There is **no Trino** and no SQL
-string — MemGQL owns the entire execution loop.
+string; MemGQL owns the entire execution loop.
 
 It is **read-only**: `INSERT`, `DELETE`, `SET`, and `REMOVE` return an explicit
 "unsupported" error.
@@ -293,4 +293,4 @@ aggregation run **in-process** over Arrow batches.
 | Aggregation                                   | ✓ (local)        | ✓               |
 | Time-travel (snapshot)                        | ✓                | ✓               |
 | `INSERT (a {…})`                              | ❌ (read-only)   | ✓               |
-| `DELETE` (no alias — Trino requirement)       | ❌ (read-only)   | ✓               |
+| `DELETE` (no alias; Trino requirement)        | ❌ (read-only)   | ✓               |

pages/memgraph-zero/memgql/connect/mysql.mdx

@@ -99,7 +99,7 @@ MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name;
 ## Dialect notes
 
 - Positional `?` parameter placeholders (no numbered `$1` form).
-- No `RETURNING` on `INSERT` — use `last_insert_id()` if you need the
+- No `RETURNING` on `INSERT`; use `last_insert_id()` if you need the
   generated row id.
 - Aliased single-table `DELETE` is emitted as the multi-table form
   `DELETE alias FROM table AS alias WHERE …` (MySQL 8.0+ requirement).
@@ -121,7 +121,7 @@ For environment variables, see [Reference](../reference.mdx#mysql-mysql).
 | Typed edge `(a)-[r:R]->(b)`                   | ✓     |
 | Untyped edge `()-[]->(b)`                     | ✗     |
 | `UNION` / `UNION ALL` / `UNION DISTINCT`      | ✓     |
-| Quantified path `(){m,n}` — bounded           | ✓     |
+| Quantified path `(){m,n}` (bounded)           | ✓     |
 | Whole-node `RETURN n` / whole-rel `RETURN r`  | ✓     |
 | Map projections `RETURN n {.a, .b}`           | ✓     |
 | `IN` list membership `WHERE x IN [...]`       | ✓     |
@@ -137,11 +137,11 @@ For environment variables, see [Reference](../reference.mdx#mysql-mysql).
 | `SET` / `REMOVE` (property update / delete)   | ✗     |
 | `DETACH DELETE`                               | ✗     |
 | `INTERSECT` / `EXCEPT`                        | ✗     |
-| Quantified path `(){m,}` — unbounded          | ✗     |
+| Quantified path `(){m,}` (unbounded)          | ✗     |
 | Shortest-path (`ALL SHORTEST` / `SHORTEST k`) | ✗     |
 
 ## Known limitations
 
 - **Unbounded variable-length paths** (`()-[*]->()`) are rejected. Bound the depth (`{1,5}`) or run the query against a Cypher backend.
 - **`FOR x IN [...]` (UNWIND-style)** is rejected with an actionable error. Cypher backends (Memgraph, Neo4j) handle this syntax natively.
-- **Path variables on variable-length patterns** — `MATCH p = (a){1,3}(b) RETURN p` is not supported. Drop the `p =` binding (or query a Cypher backend) and `RETURN` the individual nodes / edges instead.
+- **Path variables on variable-length patterns**: `MATCH p = (a){1,3}(b) RETURN p` is not supported. Drop the `p =` binding (or query a Cypher backend) and `RETURN` the individual nodes / edges instead.

pages/memgraph-zero/memgql/connect/oracle.mdx

@@ -14,7 +14,7 @@ relational tables.
 The driver is [oracle-rs](https://crates.io/crates/oracle-rs), a **pure-Rust**
 implementation of Oracle's TNS wire protocol, pooled via
 [deadpool-oracle](https://crates.io/crates/deadpool-oracle). No OCI / ODPI-C /
-Instant Client is required at build or runtime — the `memgraph/memgql:latest`
+Instant Client is required at build or runtime: the `memgraph/memgql:latest`
 Docker image ships only the bolt server binary plus TLS roots, and `cargo run`
 works on macOS, Linux, and Windows without any extra system packages.
 
@@ -122,14 +122,14 @@ MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name;
 - Positional bind variables use Oracle's native `:1`, `:2`, … form.
 - `LIMIT n OFFSET m` is rendered as the SQL-standard
   `OFFSET m ROWS FETCH NEXT n ROWS ONLY` (Oracle 12c+).
-- Aliased single-table `DELETE` is `DELETE FROM table alias WHERE alias.col …`
-  — Oracle accepts table aliases but does not allow the `AS` keyword in this
+- Aliased single-table `DELETE` is `DELETE FROM table alias WHERE alias.col …`.
+  Oracle accepts table aliases but does not allow the `AS` keyword in this
   position.
 - No `INSERT … RETURNING *`. Oracle supports `RETURNING <cols> INTO :out`, but
   this is bind-variable based and the planner stays bind-agnostic; the executor
   uses it only when the caller needs the auto-generated key.
 - Identifiers from the mapping file are emitted unquoted, so Oracle's
-  default UPPERCASE folding applies — match your mapping `table` / `id_column`
+  default UPPERCASE folding applies; match your mapping's `table` and column
   spellings to your physical schema accordingly.
 
 ## Multi-connection mode
@@ -138,10 +138,9 @@ Inside `CONNECTOR_TYPE=multi`, register Oracle the same way as any other
 backend:
 
 ```gql
-ADD MAPPING social FROM '/data/mapping.json';
-ADD CONNECTOR ora TYPE oracle URI 'oracle://system:oracle@oracle-dev:1521/FREEPDB1' MAPPING social;
-CONNECT ora AS ora_conn;
-USE CONNECTION ora_conn MATCH (n:Person) RETURN n.name LIMIT 5;
+ADD CONNECTOR ora TYPE oracle URI 'oracle://system:oracle@oracle-dev:1521/FREEPDB1';
+CREATE GRAPH social FROM FILE '/data/mapping.json';
+MATCH (n:Person) RETURN n.name LIMIT 5;
 ```
 
 For environment variables, see [Reference](../reference.mdx#oracle-oracle).

pages/memgraph-zero/memgql/connect/postgres.mdx

@@ -105,7 +105,7 @@ For environment variables, see [Reference](../reference.mdx#postgresql-postgres)
 | Typed edge `(a)-[r:R]->(b)`                   | ✓        |
 | Untyped edge `()-[]->(b)`                     | ✗        |
 | `UNION` / `UNION ALL` / `UNION DISTINCT`      | ✓        |
-| Quantified path `(){m,n}` — bounded           | ✓        |
+| Quantified path `(){m,n}` (bounded)           | ✓        |
 | Whole-node `RETURN n` / whole-rel `RETURN r`  | ✓        |
 | Map projections `RETURN n {.a, .b}`           | ✓        |
 | `IN` list membership `WHERE x IN [...]`       | ✓        |
@@ -121,11 +121,11 @@ For environment variables, see [Reference](../reference.mdx#postgresql-postgres)
 | `SET` / `REMOVE` (property update / delete)   | ✗        |
 | `DETACH DELETE`                               | ✗        |
 | `INTERSECT` / `EXCEPT`                        | ✗        |
-| Quantified path `(){m,}` — unbounded          | ✗        |
+| Quantified path `(){m,}` (unbounded)          | ✗        |
 | Shortest-path (`ALL SHORTEST` / `SHORTEST k`) | ✗        |
 
 ## Known limitations
 
 - **Unbounded variable-length paths** (`()-[*]->()`) are rejected. Bound the depth (`{1,5}`) or run the query against a Cypher backend.
 - **`FOR x IN [...]` (UNWIND-style)** is rejected with an actionable error. Cypher backends (Memgraph, Neo4j) handle this syntax natively.
-- **Path variables on variable-length patterns** — `MATCH p = (a){1,3}(b) RETURN p` is not supported. Drop the `p =` binding (or query a Cypher backend) and `RETURN` the individual nodes / edges instead.
+- **Path variables on variable-length patterns**: `MATCH p = (a){1,3}(b) RETURN p` is not supported. Drop the `p =` binding (or query a Cypher backend) and `RETURN` the individual nodes / edges instead.