ClickHouse
The ClickHouse connector (CONNECTOR_TYPE=clickhouse) translates GQL queries
into ClickHouse-dialect SQL and executes them via the ClickHouse HTTP interface.
It requires a mapping file that maps graph
patterns to ClickHouse tables.
1. Start ClickHouse
docker network create memgql-net
docker run -d --rm \
--name clickhouse-dev \
--network memgql-net \
-p 9000:9000 \
-p 8123:8123 \
--ulimit nofile=262144:262144 \
-e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
-e CLICKHOUSE_PASSWORD="" \
clickhouse/clickhouse-server:latest2. Seed data
docker exec -i clickhouse-dev clickhouse-client << 'SQL'
CREATE TABLE IF NOT EXISTS persons (
id UInt32,
name String,
age UInt32
) ENGINE = MergeTree() ORDER BY id;
CREATE TABLE IF NOT EXISTS companies (
id UInt32,
name String
) ENGINE = MergeTree() ORDER BY id;
CREATE TABLE IF NOT EXISTS knows (
from_id UInt32,
to_id UInt32
) ENGINE = MergeTree() ORDER BY (from_id, to_id);
CREATE TABLE IF NOT EXISTS works_at (
person_id UInt32,
company_id UInt32
) ENGINE = MergeTree() ORDER BY (person_id, company_id);
INSERT INTO persons VALUES (1, 'Alice', 30), (2, 'Bob', 25);
INSERT INTO companies VALUES (1, 'Acme Corp');
INSERT INTO knows VALUES (1, 2);
INSERT INTO works_at VALUES (1, 1);
SQL3. Start MemGQL
docker run --rm \
--name memgql \
--network memgql-net \
--stop-timeout 2 \
-p 7688:7688 \
--env CONNECTOR_TYPE=clickhouse \
--env CLICKHOUSE_URL=http://clickhouse-dev:8123 \
--env CLICKHOUSE_DB=default \
--env MAPPING_FILE=/data/mapping.json \
-v ./mapping.json:/data/mapping.json \
memgraph/memgql:latest4. Connect
mgconsole --port 76885. Query
MATCH (p:Person) RETURN p.name, p.age;MATCH (p:Person)-[:WORKS_AT]->(c:Company) RETURN p.name, c.name;MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name;For environment variables, see Reference.
Supported GQL features
| Feature | ClickHouse |
|---|---|
MATCH / WHERE / RETURN | ✓ |
Pattern-level WHERE (MATCH (n WHERE …)) | ✓ |
Multiple MATCH clauses in one query | ✓ |
OPTIONAL MATCH | ✓ |
WITH clause (chain query steps) | ✓ |
WITH DISTINCT / WITH … ORDER BY … LIMIT N | ✓ |
Multiple chained WITH steps | ✓ |
Pass a whole node through WITH n | ✓ |
Typed edge (a)-[r:R]->(b) | ✓ |
Untyped edge ()-[]->(b) | ✗ |
UNION / UNION ALL / UNION DISTINCT | ✓ |
INTERSECT / EXCEPT | ✓ |
EXISTS { … } / pattern predicates | ✓ |
CALL { … } subquery | ✗ |
Quantified path (){m,n} / *m..n (bounded) | ✗ |
Whole-node RETURN n / whole-rel RETURN r | ✓ |
Map projections RETURN n {.a, .b} | ✓ |
IN list membership WHERE x IN [...] | ✓ |
STARTS WITH / ENDS WITH / CONTAINS | ✓ |
collect() aggregate | ✓ |
count, sum, avg, min, max | ✓ |
COUNT(DISTINCT …) | ✓ |
Arithmetic + - * / % | ✓ |
CASE WHEN … THEN … ELSE … END | ✓ |
COALESCE, NULLIF | ✓ |
CAST(x AS STRING | INT | FLOAT | BOOLEAN) | ✓ |
Scalar functions (upper, abs, char_length, …) | ✓ |
Cypher functions (toUpper, substring, toInteger, …) | ✓ |
Query parameters ($x) | ✓ |
date('YYYY-MM-DD') returns a Date | ✓ |
FOR x IN [...] / UNWIND | ✗ |
INSERT (a {…}), incl. an edge between matched nodes | ✓ |
INSERT (a {…}) RETURN a.x | ✓ |
DELETE | ✓ (ALTER TABLE … DELETE) |
SET / REMOVE (property update / delete) | ✗ |
DETACH DELETE | ✗ |
Quantified path (){m,} (unbounded) | ✗ |
Shortest-path (ALL SHORTEST / SHORTEST k) | ✗ |
Integer division (5 / 2 is 2)¹ | ✓ |
| Boolean literals as 1/0 | ✓ |
¹ Integer division needs the property typed as an integer ("type": "Int") in
the mapping; otherwise it divides as floating point.