Trustfall: Querying APIs, Files and Databases Through One GraphQL Query

The problem Trustfall solves: one query, many sources

Most query work starts with a single store. Then a second source appears, and the joins move into application code: fetch a page of results from an API, loop over them, read a file for each one, merge by hand. Trustfall's claim is that this merging belongs in the query, not in your application. The README describes it as "a query engine for querying any kind of data source, from APIs and databases to any kind of files on disk, and even AI models."

The intended reader is a developer who already has more than one source and wants one place to express the combination. The demo from the HYTRADBOI 2022 talk is the clearest statement of that intent: a single query goes from HackerNews stories, out to the GitHub API for each linked repository, and then into the YAML workflow files inside those repositories. Three sources of different kinds, one query text. The README notes that in the browser playground Trustfall runs as WASM and does parsing, compilation and execution client-side, so the engine can be embedded in a target application rather than sitting behind a server.

How the engine runs a query across sources

The query language is GraphQL, but not GraphQL as a transport. The README's examples use `@filter`, `@output`, `@fold`, `@transform` and `@recurse` directives, and the playground sample uses `@filter(op: "regex", value: ["$sitePattern"])` with variables supplied separately as JSON. So a query is a GraphQL-shaped document with directives that tell the engine how to filter, aggregate and shape results.

The repository layout explains the split. `trustfall` is described as a facade crate and the preferred way to use the engine. `trustfall_core` holds the query engine internals. `trustfall_derive` provides macros that simplify plugging in data sources. `trustfall_stubgen` exists as a separate crate, which suggests schema stubs are generated rather than written by hand. `trustfall_filetests_macros` generates test cases from files, checking that a function given one input file produces output equivalent to another file. There is also a `spec.md` at the repository root, which is where the language itself is specified.

Data sources are attached by implementing the `BasicAdapter` trait in `trustfall_core`. That is the boundary: the engine owns parsing, compilation and execution, and the adapter owns whatever it takes to answer a question about your source. The README calls this "the easiest way to plug in a new data source," which is honest about the work being non-trivial rather than optional.

Installing Trustfall and running a first query

The README does not give a cargo install line for the engine itself, so the practical path is to add the facade crate to a Rust project and follow the examples rather than copy an install command that is not documented. The repository ships runnable examples under `trustfall/examples/`, and the README lists three: HackerNews APIs, RSS/Atom feeds, and airport weather data in METAR format read from CSV.

Start from the repository and run the example closest to your data. The weather example is the smallest useful one because the source is a local CSV file rather than a network service.

git clone https://github.com/obi1kenobi/trustfall
cd trustfall
cargo run --example weather

For the Python route, the README says bindings are built automatically on every change to the engine and the most recent version may be downloaded from the releases page. It also says a getting started guide is forthcoming and points at the bindings' test suite as the best current resource. That is a real gap, not a formality: the first thing a Python user needs is a working example, and the README sends them to `pytrustfall/trustfall/tests/test_execution.py` instead.

If you want to see the query language before writing any Rust, the browser playground runs against public data sources, including the HackerNews REST APIs and the rustdoc JSON of top Rust crates. The README's own playground link runs a query asking which GitHub or Twitter users comment on stories about OpenAI, with a depth-5 `@recurse` over comment replies and a `@fold` plus `@transform(op: "count")` to require at least one matching link in the commenter's bio.

Where Trustfall is the wrong tool

The engine does not remove the cost of connecting a source; it moves that cost behind a trait. If you have one database and one query, an adapter plus a schema is pure overhead, and the README does not pretend otherwise. The payoff only appears at the second or third source.

The second limitation is documentation depth. The README is strong on examples and weak on prose. Python has no getting started guide yet, only a tracking issue and a test suite. The README does not document rollback, migration or version compatibility between the engine and existing adapters, and it does not state what happens to an adapter when the engine's public API changes. The Cargo manifest is more informative than the README here: it separates dependencies that are part of the public API (anyhow, async-graphql-parser, async-graphql-value, serde, serde_json, thiserror, regex) from internal-only ones, and states that bumping a major version of a public-API dependency requires Trustfall's own major version bump. That is a useful guarantee, but you have to read the manifest to find it.

The third limitation is the language surface. Queries use GraphQL directives that are not standard GraphQL, so a reader who knows GraphQL will still need the spec and the examples to write anything non-trivial. The `@recurse`, `@fold` and `@transform` combination in the playground query is not something you guess at.

Trustfall compared with writing the joins yourself

The obvious alternative is not another query engine; it is a script. Fetch from the API, parse the files, join in memory, print. That approach has no schema, no adapter and no build step, and for a one-off question it wins on time. Its weakness is that every new question means new joining code, and the joining logic is where bugs live.

Trustfall's difference is that the join is expressed once in the query and the sources stay behind adapters. The HYTRADBOI demo is the case that separates the two approaches: HackerNews stories, then GitHub repositories, then the YAML workflow files inside them. Written as a script, that is three fetchers and two nested loops with error handling at each level. As a query, the source transitions are invisible from the query text, which is the point the README makes when it says the transition "isn't visible from the query."

A second alternative is a database that can already reach outside itself, for example a query engine with a foreign data wrapper. The difference is where the adapter lives. Trustfall's adapters are Rust code implementing `BasicAdapter`, compiled into your binary; a database extension lives in the database process. If you need the query to run inside a browser as WASM, the compiled-in model is the one that works, and the playground is evidence that it does.

Maintenance, versioning and licence cost

The last push to the default branch was on 2024-11-08, which is also the date of the `trustfall-v0.8.0` release. The two releases before it were `trustfall-v0.7.1` on 2023-11-17 and `trustfall-v0.6.1` on 2023-08-28. The repository is not archived, but the cadence is roughly one minor release a year, so plan for the engine to be stable rather than fast-moving. The workspace sets `rust-version = "1.91"` and `edition = "2024"`, which is a hard floor: an older toolchain will not build it.

The upgrade cost is concentrated in the public-API dependency list in the root Cargo manifest. Because anyhow, async-graphql-parser, async-graphql-value, serde, serde_json, thiserror and regex are declared part of the public API, a major bump in any of them forces a major bump in Trustfall, and a major bump in Trustfall is what reaches your adapter. The manifest is explicit that internal-only dependencies can move without that consequence. Checking that distinction before upgrading is cheaper than discovering it during one.

Licensing is Apache-2.0, stated in the manifest and in the README's licence section. The README's notice covers the usual Apache terms: the licence text is at apache.org, and the software is distributed without warranties or conditions unless required by law or agreed in writing. That is a permissive licence, but it is not legal advice, and if you redistribute Trustfall inside a product you should read the notice and the patent grant yourself rather than take a summary from an article.

Editorial conclusion

Adopt Trustfall if you need one query to span more than one data source and you are willing to write a Rust adapter for each source; the HackerNews, RSS and METAR examples show the shape of that work. Do not adopt it if a single-source query is enough, since the adapter and schema are real work that buys you nothing there. Before committing, run the example that matches your data shape and confirm the BasicAdapter trait covers the operations your source actually offers.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes