Trustfall — Engine for Querying (Almost) Everything

Trustfall is 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.

Try Trustfall in your browser
10min tech talk + demo
Examples of querying real-world data with Trustfall

Try Trustfall in your browser

The Trustfall Playground supports running queries against public data sources such as:

the HackerNews REST APIs: https://play.predr.ag/hackernews
the rustdoc JSON of top Rust crates: https://play.predr.ag/rustdoc

For example, this link shows the results of the HackerNews query: "Which GitHub or Twitter users are commenting on stories about OpenAI?"

In the Playground, Trustfall is configured to run client-side as WASM, performing all aspects of query processing (parsing, compilation, and execution) within the browser. While this demo highlights Trustfall's ability to be embedded within a target application, it is of course able to be used in a more traditional client-server context as well.

10min tech talk + demo

Trustfall was featured in the "How to Query (Almost) Everything" talk talk at the HYTRADBOI 2022 conference.

Demo from the talk showing the execution of the cross-API query: "Which GitHub Actions are used in projects on the front page of HackerNews with >=10 points?"

The demo executes the following query across the HackerNews and GitHub APIs and over the YAML-formatted GitHub repository workflow files:

{
  HackerNewsTop(max: 200) {
    ... on HackerNewsStory {
      hn_score: score @filter(op: ">=", value: ["$min_score"]) @output

      link {
        ... on GitHubRepository {
          repo_url: url @output

          workflows {
            workflow: name @output
            workflow_path: path @output

            jobs {
              job: name @output

              step {
                ... on GitHubActionsImportedStep {
                  step: name @output
                  action: uses @output
                }
              }
            }
          }
        }
      }
    }
  }
}

Instructions for running the demo are available together with the source code in the demo-hytradboi directory: link.

Examples of querying real-world data with Trustfall

HackerNews APIs, including an overview of the query language and an example of querying REST APIs.
RSS/Atom feeds, showing how to query structured data like RSS/Atom feeds.
airport weather data (METAR), showing how to query CSV data from aviation weather reports.

Trustfall also powers the cargo-semver-checks semantic versioning linter. More details on the role Trustfall plays in that use case are available in this blog post.

Using Trustfall over a new data source

The easiest way to plug in a new data source is by implementing the BasicAdapter trait.

Python bindings are available, and are built automatically on every change to the engine; the most recent version may be downloaded here. A getting started guide for Python is forthcoming (tracking issue); in the meantime, the best resource is the Python bindings' test suite.

Directory Registry

trustfall is a façade crate. This is the preferred way to use Trustfall.
trustfall_core contains the query engine internals
trustfall_derive defines macros that simplify plugging in data sources.
pytrustfall contains Trustfall's Python bindings
trustfall_wasm is a WASM build of Trustfall
trustfall_filetests_macros is a procedural macro used to generate test cases defined by files: they ensure that the function under test, when given an input specified by one file, produces an output equivalent to the contents of another file.
experiments contains various experimental projects such as the Trustfall web playground.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.