Bazel クエリ リファレンス

問題を報告する ソースを表示

Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

このページは、bazel query を使用してビルドの依存関係を分析するときに使用される Bazel Query Language のリファレンス マニュアルです。また、bazel query がサポートする出力形式についても説明します。

実践的なユースケースについては、Bazel Query の入門ガイドをご覧ください。

その他のクエリ リファレンス

読み込み後のフェーズのターゲット グラフで実行される query に加えて、Bazel にはアクション グラフ クエリと構成可能なクエリが含まれています。

アクション グラフクエリ

アクション グラフクエリ（aquery）は、分析後の構成済みターゲット グラフで動作し、アクション、アーティファクト、それらの関係に関する情報を公開します。aquery は、構成済みターゲット グラフから生成されたアクション/アーティファクトのプロパティに関心がある場合に役立ちます。たとえば、実際に実行されたコマンドとその入力、出力、ニーモニックなどです。

詳細については、aquery リファレンスをご覧ください。

構成可能なクエリ

従来の Bazel クエリは読み込み後のフェーズのターゲット グラフで実行されるため、構成とその関連コンセプトの概念がありません。特に、select ステートメントを正しく解決せず、代わりに select の可能なすべての解決策を返します。ただし、構成可能なクエリ環境 cquery は構成を適切に処理しますが、この元のクエリのすべての機能を提供するわけではありません。

詳細については、cquery リファレンスをご覧ください。

例

bazel query はどのように使用されていますか？一般的な例を次に示します。

//foo ツリーが //bar/baz に依存するのはなぜですか？パスを表示する:

somepath(foo/..., //bar/baz:all)

foo_bin ターゲットが依存していない、すべての foo テストが依存している C++ ライブラリは何ですか？

kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))

トークン: 語彙構文

クエリ言語の式は、次のトークンで構成されます。

• キーワード（let など）。キーワードは言語の予約語であり、それぞれについて以下で説明します。キーワードの完全なセットは次のとおりです。

  • except

  • in

  • intersect

  • let

  • set

  • union

• 「foo/...」、「.*test rule」、「//bar/baz:all」などの単語。文字シーケンスが引用符で囲まれている（単一引用符 ' で始まり、単一引用符 ' で終わるか、二重引用符 " で始まり、二重引用符 " で終わる）場合、それは単語です。文字シーケンスが引用符で囲まれていない場合でも、単語として解析されることがあります。引用符で囲まれていない単語は、アルファベット文字 A ～ Za ～ z、数字 0 ～ 9、特殊文字 */@.-_:$~[]（アスタリスク、スラッシュ、アットマーク、ピリオド、ハイフン、アンダースコア、コロン、ドル記号、チルダ、左角かっこ、右角かっこ）から抽出された文字のシーケンスです。ただし、相対的なターゲット名はこれらの文字で始まることがありますが、引用符で囲まれていない単語はハイフン - またはアスタリスク * で始めることはできません。外部リポジトリを参照するラベルの処理を簡素化するための特別なルールとして、@@ で始まる引用符なしの単語には + 文字を含めることができます。

  引用符で囲まれていない単語には、プラス記号 + や等号 = を含めることもできません。これらの文字はターゲット名では使用できますが、引用符で囲まれていない単語では使用できません。クエリ式を生成するコードを記述する場合は、ターゲット名を引用符で囲む必要があります。

  ユーザーが指定した値から Bazel クエリ式を構築するスクリプトを作成する場合は、is を引用符で囲む必要があります。

   //foo:bar+wiz    # WRONG: scanned as //foo:bar + wiz.
   //foo:bar=wiz    # WRONG: scanned as //foo:bar = wiz.
   "//foo:bar+wiz"  # OK.
   "//foo:bar=wiz"  # OK.
  

  この引用符は、シェルで必要となる可能性のある引用符（次のようなもの）に追加されるものです。

  bazel query ' "//foo:bar=wiz" '   # single-quotes for shell, double-quotes for Bazel.

  キーワードと演算子は、引用符で囲むと通常の単語として扱われます。たとえば、some はキーワードですが、「some」は単語です。foo と「foo」はどちらも単語です。

  ただし、ターゲット名で単一引用符または二重引用符を使用する場合は注意が必要です。1 つ以上のターゲット名を引用する場合は、1 種類の引用符（すべて一重引用符またはすべて二重引用符）のみを使用します。

  Java のクエリ文字列の例を次に示します。

    'a"'a'         # WRONG: Error message: unclosed quotation.
    "a'"a"         # WRONG: Error message: unclosed quotation.
    '"a" + 'a''    # WRONG: Error message: unexpected token 'a' after query expression '"a" + '
    "'a' + "a""    # WRONG: Error message: unexpected token 'a' after query expression ''a' + '
    "a'a"          # OK.
    'a"a'          # OK.
    '"a" + "a"'    # OK
    "'a' + 'a'"    # OK
  

  ほとんどの場合、引用符が不要になるように、この構文を選択しました。（通常ではない）".*test rule" の例では、引用符が必要です。ピリオドで始まり、スペースが含まれているためです。"cc_library" を引用する必要はありませんが、害はありません。

• 句読点（括弧 ()、ピリオド .、カンマ , など）。句読点を含む単語（上記の例外を除く）は引用符で囲む必要があります。

引用符で囲まれた単語の外にある空白文字は無視されます。

Bazel クエリ言語のコンセプト

Bazel クエリ言語は式言語です。すべての式は、ターゲットの半順序集合（またはターゲットのグラフ（DAG））に評価されます。これは唯一のデータ型です。

Set と Graph は同じデータ型を指しますが、次のように異なる側面を強調します。

• 設定: ターゲットの半順序は重要ではありません。
• グラフ: ターゲットの半順序は重要です。

依存関係グラフのサイクル

ビルド依存関係グラフは非巡回グラフである必要があります。

クエリ言語で使用されるアルゴリズムはサイクルに対して堅牢であり、サイクルをエラーとして報告しません。

bazel query が動作する読み込み後のフェーズの未構成のターゲット グラフには、構成済みのターゲット グラフには存在しないサイクルが含まれている場合があります。構成されたターゲット グラフのサイクルは、bazel cquery と bazel aquery によって検出され、エラーとして報告されます。

