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.

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.
• 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 <name> ON CONNECTOR <connector>
    [GRAPH <remote_name>]
    [MAPPING <mapping_name>]
    [READ ONLY];

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;

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/stderr) and, in parallel, to a log file. Both destinations are configured via CLI flags on the Bolt server binary.

CLI Flags

Log Levels

info is the most verbose level today. There is no debug or trace. The RUST_LOG environment variable is not consulted.

The log file always receives every log line — including queries, errors, and state changes — independent of the console --log-level. To silence the console while keeping a full file record, use --log-level=info-queries-only and tail the log file separately.

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.

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"
    }
  ]
}