BazelCon 2024 註冊現已開放！

本頁面由 Cloud Translation API 翻譯而成。

Bazel 查詢參考資料

回報問題查看原始碼夜間 7.4 ，直接在 Google Cloud 控制台實際操作。 7.3 · 7.2 · 7.1 · 7.0 · 6.5

本頁是使用 bazel query 分析建構依附元件時，用於 Bazel 查詢語言的參考手冊。此外，會說明 bazel query 支援的輸出格式。

如要瞭解實際用途，請參閱 Bazel 查詢使用方法。

其他查詢參考資料

除了 query，它會在載入後階段目標圖表中執行 Bazel 包含動作圖查詢和可設定的查詢。

動作圖表查詢

動作圖表查詢 (aquery) 會針對已分析的設定目標圖表運作，並提供有關動作、構件及其關係的資訊。如果你對下列主題感興趣，aquery 非常實用屬性。例如實際執行的指令及其輸入內容、輸出內容和助憶法。

詳情請參閱 aquery 參考資料。

可設定的查詢

傳統的 Bazel 查詢會在載入後階段的目標圖表上執行，因此沒有設定和相關概念的概念。值得注意的是，它無法正確解析 select 陳述式，而是會傳回所有可能的 select 解析。不過，可設定的查詢環境 cquery 會正確處理設定，但不會提供這項原始查詢的所有功能。

詳情請參閱 cquery 參考資料。

範例

使用者會如何使用 bazel query？以下是常見的範例：

為什麼 //foo 樹狀結構依附於 //bar/baz？顯示路徑：

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

