Skip to main content

Aquery Environment

Query Value Types​

*[string]: a string. For example non_quoted_string or "quoted string"

  • string: a string. For example non_quoted_string or "quoted string"

*[integer]: an integer. query integers must be positive and fit in a u32

  • integer: an integer. query integers must be positive and fit in a u32

*[target expression]: a target expression, either a literal or the return value of a function

  • target expression: A target set expression. This could be a literal build target ("cell//some:target"), a literal build target pattern ("cell//package:" or "cell//recursive/...") or the result of another function that returns a target set. For queries in cli commands (like buck2 query), literals can be relative to the current working dir (like some:target or ...).

*[file expression]: a file expression, either a literal or the return value of a function

  • file expression: A file set expression. This could be a file literal like path/to/a.file or the return value of a function that returns files (for example, the buildfile() function).

*[target or file expression]: a file or target expression, either a literal or the return value of a function

  • target or file expression: A file set or target set expression. This could be a literal like path/to/a.file or "cell//some:target", or the return value of a function that returns files or targets.

*[query expression]: a valid query expression, evaluated in a function-specific context

  • query expression: A query expression. This is used for functions that capture an expression and evaluate it in another context. For example, the deps() function can accept an expression that it uses to find the children of a node to customize the deps traversal.

*[any value]: Any query value.

  • any value: Any query value.

Common query functions​

  • allpaths(from: target expression, to: target expression): Computes all dependency paths.

  • somepath(from: target expression, to: target expression)

  • attrfilter(attr: string, value: string, targets: target expression): The attrfilter(attribute, value, targets) operator evaluates the given target expression and filters the resulting build targets to those where the specified attribute contains the specified value.

  • nattrfilter(attr: string, value: string, targets: target expression)

  • attrregexfilter(attr: string, value: string, targets: target expression)

  • buildfile(targets: target expression)

  • rbuildfiles(universe: file expression, argset: file expression)

  • allbuildfiles(universe: target expression)

  • deps(targets: target expression, depth: ?integer, captured_expr: ?query expression)

  • filter(regex: string, set: target or file expression): Filter using regex partial match.

  • inputs(targets: target expression)

  • kind(regex: string, targets: target expression): The kind(regex, targets) operator evaluates the specified target expression, targets, and returns the targets where the rule type matches the specified regex.

  • labels(attr: string, targets: target expression): This function is not implemented, and won't be, because buck2 query core does not support

  • owner(files: file expression): The owner(inputfile) operator returns the targets that own the specified inputfile.

  • targets_in_buildfile(files: file expression)

  • rdeps(universe: target expression, targets: target expression, depth: ?integer)

  • testsof(targets: target expression)

  • first_order_deps(): A filter function that can be used in the query expression of deps query function.

  • target_deps(): A filter function that can be used in the query expression of deps query function.

  • exec_deps(): A filter function that can be used in the query expression of deps query function.

  • configuration_deps(): A filter function that can be used in the query expression of deps query function.

  • toolchain_deps(): A filter function that can be used in the query expression of deps query function.

  • intersect(left: any value, right: any value): Computes the set intersection over the given arguments.

  • except(left: any value, right: any value): Computes the arguments that are in argument A but not in argument B.

  • union(left: any value, right: any value): Computes the set union over the given arguments.

allpaths(from: target expression, to: target expression)​

Computes all dependency paths.

The allpaths(from, to) function evaluates to the graph formed by paths between the target expressions from and to, following the dependencies between nodes. For example, the value of buck query "allpaths('//foo:bar', '//foo/bar/lib:baz')" is the dependency graph rooted at the single target node //foo:bar, that includes all target nodes that depend (transitively) on //foo/bar/lib:baz.

The two arguments to allpaths() can themselves be expressions. For example, the command: buck query "allpaths(kind(java_library, '//...'), '//foo:bar')" shows all the paths between any java_library in the repository and the target //foo:bar.

We recommend using allpaths() with the --output-format=dot parameter to generate a graphviz file that can then be rendered as an image. For example:

$ buck query "allpaths('//foo:bar', '//foo/bar/lib:baz')" --output-format=dot --output-file=result.dot
$ dot -Tpng result.dot -o image.png

Graphviz is an open-source graph-visualization software tool. Graphviz uses the dot language to describe graphs.

somepath(from: target expression, to: target expression)​

attrfilter(attr: string, value: string, targets: target expression)​

The attrfilter(attribute, value, targets) operator evaluates the given target expression and filters the resulting build targets to those where the specified attribute contains the specified value.

In this context, the term attribute refers to an argument in a build rule, such as name, headers, srcs, or deps.

  • If the attribute is a single value, say name, it is compared to the specified value, and the target is returned if they match.
  • If the attribute is a list, the target is returned if that list contains the specified value.
  • If the attribute is a dictionary, the target is returned if the value exists in either the keys or the values of the dictionary.

For example: buck2 query "attrfilter(deps, '//foo:bar', '//...')" returns the build targets in the repository that depend on //foo:bar, or more precisely: those build targets that include //foo:bar in their deps argument list.

nattrfilter(attr: string, value: string, targets: target expression)​

