Skip to main content

Aquery Environment

Functions​

  • all_actions: Obtain all the actions declared within the analysis of a given target.
  • all_outputs: Obtain the actions for all the outputs provided by the DefaultInfo for the targets passed
  • allbuildfiles: Target build file with transitive imports.
  • allpaths: All dependency paths.
  • attrfilter: Rule attribute filtering.
  • attrregexfilter: Rule attribute filtering with regex.
  • buildfile: Target build file.
  • configuration_deps: A filter function that can be used in the query expression of deps query function.
  • deps: Find the dependencies of the targets in the given target universe.
  • except: Computes the arguments that are in argument A but not in argument B.
  • exec_deps: A filter function that can be used in the query expression of deps query function.
  • filter: Filter targets or files by regex.
  • first_order_deps: A filter function that can be used in the query expression of deps query function.
  • inputs: Non-transitive inputs.
  • intersect: Computes the set intersection over the given arguments.
  • kind: Filter targets by rule type.
  • labels: Not implemented.
  • nattrfilter: Negative rule attribute filtering, opposite of attrfilter.
  • owner: Targets owning the given file.
  • rbuildfiles: Build file reverse dependencies.
  • rdeps: Find the reverse dependencies of the targets in the given target universe.
  • somepath: Shortest dependency path between two sets of targets.
  • target_deps: A filter function that can be used in the query expression of deps query function.
  • targets_in_buildfile: Targets in build file.
  • testsof: Tests of specified targets.
  • toolchain_deps: A filter function that can be used in the query expression of deps query function.
  • union: Computes the set union over the given arguments.

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).

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).

allbuildfiles(universe: target expression)​

Target build file with transitive imports.

For each target in the provided target expression, returns the build file where the target is defined, along with all transitive imports of that file.

For example:

$ buck2 uquery 'allbuildfiles(//foo:bar)'

foo/BUCK
foo/defs_dependent_on_utils.bzl
baz/utils.bzl

allpaths(from: target expression, to: target expression, captured_expr: ?query expression)​

All dependency paths.

Generates a graph of paths between the target expressions from and to, based on the dependencies between nodes.

For example:

$ buck2 uquery "allpaths('//foo:bar', '//foo/bar/lib:baz')"

returns the dependency graph rooted at the target node //foo:bar, including all target nodes that transitively depend on //foo/bar/lib:baz.

Arguments from and to can themselves be expressions, for example:

$ buck2 uquery "allpaths(kind(java_library, '//...'), '//foo:bar')"

shows all the paths between any target with rule type java_library in the repository and the target //foo:bar.

We recommend using it with the --output-format=dot parameter to generate a Graphviz DOT file that can then be rendered as an image.

$ buck2 uquery "allpaths(//buck2:buck2, //buck2/app/buck2_validation:buck2_validation)" --output-format=dot > result.dot
$ dot -Tpng result.dot -o image.png

produces the following image:

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

Rule attribute filtering.

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 uquery "attrfilter(deps, '//buck2/app/buck2_validation:buck2_validation', '//...')"

//buck2/app/buck2:buck2-bin
//buck2/app/buck2_server:buck2_server
//buck2/app/buck2_server:buck2_server-unittest

returns targets that contain //buck2/app/buck2_validation:buck2_validation target in their deps attribute.

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

Rule attribute filtering with regex.

Similar to the attrfilter function except that it takes a regular expression as the second argument.

For example:

$ buck2 uquery "attrregexfilter(deps, '.+validation$', '//...')"

//buck2/app/buck2:buck2-bin
//buck2/app/buck2_server:buck2_server
//buck2/app/buck2_server:buck2_server-unittest

returns targets whose deps attribute contains at least one target suffixed with 'validation'.

buildfile(targets: target expression)​

Target build file.

For each target in the provided target expression, returns the build file where the target is defined.

For example:

$ buck2 uquery 'buildfile(//buck2:buck2)'

buck2/BUCK

In order to find the build file associated with a source file, combine the owner operator with buildfile. Examples:

$ buck2 uquery "buildfile(//buck2/app/buck2_action_impl_tests:buck2_action_impl_tests)"

and

$ buck2 uquery "buildfile(owner(app/buck2_action_impl_tests/src/context.rs))"

both return buck2/app/buck2_action_impl_tests/TARGETS.

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())"

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

Find the dependencies of the targets in the given target universe.

The first parameter targets is a specific target or target pattern. It specifies the targets to find dependencies for. The second argument depth is an optional integer literal specifying an upper bound on the depth of the search. A value of one (1) specifies that buck query should return only direct dependencies. If the depth parameter is omitted, the search is unbounded. The third argument captured_expr is an optional filter expression that controls the traversal. The expression is evaluated for each node and returns the child nodes to recurse on when collecting transitive dependencies. Available filters are configuration_deps(), exec_deps(), first_order_deps(), target_deps(), and toolchain_deps().

The first_order_deps() operator returns a set that contains the first-order dependencies of the current node. It can be combined with other filter functions, for example, kind(java_library, first_order_deps()) to make the deps traversal only traverse java_library targets. The first_order_deps() operator can only be used as an argument passed to deps().

The returned values include the nodes from the targets argument itself.

For example following uquery:

$ buck2 uquery "deps(//buck2:buck2, 1)"

returns all targets that //buck2:buck2 depends on directly.

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.

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())"

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

Filter targets or files by regex.

Use regex partial match to filter either a target expression or file expression.

  • Targets are matched against their fully-qualified name, such as cell//foo/bar:baz.
  • Files are matched against a repo path, such as cell//foo/bar/baz.py.

For example:

$ buck2 uquery "filter(validation$, //buck2/app/...)"

//buck2/app/buck2_validation:buck2_validation

returns all targets within //buck2/app that have a label with a validation suffix.

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).

See deps() for more information on how filter expressions work.

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

inputs(targets: target expression)​

Non-transitive inputs.

For each target in the provided target expression, returns the files which are an immediate input to the rule function and thus are needed to go through analysis phase (i.e. produce providers).

You could consider the inputs() and owner() functions to be inverses of each other.

For example:

$ buck2 uquery "inputs(//buck2/dice/...)"

returns the direct inputs for the //buck2/dice/... targets.

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.

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

Filter targets by rule type.

Returns a subset of 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'))"

This command returns targets matching rule type java.* (e.g., java_library, java_binary) in the transitive dependencies of //foo:bar.

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

Not implemented.

This function won't be implemented in the future, 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.

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

Negative rule attribute filtering, opposite of attrfilter.

Evaluates the given target expression and filters the resulting build targets to those where the specified attribute doesn't contain 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 don't match.
  • If the attribute is a list, the target is returned if that list doesn't contain the specified value.
  • If the attribute is a dictionary, the target is returned if the value doesn't exist in both the keys and the values of the dictionary.

For example:

$ buck2 uquery "nattrfilter(deps, '//foo:bar', '//...')"

returns targets that don't contain //foo:bar target in their deps attribute.

owner(files: file expression)​

Targets owning the given file.

Returns all targets that have a specified file as an input.

owner() and inputs() functions are inverses of each other.

If the specified file has multiple owning targets, a set of targets is returned. If no owner exists, an empty set is returned.

For example:

$ buck2 uquery "owner('app/buck2/src/lib.rs')"

//buck2/app/buck2:buck2-unittest
//buck2/app/buck2:buck2

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

Build file reverse dependencies.

Returns all build files in the provided universe that have a transitive dependency on any of the specified build files.

For example:

$ buck2 uquery "rbuildfiles(//buck2/BUCK, //buck2/defs.bzl)"

buck2/defs.bzl
buck2/BUCK

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

Find the reverse dependencies of the targets in the given target universe.

The first parameter universe defines where to look for reverse dependencies. The second parameter targets is a specific target or target pattern. It specifies the targets to find reverse dependencies for. The third argument depth is an optional integer literal specifying an upper bound on the depth of the search. A value of one (1) specifies that buck query should return only direct dependencies. If the depth parameter is omitted, the search is unbounded. The fourth argument captured_expr is an optional expression that can be used to filter the results.

The returned values include the nodes from the targets argument itself.

For example following uquery:

$ buck2 uquery "rdeps(//buck2/..., //buck2/dice/dice:dice, 1)"

returns all targets under //buck2/... that depend on //buck2/dice/dice:dice.

somepath(from: target expression, to: target expression, captured_expr: ?query expression)​

Shortest dependency path between two sets of targets.

  • The first parameter from represents the upstream targets (e.g., final binary).
  • The second parameter to represents the downstream targets (e.g., a library).

Results are returned in order from top to bottom (upstream to downstream).

If multiple paths exist, the returned path is unspecified. If no path exists, an empty set is returned.

For example:

$ buck2 uquery 'somepath(//buck2:buck2, //buck2/app/buck2_node:buck2_node)'

//buck2:buck2
//buck2/app/buck2:buck2-bin
//buck2/app/buck2_analysis:buck2_analysis
//buck2/app/buck2_node:buck2_node

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())"

targets_in_buildfile(files: file expression)​

Targets in build file.

For each file in the provided file expression, returns a list of all targets defined there.

targets_in_buildfile() and buildfile() functions are inverses of each other.

For example:

$ buck2 uquery 'targets_in_buildfile(buildfile(//buck2:buck2))'

//buck2:buck2
//buck2:buck2_bundle
//buck2:symlinked_buck2_and_tpx

testsof(targets: target expression)​

Tests of specified targets.

Returns the test targets associated with the targets from the given target expressions.

For example:

$ buck2 uquery "testsof(set(//buck2/dice/dice:dice //buck2/app/buck2:buck2))"

//buck2/dice/dice:dice-unittest
//buck2/app/buck2:buck2-unittest

returns the tests associated with both //buck2/dice/dice:dice and //buck2/app/buck2:buck2.

To obtain all the tests associated with the target and its dependencies, you can combine the testsof() function with the deps() function.

For example:

$ buck2 uquery "testsof(deps(//buck2/app/buck2:buck2))"

first finds the transitive closure of //buck2/app/buck2:buck2, and then lists all the tests associated with the targets in this transitive closure.

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())"

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.

Value Types​

string​

for example, non_quoted_string or "quoted string"

integer​

must be positive and fit in u32

target expression​

either a literal or the return value of a function

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

file expression​

either a literal or the return value of a function

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​

either a file expression or target 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

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