暗黙的な依存関係

BUILD ファイルで明示的に定義されたビルド依存関係に加えて、Bazel は追加の暗黙的依存関係をルールに追加します。暗黙的な依存関係は、次の方法で定義できます。

• プライベート属性
• ツールチェーンの要件

デフォルトでは、bazel query はクエリ結果の計算時に暗黙的な依存関係を考慮します。この動作は、--[no]implicit_deps オプションで変更できます。

クエリは構成を考慮しないため、潜在的なツールチェーンの実装は依存関係と見なされず、必要なツールチェーンの型のみが依存関係と見なされます。ツールチェーンのドキュメントをご覧ください。

健全性

Bazel クエリ言語式は、ビルド依存関係グラフに対して動作します。このグラフは、すべての BUILD ファイル内のすべてのルール宣言によって暗黙的に定義されるグラフです。このグラフはやや抽象的であり、ビルドのすべてのステップを実行する方法を完全に説明するものではないことを理解しておくことが重要です。ビルドを実行するには、構成も必要です。詳細については、ユーザーガイドの構成セクションをご覧ください。

Bazel クエリ言語で式を評価した結果は、すべての構成で true になります。つまり、保守的な過大評価になる可能性があり、正確ではない可能性があります。クエリツールを使用してビルド中に必要なすべてのソースファイルのセットを計算すると、実際には必要のないファイルが報告されることがあります。たとえば、ビルドでメッセージ翻訳機能を使用する予定がない場合でも、クエリツールはメッセージ翻訳のサポートに必要なすべてのファイルを含めます。

グラフの順序の保持について

オペレーションは、サブ式から継承された順序制約を保持します。これは「半順序の保存則」と考えることができます。たとえば、特定のターゲットの依存関係の推移閉包を特定するクエリを発行すると、結果のセットは依存関係グラフに従って順序付けられます。そのセットを file 種類のターゲットのみを含むようにフィルタすると、結果のサブセット内のターゲットのすべてのペア間で同じ推移的半順序関係が保持されます。これらのペアのいずれも元のグラフで直接接続されていません。（ビルド依存関係グラフにはファイル間のエッジはありません）。

ただし、すべての演算子は順序を保持しますが、集合演算などの一部のオペレーションは、独自の順序制約を導入しません。次の式について考えてみましょう。

deps(x) union y

最終結果セットの順序は、サブ式のすべての順序制約を保持することが保証されます。つまり、x のすべての推移的依存関係が互いに正しく順序付けられます。ただし、このクエリでは、y のターゲットの順序や、y のターゲットに対する deps(x) のターゲットの順序（y にも deps(x) にもあるターゲットを除く）については保証されません。

順序制約を導入する演算子には、allpaths、deps、rdeps、somepath、ターゲット パターン ワイルドカード package:*、dir/... などがあります。

Sky クエリ

Sky Query は、指定されたユニバース スコープで動作するクエリモードです。

SkyQuery でのみ使用できる特殊関数

Sky Query モードには、追加のクエリ関数 allrdeps と rbuildfiles があります。これらの関数は、ユニバース スコープ全体で動作します（そのため、通常のクエリでは意味がありません）。

ユニバース スコープの指定

Sky Query モードは、次の 2 つのフラグ（--universe_scope または --infer_universe_scope）と --order_output=no を渡すことで有効になります。--universe_scope=<target_pattern1>,...,<target_patternN> は、ターゲット パターンで指定されたターゲット パターンの推移閉包をプリロードするようにクエリに指示します。これは加法的にも減法的にもなります。すべてのクエリは、この「スコープ」で評価されます。特に、allrdeps 演算子と rbuildfiles 演算子は、このスコープの結果のみを返します。--infer_universe_scope は、クエリ式から --universe_scope の値を推測するように Bazel に指示します。この推論値は、クエリ式の固有のターゲット パターンのリストですが、これは望ましくない可能性があります。次に例を示します。

bazel query --infer_universe_scope --order_output=no "allrdeps(//my:target)"

このクエリ式の一意のターゲット パターンのリストは ["//my:target"] であるため、Bazel はこれを次のような呼び出しと同じように扱います。

bazel query --universe_scope=//my:target --order_output=no "allrdeps(//my:target)"

ただし、--universe_scope を使用したクエリの結果は //my:target のみです。//my:target の逆依存関係は、構築によってユニバースに含まれません。一方、次の点も考慮してください。

bazel query --infer_universe_scope --order_output=no "tests(//a/... + b/...) intersect allrdeps(siblings(rbuildfiles(my/starlark/file.bzl)))"

これは、特定の .bzl ファイルを使用する定義のターゲットに推移的に依存する、一部のディレクトリのターゲットの tests 拡張でテスト ターゲットを計算しようとする、意味のあるクエリ呼び出しです。ここで、--infer_universe_scope は利便性を提供します。特に、--universe_scope の選択でクエリ式を自分で解析する必要がある場合に便利です。

そのため、allrdeps や rbuildfiles などのユニバース スコープの演算子を使用するクエリ式では、--infer_universe_scope の動作が目的の動作である場合にのみ --infer_universe_scope を使用してください。

Sky Query には、デフォルトのクエリと比較してメリットとデメリットがあります。主な欠点は、グラフの順序に従って出力を並べ替えることができないため、特定の出力形式が禁止されていることです。この方法の利点は、デフォルトのクエリでは使用できない 2 つの演算子（allrdeps と rbuildfiles）を使用できることです。また、Sky Query は、デフォルトの実装が行うように新しいグラフを作成するのではなく、Skyframe グラフをイントロスペクションすることで処理を行います。そのため、状況によっては高速でメモリ使用量が少なくなることがあります。

式: 文法の構文とセマンティクス

これは、EBNF 表記で表された Bazel クエリ言語の文法です。

expr ::= word
       | let name = expr in expr
       | (expr)
       | expr intersect expr
       | expr ^ expr
       | expr union expr
       | expr + expr
       | expr except expr
       | expr - expr
       | set(word *)
       | word '(' int | word | expr ... ')'

以降のセクションでは、この文法の各生成規則について順に説明します。

ターゲット パターン

expr ::= word