attrregexfilter(attr: string, value: string, targets: target expression)​

buildfile(targets: target expression)​

rbuildfiles(universe: file expression, argset: file expression)​

allbuildfiles(universe: target expression)​

deps(targets: target expression, depth: ?integer, captured_expr: ?query expression)​

filter(regex: string, set: target or file expression)​

Filter using regex partial match.

Target are matched against their fully qualified name. Files are matched against their repo path like repo//foo/bar/baz.py.

inputs(targets: target expression)​

kind(regex: string, targets: target expression)​

The kind(regex, targets) operator evaluates the specified target expression, targets, and returns the targets where the rule type matches the specified regex.

The specified pattern can be a regular expression. For example, buck2 query "kind('java.*', deps('//foo:bar'))" returns the targets that match the rule type java.* (java_library, java_binary, etc.) in the transitive dependencies of //foo:bar.

labels(attr: string, targets: target expression)​

This function is not implemented, and won't be, because buck2 query core does not support

returning both files and targets from a single function.

In buck1 it returns targets and files referenced by the given attribute in the given targets.

Some discussion in T126638795.

owner(files: file expression)​

The owner(inputfile) operator returns the targets that own the specified inputfile.

In this context, own means that the target has the specified file as an input. You could consider the owner() and inputs() operators to be inverses of each other.

Example: buck2 query "owner('examples/1.txt')" returns the targets that owns the file examples/1.txt, which could be a value such as //examples:one.

It is possible for the specified file to have multiple owners, in which case, owner() returns a set of targets.

If no owner for the file is found, owner() outputs the message: No owner was found for <file>

targets_in_buildfile(files: file expression)​

rdeps(universe: target expression, targets: target expression, depth: ?integer)​

testsof(targets: target expression)​

first_order_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the output of deps function for the immediate dependencies of the given targets. Output is equivalent to deps(<targets>, 1).

Example: buck2 cquery "deps('//foo:bar', 1, first_order_deps())"`` is equivalent to buck2 cquery "deps('//foo:bar', 1)"`

target_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the target dependencies of each dependency of the given targets, excluding any configuration, toolchain and execution dependencies (build time dependencies) like compiler used as a part of the build.

Example: `buck2 cquery "deps('//foo:bar', 1, target_deps())"``

exec_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the output of deps function for execution dependencies (build time dependencies), ex. compiler used as a part of the build.

Example: `buck2 cquery "deps('//foo:bar', 1, exec_deps())"``

configuration_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the output of deps function for configuration dependencies (that appear as conditions in selects).

Example: `buck2 cquery "deps('//foo:bar', 1, configuration_deps())"``

toolchain_deps()​

A filter function that can be used in the query expression of deps query function.

Returns the output of deps function for toolchain dependencies.

Example: `buck2 cquery "deps('//foo:bar', 1, toolchain_deps())"``

intersect(left: any value, right: any value)​

Computes the set intersection over the given arguments.

Can be used with the ^ symbol. This operator is commutative.

The parser treats this operator as left-associative and of equal precedence, so we recommend that you use parentheses if you need to ensure a specific order of evaluation. A parenthesized expression resolves to the value of the expression it encloses.

Example: buck2 aquery "deps('//foo:bar') intersect deps('//baz:lib')" is the same as buck2 aquery "deps('//foo:bar') ^ deps('//baz:lib')" Both return the targets that appear in the transitive closure of //foo:bar and //baz:lib.

except(left: any value, right: any value)​

Computes the arguments that are in argument A but not in argument B.

Can be used with the - symbol. This operator is NOT commutative.

The parser treats this operator as left-associative and of equal precedence, so we recommend that you use parentheses if you need to ensure a specific order of evaluation. A parenthesized expression resolves to the value of the expression it encloses.

Example: buck2 aquery "deps('//foo:bar') except deps('//baz:lib')" is the same as buck2 aquery "deps('//foo:bar') - deps('//baz:lib')" Both return the targets that //foo:bar depends on and that //baz:lib does NOT depend on.

union(left: any value, right: any value)​

Computes the set union over the given arguments.

Can be used with the + symbol. This operator is commutative.

The parser treats all this operator as left-associative and of equal precedence, so we recommend that you use parentheses if you need to ensure a specific order of evaluation. A parenthesized expression resolves to the value of the expression it encloses.

Example: buck2 aquery "deps('//foo:bar') union deps('//baz:lib')" is the same as buck2 aquery "deps('//foo:bar') + deps('//baz:lib')" Both return the aggregation of the targets that //foo:bar and //baz:lib depend on.

Query functions​

  • all_outputs(targets: target expression): Obtain the actions for all the outputs provided by the DefaultInfo for the targets passed

  • all_actions(targets: target expression): Obtain all the actions declared within the analysis of a given target.

all_outputs(targets: target expression)​

Obtain the actions for all the outputs provided by the DefaultInfo for the targets passed

as input. This includes both the default_outputs and other_outputs.

This operation only makes sense on a target literal (it does nothing if passed something else).

all_actions(targets: target expression)​

Obtain all the actions declared within the analysis of a given target.

This operation only makes sense on a target literal (it is a simple passthrough when passed an action).