Supported GQL Query Features

What works today, split by backend category. “Cypher backends” means Memgraph and Neo4j (translation is largely passthrough); “SQL backends” means PostgreSQL, MySQL and DuckDB.

SQL Server, ClickHouse, Apache Iceberg, and Apache Pinot are also supported as connectors but with a narrower verified surface. See each connector’s page for the exact list of features each one supports.

Known limitations

• Unbounded variable-length paths on SQL backends (()-[*]->()) return an actionable error.
• Untyped edge traversal on SQL backends (MATCH ()-[]->(b) with no rel-type) returns an actionable error pointing users at declaring the edge type or running on a Cypher backend. The form is still accepted natively on Cypher backends.
• FOR x IN [...] (UNWIND-style) on SQL backends returns an actionable error pointing users at running the query on a Cypher backend. The form is still accepted natively on Cypher backends.
• DETACH DELETE on SQL backends currently executes as a plain DELETE — relationship rows are not detached. It deletes a node that has no relationship rows and otherwise surfaces the backend’s constraint error; don’t rely on it.
• Path variables on variable-length patterns — MATCH p = (a){1,3}(b) RETURN p is not yet supported on SQL backends. Drop the p = binding (or query a Cypher backend) and RETURN the individual nodes / edges instead.

Graph Management Query Syntax

ADD GRAPH [IF NOT EXISTS] <name> ON CONNECTOR <connector>
    [GRAPH <remote_name>]
    [MAPPING <mapping_name>]
    [READ ONLY]
    [CACHE CONNECTOR <cache_connector> [TTL <secs>] [MAX_BYTES <n>[K|M|G|T]]];

CREATE GRAPH <name>
    [{ <gql_schema_body> } | ANY]
    ON CONNECTOR <connector>;

UNADD GRAPH [IF EXISTS] <name>;
DROP GRAPH [IF EXISTS] <name>;

ALTER GRAPH <name> SET READ ONLY;
ALTER GRAPH <name> SET READ WRITE;
ALTER GRAPH <name> SET CONNECTOR <connector>;
ALTER GRAPH <name> SET GRAPH <remote_name>;
ALTER GRAPH <name> SET MAPPING <mapping_name>;
ALTER GRAPH <name> REMOVE MAPPING;
ALTER GRAPH <name> SET CACHE CONNECTOR <cache_connector> [TTL <secs>] [MAX_BYTES <n>[K|M|G|T]];
ALTER GRAPH <name> REMOVE CACHE;

SHOW GRAPH CACHES;   -- graph, cache_connector, ttl_secs, max_bytes, fragment count

ADD GRAPH IF NOT EXISTS succeeds as a no-op when the name is already registered — for re-runnable setup scripts; plain ADD GRAPH errors on a duplicate name.

CACHE CONNECTOR makes a graph cache-enabled: its scans are populated into a Memgraph cache connector on first read, and later covered queries are served from that cache — see Multiple Graphs → Caching. TTL is in seconds; MAX_BYTES accepts a plain byte count or a K/M/G/T binary suffix (e.g. 8G).

SHOW SCHEMA [FOR <graph>];   -- unified routing index: labels, rel-types, properties
REFRESH SCHEMA;              -- re-introspect live Cypher connections (Memgraph/Neo4j)

-- Single graph
USE <graph> <query>;

-- Composite
USE <graph1> <query>
UNION | UNION ALL | INTERSECT | INTERSECT ALL | EXCEPT | EXCEPT ALL
USE <graph2> <query>;

-- USE-free: routes automatically when the query's labels / rel-types /
-- properties match exactly one registered source (see Multiple Graphs).
<query>;

In multi mode, a query with no USE clause routes automatically when its schema signals (labels, relationship types, properties) match exactly one source; zero or multiple matches hard-error. Identifier matching is exact (:person ≠ Person). Memgraph sources must run with --schema-info-enabled for property-level introspection. See Multiple Graphs → USE-free routing.