構文的には、ターゲット パターンは単語にすぎません。ターゲットの（順不同の）セットとして解釈されます。最も単純なターゲット パターンはラベルです。これは、単一のターゲット（ファイルまたはルール）を識別します。たとえば、ターゲット パターン //foo:bar は、ターゲットである bar ルールという 1 つの要素を含むセットに評価されます。

ターゲット パターンは、パッケージとターゲットにワイルドカードを含めるようにラベルを一般化します。たとえば、foo/...:all（または foo/...）は、foo ディレクトリの下にあるすべてのパッケージのすべてのルールを再帰的に含むセットに評価されるターゲット パターンです。bar/baz:all は、bar/baz パッケージのすべてのルールを含むセットに評価されるターゲット パターンですが、サブパッケージは含まれません。

同様に、foo/...:* は、foo ディレクトリのすべてのパッケージのすべてのターゲット（ルールとファイル）を再帰的に含むセットに評価されるターゲット パターンです。bar/baz:* は、bar/baz パッケージのすべてのターゲットを含むセットに評価されますが、サブパッケージは含まれません。

:* ワイルドカードはファイルとルールに一致するため、クエリでは :all よりも有用なことがよくあります。一方、:all ワイルドカード（foo/... などのターゲット パターンで暗黙的に使用）は、通常、ビルドでより有用です。

bazel query ターゲット パターンは、bazel build ビルド ターゲットと同じように動作します。詳しくは、ターゲット パターンまたは bazel help target-syntax と入力してください。

ターゲット パターンは、単一のセット（ラベルの場合）、多くの要素を含むセット（foo/... の場合など。数千の要素を含む）、またはターゲット パターンがターゲットと一致しない場合は空のセットに評価されることがあります。

ターゲット パターン式の結果に含まれるすべてのノードが、依存関係に従って相互に正しく順序付けられている。したがって、foo:* の結果は、パッケージ foo のターゲットのセットだけでなく、それらのターゲットのグラフでもあります。（結果ノードと他のノードの相対的な順序は保証されません）。詳細については、グラフの順序のセクションをご覧ください。

変数

expr ::= let name = expr1 in expr2
       | $name

Bazel クエリ言語では、変数の定義と参照が可能です。let 式の評価結果は、expr₂ の評価結果と同じです。ただし、変数 name のすべての自由な出現は expr₁ の値に置き換えられます。