所有 foo 測試都依賴哪些 C++ 程式庫，而 foo_bin 目標不依賴？

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 查詢的指令碼時，「是」必須進行佇列運算式。
```
 //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 是而是「某」是一個字詞foo 和「foo」都有效字詞

不過，請務必謹慎在目標名稱中使用單引號或雙引號。引用一或多個目標名稱時，請只使用一種引號 (全部使用單引號或全部使用雙引號)。

以下是 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：目標的部分順序不重要。
圖表：目標的部分順序相當重要。

依附元件圖中的循環

建構依附元件圖表應循環出現。

查詢語言所使用的演算法但針對循環次數十分強大詳細介紹系統不會指定週期，因此不應仰賴週期。

隱含依附性

除了在 BUILD 檔案中明確定義的建構依附元件外，Bazel 也會在規則中新增額外的隱含依附元件。舉例來說，每個 Java 規則都會間接依附於 JavaBuilder。隱含的依附元件會使用以 $ 開頭的屬性建立，且無法在 BUILD 檔案中覆寫。

每個預設的 bazel query 會將隱含依附元件列入考量當我們計算查詢結果時您可以使用 --[no]implicit_deps 選項變更這項行為。請注意，由於查詢不會考量設定，因此不會考量潛在的工具鏈。

健全性

Bazel 查詢語言運算式會在建構相依關係圖上運作，這是由所有 BUILD 檔案中的所有規則宣告隱含定義的圖表。請務必瞭解這張圖是抽象的執行建構所有步驟的完整說明。於需要設定才能執行建構；請參閱設定一節。

以 Bazel 查詢語言評估運算式的結果為 true，也就是保守的高估值，而不是精確的結果。如果發生以下情況：使用查詢工具來計算所需的所有來源檔案可能會回報超過您實際需要的資料因為例如，查詢工具系統仍然必須支援訊息翻譯這樣就能在建構中使用該功能

關於圖表順序的保留

作業會保留任何排序順序繼承自其子運算式的限制您可以將這視為「部分順序守恆定律」。假設範例：如果發出查詢來判斷對特定目標的依附元件進行排序按照依附關係圖而定如果將篩選器設為只包含 file 種類的目標介於每個 Pod 之間的遞移關係保留產生的一組目標這些組合實際上與原始圖表有直接關聯 (建構依附元件圖表中沒有檔案-檔案邊緣)。

不過，雖然所有運算子都會保留順序，但某些運算 (例如集合運算) 不會引入任何排序限制。請參考以下運算式：

deps(x) union y

最終結果集的順序保證會保留其子運算式的所有排序限制，也就是說，x 的所有傳遞式依附元件都會以正確的順序排列。不過，查詢不會保證 y 中的目標順序，也不會保證 deps(x) 中的目標順序相對於 y 中的目標順序 (y 中的目標如果同時位於 deps(x) 中，則不在此限)。

導入排序限制的運算子包括： allpaths、deps、rdeps、somepath 和目標模式萬用字元 package:*、dir/... 等

Sky 查詢

「Sky Query」是一種查詢模式，可針對指定「宇宙」運作。

僅適用於 SkyQuery 的特殊函式

Sky 查詢模式提供額外的查詢函式 allrdeps 和 rbuildfiles。這些函式會在整個 Universe 範圍內運作 (這也是為何不建議在一般查詢中使用這些函式的原因)。

指定宇宙範圍

傳遞下列兩個旗標，即可啟用 Sky Query 模式： (--universe_scope 或 --infer_universe_scope) 和 --order_output=no。 --universe_scope=<target_pattern1>,...,<target_patternN> 會告知查詢：預先載入目標模式指定目標模式的遞移性閉包，影響程度可能為加減系統會在這個「範圍」中評估所有查詢。具體來說，allrdeps 和 rbuildfiles 運算子只會傳回這個範圍內的結果。--infer_universe_scope 會指示 Bazel 從查詢運算式推斷 --universe_scope 的值。這項推測值是但這可能不是您想要的結果例如：

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

此為有意義的查詢叫用作業，會嘗試計算 tests 會擴大一些目錄中的目標間接依附於定義使用特定 .bzl 檔案的目標。在這裡 --infer_universe_scope 是便利的方式，尤其是在否則，您必須使用 --universe_scope 自行剖析查詢運算式。

因此，對於使用宇宙範圍運算子的查詢運算式 (例如 allrdeps 和 rbuildfiles 請務必使用 --infer_universe_scope。

與預設查詢相比，「星空查詢」有一些優缺點。主要缺點是無法根據圖表順序排列輸出內容，因此可能會系統禁止使用輸出格式。這麼做的好處是兩種運算子 (allrdeps 和 rbuildfiles) 未在預設查詢中使用。此外，Sky 查詢會透過檢視 Skyframe 圖表來執行工作，而非建立新圖表 (這是預設實作方式)。因此，在某些情況下，它會變得更快，並使用更少的記憶體。

運算式：語法和語意

以下是 Bazel 查詢語言的文法，以 EBNF 標記法表示：

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) 的集合規則。

目標模式可將標籤泛用化，以便在套件和目標中加入萬用字元。舉例來說，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 = expr₁ in expr₂
       | $name

Bazel 查詢語言允許變數。評估 let 運算式的結果與 expr₂ 相同，變數 name 的所有自由出現都會替換為 expr₁ 的值。

例如，let v = foo/... in allpaths($v, //common) intersect $v 是相當於 allpaths(foo/...,//common) intersect foo/...。

變數參照 name 出現，包含 let name = ... 運算式是錯誤。換句話說，頂層查詢運算式不能含有免費值變數。

以上述文法建立方式而言，name 與 word 相似，但做為 C 程式設計中法律 ID 的額外限制語言。變數參照的前面必須加上「$」字元。

每個 let 運算式都只能定義單一變數，但您可以為其建立巢狀結構。

目標模式和變數參照都包含只會傳回一個符記，代表語法模糊不清不過語意不明確，因為屬於法律變數的字詞名稱與合法目標模式字詞的子集不一致。

嚴格說來，let 運算式並未增加查詢語言的表達性，也就是也能表達出沒有用字遣詞不過，這類查詢可讓許多查詢更精簡，也可能有助於更有效率地評估查詢。

加括號的運算式

expr ::= (expr)

半形括號可連結子運算式，強制評估順序。括號內的運算式會評估為其引數的值。

代數集運算：交集、聯集、設定差異

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

這三個運算子會計算其引數的一般集運算。每個運算子都有兩種形式：名目形式 (例如 intersect)，以及等符號形式，例如 ^。兩種形式都相同，但符號形式的輸入速度較快。(為求明確，本頁其餘部分採用了名目形式)。

例如：

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

會評估符合 foo/... 但不含 foo/bar/... 的目標組合。

您可以編寫相同的查詢：

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

intersect (^) 和 union (+) 作業為可交換 (對稱) except (-) 不對稱。剖析器會將這三種運算子左右優先順序，因此建議您使用括號。舉例來說，以下前兩個運算式是相等的，但第三個則不是：

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

從外部來源讀取目標：組合

expr ::= set(word *)

set(a b c ...) 運算子會計算一組零或多個目標模式的聯集，並以空格 (不含逗號) 分隔。

結合 Bourne 殼層的 $(...) 功能時，set() 可提供將單一查詢的結果儲存在一般文字檔中，其他程式 (例如標準 UNIX 殼層工具) 擷取文字檔，然後將結果傳回查詢工具，做為進一步和資料處理之間例如：

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

在下一個範例中，kind(cc_library, deps(//some_dir/foo:main, 5)) 是透過使用 awk 程式篩選 maxrank 值來計算。

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 指令。

函式

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 運算子接受選用的第二個引數 (整數是整數) 用於指定搜尋深度上限的常值。因此，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) 運算子會評估引數集的反依附性宇宙集大眾運輸系統中的 x u。

產生的圖表會依依附元件關係排序。詳情請參閱圖表順序一節。

rdeps 運算子可接受選用的第三個引數，也就是指定搜尋深度上限的整數值。產生的圖表只包含與引數集合中任一節點之間距離為指定深度的節點。因此，rdeps(//foo, //common, 1) 會評估為 //foo 傳遞閉包中直接依附 //common 的所有節點。(這些數字對應 minrank 輸出內容中顯示的排名 format.)如果省略 depth 參數，可以無限搜尋。

所有反向依附元件的遞移性關閉：allrdeps

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

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 為選用項；如果缺少，結果會是單一組，只包含任意選取的一個目標。如果引數集 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) 運算子運算功能找出兩組目標之間的路徑兩項查詢都接受兩種查詢以及一組 S 起點和集合終點 E。somepath 會傳回某些任意路徑上的節點圖表，從 S 中的目標到 E 中的目標；allpaths 會傳回所有路徑上的節點圖表，從 S 中的任何目標到 E 中的任何目標。

產生的圖表會根據依附元件關係排序。詳情請參閱「圖表順序」一節。

目標類型篩選：kind

expr ::= kind(word, expr)

kind(pattern, input) 運算子可將篩選器套用至一組目標，然後捨棄這些目標不屬於預期的類別pattern 參數會指定要比對的目標類型。

舉例來說，下表列出 BUILD 檔案 (針對套件 p) 定義的四個目標類型：

程式碼	目標	種類
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/...) 的評估結果為包含所有 cc_library、cc_binary 等 foo 和 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 的集合，以便 x 成為集合 input 的元素，而 x 的標籤 (以絕對形式，例如 //foo:bar) 則包含規則運算式 pattern 的 (未錨定) 比對項目。由於所有目標名稱都以 // 開頭，因此可用於替代 ^ 規則運算式錨點。

這個運算子通常會提供更快、更可靠的替代方案。 intersect 運算子。舉例來說，假設您要查看 //foo:foo 目標的 bar 項依附元件，一項可評估

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

不過，這項陳述式需要剖析 bar 樹狀結構中的所有 BUILD 檔案，這會導致速度變慢，且在無關的 BUILD 檔案中容易發生錯誤。替代方法是：

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

系統會先計算一組 //foo 依附元件這樣就只會篩選符合指定模式的目標，其他且名稱包含 //bar 做為子字串的目標。

filter(pattern, expr) 運算子的另一個常見用途，是依據檔案名稱或副檔名篩選特定檔案。例如：

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

將會提供一份清單，列出所有用於建構 //foo 的 .cc 檔案。

規則屬性篩選：attr

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

attr(name, pattern, input) 運算子可將篩選器套用至一組目標，並捨棄不符合的目標規則, 規則目標不含 name 屬性定義或規則目標，但屬性值與提供的規則運算式 pattern；模型會評估屬於輸入內容子集

第一個引數 name 是規則屬性的名稱，應與提供的規則運算式模式相符。第二個引數 pattern 是屬性上的規則運算式輕鬆分配獎金attr 運算式會評估為包含所有目標的資料集 x，且 x 是 input 集合的成員是具有已定義 name 屬性，而且屬性值包含 (未錨定) 比對規則運算式 pattern。如果 name 是選用屬性，且規則未明確指定該屬性，則系統會使用預設屬性值進行比較。例如：

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

將會選取所有 //foo 可存取的依附元件連結共用屬性 (例如 cc_binary 規則) 並加上明確設為 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))

會選取 //foo 依附元件中所有具有空白 srcs 屬性的規則，而

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

將會選取 //foo 項依附元件當中指定下列所有規則的規則 data 屬性中至少有一個值 (每個標籤至少由於 // 和 : 的關係，長度為 3 個字元)。

如要在 //foo 依附元件中，具有特定 value 的所有規則，請在 list-type 屬性，請使用

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

這是因為 value 前方的字元會是 [ 或空格，而 value 後方的字元會是逗號或 ]。

規則瀏覽權限篩選：可見

expr ::= visible(expr, expr)

visible(predicate, input) 運算子將篩選器套用至一組目標，並在沒有所需的瀏覽權限

第一個引數 predicate 是一組目標還是只有能看得見的結果visible 運算式會評估為包含所有目標 x 的集合，以便 x 成為 input 集合的成員，且 predicate 中的所有目標 y 對 y 皆可見。例如：

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

會選取 //bar 中 //foo 可依附的所有目標，且不會違反可見度限制。

評估「label」類型的規則屬性

expr ::= labels(word, expr)

labels(attr_name, inputs) 運算子會傳回 inputs 集合中某個規則中屬性 attr_name 中指定的目標集合，屬性類型為「label」或「label 清單」。

舉例來說，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:*) 會列出所有 *_test 和 test_suite 規則 foo 套件中。根據定義，所有結果都是 foo 套件的成員。相對地 tests(foo:*) 查詢會傳回由 bazel test foo:* 執行的個別測試：這可能包括其他套件的測試直接或間接參照透過 test_suite 規則來控制這些權限

套件定義檔：buildfiles

expr ::= buildfiles(expr)

buildfiles(x) 運算子會傳回檔案集，這些檔案會定義 x 集合中每個目標的套件；換句話說，每個套件都會傳回其 BUILD 檔案，以及透過 load 參照的任何 .bzl 檔案。請注意，此也會傳回含有這些參數的套件的 BUILD 檔案 load 個檔案。

這個運算子通常用於判斷建構指定目標所需的檔案或套件，通常會與下方的 --output package 選項搭配使用。例如：

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

會傳回 //foo 間接依附的所有套件組合。

套件定義檔案：rbuildfiles

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

rbuildfiles 運算子會採用以逗號分隔的路徑片段清單，並傳回以遞迴方式依賴這些路徑片段的 BUILD 檔案集。舉例來說，如果 //foo 是套件，rbuildfiles(foo/BUILD) 就會傳回 //foo:BUILD 目標。如果 foo/BUILD 檔案的進入 load('//bar:file.bzl'...，之後「rbuildfiles(bar/file.bzl)」會會傳回 //foo:BUILD 目標，以及其他 BUILD 檔案的目標載入 //bar:file.bzl

rbuildfiles 運算子的範圍是指 --universe_scope 旗標。未直接對應至 BUILD 檔案和 .bzl 的檔案檔案不會影響結果。舉例來說，即使來源檔案 (例如 foo.cc) 在 BUILD 檔案中明確提及，系統也會略過這些檔案。不過，系統會尊重符號連結，因此如果 foo/BUILD 是 bar/BUILD 的符號連結，rbuildfiles(bar/BUILD) 的結果就會包含 //foo:BUILD。

rbuildfiles 運算子幾乎是 buildfiles 運算子。然而，這種道德反轉就連單一方向來說都較為強烈：rbuildfiles 的輸出內容和輸入 buildfiles；前者只會包含套件中的 BUILD 個檔案目標，後者則可能包含這類目標在另一個方向上，對應關係較為薄弱。buildfiles 運算子的輸出內容是與所有套件和對應的目標。bzl 特定輸入內容所需的檔案不過，rbuildfiles 運算子的輸入內容而非這些目標，而是對應這些目標的路徑片段。

套件定義檔案：loadfiles

expr ::= loadfiles(expr)

loadfiles(x) 運算子會傳回一組當中載入每個目標套件所需的 Starlark 檔案設定「x」。換句話說，對於每個套件，它會傳回從其 BUILD 檔案參照的 .bzl 檔案。

輸出格式

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，請參閱結果排序的附註)。(按拓撲排序即為節點比其所有繼承者更早出現)。當然這些都是圖形的可能拓撲排序 (往回推移) postorder 僅剩一個)；也就是未指定的

輸出 somepath 查詢的輸出內容時，節點會依照路徑的順序顯示。

注意：在某些極端的情況下，可能會有兩個不同的目標加入相同標籤例如 sh_binary 規則及其單一 (隱含) srcs 檔案可同時呼叫 foo.sh。如果查詢結果包含這兩個目標，輸出內容 (以 label 格式) 就會顯示重複項目。使用 label_kind 格式 (請參閱下文) 時，兩者之間的差異就會變得明顯：兩個目標名稱相同，但其中一個是 sh_binary rule 類型，另一個是 source file 類型。

列印每個目標的標籤和類型

--output label_kind

就像 label 一樣，這個輸出格式會以拓樸順序，在結果圖中列印每個目標的標籤，但標籤前會加上目標的 kind。

以通訊協定緩衝區格式列印目標

--output proto

將查詢輸出內容列印為 QueryResult 通訊協定緩衝區

以長度分隔的 Protocol Buffers 格式列印目標

--output streamed_proto

列印長度分隔串流 Target 通訊協定緩衝區這項功能可用於(i)在單一 QueryResult 中放入太多目標時，避開通訊協定緩衝區的大小限制，或(ii)在 Bazel 仍在輸出時開始處理。

以文字 proto 格式列印目標

--output textproto

與 --output proto 類似，但會以文字格式輸出 QueryResult 通訊協定緩衝區。

以 ndjson 格式列印目標

--output streamed_jsonproto

與 --output streamed_proto 類似，但會以 ndjson 格式輸出 Target 通訊協定緩衝區的串流。

按照排名順序顯示每個目標的標籤

--output minrank --output maxrank

與 label 一樣，minrank 和 maxrank 輸出格式會在結果圖中列印每個目標的標籤，但標籤會以排名順序顯示，而非以拓樸順序顯示，並在標籤前方加上排名號碼。這些項目不會受到結果排序 --[no]order_results 旗標的影響 (請參閱結果排序的相關注意事項)。

這個格式有兩種變化版本：minrank 會根據從根節點到該節點的最短路徑長度，為每個節點排序。「根」節點 (沒有傳入邊的節點) 的等級為 0，其後繼節點的等級為 1，依此類推 (邊一律從目標指向其必要條件：目標所依賴的目標)。

maxrank 會根據最長長度為各個節點排名提供完整路徑再說一次「根層級」排名為 0、所有其他節點的排名高於所有節點包括前身。

系統會將週期中的所有節點視為相同排名，(大多數圖表都是無環的，但循環確實會發生，原因在於 BUILD 檔案包含錯誤的循環)。

這些輸出格式可用於瞭解圖表的深度。如果用於 deps(x)、rdeps(x) 的結果或 allpaths 查詢，那麼排名數字等於最短 (含 minrank) 或最長的長度 (含 maxrank) 從 x 到中節點的路徑排名maxrank可用來判斷建構目標所需的最長建構步驟序列。

舉例來說，當分別指定 --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 查詢工具做為可偵測依附元件的「grep for BUILD 檔案」。

位置資訊會因目標類型而異 (請參閱 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。

根據預設，圖表會以「因數」格式呈現。也就是說，拓樸相等的節點會合併為單一節點，並且有多個標籤。這可讓圖表更精簡易讀，因為一般結果圖表含有高度重複的模式。舉例來說，java_library 規則可能會依賴由同一個 genrule 產生的數百個 Java 來源檔案；在分解圖表中，所有這些檔案都由單一節點代表。您可以使用 --nograph:factored 選項停用這項行為。

`--graph:node_limit n`

這個選項會指定輸出圖表節點較長的標籤會遭到截斷；-1 會停用截斷功能。由於圖表通常會以因式化形式列印，因此節點標籤可能會非常長。GraphViz 無法處理標籤超過 1024 個字元 (此為預設值) 只要採用這個選項除非使用 --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 屬性的內容是後向依附元件 (消費者)，即可重建依附元件圖表的拓樸結構。

隱含依附元件的 rule-input 元素會遭到抑制，前提是已指定 --noimplicit_deps。

  <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 屬性，其值為目標的標籤，以及 location 屬性，其值為 --output location 列印的目標位置。

`--[no]xml:line_numbers`

根據預設，XML 輸出內容中顯示的位置會包含行號。如果您指定 --noxml:line_numbers，系統就不會列印行號。

`--[no]xml:default_values`

根據預設，XML 輸出不會包含含有值的規則屬性是該種類屬性的預設值 (例如，未在 BUILD 檔案中指定，或預設值為明確提供)。這個選項會將這些屬性值納入 XML 輸出內容。

規則運算式

查詢語言中的規則運算式使用 Java regex 程式庫，因此您可以使用完整的語法 java.util.regex.Pattern。

使用外部存放區查詢

如果建構取決於外部存放區的規則 ( WORKSPACE 檔案)，查詢結果會包含這些依附元件。適用對象舉例來說，如果 //foo:bar 依賴 //external:some-lib //external:some-lib 會繫結至 @other-repo//baz:lib，然後 bazel query 'deps(//foo:bar)' 會列出「@other-repo//baz:lib」和 //external:some-lib 做為依附元件。

外部存放區本身不是建構作業的依附元件。也就是說，在上述範例中，//external:other-repo 並非依附元件。這項服務也可視為 //external 套件的成員進行查詢例如：

  # Querying over all members of //external returns the repository.
  bazel query 'kind(http_archive, //external:*)'
  //external:other-repo

  # ...but the repository is not a dependency.
  bazel query 'kind(http_archive, deps(//foo:bar))'
  INFO: Empty results