# Memgraph

MemGQL supports two Memgraph connector modes:

- **`memgraph`** — passthrough, forwards queries as-is (Cypher)
- **`memgraph-gql`** — translates GQL to Cypher before execution

## 1. Start Memgraph

```bash
docker network create memgql-net

docker run -d --rm \
    --name memgraph-dev \
    --network memgql-net \
    -p 7687:7687 \
    memgraph/memgraph-mage:3.13.1 \
    --log-level=TRACE --also-log-to-stderr
```

## 2. Start MemGQL (GQL mode)

```bash
docker run --rm \
    --name memgql \
    --network memgql-net \
    --stop-timeout 2 \
    -p 7688:7688 \
    --env CONNECTOR_TYPE=memgraph-gql \
    --env MEMGRAPH_URI=memgraph-dev:7687 \
    --env BOLT_LISTEN_ADDR=0.0.0.0:7688 \
    memgraph/memgql:latest
```

For passthrough mode, use `CONNECTOR_TYPE=memgraph` instead.

## 3. Connect

```bash
mgconsole --port 7688
```

## 4. Seed data

```gql
INSERT
  (alice:Person {name: "Alice", age: 30}),
  (bob:Person {name: "Bob", age: 25}),
  (acme:Company {name: "Acme Corp"}),
  (alice)-[:KNOWS]->(bob),
  (alice)-[:WORKS_AT {role: "Engineer"}]->(acme);
```

## 5. Query

```gql
MATCH (p:Person) RETURN p.name, p.age;
```

```gql
MATCH (p:Person)-[:WORKS_AT]->(c:Company) RETURN p.name, c.name;
```

```gql
MATCH (a:Person)-[:KNOWS]->(b:Person) RETURN a.name, b.name;
```

A statement prefixed with `CYPHER` is [parsed as Cypher](https://memgraph.com/docs/memgraph-zero/memgql/reference#query-languages)
and executes on Memgraph verbatim — Cypher-only syntax like variable-length
`[:KNOWS*1..2]` works as-is:

```cypher
CYPHER MATCH (a:Person)-[:KNOWS*1..2]->(b:Person) RETURN a.name, b.name;
```

```
+---------+---------+
| a.name  | b.name  |
+---------+---------+
| "Alice" | "Bob"   |
+---------+---------+
```

For environment variables, see [Reference](https://memgraph.com/docs/memgraph-zero/memgql/reference#memgraph-memgraph-memgraph-gql).

## Supported GQL features

GQL-specific syntax (INSERT, LOCAL_DATETIME, etc.) only works on `memgraph-gql`; the plain `memgraph` connector is Cypher passthrough.

| Feature                                       | Memgraph |
|-----------------------------------------------|----------|
| `MATCH` / `WHERE` / `RETURN`                  | ✓        |
| Pattern-level `WHERE` (`MATCH (n WHERE …)`)   | ✓        |
| Multi-MATCH (cross-join)                      | ✓        |
| `OPTIONAL MATCH`                              | ✓        |
| `WITH` pipeline boundary                      | ✓        |
| `WITH DISTINCT` / `WITH … ORDER BY … LIMIT N` | ✓        |
| Chained `WITH … WITH …`                       | ✓        |
| Whole-node `WITH n` carry-through             | ✓        |
| Typed edge `(a)-[r:R]->(b)`                   | ✓        |
| Untyped edge `()-[]->(b)`                     | ✓        |
| `UNION` / `UNION ALL` / `UNION DISTINCT`      | ✓        |
| `INTERSECT` / `EXCEPT`                        | ✗        |
| Quantified path `(){m,n}` — bounded           | ✓        |
| Quantified path `(){m,}` — unbounded          | ✓        |
| Shortest-path (`ALL SHORTEST` / `SHORTEST k`) | ✓        |
| Path binding `MATCH p = (…) RETURN p`         | ✓        |
| Whole-node `RETURN n`                         | ✓        |
| 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`                          | ✓        |
| Temporals (`date`, `LOCAL_DATETIME`, …)       | ✓        |
| `INSERT (a {…}) RETURN a.x`                   | ✓        |
| `DELETE` / `DETACH DELETE`                    | ✓        |
| `SET` / `REMOVE` (property update / delete)   | ✓        |