たとえば、let v = foo/... in allpaths($v, //common) intersect $v は allpaths(foo/...,//common) intersect foo/... と同じです。

囲み let name = ... 式以外の変数参照 name の出現はエラーです。つまり、トップレベルのクエリ式に自由変数を含めることはできません。

上記の文法生成では、name は word に似ていますが、C プログラミング言語の有効な識別子であるという制約が追加されています。変数への参照の先頭には「$」文字を付ける必要があります。

各 let 式は 1 つの変数のみを定義しますが、ネストできます。

ターゲット パターンと変数参照はどちらも単一のトークン（単語）で構成されているため、構文上の曖昧さが生じます。ただし、有効な変数名である単語のサブセットと、有効なターゲット パターンである単語のサブセットは互いに素であるため、意味の曖昧さはありません。

技術的には、let 式はクエリ言語の表現力を高めません。言語で表現できるクエリは、let 式なしでも表現できます。ただし、多くのクエリの簡潔性が向上し、クエリ評価の効率も向上する可能性があります。

かっこで囲まれた式

expr ::= (expr)

かっこは、評価の順序を強制するために部分式を関連付けます。かっこで囲まれた式は、引数の値に評価されます。

代数集合演算: 積集合、和集合、差集合

expr ::= expr intersect expr
       | expr ^ expr
       | expr union expr
       | expr + expr
       | expr except expr
       | expr - expr

これらの 3 つの演算子は、引数に対して通常の集合演算を行います。各演算子には、intersect などの名目形式と、^ などの記号形式の 2 つの形式があります。どちらの形式も同等です。記号形式の方が入力が簡単です。（わかりやすくするため、このページの残りの部分では名詞形を使用します）。

次に例を示します。

foo/... except foo/bar/...

は、foo/... と一致するが foo/bar/... とは一致しないターゲットのセットに評価されます。

同じクエリを次のように記述できます。

foo/... - foo/bar/...

intersect（^）と union（+）のオペレーションは可換（対称）です。except（-）は非対称です。パーサーは 3 つの演算子をすべて左結合で優先順位が同じと見なすため、かっこが必要になる場合があります。たとえば、これらの式の最初の 2 つは同等ですが、3 つ目は同等ではありません。

x intersect y union z
(x intersect y) union z
x intersect (y union z)

重要: クエリ式の読み取りがあいまいになる可能性がある場合は、かっこを使用します。

外部ソースからターゲットを読み取る: 設定

expr ::= set(word *)

set(a b c ...) 演算子は、空白で区切られた（カンマなし）0 個以上のターゲット パターンのセットのユニオンを計算します。

set() は、Bourne シェルの $(...) 機能と組み合わせて、1 つのクエリの結果を通常のテキスト ファイルに保存し、他のプログラム（標準の UNIX シェルツールなど）を使用してそのテキスト ファイルを操作し、さらに処理を行うための値として結果をクエリツールに再度導入する手段を提供します。次に例を示します。

bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... > foo
bazel query "kind(cc_binary, set($(<foo)))"

次の例では、awk プログラムを使用して maxrank 値をフィルタし、kind(cc_library, deps(//some_dir/foo:main, 5)) を計算します。

bazel query 'deps(//some_dir/foo:main)' --output maxrank | awk '($1 < 5) { print $2;} ' > foo
bazel query "kind(cc_library, set($(<foo)))"

これらの例では、$(<foo) は $(cat foo) の省略形ですが、cat 以外のシェル コマンド（前の awk コマンドなど）も使用できます。

注: set() にはグラフの順序付けの制約がないため、これを使用してノードのセットを保存して再読み込みすると、パス情報が失われる可能性があります。詳細については、下記のグラフの順序セクションをご覧ください。

関数

expr ::= word '(' int | word | expr ... ')'

クエリ言語には、いくつかの関数が定義されています。関数の名前によって、必要な引数の数と型が決まります。次の関数を使用できます。

• allpaths
• attr
• buildfiles
• rbuildfiles
• deps
• filter
• kind
• labels
• loadfiles
• rdeps
• allrdeps
• same_pkg_direct_rdeps
• siblings
• some
• somepath
• tests
• visible

依存関係の推移閉包: deps

expr ::= deps(expr)
       | deps(expr, depth)

deps(x) 演算子は、引数セット x の依存関係の推移閉包によって形成されるグラフとして評価されます。たとえば、deps(//foo) の値は、単一ノード foo をルートとする依存関係グラフであり、すべての依存関係が含まれます。deps(foo/...) の値は、foo ディレクトリの下にあるすべてのパッケージのすべてのルールをルートとする依存関係グラフです。このコンテキストでは、「依存関係」はルールとファイル ターゲットのみを意味します。したがって、これらのターゲットの作成に必要な BUILD ファイルと Starlark ファイルはここには含まれません。そのためには、buildfiles 演算子を使用する必要があります。

結果のグラフは、依存関係に従って順序付けされます。詳しくは、グラフの順序のセクションをご覧ください。

deps 演算子は、検索の深さの上限を指定する整数リテラルである 2 番目の引数をオプションで受け取ります。したがって、deps(foo:*, 0) は foo パッケージ内のすべてのターゲットを返しますが、deps(foo:*, 1) は foo パッケージ内のターゲットの直接の前提条件も返します。また、deps(foo:*, 2) は deps(foo:*, 1) 内のノードから直接到達可能なノードも返します。（これらの数値は、minrank 出力形式に示されているランクに対応しています）。depth パラメータが省略されている場合、検索は無制限になります。前提条件の反射的推移閉包が計算されます。

逆依存関係の推移閉包: rdeps

expr ::= rdeps(expr, expr)
       | rdeps(expr, expr, depth)

rdeps(u, x) 演算子は、宇宙集合 u の推移閉包内の引数セット x の逆依存関係を評価します。

結果のグラフは、依存関係に従って順序付けされます。詳細については、グラフの順序のセクションをご覧ください。

rdeps 演算子は、検索の深さの上限を指定する整数リテラルであるオプションの 3 番目の引数を受け取ります。結果のグラフには、引数セット内の任意のノードから指定された深さの範囲内のノードのみが含まれます。したがって、rdeps(//foo, //common, 1) は、//common に直接依存する //foo の推移閉包内のすべてのノードを評価します。（これらの番号は、minrank 出力形式に表示されるランクに対応しています）。depth パラメータを省略すると、検索は無制限になります。

すべての逆依存関係の推移閉包: allrdeps

expr ::= allrdeps(expr)
       | allrdeps(expr, depth)

注: Sky Query でのみ使用できます。

allrdeps 演算子は rdeps 演算子とまったく同じように動作しますが、「ユニバース セット」は個別に指定されるのではなく、--universe_scope フラグの評価結果になります。したがって、--universe_scope=//foo/... が渡された場合、allrdeps(//bar) は rdeps(//foo/..., //bar) と同等です。

同じパッケージ内の直接逆依存関係: same_pkg_direct_rdeps

expr ::= same_pkg_direct_rdeps(expr)

same_pkg_direct_rdeps(x) 演算子は、引数セット内のターゲットと同じパッケージにあり、そのターゲットに直接依存するターゲットの完全なセットとして評価されます。

ターゲットのパッケージの処理: 兄弟

expr ::= siblings(expr)

siblings(x) 演算子は、引数セット内のターゲットと同じパッケージに含まれるターゲットの完全なセットを評価します。

任意の選択: 一部

expr ::= some(expr)
       | some(expr, count )

some(x, k) 演算子は、引数セット x から最大 k 個のターゲットを任意に選択し、それらのターゲットのみを含むセットを返します。パラメータ k は省略可能です。省略すると、結果は任意に選択された 1 つのターゲットのみを含むシングルトン セットになります。引数セット x のサイズが k より小さい場合は、引数セット x 全体が返されます。

たとえば、式 some(//foo:main union //bar:baz) は、//foo:main または //bar:baz のいずれかを含むシングルトン セットとして評価されます（どちらになるかは定義されていません）。式 some(//foo:main union //bar:baz, 2) または some(//foo:main union //bar:baz, 3) は、//foo:main と //bar:baz の両方を返します。

引数がシングルトンの場合、some は恒等関数を計算します。some(//foo:main) は //foo:main と同等です。

指定された引数セットが some(//foo:main intersect //bar:baz) 式のように空の場合、エラーになります。

パス演算子: somepath、allpaths

expr ::= somepath(expr, expr)
       | allpaths(expr, expr)

somepath(S, E) 演算子と allpaths(S, E) 演算子は、2 つのターゲット セット間のパスを計算します。どちらのクエリも、開始点のセット S と終了点のセット E の 2 つの引数を受け取ります。somepath は、S のターゲットから E のターゲットまでの任意のパス上のノードのグラフを返します。allpaths は、S の任意のターゲットから E の任意のターゲットまでのすべてのパス上のノードのグラフを返します。

結果のグラフは、依存関係の順に並べ替えられます。詳しくは、グラフの順序のセクションをご覧ください。

somepath(S1 + S2, E)、1 つの結果の可能性。

somepath(S1 + S2, E) は、別の可能な結果です。

allpaths(S1 + S2, E)

ターゲットの種類のフィルタリング: kind

expr ::= kind(word, expr)

kind(pattern, input) 演算子は、ターゲットのセットにフィルタを適用し、想定される種類ではないターゲットを破棄します。pattern パラメータは、照合するターゲットの種類を指定します。

たとえば、次の BUILD ファイル（パッケージ p 用）で定義された 4 つのターゲットの種類は、次の表のとおりです。

コード	ターゲット	種類
genrule( name = "a", srcs = ["a.in"], outs = ["a.out"], cmd = "...", )	//p:a	genrule ルール
	//p:a.in	ソースファイル
	//p:a.out	生成されたファイル
	//p:BUILD	ソースファイル

したがって、kind("cc_.* rule", foo/...) は foo の下のすべての cc_library、cc_binary などのルール ターゲットのセットに評価され、kind("source file", deps(//foo)) は //foo ターゲットの依存関係の推移的閉包にあるすべてのソースファイルのセットに評価されます。

pattern 引数の引用符は、多くの場合必要です。引用符がないと、source file や .*_test などの多くの正規表現が、パーサーによって単語と見なされません。

package group の照合では、:all で終わるターゲットで結果が返されないことがあります。代わりに :all-targets を使用してください。

ターゲット名のフィルタリング: フィルタ

expr ::= filter(word, expr)

filter(pattern, input) 演算子は、一連のターゲットにフィルタを適用し、ラベル（絶対形式）がパターンと一致しないターゲットを破棄します。入力のサブセットを評価します。

最初の引数 pattern は、ターゲット名に対する正規表現を含む単語です。filter 式は、x が input のメンバーであり、x のラベル（//foo:bar などの絶対形式）に正規表現 pattern の（アンカーなしの）一致が含まれるすべてのターゲット x を含むセットとして評価されます。すべてのターゲット名は // で始まるため、^ 正規表現アンカーの代わりに使用できます。

この演算子は、intersect 演算子よりもはるかに高速で堅牢な代替手段を提供することがよくあります。たとえば、//foo:foo ターゲットのすべての bar 依存関係を確認するには、次のように評価します。

deps(//foo) intersect //bar/...

ただし、このステートメントでは bar ツリー内のすべての BUILD ファイルの解析が必要になるため、処理が遅くなり、無関係な BUILD ファイルでエラーが発生しやすくなります。別の方法としては、次のようなものがあります。

filter(//bar, deps(//foo))

これは、まず //foo 依存関係のセットを計算し、指定されたパターンに一致するターゲット（つまり、名前に //bar が部分文字列として含まれているターゲット）のみをフィルタリングします。

filter(pattern, expr) 演算子のもう 1 つの一般的な用途は、名前または拡張子で特定のファイルをフィルタすることです。次に例を示します。

filter("\.cc$", deps(//foo))

//foo のビルドに使用されるすべての .cc ファイルのリストを取得します。

ルール属性のフィルタリング: attr

expr ::= attr(word, word, expr)

attr(name, pattern, input) 演算子は、一連のターゲットにフィルタを適用し、ルールではないターゲット、属性 name が定義されていないルール ターゲット、属性値が指定された正規表現 pattern と一致しないルール ターゲットを破棄します。入力のサブセットに評価されます。

最初の引数 name は、指定された正規表現パターンと照合するルール属性の名前です。2 番目の引数 pattern は、属性値に対する正規表現です。attr 式は、x がセット input のメンバーであり、定義された属性 name を持つルールであり、属性値に正規表現 pattern の（アンカーなしの）一致が含まれるような、すべてのターゲット x を含むセットに評価されます。name がオプションの属性で、ルールで明示的に指定されていない場合は、比較にデフォルトの属性値が使用されます。次に例を示します。

attr(linkshared, 0, deps(//foo))

は、linkshared 属性を持つことが許可されている（cc_binary ルールなど）すべての //foo 依存関係を選択し、明示的に 0 に設定するか、まったく設定しないがデフォルト値が 0（cc_binary ルールなど）にします。

リスト型の属性（srcs、data など）は、[value<sub>1</sub>, ..., value<sub>n</sub>] 形式の文字列に変換されます。この文字列は [ 括弧で始まり、] 括弧で終わり、複数の値を区切るために「,」（カンマとスペース）を使用します。ラベルは、ラベルの絶対形式を使用して文字列に変換されます。たとえば、属性 deps=[":foo", "//otherpkg:bar", "wiz"] は文字列 [//thispkg:foo, //otherpkg:bar, //thispkg:wiz] に変換されます。角かっこは常に存在するため、空のリストは照合目的で文字列値 [] を使用します。次に例を示します。

attr("srcs", "\[\]", deps(//foo))

は、srcs 属性が空の //foo 依存関係のすべてのルールを選択します。

attr("data", ".{3,}", deps(//foo))

//foo 依存関係のうち、data 属性に 1 つ以上の値を指定するすべてのルールを選択します（// と : により、すべてのラベルは 3 文字以上になります）。

リスト型の属性で特定の value を持つ //foo 依存関係のすべてのルールを選択するには、次のようにします。

attr("tags", "[\[ ]value[,\]]", deps(//foo))

これは、value の前の文字が [ またはスペースで、value の後の文字がカンマまたは ] になるためです。

dict 型の属性で特定の key と value を持つ //foo 依存関係のすべてのルールを選択するには、次のようにします。

attr("some_dict_attribute", "[\{ ]key=value[,\}]", deps(//foo))

//foo が次のように定義されている場合、//foo が選択されます。

some_rule(
  name = "foo",
  some_dict_attribute = {
    "key": "value",
  },
)

これは、key=value の前の文字が { またはスペースで、key=value の後の文字がカンマまたは } になるためです。

ルールの可視性フィルタリング: 可視

expr ::= visible(expr, expr)

visible(predicate, input) 演算子は、一連のターゲットにフィルタを適用し、必要な可視性がないターゲットを破棄します。

最初の引数 predicate は、出力内のすべてのターゲットから可視である必要があるターゲットのセットです。visible 式は、x が input のメンバーであり、predicate 内のすべてのターゲット y に対して x が表示されるようなすべてのターゲット x を含むセットに評価されます。y次に例を示します。

visible(//foo, //bar:*)

は、可視性の制限に違反することなく //foo が依存できるパッケージ //bar 内のすべてのターゲットを選択します。

ラベルタイプのルール属性の評価: ラベル

expr ::= labels(word, expr)

labels(attr_name, inputs) 演算子は、セット inputs の一部のルールで、タイプ「label」または「list of label」の属性 attr_name に指定されたターゲットのセットを返します。

たとえば、labels(srcs, //foo) は //foo ルールの srcs 属性に表示されるターゲットのセットを返します。inputs セットに srcs 属性を持つルールが複数ある場合は、それらの srcs の和集合が返されます。

test_suites: tests を展開してフィルタする

expr ::= tests(expr)

tests(x) 演算子は、x セット内のすべてのテストルールのセットを返します。test_suite ルールは、参照先の個々のテストのセットに展開され、tag と size によるフィルタリングが適用されます。

デフォルトでは、クエリ評価はすべての test_suite ルールでテスト以外のターゲットを無視します。これは、--strict_test_suite オプションを使用してエラーに変更できます。

たとえば、クエリ kind(test, foo:*) は、foo パッケージ内のすべての *_test ルールと test_suite ルールを一覧表示します。すべての結果は（定義により）foo パッケージのメンバーです。一方、クエリ tests(foo:*) は、bazel test foo:* によって実行される個々のテストをすべて返します。これには、test_suite ルールを介して直接的または間接的に参照される、他のパッケージに属するテストが含まれる場合があります。

パッケージ定義ファイル: buildfiles

expr ::= buildfiles(expr)

buildfiles(x) 演算子は、セット x 内の各ターゲットのパッケージを定義するファイルのセットを返します。つまり、各パッケージの BUILD ファイルと、load を介して参照する .bzl ファイルです。このコマンドは、これらの load ファイルを含むパッケージの BUILD ファイルも返します。

この演算子は通常、指定されたターゲットをビルドするために必要なファイルまたはパッケージを特定する場合に使用されます（多くの場合、後述の --output package オプションと組み合わせて使用されます）。次に例を示します。

bazel query 'buildfiles(deps(//foo))' --output package

//foo が推移的に依存するすべてのパッケージのセットを返します。

注: 上記のクエリを単純に試すと、buildfiles 演算子が省略され、deps のみが使用されますが、これは正しくない結果になります。結果には必要なパッケージの大部分が含まれますが、load() されたファイルのみを含むパッケージは含まれません。

警告: Bazel は、buildfiles によって生成された各 .bzl ファイルに対応するターゲット（ファイル a/b.bzl => ターゲット //a:b.bzl など）があると見なしますが、必ずしもそうとは限りません。そのため、buildfiles は他のクエリ演算子と適切に構成されず、--output=xml などの構造化された方法でフォーマットすると、結果が誤解を招く可能性があります。

パッケージ定義ファイル: rbuildfiles

expr ::= rbuildfiles(word, ...)

注: Sky Query でのみ使用できます。

rbuildfiles 演算子は、パス フラグメントのカンマ区切りリストを受け取り、これらのパス フラグメントに推移的に依存する BUILD ファイルのセットを返します。たとえば、//foo がパッケージの場合、rbuildfiles(foo/BUILD) は //foo:BUILD ターゲットを返します。foo/BUILD ファイルに load('//bar:file.bzl'... が含まれている場合、rbuildfiles(bar/file.bzl) は //foo:BUILD ターゲットと、//bar:file.bzl を読み込む他の BUILD ファイルのターゲットを返します。

rbuildfiles 演算子のスコープは、--universe_scope フラグで指定されたユニバースです。BUILD ファイルと .bzl ファイルに直接対応しないファイルは、結果に影響しません。たとえば、BUILD ファイルで明示的に言及されている場合でも、ソースファイル（foo.cc など）は無視されます。ただし、シンボリック リンクは尊重されるため、foo/BUILD が bar/BUILD へのシンボリック リンクである場合、rbuildfiles(bar/BUILD) の結果には //foo:BUILD が含まれます。

rbuildfiles 演算子は、buildfiles 演算子の逆とほぼ同じです。ただし、このモラルの反転は一方向に強く働きます。rbuildfiles の出力は buildfiles の入力と同じです。前者はパッケージ内の BUILD ファイル ターゲットのみを含み、後者はそのようなターゲットを含む可能性があります。反対方向の対応は弱くなります。buildfiles 演算子の出力は、すべてのパッケージと に対応するターゲットです。特定の入力に必要な bzl ファイル。ただし、rbuildfiles 演算子の入力は、これらのターゲットではなく、これらのターゲットに対応するパス フラグメントです。

パッケージ定義ファイル: loadfiles

expr ::= loadfiles(expr)

loadfiles(x) 演算子は、セット x 内の各ターゲットのパッケージを読み込むために必要な Starlark ファイルのセットを返します。つまり、各パッケージについて、その BUILD ファイルから参照されている .bzl ファイルを返します。

警告: Bazel は、これらの .bzl ファイルのそれぞれに対応するターゲット（ファイル a/b.bzl => ターゲット //a:b.bzl など）があると想定しますが、必ずしもそうとは限りません。そのため、loadfiles は他のクエリ演算子と適切に構成されず、--output=xml などの構造化された形式で結果を表示すると、誤解を招く可能性があります。

出力形式

bazel query はグラフを生成します。bazel query がこのグラフを表示するコンテンツ、形式、順序は、--output コマンドライン オプションで指定します。

Sky Query で実行する場合、順序なし出力と互換性のある出力形式のみが許可されます。具体的には、graph、minrank、maxrank の出力形式は禁止されています。

出力形式によっては、追加のオプションを指定できます。各出力オプションの名前には、適用される出力形式の接頭辞が付いています。たとえば、--graph:factored は --output=graph が使用されている場合にのみ適用されます。graph 以外の出力形式が使用されている場合は効果がありません。同様に、--xml:line_numbers は --output=xml が使用されている場合にのみ適用されます。

結果の並べ替えについて

クエリ式は常に「グラフ順序の保存の法則」に従いますが、結果の提示は依存関係順または順序なしで行うことができます。これは、結果セット内のターゲットやクエリの計算方法には影響しません。結果が stdout に出力される方法にのみ影響します。また、依存関係の順序が同等のノードは、アルファベット順に並べ替えられる場合と並べ替えられない場合があります。--order_output フラグを使用してこの動作を制御できます。（--[no]order_results フラグは --order_output フラグの機能のサブセットであり、非推奨です）。

このフラグのデフォルト値は auto で、結果を辞書順で出力します。ただし、somepath(a,b) を使用すると、結果は deps の順序で出力されます。

このフラグが no で、--output が build、label、label_kind、location、package、proto、xml のいずれかの場合、出力は任意の順序で出力されます。通常、これが最も速いオプションです。ただし、--output が graph、minrank、maxrank のいずれかの場合、この形式はサポートされません。これらの形式では、Bazel は常に依存関係の順序またはランクで並べ替えられた結果を出力します。

このフラグが deps の場合、Bazel は結果をトポロジカル順序で出力します。つまり、依存関係の後に依存関係が続きます。ただし、依存関係の順序で順序付けされていないノード（一方から他方へのパスがないため）は、任意の順序で出力されることがあります。

このフラグが full の場合、Bazel はノードを完全に決定論的な（合計）順序で出力します。まず、すべてのノードがアルファベット順に並べ替えられます。次に、リスト内の各ノードが、後順序の深さ優先探索の開始点として使用されます。この探索では、未訪問のノードへの発信エッジが後続ノードのアルファベット順にトラバースされます。最後に、ノードは訪問された順序の逆順で出力されます。

この順序でノードを印刷すると処理が遅くなる可能性があるため、決定論が重要な場合にのみ使用する必要があります。

BUILD に表示されるターゲットのソース形式を出力する

--output build

このオプションを使用すると、各ターゲットの表現は、BUILD 言語で手書きされたかのように表示されます。すべての変数と関数呼び出し（glob、マクロなど）が展開されます。これは、Starlark マクロの効果を確認するのに便利です。また、各有効なルールは generator_name 値または generator_function 値（あるいはその両方）をレポートし、有効なルールを生成するために評価されたマクロの名前を示します。

出力では BUILD ファイルと同じ構文が使用されますが、有効な BUILD ファイルが生成されるとは限りません。

各ターゲットのラベルを印刷する

--output label

このオプションを指定すると、結果のグラフ内の各ターゲットの名前（またはラベル）のセットが、トポロジカル順に（--noorder_results が指定されていない場合。結果の順序に関する注意事項を参照）、1 行に 1 つのラベルで出力されます。（トポロジカル ソートとは、グラフノードがそのすべての後続ノードよりも前に現れる順序のことです）。もちろん、グラフのトポロジカル順序付けには多くの可能性があります（逆後順はその 1 つにすぎません）。どれが選択されるかは指定されていません。

somepath クエリの出力を出力する場合、ノードが出力される順序はパスの順序です。

注意: 特殊なケースでは、同じラベルを持つ 2 つの異なるターゲットが存在する可能性があります。たとえば、sh_binary ルールとその唯一の（暗黙的な）srcs ファイルの両方が foo.sh と呼ばれることがあります。クエリの結果にこれらのターゲットの両方が含まれている場合、出力（label 形式）に重複が含まれているように見えます。label_kind（下記参照）形式を使用すると、2 つのターゲットの名前は同じですが、1 つは種類が sh_binary rule で、もう 1 つは種類が source file であることが明確になります。

各ターゲットのラベルと種類を出力する

--output label_kind

label と同様に、この出力形式では、結果のグラフ内の各ターゲットのラベルがトポロジカル順序で出力されますが、ラベルの前にターゲットの種類が追加されます。

プロトコル バッファ形式で印刷ターゲットを出力する

--output proto

クエリの出力を QueryResult プロトコル バッファとして出力します。

長さ区切りプロトコル バッファ形式でターゲットを出力

--output streamed_proto

Target プロトコル バッファの長さ区切りストリームを出力します。これは、（i）単一の QueryResult に収まるターゲットが多すぎる場合に、プロトコル バッファのサイズ制限を回避したり、（ii）Bazel がまだ出力している間に処理を開始したりする場合に便利です。

テキスト proto 形式でターゲットを出力する

--output textproto

--output proto と同様に、QueryResult プロトコル バッファを テキスト形式で出力します。

ndjson 形式でターゲットを出力する

--output streamed_jsonproto

--output streamed_proto と同様に、Target プロトコル バッファのストリームを出力しますが、ndjson 形式で出力します。

各ターゲットのラベルをランク順に出力する

--output minrank --output maxrank

label と同様に、minrank と maxrank の出力形式では、結果のグラフに各ターゲットのラベルが出力されますが、トポロジカル順ではなく、ランク順で表示され、ランク番号が前に付加されます。これらは、結果の順序付けの --[no]order_results フラグの影響を受けません（結果の順序付けに関する注意事項を参照）。

この形式には 2 つのバリエーションがあります。minrank は、ルートノードから各ノードまでの最短パスの長さで各ノードをランク付けします。「ルート」ノード（入ってくるエッジがないノード）はランク 0、そのサクセサーはランク 1 などです（常に、エッジはターゲットからその前提条件（依存するターゲット）を指します）。

maxrank は、ルートノードから各ノードまでの最長パスの長さで各ノードをランク付けします。ここでも、「ルート」のランクは 0 で、他のすべてのノードのランクは、そのすべての先行ノードの最大ランクより 1 つ大きくなります。

サイクル内のすべてのノードは同じランクと見なされます。（ほとんどのグラフは非巡回ですが、BUILD ファイルに誤ったサイクルが含まれているため、サイクルが発生します）。

これらの出力形式は、グラフの深さを調べるのに役立ちます。deps(x)、rdeps(x)、allpaths クエリの結果に使用すると、ランク番号は、x からそのランクのノードまでの最短（minrank を使用）または最長（maxrank を使用）パスの長さに等しくなります。maxrank を使用して、ターゲットのビルドに必要なビルドステップの最長シーケンスを特定できます。

注: somepath クエリのランク付けされた出力は、基本的に意味がありません。somepath は最短パスまたは最長パスのいずれかを返すことを保証せず、元のグラフの直接エッジではないパスノード間の「推移的」エッジが含まれる可能性があるためです。

たとえば、左側のグラフでは、--output minrank と --output maxrank がそれぞれ指定されている場合、右側の出力が得られます。

minrank 0 //c:c 1 //b:b 1 //a:a 2 //b:b.cc 2 //a:a.cc

maxrank 0 //c:c 1 //b:b 2 //a:a 2 //b:b.cc 3 //a:a.cc

各ターゲットの位置を出力する

--output location

label_kind と同様に、このオプションは結果内の各ターゲットについて、ターゲットの種類とラベルを出力しますが、そのターゲットの場所を説明する文字列（ファイル名と行番号）が前に付加されます。形式は grep の出力のようになります。したがって、後者を解析できるツール（Emacs や vi など）は、クエリの出力を一連の一致をステップ実行するために使用することもできます。これにより、Bazel クエリツールを依存関係グラフを認識する「BUILD ファイルの grep」として使用できます。

ロケーション情報はターゲットの種類によって異なります（kind 演算子を参照）。ルールの場合、BUILD ファイル内のルール宣言の場所が出力されます。ソースファイルの場合、実際のファイルの 1 行目の場所が出力されます。生成されたファイルの場合、そのファイルを生成するルールの場所が出力されます。（クエリツールには、生成されたファイルの実際の場所を特定するのに十分な情報がありません。また、ビルドがまだ実行されていない場合は、ファイルが存在しない可能性があります）。

パッケージのセットを印刷する

--output package

このオプションは、結果セット内のターゲットが属するすべてのパッケージの名前を出力します。名前は辞書順に出力されます。重複は除外されます。形式的には、これはラベル（パッケージ、ターゲット）のセットからパッケージへの射影です。

外部リポジトリのパッケージは @repo//foo/bar 形式で、メイン リポジトリのパッケージは foo/bar 形式です。

deps(...) クエリと組み合わせて、この出力オプションを使用すると、特定のターゲットセットをビルドするためにチェックアウトする必要があるパッケージのセットを見つけることができます。

結果のグラフを表示する

--output graph

このオプションを指定すると、クエリ結果が一般的な AT&T GraphViz 形式の有向グラフとして出力されます。通常、結果は .png や .svg などのファイルに保存されます。（ワークステーションに dot プログラムがインストールされていない場合は、コマンド sudo apt-get install graphviz を使用してインストールできます）。呼び出しの例については、以下の例のセクションをご覧ください。

この出力形式は、allpaths、deps、rdeps クエリで特に便利です。これらのクエリでは、--output label などの線形形式でレンダリングすると簡単に可視化できない一連のパスが結果に含まれます。

デフォルトでは、グラフは因数分解された形式でレンダリングされます。つまり、トポロジ的に同等のノードが 1 つのノードに統合され、複数のラベルが付けられます。一般的な結果グラフには非常に反復的なパターンが含まれているため、グラフがよりコンパクトで読みやすくなります。たとえば、java_library ルールが同じ genrule によって生成された数百もの Java ソースファイルに依存している場合、ファクタリングされたグラフでは、これらのファイルはすべて単一のノードで表されます。この動作は、--nograph:factored オプションで無効にできます。

--graph:node_limit n

このオプションは、出力のグラフノードのラベル文字列の最大長を指定します。長いラベルは切り捨てられます。-1 を指定すると切り捨てが無効になります。グラフは通常、因数分解された形式で印刷されるため、ノードラベルが非常に長くなることがあります。GraphViz は、このオプションのデフォルト値である 1, 024 文字を超えるラベルを処理できません。--output=graph が使用されていない場合、このオプションは無効です。

--[no]graph:factored

デフォルトでは、グラフは上記で説明したように、因数分解された形式で表示されます。--nograph:factored が指定されている場合、グラフはファクタリングなしで出力されます。これにより、GraphViz を使用した可視化は実用的ではなくなりますが、よりシンプルな形式にすることで、他のツール（grep など）による処理が容易になる可能性があります。--output=graph を使用していない場合、このオプションは無効です。

XML

--output xml

このオプションを指定すると、結果のターゲットが XML 形式で出力されます。出力は次のような XML ヘッダーで始まります。

  <?xml version="1.0" encoding="UTF-8"?>
  <query version="2">

次に、結果グラフ内の各ターゲットの XML 要素がトポロジカル順に続き（順序なしの結果がリクエストされていない場合）、最後に終了

</query>

単純なエントリは、file 種類のターゲットに対して発行されます。

  <source-file name='//foo:foo_main.cc' .../>
  <generated-file name='//foo:libfoo.so' .../>

ただし、ルールの場合、XML は構造化されており、ルールの BUILD ファイルで値が明示的に指定されていない属性も含め、ルールのすべての属性の定義が含まれています。

また、結果には rule-input 要素と rule-output 要素が含まれているため、たとえば srcs 属性の要素が前方依存関係（前提条件）であり、outs 属性の内容が後方依存関係（コンシューマー）であることを知らなくても、依存関係グラフのトポロジを再構築できます。

--noimplicit_deps が指定されている場合、暗黙的な依存関係の rule-input 要素は抑制されます。

  <rule class='cc_binary rule' name='//foo:foo' ...>
    <list name='srcs'>
      <label value='//foo:foo_main.cc'/>
      <label value='//foo:bar.cc'/>
      ...
    </list>
    <list name='deps'>
      <label value='//common:common'/>
      <label value='//collections:collections'/>
      ...
    </list>
    <list name='data'>
      ...
    </list>
    <int name='linkstatic' value='0'/>
    <int name='linkshared' value='0'/>
    <list name='licenses'/>
    <list name='distribs'>
      <distribution value="INTERNAL" />
    </list>
    <rule-input name="//common:common" />
    <rule-input name="//collections:collections" />
    <rule-input name="//foo:foo_main.cc" />
    <rule-input name="//foo:bar.cc" />
    ...
  </rule>

ターゲットのすべての XML 要素には、値がターゲットのラベルである name 属性と、値が --output location によって出力されるターゲットの場所である location 属性が含まれています。

--[no]xml:line_numbers

デフォルトでは、XML 出力に表示されるロケーションには行番号が含まれます。--noxml:line_numbers を指定すると、行番号は出力されません。

--[no]xml:default_values

デフォルトでは、XML 出力には、その種類の属性のデフォルト値である値を持つルール属性は含まれません（たとえば、BUILD ファイルで指定されていない場合や、デフォルト値が明示的に指定されている場合など）。このオプションを指定すると、このような属性値が XML 出力に含まれます。

正規表現

クエリ言語の正規表現は Java 正規表現ライブラリを使用するため、java.util.regex.Pattern の完全な構文を使用できます。

外部リポジトリを使用したクエリ

ビルドが外部リポジトリのルールに依存している場合、クエリ結果にはこれらの依存関係が含まれます。たとえば、//foo:bar が @other-repo//baz:lib に依存している場合、bazel query 'deps(//foo:bar)' は @other-repo//baz:lib を依存関係としてリストします。