Configuration Reference

General

Logging

MemGQL writes log lines to the console (stdout for most levels, stderr for ERROR and CRITICAL) and, in parallel, to a log file. Both destinations receive the same stream, filtered by --log-level. Both are configured via CLI flags on the Bolt server binary.

CLI Flags

Log Levels

Levels form a severity ladder — picking a level also emits everything more severe. Values are case-insensitive (--log-level=debug and --log-level=DEBUG are the same; WARN is accepted for WARNING).

An unknown level fails at startup with an actionable error listing the valid values. The RUST_LOG environment variable is not consulted.

To see query traffic and what MemGQL translates it into, run with --log-level=DEBUG. The info-queries-only value from earlier releases was removed in v0.7.0 — see the changelog.

Enterprise License

When set, the license is decoded and verified against the organization name at startup. A valid enterprise license removes connector and connection limits. Without a license, community mode allows up to 2 connectors and 2 simultaneous connections.

Connector Types

Memgraph (memgraph, memgraph-gql)

Neo4j (neo4j, neo4j-gql)

PostgreSQL (postgres)

MySQL (mysql)

Oracle (oracle)

The Oracle connector uses oracle-rs, a pure-Rust implementation of Oracle’s TNS wire protocol, pooled via deadpool-oracle. No OCI / ODPI-C / Instant Client is required at build or runtime — the bundled Docker image ships only the bolt server binary plus TLS roots, and local builds work on macOS, Linux, and Windows without any extra system packages.

SQL Server (sqlserver)

SQL Server has no standalone environment-variable mode — CONNECTOR_TYPE=sqlserver is not supported. Register it at runtime in multi mode with an ADO-style connection string:

ADD CONNECTOR mssql TYPE sqlserver
    URI 'Server=localhost,1433;Database=test;User Id=sa;Password=YourPassword;TrustServerCertificate=true'
    MAPPING <mapping>;

mssql, sql_server, and sql-server are accepted aliases for the sqlserver type. See the SQL Server connector page.

DuckDB (duckdb)

ClickHouse (clickhouse)

Apache Pinot (pinot)

Iceberg (iceberg)

Iceberg Direct (iceberg-direct)

Native, in-process execution over Iceberg — reads the REST catalog and object storage (S3/MinIO) directly, no Trino. Read-only.

S3 path-style access is always enabled (s3.path-style-access=true).

Mapping Schema

The graph mapping file is a JSON document with two top-level arrays: nodes and edges. MemGQL loads it either from the path in MAPPING_FILE at startup or via the ADD MAPPING <name> FROM '<path>' statement at runtime — both paths apply the same validation. A mapping with any required field missing is rejected before the server begins serving queries against it.

{
  "nodes": [ /* NodeMapping objects */ ],
  "edges": [ /* EdgeMapping objects */ ]
}

Node mapping fields

Connector-specific fields:

• Iceberg also accepts catalog and schema_name to fully qualify the table reference (defaults: "iceberg", "default").
• ClickHouse also accepts database (default: "default").

Edge mapping fields

Connector-specific fields are the same as for nodes (catalog / schema_name for Iceberg; database for ClickHouse).

Example

{
  "nodes": [
    {
      "label": "Person",
      "table": "persons",
      "id_column": "id",
      "properties": { "name": "full_name", "age": "age" }
    },
    {
      "label": "Company",
      "table": "companies",
      "id_column": "id"
    }
  ],
  "edges": [
    {
      "rel_type": "KNOWS",
      "table": "knows",
      "id_column": "id",
      "source_column": "from_id",
      "target_column": "to_id",
      "source_label": "Person",
      "target_label": "Person"
    },
    {
      "rel_type": "WORKS_AT",
      "table": "works_at",
      "id_column": "id",
      "source_column": "person_id",
      "target_column": "company_id",
      "source_label": "Person",
      "target_label": "Company"
    }
  ]
}