GraphLift

One typed query contract over three graph databases and an edge store. Compose a query once; each dialect renders it — or refuses it by name, rather than emitting something that runs and means something else.

Pre-release. Nothing here is published to a registry yet, and this page says which parts are built and which are planned.

One description, four dialects. Where a dialect cannot express the request, it refuses it by name rather than emitting something that means something else.

The contract

A graph query is not portable by accident. Every backend has operations the others do not, and a layer that papers over the difference silently changes what your query means.

So the contract is explicit about it. Each backend's translator declares, per operation, what it can render and what it cannot — and where it cannot, the reason is the one measured against that server.

The same suite judges all four. Each implementation runs assert_dialect_translator_laws, which needs no server: rendering is pure, so it proves the four renderings are comparable, not that a server accepts them.

Acceptance is a separate suite with a server behind it. assert_result_reader_laws writes, reads back and compares against a pinned server in CI for each of the three databases, and against the edge store running locally. The table below says which.

Backends

Backend Dialect Read side run against
TypeDB TypeQL 3.x a pinned TypeDB server in CI
Neo4j Cypher pinned Neo4j servers in CI, Community and Enterprise
TerminusDB JSON-LD WOQL a pinned TerminusDB server in CI
edgegraph (SQLite in a Cloudflare Durable Object) SQL over one graph layout the store under wrangler dev --local in CI

Compare the four, capability by capability. All four are landed. The three databases are live-tested against pinned servers in CI; the edge store runs under wrangler dev --local in its own CI job. No other backend is in progress — this page used to promise Weaviate and ArangoDB as upcoming, and nothing in the tree was ever started for either.

For agents

graphlift-mcp is an MCP server over the contract, speaking stdio — the transport Claude Desktop and most MCP clients use. Three tools:

backends
What each dialect declares it can render, per operation — with the measured reason where a capability is absent.
check
Would this request render for this backend? Answers supported, or refuses by name, without emitting a query.
render
The query, or the same refusal. A returned query is one the dialect declared it can render.

What it does not do: execute. It renders and refuses, and opens no connection, takes no credential and runs no transaction — that decision is graphlift#463. Reaching data is a separate binary, graphlift-exec: read-only unless given --allow-write, capped by a timeout and a row limit, with one audit line per call, so an agent's reach is the set of binaries and flags you grant it. There is no HTTP MCP API. This page advertised three HTTP endpoints for query building, schema and migration while no route served any of them (graphlift#441).

Clients for the edge

@graphlift/typedb-clients speaks TypeDB 3.x's HTTP API, so one transport serves Node 18+, browsers and Cloudflare Workers, and the subpath entry points differ only in their defaults. There is also a Durable Object connection pool in @graphlift/typedb-cloudflare.

HTTP only. Not gRPC: npm's typedb-driver tops out at 2.29.7, which a 3.x server refuses outright, and no 3.x driver is published there (graphlift#243). No WebSocket client exists either. This page once claimed three transports over a module whose own first comment names the one it does not speak.

Installing

Nothing is published yet. The npm entry package is @graphlift/typedb, and the release workflow publishes it and its workspace dependency closure on a v* tag — but it lands inert: no registry token is configured, so a tag stops at a named error rather than reaching npm (graphlift#440). Until then, build from source:

git clone https://github.com/CaptainEmpower/graphlift
cd graphlift
pnpm install
cargo build --locked --manifest-path crates/graphlift-cli/Cargo.toml
cargo build --locked --manifest-path crates/graphlift-exec/Cargo.toml
cargo build --locked --manifest-path crates/graphlift-mcp/Cargo.toml

Each Rust product is its own workspace, so there is no single build. The CLI, the execution binary and the MCP server take the contract and the backends in by path. A bare cargo build --workspace at the root builds only the repository's own scripts and its BDD harness.

This page used to offer an install command for a package called graphlift-client. No package of that name exists in this repository or on npm, and the command is not reproduced here — a wrong command in a code block is one copy-paste away from being run.

The CLI

graphlift, the CLI — what works today:

  • graphlift backends — the capability table the contract declares
  • graphlift db schema introspect — read a live database's schema back as TypeQL, Cypher or JSON-LD
  • graphlift db schema diff — compare a live schema with its migrations or with another database's, and exit 4 when they differ
  • graphlift db ping — reach the server the environment names and open one database, writing nothing
  • graphlift db create, list and drop — manage a server's databases; drop takes the name twice
  • graphlift migrate — create a migration from what changed on a server, apply it, roll it back, and report applied state
  • graphlift sync — copy schema and data from one backend's database into another's, the edge store included; it previews unless given --allow-write, and --move, given --allow-source-delete as well, deletes from the source only what it verified on the target
  • graphlift query — render a query for a backend, or refuse it by name; it prints the query and runs nothing
  • graphlift generate types — typed Rust or TypeScript models from the schema, offline from the migrations or from a live database
  • graphlift new and graphlift init — scaffold a project with a sample query and a migrations directory
  • graphlift validate — check that every query description in a project renders, exit 2 on a refusal
  • graphlift dev — serve the same answers as the render commands over local HTTP while you edit
  • graphlift ai query — a plain-language request, by keyword matching, rendered by the contract for TypeDB, Neo4j or TerminusDB, or refused by name

And what does not. Every subcommand that only refused was removed (graphlift#362), so graphlift --help lists what works and nothing else.

Natural language

A keyword parser turns a plain-language request into a contract request. No model is called: the configured AI provider is printed and not used.

It does not read your schema. No database is consulted. Given --schema, the file is not parsed and a fixed example set (person, company, employment) is used instead; without it the type list is empty. So the types a generated query names are not checked against anything you have.

Through the contract, and unit-tested only, with no benchmark, so nothing here measures how often it is right. The sentence becomes the same request graphlift query --spec takes, and the contract renders it for the backend you name or refuses it; what a request cannot say, such as an average, is declined by name rather than answered with a count (graphlift#464).

Where to look

The datasheet grades every capability ✅ Verified, 🟦 By design, 🟡 Partial, 🔴 Aspirational or ⚪ Planned, with the evidence that backs it. If this page and that document ever disagree, the document is the one under a CI gate.