[RFC] turbo query

[NicholasLYang]

Abstract

turbo query is a new command that lets you query data about your repository using GraphQL.

How to try

In a repository using turbo@>2.1.0

Run turbo query to open a GraphiQL session. To directly execute a query, you can pass the query as a parameter:

turbo query "query { package(name: \"web\") { name }"

In a repository using turbo@<2.1.0

You can avoid upgrading your repository by using npx for a one-off turbo command.

npx turbo@latest query --skip-infer

We look forward to hearing your feedback on this feature!

Background

Turborepo computes a lot of data about your repository so that it can execute your tasks with maximum efficiency. This includes your package dependency graph, changed packages, task dependencies, log output from your tasks, and so on. This data is potentially quite useful for getting insights into your codebase, and also for third party tools.

Previously, Turborepo has added APIs for structured data, such as [run summaries](https://turbo.build/repo/docs/reference/run#--summarize) and [dry run](https://turbo.build/repo/docs/reference/run#--dry----dry-run). However, these APIs have some limitations. For one, they’re centered around a single run, not general repository info. Second, as we added more and more fields, the output quickly became rather bloated. For small repositories, that’s not a huge deal, but in larger codebases, this output started stretching into the megabytes.

We need a way to query repository data in a run-agnostic fashion, and make the returned data more customizable. However, we don’t intend on replacing dry run or run summaries. Our goal is to facilitate understanding in large repositories, while also making a tool that’s easy to use for everyone.

Solution

We’re introducing a new command, turbo query. This command will allow users to run GraphQL queries against Turborepo’s repository data.

Running turbo query will open up GraphiQL, a custom IDE for writing GraphQL queries. Alternatively, you can pass the query directly as a string:

turbo query "query { package(name: \"web\") { name } }"

or pass a file path:

turbo query myQuery.gql

Some example queries include:

Which packages have more than 10 immediate dependents:

query {
  packages(
    filter: {
      greaterThan: { field: DIRECT_DEPENDENT_COUNT, value: 10 }
    }
  ) {
    name
  }
}

They can get the changed packages within a git range

query {
  affectedPackages(base: "main", head: "HEAD") {
    name
  }
}

They can find a specific package and get its direct dependencies

query {
  package(name: "cli") {
    directDependencies {
      name
    }
  }
}

And much more! To learn more, run turbo query on the latest canary to open up GraphiQL, GraphQL’s built in IDE, with a full schema explorer.

We also plan on integrating live run output into this query interface, so you can query the status of your running tasks.

Feedback

We would love feedback on turbo query! The goal here is to help our users, i.e. you, create scripts and checks using Turbo’s knowledge. Therefore, it’s really important to us that turbo query works for you.

Specifically, we would like to know:

• What queries do you want?
• Do you have other query languages that you’d prefer over GraphQL?
• What would you build on top of this?

[maschwenk]

What queries do you want?

• Obviously in addition to immediate dependents it'd be cool to see transitive dependents
• We could use that data to easily calculate the most "weighty" packages (e.g. if you change this leaf node here you will invalidate the whole graph's cache)
• If we could combine that data with git data (or vercel api data for those who use the managed services) on how often these dependency are changing, you could get a data-dependent assessment of this "weight"
  • This would mean that leaf nodes that are depended on by everything but not actually changed very much would not be considered as weighty as ones that do change a lot
• Also include data (either locally or from Vercel api) about execution time and cache hit rates
• Maybe even suggestions about dead dependencies or opportunities to simplify dependency structures

Do you have other query languages that you’d prefer over GraphQL?

• Nope. Seems Good™. Probably a fair number of Turbo users are using GraphQL as their backend already.

What would you build on top of this?

• Tooling to help answer the question: "Which of my packages are invalidating the cache the most and wasting developers time". Such that using that data you could start breaking down monolithic packages/tasks that are too easily invalidated into smaller chunks that are scoped more effectively.
• It follows that good package design yields good cache semantics, which leads to happier developers and less time waiting for things
• We could pipe this data into Datadog

[NicholasLYang]

Obviously in addition to immediate dependents it'd be cool to see transitive dependents

Yep! That's implemented. We have directDependents, allDependents and indirectDependents, where allDependents is the transitive dependents and indirectDependents is allDependents - directDependents

If we could combine that data with git data (or vercel api data for those who use the managed services) on how often these dependency are changing, you could get a data-dependent assessment of this "weight"

We have a query for getting the affected packages in a git range (affectedPackages). I also have a PR up for getting the affected files and mapping those to the packages, so you can get insights into which files are causing these changed packages.

Also include data (either locally or from Vercel api) about execution time and cache hit rates

Yes, definitely Vercel integration is high priority

Maybe even suggestions about dead dependencies or opportunities to simplify dependency structures

Dead dependencies are a little tricky cause they require tracing through file dependencies, but that's coming hopefully soon.

Tooling to help answer the question: "Which of my packages are invalidating the cache the most and wasting developers time". Such that using that data you could start breaking down monolithic packages/tasks that are too easily invalidated into smaller chunks that are scoped more effectively.

Yep! We've noticed this as a pretty common request. Looking into it.

[rafaeltab]

First I'd like to say that I really love this feature. Being able to query the monorepo using a simple well known query language like graphql is amazing.

What queries do you want?

• Query results from a run or multiple runs, such as duration, hashes, etc. (Calculate the min, avg, max duration of a task)
• Query the task definitions, such as querying all inputs for a task in a specfic package (Get all files that are used as input for a specific task in a specific package)
• Query the live terminal output, (the actual text outputted by the command)
• NPM dependencies of a task
• Use a query to filter packages and tasks to run using turbo run
• Use a query to determine the hash of a task

Would you use another language?
For querying the data that is outputted by turbo I think GraphQL is an excellent choice. If it would also become an option to use a query file to influence the hash or filter of turbo run I think another language is probably better suited, perhaps open policy agent could be used, or something based on hcl.

What would you build on top of this?

• UI for neovim that has the output inside the editor itself as a buffer
• Find out which tasks are very slow and which are very fast
• Find out which tasks run really often
• List which packages depend on what npm packages
• Influence hash of a task for this purpose: Shallow dependencies #9124
• Use a query to decide which tasks to run (We love the current --filter , but actual query files would be amazing)

[weyert]

Would this help with answering the question why a particular package gets rebuild instead of using a cache?

[NicholasLYang]

Yep! That's exactly the goal. There's already a query for getting the affected packages in a git range, and I have a PR up for getting the changed files in a git range, which can in turn be linked to a package