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

-- Connectors (connections only)
ADD CONNECTOR <name> TYPE <type>
    [URI '<uri>'] [PATH '<path>']
    [USER '<user>'] [PASSWORD '<pass>']
    [CATALOG '<catalog>'] [SCHEMA '<schema>'] [GRAPH '<db>'];
DROP CONNECTOR <name>;
PING <connector>;

-- Graphs (mappings over connectors)
CREATE GRAPH <name> FROM '<json>';        -- inline { "vertices": …, "edges": … } body
CREATE GRAPH <name> FROM FILE '<path>';   -- same body from a file
DROP GRAPH [IF EXISTS] <name>;
ALTER GRAPH <name> SET READ ONLY;
ALTER GRAPH <name> SET READ WRITE;

-- Query-driven cache
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

A connector is a connection only; it carries no graph shape. GRAPH <db> selects the Cypher database on Memgraph / Neo4j (it is not a mapping). Re-adding a connector replaces its config; DROP CONNECTOR is refused while a graph still references it.

CREATE GRAPH … FROM registers a graph from a { "vertices": …, "edges": … } body and auto-connects the connectors it references. The mapping format is documented on the Schema File page; the same body loads at boot via --schema.

SET CACHE CONNECTOR makes a graph cache-enabled: touched labels and edge types are copied into the 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).

-- Introspection
SHOW CONNECTORS;                 -- registered connectors
SHOW CONNECTIONS;                -- live connections
SHOW GRAPHS [ON CONNECTOR <c>];  -- registered graphs (name, connector(s), type, access, counts)
SHOW GRAPH <name>;               -- one graph's details
SHOW MAPPINGS;                   -- per-graph mappings
SHOW SCHEMA [FOR <graph>];       -- unified routing index: labels, rel-types, properties
EXPORT SCHEMA [TO '<path>'];     -- merged catalog as canonical schema JSON (round-trippable)
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>;

-- Routing: 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 → 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';
-- then map it into a graph
CREATE GRAPH sales FROM FILE '/data/sales.graph.json';

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

A graph’s mapping declares its vertices and edges: labels and relationship types mapped to backend tables (via metaFields and attributes) or to native graph sources. The full format, with field tables and worked examples, lives on the Schema File page.

The same mapping body is used everywhere a graph is defined:

• --schema=<path> at boot: connectors + graphs in one file.
• CREATE GRAPH <name> FROM '<json>' / FROM FILE '<path>' at runtime.
• MAPPING_FILE in single-connector mode: a bare { "vertices": …, "edges": … } body (the connector comes from the environment).

A mapping with a required field missing (for example a relational edge without metaFields.from / metaFields.to) is rejected before the server serves queries against it. The legacy nodes / id_column / rel_type format is no longer accepted; loading it raises an actionable error pointing at the new format.