site/docs/aquery.html

---
layout: documentation
title: Aquery (Action Graph Query)
---
<h1>Aquery (Action Graph Query)</h1>


<ul class="toc">
  <li><a href="#overview">Overview</a></li>
  <li><a href="#basic-syntax">Basic Syntax</a></li>
  <li><a href="#functions">Aquery Functions</a></li>
  <li><a href="#options">Options</a></li>
  <li><a href="#misc">Miscellaneous</a></li>
  <li><a href="#known-issues">Known Issues</a></li>
  <li><a href="#updates">Updates</a></li>
</ul>

<h2 id='overview'>Overview</h2>

<b>Caution</b>: The aquery command is still experimental and its API will change.

<p>
  The <code>aquery</code> command allows you to query for actions in your build graph.
  It operates on the post-analysis Configured Target Graph and exposes
  information about <b>Actions, Artifacts and their relationships.</b>
</p>

<p>
  <code>aquery</code> is useful when we are interested in the properties of the Actions/Artifacts
  generated from the Configured Target Graph. For example, the actual commands run
  and their inputs/outputs/mnemonics.
</p>

<p>
  The tool accepts several command-line <a href="#aquery-options">options</a>.
  Notably, the aquery command runs on top of a regular Bazel build and inherits
  the set of options available during a build.
</p>

<p>
  It supports the same set of functions that is also available to traditional
  <code>query</code> but <code>siblings</code>, <code>buildfiles</code> and
  <code>tests</code>.
</p>

<p>An example <code>aquery</code> output (without specific details):</p>

<pre>
$ bazel aquery 'deps(//some:label)'
action 'Writing file some_file_name'
  Mnemonic: ...
  Owner: ...
  Configuration: ...
  ActionKey: ...
  Inputs: [...]
  Outputs: [...]
</pre>

<h2 id='basic-syntax'>Basic Syntax</h2>

<p>A simple example of the syntax for <code>aquery</code> is as follows:</p>

<p><code>bazel aquery "aquery_function(function(//target))"</code></p>

<p>The query expression (in quotes) consists of the following:

<ul>
  <li>
    <code>aquery_function(...)</code>: functions specific to <code>aquery</code>.
    More details <a href="#functions">below</a>.
  </li>
  <li>
    <code>function(...)</code>: the standard <a href="query.html#functions">functions</a>
    as traditional <code>query</code>.
  </li>
  <li>
    <code>//target</code> is the label to the interested target.
   </li>
</ul>

<pre>
# aquery examples:
# Get the action graph generated while building //src/target_a
$ bazel aquery '//src/target_a'

# Get the action graph generated while building all dependencies of //src/target_a
$ bazel aquery 'deps(//src/target_a)'

# Get the action graph generated while building all dependencies of //src/target_a
# whose inputs filenames match the regex ".*cpp".
$ bazel aquery 'inputs(".*cpp, deps(//src/target_a))'
</pre>

<h2 id='functions'>Aquery Functions</h2>

<p>There are currently 3 <code>aquery</code> functions:</p>
<ul>
  <li><code>inputs</code>: filter actions by inputs.</li>
  <li><code>outputs</code>: filter actions by outputs</li>
  <li><code>mnemonic</code>: filter actions by mnemonic</li>
</ul>

<p><code>expr ::= inputs(word, expr)</code></p>

<p>
  The <code>inputs</code> operator returns the actions generated from building <code>expr</code>,
  whose input filenames match the regex provided by <code>word</code>.
</p>

<p><code>$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'</code></p>

<p><code>outputs</code> and <code>mnemonic</code> functions share a similar syntax.</p>

<p>You can also combine functions to achieve the AND operation. For example:</p>
<pre>
  $ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'
</pre>
<p>
  The above command would find all actions involved in building <code>//src/target_a</code>,
  whose mnemonics match <code>"Cpp.*"</code> and inputs match the patterns
  <code>".*cpp"</code> and <code>"foo.*"</code>.
</p>

