Graph databases are not interchangeable, and tools that pretend they are change what your
queries mean without telling you. GraphLift takes the opposite position. It says exactly
what each backend can answer, and it refuses the rest by name.
The problem it solves
A query can fail in two ways. In the first, the server rejects it and you find out at once.
In the second, the server accepts it, but it means something other than
what you asked: a filter one dialect has no form for, a relation write that binds nothing,
an ordering applied after the limit instead of before it. Nothing errors. The numbers are
wrong.
That second failure is what a portability layer is most likely to cause, and it is the
one GraphLift is built to rule out. Every rendering is either one the dialect declared it
can produce, or a refusal you can read.
7 properties, each with the decision behind it
It refuses by name instead of guessing
Most portability layers fail quietly: a filter is dropped, an ordering lands after the limit, a write binds nothing. The query still returns, so nobody notices. Here every dialect declares what it can render, and anything it has not declared is refused before a query is emitted. The refusal names the capability, the operation and the measured reason.
A capability is declared per operation, not as a flag
A backend that can match a relation may still be unable to create one. Declarations are a matrix of capability × operation, so "Neo4j supports relations" is never a single yes. The matrix is what the CLI’s backends command prints and what the MCP backends tool hands an agent.
Something joins the shared tier only after all the servers answered it alike over a seed built so that each way they might differ gives a different answer. Comparison filters, ordering, paging, projection, aggregation and disjunction got in that way, and so did bounded walks, distinct results and degree in the graph-native tier.
The four translators do not just share a trait name. Each runs the same conformance laws against itself, and a reader-law suite writes, reads back and compares against a real backend in CI. A backend whose answer diverges fails the shared suite, not a test someone wrote to match it.
Typed answers, with absence kept distinct from null
A row maps the query’s variables to bindings: a node, a relation with its roles, or a scalar in the contract’s own value type. A variable the query did not bind is absent, not null. An attribute with several values comes back one value at a time on every backend.
The surfaces that render (the CLI’s query command and the MCP server) hold no credentials and open no connection. Execution is one separate binary, read-only unless told otherwise, bounded by a timeout and a row cap, and it writes an audit line for every run. You choose how much reach to give a person or an agent by choosing which binary they get.
A sync reads a graph through one backend’s contract and writes it through another’s, schema first. Identity is a key you declare, never a backend’s internal id. It previews unless allowed to write. A move copies, reads the target back to verify, and deletes from the source only the records it verified.
Every feature of that database, nothing in between
The database choice is a rewrite to undo. Every team learns every dialect.
Queries are written once against the contract. When you need a backend’s own terms, its native surface is still there beside the contract.
A lowest-common-denominator translation layer
One API
Where backends differ, the layer picks a meaning for you, silently.
Where backends differ, the difference is declared and asserted, and a request that would change meaning is refused by name.
Generating query text from a prompt
Fast to start
A query the server accepts but that means something else is the failure nobody sees.
An agent composes a structured request. The contract renders it or names why not, so the agent fixes its request rather than trusting its text.
How it is kept honest
A capability is not admitted when the code is written. It is admitted when a live suite
against each pinned server passes, and the decision record moves from Proposed to Accepted
in the commit whose run turned green. TypeDB, Neo4j and TerminusDB run as service
containers in CI. The edge store runs under wrangler dev --local.
Coverage has a floor per workspace that CI enforces, and the roadmap is checked against
the issue tracker on every pull request. Even this site is gated: CI fails if a page
names a command or an agent tool that does not exist, or brings back a claim that was
retracted. The datasheet grades every
capability with the evidence behind it.
What it is not, today
Not published. No crate or npm package is on a public registry yet;
you build from source (graphlift#895, graphlift#154).
Not a federated query engine. It copies and moves graphs between
backends; a single query across several at once is not planned
(docs/FEDERATION.md).
Not a lowest common denominator. Speciality features such as TypeDB
functions or Neo4j’s index kinds have no place in the schema contract yet
(graphlift#925). Use each backend’s native surface for those.
The TypeScript packages are not on the contract. The agnostic layer is
Rust, and the TypeScript packages do not sit on it (graphlift#302).