Trustfall: A Query Engine That Treats APIs and Files as One Database

The Problem: Querying Across Silos Without Custom Glue

Most engineers face a familiar pain: data lives in a REST API, a CSV file, a database, and a YAML config, and answering a cross-cutting question means writing custom code to fetch, join, and filter each source separately. Trustfall addresses this by providing a query engine that treats any combination of data sources as a single queryable database. It is designed for developers who need to ask questions like "Which GitHub Actions are used in projects on the front page of HackerNews with >=10 points?" which requires hitting the HackerNews API, the GitHub API, and parsing YAML workflow files. The intended audience is not end users but developers building tools that need to query across data sources, such as linters, analyzers, or data exploration utilities. The README highlights that Trustfall powers cargo-semver-checks, a semantic versioning linter, which is a concrete example of this use case.

How Trustfall Works: Adapters and a GraphQL-Like Language

Trustfall does not store data. Instead, it compiles a query written in a GraphQL-like syntax into an execution plan that delegates to adapters for each data source. The core mechanism is the BasicAdapter trait, which you implement to plug in a new source. The query language supports directives like @filter, @output, @fold, and @transform, allowing you to filter, project, and aggregate results. The data flow is visible in the README's cross-API example: a query starts at a root type like HackerNewsTop, then traverses edges to related types (Story, link, GitHubRepository, workflows, jobs, step). Each edge is resolved by the corresponding adapter, which may call an external API or parse a file. The engine orchestrates these calls, and the transition between sources is seamless from the query's perspective; the README notes that the transition is not visible from the query. This separation means that the query language is independent of the underlying data format, whether it is REST, RSS, CSV, or YAML.

Getting It Running: From Playground to Your Own Adapter

The fastest way to try Trustfall is the Playground, which runs queries in the browser via WASM against public data sources like HackerNews and rustdoc JSON. You can open a pre-built query link that demonstrates a cross-API query. For local development, the repository is organized into several crates: trustfall is the façade crate, trustfall_core contains the engine internals, and trustfall_derive provides macros to simplify adapter implementation. To use Trustfall over a new data source, the README says the easiest path is implementing the BasicAdapter trait, which is documented at docs.rs. There are example projects in the trustfall/examples directory for HackerNews, RSS/Atom feeds, and airport weather data (METAR) in CSV format. Python bindings exist in pytrustfall, but the getting started guide is forthcoming; the README directs you to the test suite as the best resource. The demo-hytradboi directory contains source code and instructions for running the conference demo, which shows the cross-API query in action.

Where Trustfall Struggles: Adapter Complexity and Performance Uncertainty

Trustfall's power comes with a cost: you must implement an adapter for each new data source, and that adapter must expose the right schema and traversal logic. The README does not provide a full tutorial for writing adapters, only pointing to the trait and examples. For a source with complex authentication, pagination, or rate limits, the adapter will need to handle those concerns, and the engine cannot magically optimize network calls. The README mentions that the Playground runs in WASM, which implies that for large data sets, performance may be constrained by the browser environment. There is no benchmark data in the material, so claims about speed, such as the blog post title mentioning a 2000x speedup for cargo-semver-checks, are specific to that use case and not generalizable. A user expecting Trustfall to be a drop-in replacement for a database query engine will be disappointed: it is an orchestration layer, and the underlying sources' latency dominates.

Comparing to Alternatives: GraphQL Federation and Custom ETL

The closest alternative to Trustfall is GraphQL federation, where a single GraphQL endpoint aggregates multiple services. The difference is that federation typically requires each service to expose a GraphQL schema and uses a gateway to stitch them, whereas Trustfall does not require the sources to speak GraphQL; they only need an adapter that implements a trait. Another alternative is writing custom ETL scripts that fetch data from each source and merge them in code, but that approach lacks a declarative query language and makes cross-source joins manual. Trustfall's advantage is that the query language is uniform, so you can express complex traversals like recursive comments (the README shows @recursive(depth: 5)) without writing loops. However, federation benefits from existing infrastructure and tooling, while Trustfall requires more upfront adapter work. For a single source, a standard SQL database or a dedicated client library is simpler and more efficient.

Maintenance and Licensing: What to Expect

Trustfall is licensed under Apache-2.0, which permits commercial use and modification, but you should review the license terms for your specific use case. The repository shows active development with a release in November 2024 (v0.8.0), but the release cadence is irregular: v0.7.1 came a year earlier. The project is not archived, and the last push is recent, suggesting ongoing maintenance. The codebase is modular, with separate crates for core, derive macros, WASM, and Python bindings, which can ease upgrades but also means you need to track multiple versions. The README mentions that Python bindings are built automatically on every change, but the lack of a getting started guide is a maintenance gap for new users. For production use, you should pin a specific version and test your adapters against engine updates, as the API for BasicAdapter may change between minor versions.

Editorial conclusion

Adopt Trustfall if you need to query across heterogeneous data sources with a single, declarative language, especially if you are building tools like cargo-semver-checks or need browser-based querying via WASM. Do not use it if your data sources are all in one SQL database, where a standard query language and mature tooling already exist. Before adopting, verify that the BasicAdapter trait is sufficient for your data source's access patterns, and check whether the Python bindings are stable enough for your workflow, since the getting started guide is still forthcoming.

Official sources

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