BazelCon 2024 註冊現已開放！

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

Bazel 查詢參考資料

回報問題查看原始碼夜間 7.2 7.1 7.0 6.5 6.4

本頁面提供使用 Bazel Query Language 的參考手冊當您使用 bazel query 分析建構依附元件時。此外，會說明 bazel query 支援的輸出格式。

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

其他查詢參考資料

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

動作圖表查詢

動作圖表查詢 (aquery) 會根據設定後的分析作業「目標圖表」會顯示動作、成果和包括模型和網路之間的關係如果你對下列主題感興趣，aquery 非常實用屬性。舉例來說，實際指令會執行，以及指令的輸入內容、輸出內容和助詞。

詳情請參閱查詢參考資料。

可設定的查詢

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

詳情請參閱 cquery 參考資料。

範例

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

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

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

C++ 程式庫執行所有 foo 測試依附於哪些項目不是「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)。只有資料類型。

組合和圖表參照相同資料類型，但重點不同相關面向，例如：

設定：目標的部分順序對結果不重要。
圖表：指定目標的部分順序相當重要。

依附元件圖表中的週期

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

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

隱含依附性

除了建構在 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 (下列區域的這些目標除外) 發生在 deps(x) 中的 y)。

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

星空查詢

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

僅適用於 SkyQuery 的特殊函式

「星空查詢」模式具有額外的查詢函式 allrdeps 和 rbuildfiles。這類函式會針對範圍 (所以這對一般查詢來說無意義)。

指定宇宙範圍

傳遞下列兩個旗標，即可啟用 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) 未在預設查詢中使用。「星空查詢」同樣會遵循顯示 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 ...) 運算子會計算 0 或多個實體集合的聯集目標模式，以空白字元分隔 (不含半形逗號)。

結合 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 目錄下每個套件的所有規則。在這個情況下「dependencies」表示只有規則和檔案目標，因此 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 運算子接受選用的第三個引數 (整數) 用於指定搜尋深度上限的常值。最終產生的圖表只包含指定深度與任意深遠距離內的節點加入任何 Pod 的節點因此，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) 運算子最多只能從以下位置選擇最多 k 個目標引數集 x，且評估為包含只有這些目標「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 集合的成員，標籤 (以絕對格式，例如 //foo:bar) 的 x 包含 (未錨定) 比對規則運算式 pattern和所有參與者目標名稱開頭為 //，可當做替代名稱使用加到 ^ 規則運算式錨點

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

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

不過，這個陳述式需要剖析BUILD bar 樹狀結構，速度較慢，且容易出現錯誤不相關的 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 集合的成員，且為 y 中的所有目標「y」可以看到 predicate x。例如：

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

將會選取 //foo 套件中 //bar 的所有目標仰賴沒有違反瀏覽權限限制的依附元件。

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

expr ::= labels(word, expr)

labels(attr_name, inputs) 運算子會傳回在「label」類型的屬性 attr_name或「標籤清單」英吋「inputs」組合中的一些規則。

舉例來說，labels(srcs, //foo) 會傳回一組出現在目標網頁的 srcs 屬性中 //foo 規則。如果有多個規則在 inputs 中設定 srcs 屬性時，其 srcs 的聯集會傳回。

展開並篩選 test_suites：測試

expr ::= tests(expr)

tests(x) 運算子會傳回所有測試的集合將任何 test_suite 規則展開為「x」集內的規則並套用篩選條件 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 通訊協定緩衝區

以長度分隔的通訊協定緩衝區格式列印目標

--output streamed_proto

列印長度分隔串流 Target敬上通訊協定緩衝區這有助於 (i) 掌握尺寸限制單一通訊協定緩衝區無法容納超過 15 個目標 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 標記 (請參閱結果的排序)。

這種格式有兩個變化版本：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 規則可能依附於數百個 Java 原始碼檔案，所有檔案均由相同的 genrule；所有這些檔案都以單一節點表示系統可能會停用這項行為與 --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