Aquery Environment

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

Common query functions

allpaths(from: target expression, to: target expression, captured_expr: ?query expression): Computes all dependency paths.
somepath(from: target expression, to: target expression, captured_expr: ?query 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, captured_expr: ?query expression)
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, captured_expr: ?query 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, captured_expr: ?query 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>