# Quick Start MemGQL is a federated GQL (ISO/IEC 39075) query engine that translates GQL queries into backend-native languages and executes them across graph databases. Clients connect via the Bolt protocol (port 7688) using any Bolt-compatible driver. ## Prerequisites - [Docker](https://docs.docker.com/get-started/get-docker/) - [mgconsole](https://github.com/memgraph/mgconsole) (Memgraph Bolt CLI client) ## Quick Start: Memgraph + MemGQL ### 1. Create a Docker network ```bash docker network create memgql-net ``` ### 2. Start Memgraph ```bash 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 ``` ### 3. Start MemGQL ```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 ``` ### 4. Connect with mgconsole ```bash mgconsole --port 7688 ``` ### 5. Seed some data ```gql INSERT (lana:Developer {name: "Lana", level: "senior", yoe: 12}), (marco:Developer {name: "Marco", level: "mid", yoe: 5}), (priya:Developer {name: "Priya", level: "senior", yoe: 9}), (rs:Language {name: "Rust", releaseYear: 2010}), (go:Language {name: "Go", releaseYear: 2009}), (ts:Language {name: "TypeScript", releaseYear: 2012}), (acme:Startup {name: "Acme Labs", funding: 4200000}), (nova:Startup {name: "Nova AI", funding: 18500000}), (lana)-[:WRITES {since: 2018}]->(rs), (lana)-[:WRITES {since: 2021}]->(go), (marco)-[:WRITES {since: 2022}]->(ts), (priya)-[:WRITES {since: 2019}]->(rs), (priya)-[:WRITES {since: 2020}]->(ts), (lana)-[:MENTORS]->(marco), (priya)-[:MENTORS]->(marco), (lana)-[:EMPLOYED_AT {role: "CTO"}]->(acme), (marco)-[:EMPLOYED_AT {role: "Backend Engineer"}]->(nova), (priya)-[:EMPLOYED_AT {role: "Tech Lead"}]->(nova); ``` ### 6. Run GQL queries Count all nodes in the graph: ```gql MATCH () RETURN count(*); ``` Return developers and their experience: ```gql MATCH (d:Developer) RETURN d.name, d.yoe; ``` Filter with WHERE inside the pattern (GQL syntax): ```gql MATCH (d:Developer WHERE d.yoe > 8) RETURN d.name, d.level; ``` Label expression with IS keyword: ```gql MATCH (s IS Startup) RETURN s.name, s.funding; ``` OR label expression — match multiple labels at once: ```gql MATCH (n:Language|Startup) RETURN n; ``` Edge pattern with direction and type: ```gql MATCH (:Developer)-[w:WRITES]->(lang:Language) RETURN lang.name, w.since; ``` Edge with WHERE clause: ```gql MATCH (:Developer)-[w:WRITES WHERE w.since < 2020]->(lang:Language) RETURN lang.name; ``` Path variable binding: ```gql MATCH p = (:Developer)-[:MENTORS]->(:Developer) RETURN p; ``` Two-hop traversal — who mentors someone employed at a startup: ```gql MATCH (senior:Developer)-[:MENTORS]->(junior:Developer)-[:EMPLOYED_AT]->(s:Startup) RETURN senior.name, junior.name, s.name; ``` Variable-length path (quantified path pattern): ```gql MATCH (d:Developer {name: "Lana"})-[:MENTORS]->{1,3}(mentee:Developer) RETURN mentee.name; ``` ## Environment Variables See [Reference](https://memgraph.com/docs/memgraph-zero/memgql/reference) for the full list of environment variables and connector-specific settings. ## Mapping File A mapping describes how a relational backend's tables appear as graph labels and relationship types: node labels over tables (`vertices`), edge types over association tables (`edges`). The full field reference is on the [Schema File](https://memgraph.com/docs/memgraph-zero/memgql/schema-file) page. The example below is a standalone mapping body, the shape `MAPPING_FILE` expects. Create a mapping file: ```bash cat > mapping.json << 'EOF' { "vertices": [ { "label": "Person", "mappedTableSource": { "table": "persons", "metaFields": { "id": "id" } }, "attributes": [ { "name": "name" }, { "name": "age", "type": "Int" } ] }, { "label": "Company", "mappedTableSource": { "table": "companies", "metaFields": { "id": "id" } }, "attributes": [ { "name": "name" } ] } ], "edges": [ { "label": "KNOWS", "from": "Person", "to": "Person", "mappedTableSource": { "table": "knows", "metaFields": { "id": "id", "from": "from_id", "to": "to_id" } } }, { "label": "WORKS_AT", "from": "Person", "to": "Company", "mappedTableSource": { "table": "works_at", "metaFields": { "id": "id", "from": "person_id", "to": "company_id" } } } ] } EOF ``` ## Connecting your data with a schema file Declare your backends and the graphs over them in one file, boot from it, and query straight away, then add more whenever you need. ### 1. Write a schema file A schema file declares the backends (`connectors`) and the graphs mapped over them. Here is a minimal `schema.json` with one Memgraph connector and an `engineering` graph over the data you seeded above: ```json { "connectors": [ { "name": "mg", "type": "memgraph", "connection": { "uri": "memgraph-dev:7687" } } ], "graphs": [ { "name": "engineering", "vertices": [ { "label": "Developer", "mappedGraphSource": { "connector": "mg" } }, { "label": "Language", "mappedGraphSource": { "connector": "mg" } } ], "edges": [ { "label": "WRITES", "from": "Developer", "to": "Language", "mappedGraphSource": { "connector": "mg" } } ] } ] } ``` See the [Schema File](https://memgraph.com/docs/memgraph-zero/memgql/schema-file) page for every field. ### 2. Boot from it Point MemGQL at the file. Every connector connects and every graph registers at startup, with no further setup. This reuses the Memgraph you started above, so stop the MemGQL container you started earlier (Ctrl-C) to free port 7688: ```bash docker run --rm -p 7688:7688 \ --network memgql-net \ -e BOLT_LISTEN_ADDR=0.0.0.0:7688 \ -v "$(pwd)/schema.json:/data/schema.json" \ memgraph/memgql:latest --schema=/data/schema.json ``` ### 3. Query ```bash mgconsole --port 7688 ``` No `USE` clause is needed; the query routes to `engineering` by its labels. ```gql MATCH (d:Developer)-[:WRITES]->(l:Language) RETURN d.name, l.name LIMIT 5; ``` ### 4. Add more backends at runtime Register more connectors and graphs live, without a restart. Changes persist back to `schema.json`. For example, with a PostgreSQL reachable on the same network, add it and map a `store` graph over one of its tables: ```gql ADD CONNECTOR pg TYPE postgres URI 'postgresql://postgres:postgres@postgres-dev:5432/postgres'; CREATE GRAPH store FROM '{ "vertices": [ { "label": "Customer", "mappedTableSource": { "connector": "pg", "table": "customers", "metaFields": { "id": "id" } }, "attributes": [ { "name": "name" } ] } ] }'; MATCH (c:Customer) RETURN c.name LIMIT 5; ``` `CREATE GRAPH … FROM` also accepts `FROM FILE ''` (the [mapping file](#mapping-file) format). Pinot can additionally run as a single backend via the `CONNECTION_TYPE` alias (`CONNECTION_TYPE=pinot PINOT_URL=…`). ### 5. Introspection ```gql SHOW CONNECTORS; SHOW GRAPHS; SHOW MAPPINGS; SHOW SCHEMA; PING mg; ``` ### 6. Cleanup ```gql DROP GRAPH store; DROP CONNECTOR pg; ``` ## MemGQL Statements Reference | Statement | Description | |----------------------------------------------------------|------------------------------------------| | `ADD CONNECTOR TYPE [options...]` | Register a backend connector (connection)| | `DROP CONNECTOR ` | Remove a connector | | `CREATE GRAPH FROM '' \| FROM FILE ''`| Define a graph (mapping) over connectors | | `DROP GRAPH [IF EXISTS] ` | Remove a graph | | `ALTER GRAPH SET READ ONLY \| READ WRITE` | Toggle a graph's access mode | | `ALTER GRAPH SET CACHE CONNECTOR [...]` | Cache a graph in Memgraph | | `USE ` | Route a query to a named graph | | `PING ` | Test a connector is alive | | `SHOW CONNECTORS` / `SHOW CONNECTIONS` | List connectors / live connections | | `SHOW GRAPHS` / `SHOW GRAPH ` | List graphs / one graph's details | | `SHOW MAPPINGS` | List per-graph mappings | | `SHOW SCHEMA` / `REFRESH SCHEMA` | Routing index / re-introspect | | `EXPORT SCHEMA [TO '']` | Export the catalog as JSON |