<h3>Important: aquery functions can't be nested inside non-aquery functions</h3>
<ul>
  <li>Conceptually this makes sense since the output of aquery functions is Actions,
    not Configured Targets.</li>
  <li>
    An example of the syntax error produced:
    <pre>
        $ bazel aquery 'deps(inputs(".*cpp", //src/target_a))'
        ERROR: aquery filter functions (inputs, outputs, mnemonic) produce actions,
        and therefore can't be the input of other function types: deps
        deps(inputs(".*cpp", //src/target_a))
      </pre>
  </li>
</ul>

<h2 id='options'>Options</h2>

<h3>Build Options</h3>

<p>
  <code>aquery</code> runs on top of a regular Bazel build and thus inherits the set of
  <a href="command-line-reference.html#build-options">options</a>
  available during a build.
</p>

<h3 id="aquery-options">Aquery options</h3>

<h4><code class='flag'>--output=(text|proto|textproto), default=text</code></h4>

<p>
  The default output format (<code>text</code>) is human-readable,
  use <code>proto</code> or <code>textproto</code> for machine-readable format.
</p>

<h4><code class='flag'>--include_commandline, default=true</code></h4>

<p>
  Includes the content of the action command lines in the output (potentially large).
</p>

<h4><code class='flag'>--include_aspects, default=false</code></h4>

<p>
  Whether to include Aspect-generated actions in the output.
</p>

<h4><code class='flag'>--include_param_files, default=false</code></h4>

<p>
  Include the content of the param files used in the command (potentially large).
  Warning: Enabling this flag will automatically enable the <code>--include_commandline</code> flag.
</p>

<h2 id='misc'>Miscellaneous</h2>

<h3>Aspect-on-Aspect</h3>

<p>
  It is possible for <a href="https://docs.bazel.build/versions/master/skylark/aspects.html">Aspects</a>
  to be applied on top of each other. The aquery output of the action generated by these Aspects would
  then include the <i>Aspect path</i>, which is the sequence of Aspects applied to the target which generated the action.
</p>

<p>An example of Aspect-on-Aspect:</p>

<pre>
  t0
  ^
  | <- a1
  t1
  ^
  | <- a2
  t2
</pre>

<p>
  Let t<sub>i</sub> be a target of rule r<sub>i</sub>, which applies an Aspect a<sub>i</sub>
  to its dependencies.
</p>

<p>Assume that a2 generates an action X when applied to target t0. The text output of
  <code>bazel aquery --include_aspects 'deps(//t2)'</code> for action X would be:</p>

<pre>
  action ...
  Mnemonic: ...
  Target: //my_pkg:t0
  Configuration: ...
  AspectDescriptors: [//my_pkg:rule.bzl%<b>a2</b>(foo=...)
    -> //my_pkg:rule.bzl%<b>a1</b>(bar=...)]
  ...
</pre>

<p>
  This means that action <code>X</code> was generated by Aspect <code>a2</code> applied onto
  <code>a1(t0)</code>, where <code>a1(t0)</code> is the result of Aspect <code>a1</code> applied
  onto target <code>t0</code>.
</p>

<p>Each <code>AspectDescriptor</code> has the following format:</p>

<pre>
  AspectClass([param=value,...])
</pre>

<p>
  <code>AspectClass</code> could be the name of the Aspect class (for native Aspects) or
  <code>bzl_file%aspect_name</code> (for Starlark Aspects). <code>AspectDescriptor</code> are
  sorted in topological order of the
  <a href="https://docs.bazel.build/versions/master/skylark/aspects.html#aspect-basics">dependency graph</a>.
</p>

<h2 id='known-issues'>Known Issues</h2>

<p>
  The list of aquery issues/planned features can be found on
  <a href="https://github.com/bazelbuild/bazel/labels/team-Performance">GitHub</a>.
</p>

<h2 id='updates'>Updates</h2>

<p>
  Aquery is a work in progress, and its API might change in the future.
  Please contact twerth@google.com and leba@google.com for any issue/feature request.
</p>