Chương trình đăng ký tham gia sự kiện BazelCon 2024 đã bắt đầu!

Trang này được dịch bởi Cloud Translation API.

Tài liệu tham khảo về truy vấn Bazel

7.3 · 7.2 · 7.1 · 7.0 · 6.5

Trang này là tài liệu tham khảo cho Ngôn ngữ truy vấn Bazel được sử dụng khi bạn sử dụng bazel query để phân tích các phần phụ thuộc của bản dựng. Phương thức này cũng mô tả các định dạng đầu ra mà bazel query hỗ trợ.

Để biết các trường hợp sử dụng thực tế, hãy xem Hướng dẫn truy vấn Bazel.

Tài liệu tham khảo khác về truy vấn

Ngoài query chạy trên biểu đồ mục tiêu giai đoạn sau tải, Baazel còn bao gồm truy vấn biểu đồ hành động và truy vấn có thể định cấu hình.

Truy vấn biểu đồ hành động

Truy vấn biểu đồ hành động (aquery) hoạt động trên Biểu đồ mục tiêu đã định cấu hình sau khi phân tích và hiển thị thông tin về Hành động, Cấu phần phần mềm và mối quan hệ giữa các hành động đó. aquery rất hữu ích khi bạn quan tâm đến các thuộc tính của Thao tác/Cấu phần phần mềm được tạo từ Biểu đồ mục tiêu đã định cấu hình. Ví dụ: các lệnh thực tế chạy và dữ liệu đầu vào, đầu ra và câu thần chú của các lệnh đó.

Để biết thêm thông tin chi tiết, hãy xem tài liệu tham khảo về truy vấn.

Truy vấn có thể định cấu hình

Truy vấn Bazel truyền thống chạy trên biểu đồ mục tiêu giai đoạn sau khi tải và do đó không có khái niệm về cấu hình cũng như các khái niệm liên quan. Đáng chú ý là phương thức này không phân giải chính xác các câu lệnh chọn mà thay vào đó sẽ trả về mọi độ phân giải có thể có của lựa chọn. Tuy nhiên, môi trường truy vấn có thể định cấu hình cquery sẽ xử lý các cấu hình đúng cách nhưng không cung cấp tất cả chức năng của truy vấn gốc này.

Để biết thêm thông tin chi tiết, hãy xem tài liệu tham khảo về cquery.

Ví dụ

Mọi người sử dụng bazel query như thế nào? Dưới đây là các ví dụ điển hình:

Tại sao cây //foo phụ thuộc vào //bar/baz? Hiển thị một đường dẫn:

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

Tất cả kiểm thử foo phụ thuộc vào thư viện C++ nào mà mục tiêu foo_bin thì không?

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

Mã thông báo: Cú pháp từ vựng

Biểu thức trong ngôn ngữ truy vấn bao gồm các mã thông báo sau:

Từ khoá, chẳng hạn như let. Từ khoá là các từ dành riêng trong ngôn ngữ đó và từng từ trong số đó được mô tả ở bên dưới. Bộ từ khoá hoàn chỉnh là:
- except
- in
- intersect
- let
- set
- union
Từ, chẳng hạn như "foo/...", ".*test rule" hoặc "//bar/baz:all". Nếu chuỗi ký tự được "dấu ngoặc kép" (bắt đầu và kết thúc bằng dấu ngoặc đơn ' hoặc bắt đầu và kết thúc bằng dấu ngoặc kép "), thì đó là một từ. Nếu một chuỗi ký tự không được đặt trong dấu ngoặc kép, thì chuỗi đó vẫn có thể được phân tích cú pháp dưới dạng một từ. Từ không được trích dẫn là các chuỗi ký tự được lấy từ các ký tự chữ cái A-Za-z, chữ số 0-9 và các ký tự đặc biệt */@.-_:$~[] (dấu sao, dấu gạch chéo lên, dấu @, dấu chấm, dấu gạch nối, dấu gạch dưới, dấu hai chấm, dấu đô la, dấu ngã, dấu ngoặc vuông trái, dấu ngoặc vuông phải). Tuy nhiên, các từ không được trích dẫn không được bắt đầu bằng dấu gạch nối - hoặc dấu hoa thị * mặc dù tên mục tiêu tương đối có thể bắt đầu bằng các ký tự đó. Theo quy tắc đặc biệt, nhằm đơn giản hoá việc xử lý các nhãn tham chiếu đến những kho lưu trữ bên ngoài, những từ không có dấu ngoặc kép bắt đầu bằng @@ có thể chứa + ký tự.

Các từ không được đặt dấu ngoặc kép cũng không được chứa ký tự dấu cộng + hoặc dấu bằng =, mặc dù các ký tự đó được phép xuất hiện trong tên mục tiêu. Khi viết mã tạo biểu thức truy vấn, bạn phải đặt tên mục tiêu trong dấu ngoặc kép.

Bạn cần phải trích dẫn khi viết tập lệnh tạo biểu thức truy vấn Bazel từ các giá trị do người dùng cung cấp.
```
 //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.
```
Xin lưu ý rằng câu trích dẫn này bổ sung cho bất kỳ câu trích dẫn nào mà lệnh shell yêu cầu, chẳng hạn như:
```
bazel query ' "//foo:bar=wiz" '   # single-quotes for shell, double-quotes for Bazel.
```
Từ khoá và toán tử, khi được trích dẫn, được coi là từ thông thường. Ví dụ: some là từ khoá nhưng "some" (một số) là một từ. Cả foo và "foo" đều là từ.

Tuy nhiên, hãy cẩn thận khi sử dụng dấu ngoặc đơn hoặc dấu ngoặc kép trong tên mục tiêu. Khi trích dẫn một hoặc nhiều tên mục tiêu, chỉ sử dụng một loại dấu ngoặc kép (tất cả dấu ngoặc đơn hoặc tất cả dấu ngoặc kép).

Sau đây là ví dụ về ý nghĩa của chuỗi truy vấn 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
```
Chúng tôi chọn cú pháp này để không cần dấu ngoặc kép trong hầu hết các trường hợp. Ví dụ về ".*test rule" (không bình thường) cần có dấu ngoặc kép: ví dụ này bắt đầu bằng dấu chấm và chứa một dấu cách. Việc trích dẫn "cc_library" là không cần thiết nhưng không gây hại.
Dấu câu, chẳng hạn như dấu ngoặc đơn (), dấu chấm . và dấu phẩy ,. Những từ có chứa dấu câu (ngoài các trường hợp ngoại lệ được liệt kê ở trên) phải được đặt trong cặp dấu ngoặc kép/dấu ngoặc đơn.

Các ký tự khoảng trắng bên ngoài từ được trích dẫn sẽ bị bỏ qua.

Các khái niệm về ngôn ngữ truy vấn Bazel

Ngôn ngữ truy vấn Bazel là ngôn ngữ của biểu thức. Mọi biểu thức đều đánh giá thành một tập hợp được sắp xếp một phần các mục tiêu, hoặc tương đương là một biểu đồ (DAG) của các mục tiêu. Đây là kiểu dữ liệu duy nhất.

Tập hợp và biểu đồ tham chiếu đến cùng một loại dữ liệu, nhưng nhấn mạnh các khía cạnh khác nhau của dữ liệu đó, ví dụ:

Đặt: Thứ tự một phần của các mục tiêu không đáng chú ý.
Biểu đồ: Thứ tự một phần của các mục tiêu là rất quan trọng.

Các chu kỳ trong biểu đồ phần phụ thuộc

Tạo biểu đồ phần phụ thuộc phải có chu trình.

Các thuật toán mà ngôn ngữ truy vấn sử dụng được dùng trong đồ thị không chu trình, nhưng vẫn mạnh mẽ chống lại các chu trình. Thông tin chi tiết về cách xử lý chu kỳ chưa được chỉ định và không nên dựa vào.

Phần phụ thuộc ngầm ẩn

Ngoài việc xây dựng các phần phụ thuộc được xác định rõ ràng trong các tệp BUILD, Bazel thêm các phần phụ thuộc ngầm ẩn khác vào các quy tắc. Ví dụ: mọi quy tắc Java đều ngầm phụ thuộc vào JavaBuilder. Các phần phụ thuộc ngầm ẩn được thiết lập bằng cách sử dụng các thuộc tính bắt đầu bằng $ và không thể ghi đè các phần phụ thuộc đó trong tệp BUILD.

Theo mặc định, bazel query sẽ tính đến các phần phụ thuộc ngầm ẩn khi tính toán kết quả truy vấn. Bạn có thể thay đổi hành vi này bằng tuỳ chọn --[no]implicit_deps. Xin lưu ý rằng vì truy vấn không xem xét cấu hình nên các chuỗi công cụ tiềm năng không bao giờ được xem xét.

Độ âm thanh

Biểu thức ngôn ngữ truy vấn Bazel hoạt động trên biểu đồ phần phụ thuộc của bản dựng. Biểu đồ này được ngầm xác định trong mọi nội dung khai báo quy tắc trong mọi tệp BUILD. Bạn cần hiểu rằng biểu đồ này có phần trừu tượng và không cấu thành nội dung mô tả đầy đủ về cách thực hiện tất cả các bước của một bản dựng. Để tạo bản dựng, bạn cũng cần có cấu hình; hãy xem phần cấu hình trong Hướng dẫn sử dụng để biết thêm chi tiết.

Kết quả của việc đánh giá một biểu thức trong ngôn ngữ truy vấn Bazel là đúng đối với tất cả cấu hình, nghĩa là kết quả này có thể là một giá trị ước chừng an toàn và không chính xác. Nếu bạn sử dụng công cụ truy vấn để tính toán tập hợp tất cả các tệp nguồn cần thiết trong quá trình tạo bản dựng, thì công cụ này có thể báo cáo nhiều hơn mức cần thiết, chẳng hạn như công cụ truy vấn sẽ bao gồm tất cả các tệp cần thiết để hỗ trợ dịch thông báo, mặc dù bạn không có ý định sử dụng tính năng đó trong bản dựng.

Về việc duy trì thứ tự biểu đồ

Các toán tử giữ nguyên mọi quy tắc ràng buộc thứ tự kế thừa từ biểu thức con. Bạn có thể coi điều này là "quy luật bảo toàn thứ tự một phần". Hãy xem xét một ví dụ: nếu bạn đưa ra một truy vấn để xác định tập hợp đóng bắc cầu của các phần phụ thuộc của một mục tiêu cụ thể, thì tập hợp kết quả sẽ được sắp xếp theo biểu đồ phần phụ thuộc. Nếu bạn lọc tập hợp đó để chỉ bao gồm các mục tiêu thuộc loại file, thì mối quan hệ thứ tự một phần truyền tải tương tự sẽ giữ nguyên giữa mọi cặp mục tiêu trong tập hợp con thu được – mặc dù không có cặp nào trong số này thực sự được kết nối trực tiếp trong biểu đồ ban đầu. (Không có cạnh tệp-tệp nào trong biểu đồ phần phụ thuộc của bản dựng).

Tuy nhiên, mặc dù tất cả các toán tử đều duy trì thứ tự, một số toán tử, chẳng hạn như thao tác tập hợp không tạo ra bất kỳ quy tắc ràng buộc nào về thứ tự của riêng chúng. Hãy xem xét biểu thức sau:

deps(x) union y

Thứ tự của tập hợp kết quả cuối cùng được đảm bảo sẽ giữ nguyên tất cả các quy tắc ràng buộc thứ tự của biểu thức con, cụ thể là tất cả các phần phụ thuộc bắc cầu của x được sắp xếp chính xác so với nhau. Tuy nhiên, truy vấn này không đảm bảo gì về thứ tự của các mục tiêu trong y cũng như thứ tự của các mục tiêu trong deps(x) so với các mục tiêu trong y (ngoại trừ các mục tiêu trong y cũng có trong deps(x)).

Các toán tử đưa ra các quy tắc ràng buộc về thứ tự bao gồm: allpaths, deps, rdeps, somepath và các ký tự đại diện mẫu mục tiêu package:*, dir/..., v.v.

Truy vấn bầu trời

Sky Query là chế độ truy vấn hoạt động trong phạm vi vũ trụ được chỉ định.

Các hàm đặc biệt chỉ có trong SkyQuery

Chế độ Truy vấn bầu trời có các hàm truy vấn bổ sung allrdeps và rbuildfiles. Các hàm này hoạt động trên toàn bộ phạm vi vũ trụ (đó là lý do tại sao chúng không phù hợp với Truy vấn thông thường).

Chỉ định phạm vi vũ trụ

Chế độ Truy vấn trên bầu trời được kích hoạt bằng cách truyền hai cờ sau: (--universe_scope hoặc --infer_universe_scope) và --order_output=no. --universe_scope=<target_pattern1>,...,<target_patternN> yêu cầu truy vấn tải trước tính năng đóng kín bắc cầu của mẫu mục tiêu do các mẫu mục tiêu chỉ định, có thể là cả tính năng cộng và trừ. Sau đó, tất cả truy vấn sẽ được đánh giá trong "phạm vi" này. Cụ thể, các toán tử allrdeps và rbuildfiles chỉ trả về kết quả từ phạm vi này. --infer_universe_scope yêu cầu Bazel suy luận giá trị cho --universe_scope từ biểu thức truy vấn. Giá trị được dự đoán này là danh sách các mẫu mục tiêu riêng biệt trong biểu thức truy vấn, nhưng có thể không phải là điều bạn muốn. Ví dụ:

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

Danh sách các mẫu mục tiêu duy nhất trong biểu thức truy vấn này là ["//my:target"], vì vậy, Bazel xử lý vấn đề này giống như lệnh gọi:

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

Nhưng kết quả của truy vấn đó với --universe_scope chỉ là //my:target; không có phần phụ thuộc ngược nào của //my:target trong vũ trụ, bằng cách tạo! Mặt khác, hãy cân nhắc:

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

Đây là một lệnh gọi truy vấn có ý nghĩa đang cố gắng tính toán các mục tiêu kiểm thử trong phần mở rộng tests của các mục tiêu trong một số thư mục phụ thuộc bắc cầu vào các mục tiêu có định nghĩa sử dụng tệp .bzl nhất định. Ở đây, --infer_universe_scope là để thuận tiện, đặc biệt là trong trường hợp lựa chọn --universe_scope sẽ yêu cầu bạn tự phân tích cú pháp biểu thức truy vấn.

Vì vậy, đối với biểu thức truy vấn sử dụng các toán tử ở phạm vi vũ trụ như allrdeps và rbuildfiles, hãy nhớ chỉ sử dụng --infer_universe_scope nếu hành vi của nó là điều bạn muốn.

Truy vấn Sky có một số ưu điểm và nhược điểm so với truy vấn mặc định. Nhược điểm chính là không thể sắp xếp đầu ra theo thứ tự trong biểu đồ và do đó, một số định dạng đầu ra bị cấm. Ưu điểm của lớp này là cung cấp 2 toán tử (allrdeps và rbuildfiles) không có trong truy vấn mặc định. Đồng thời, Sky Query thực hiện công việc của mình bằng cách xem xét biểu đồ Skyframe, thay vì tạo một biểu đồ mới (đây là cách triển khai mặc định). Do đó, trong một số trường hợp, công cụ này nhanh hơn và sử dụng ít bộ nhớ hơn.

Biểu thức: Cú pháp và ngữ nghĩa của ngữ pháp

Đây là cú pháp của ngôn ngữ truy vấn Bazel, được biểu thị bằng ký hiệu 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 ... ')'

Các phần sau đây mô tả theo thứ tự từng tác phẩm của ngữ pháp này.

Mẫu mục tiêu

expr ::= word

Theo cú pháp, mẫu mục tiêu chỉ là một từ. Giá trị này được hiểu là một tập hợp các mục tiêu (không theo thứ tự). Mẫu mục tiêu đơn giản nhất là nhãn, giúp xác định một mục tiêu duy nhất (tệp hoặc quy tắc). Ví dụ: mẫu mục tiêu //foo:bar sẽ đánh giá thành một tập hợp chứa một phần tử, mục tiêu, quy tắc bar.

Các mẫu mục tiêu tổng quát hoá các nhãn để đưa ký tự đại diện vào gói và mục tiêu. Ví dụ: foo/...:all (hoặc chỉ foo/...) là mẫu mục tiêu đánh giá một tập hợp chứa tất cả quy tắc trong mọi gói theo cách đệ quy bên dưới thư mục foo; bar/baz:all là mẫu mục tiêu đánh giá một tập hợp chứa mọi quy tắc trong gói bar/baz chứ không phải các gói con.

Tương tự, foo/...:* là mẫu mục tiêu đánh giá một tập hợp chứa tất cả các mục tiêu (quy tắc và tệp) trong mỗi gói theo cách đệ quy bên dưới thư mục foo; bar/baz:* sẽ đánh giá một tập hợp chứa tất cả mục tiêu trong gói bar/baz, chứ không phải các gói con.

Vì ký tự đại diện :* khớp với các tệp cũng như quy tắc, nên ký tự này thường hữu ích hơn :all đối với các truy vấn. Ngược lại, ký tự đại diện :all (ngầm ẩn trong các mẫu mục tiêu như foo/...) thường hữu ích hơn cho các bản dựng.

Mẫu mục tiêu bazel query hoạt động giống như mục tiêu bản dựng bazel build. Để biết thêm thông tin, hãy xem phần Mẫu mục tiêu hoặc nhập bazel help target-syntax.

Mẫu mục tiêu có thể đánh giá thành một tập hợp singleton (trong trường hợp nhãn), thành một tập hợp chứa nhiều phần tử (như trong trường hợp foo/... có hàng nghìn phần tử) hoặc thành tập hợp trống nếu mẫu mục tiêu không khớp với mục tiêu nào.

Tất cả các nút trong kết quả của biểu thức mẫu mục tiêu được sắp xếp chính xác tương ứng với nhau theo mối quan hệ phần phụ thuộc. Vì vậy, kết quả của foo:* không chỉ là tập hợp các mục tiêu trong gói foo, mà còn là biểu đồ của các mục tiêu đó. (Không đảm bảo về thứ tự tương đối của các nút kết quả so với các nút khác.) Để biết thêm thông tin chi tiết, hãy xem phần thứ tự biểu đồ.

Biến

expr ::= let name = expr₁ in expr₂
       | $name

Ngôn ngữ truy vấn Bazel cho phép định nghĩa và tham chiếu đến các biến. Kết quả đánh giá biểu thức let giống như kết quả của expr₂, với tất cả các lần xuất hiện tự do của biến name được thay thế bằng giá trị của expr₁.

Ví dụ: let v = foo/... in allpaths($v, //common) intersect $v tương đương với allpaths(foo/...,//common) intersect foo/....

Lỗi nếu xảy ra tham chiếu biến name không phải trong biểu thức let name = ... đi kèm. Nói cách khác, biểu thức truy vấn cấp cao nhất không thể có biến miễn phí.

Trong các tác phẩm ngữ pháp ở trên, name giống như từ, nhưng có thêm một ràng buộc nữa đó là giá trị nhận dạng hợp pháp trong ngôn ngữ lập trình C. Bạn phải thêm ký tự "$" vào đầu tham chiếu đến biến.

Mỗi biểu thức let chỉ xác định một biến, nhưng bạn có thể lồng các biến đó.

Cả mẫu mục tiêu và tham chiếu biến đều chỉ bao gồm một mã thông báo, một từ, tạo ra sự mơ hồ về cú pháp. Tuy nhiên, không có sự không rõ ràng về ngữ nghĩa, vì tập hợp con các từ là tên biến hợp pháp bị tách khỏi tập hợp con các từ là mẫu mục tiêu hợp pháp.

Về mặt kỹ thuật, biểu thức let không làm tăng tính biểu cảm của ngôn ngữ truy vấn: mọi truy vấn có thể biểu thị bằng ngôn ngữ này cũng có thể được biểu thị mà không cần biểu thức let. Tuy nhiên, các hàm này giúp cải thiện tính ngắn gọn của nhiều truy vấn và cũng có thể giúp đánh giá truy vấn hiệu quả hơn.

Biểu thức trong dấu ngoặc đơn

expr ::= (expr)

Dấu ngoặc đơn liên kết các biểu thức phụ để buộc một thứ tự đánh giá. Biểu thức nằm trong ngoặc đơn sẽ đánh giá giá trị của đối số.

Toán tử tập đại số: giao điểm, hợp nhất, hiệu sai số

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

Ba toán tử này tính toán các toán tử thông thường của tập hợp cho đối số của chúng. Mỗi toán tử có hai dạng: dạng danh nghĩa, chẳng hạn như intersect và dạng biểu tượng, chẳng hạn như ^. Cả hai dạng đều tương đương; các dạng ký hiệu đều nhập nhanh hơn. (Để cho rõ ràng, phần còn lại của trang này sử dụng các dạng danh nghĩa.)

Ví dụ:

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

đánh giá tập hợp mục tiêu phù hợp với foo/... nhưng không khớp với foo/bar/....

Bạn có thể viết cùng một truy vấn như:

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

Toán tử intersect (^) và union (+) có tính giao hoán (đối xứng); except (-) là bất đối xứng. Trình phân tích cú pháp coi cả 3 toán tử là liên kết bên trái và có mức độ ưu tiên bằng nhau, vì vậy, bạn có thể cần dùng dấu ngoặc đơn. Ví dụ: hai biểu thức đầu tiên trong số này tương đương nhau, nhưng biểu thức thứ ba thì không:

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

Đọc mục tiêu từ một nguồn bên ngoài: set

expr ::= set(word *)

Toán tử set(a b c ...) tính toán hợp của một tập hợp các mẫu mục tiêu không hoặc nhiều hơn, được phân tách bằng khoảng trắng (không có dấu phẩy).

Cùng với tính năng $(...) của Bourne shell, set() cung cấp phương tiện lưu kết quả của một truy vấn trong tệp văn bản thông thường, điều chỉnh tệp văn bản đó bằng các chương trình khác (chẳng hạn như công cụ shell UNIX tiêu chuẩn), sau đó đưa kết quả trở lại công cụ truy vấn làm giá trị để xử lý thêm. Ví dụ:

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

Trong ví dụ tiếp theo,kind(cc_library, deps(//some_dir/foo:main, 5)) được tính bằng cách lọc các giá trị maxrank bằng chương trình awk.

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

Trong những ví dụ này, $(<foo) là cách viết tắt của $(cat foo), nhưng bạn cũng có thể sử dụng các lệnh shell không phải cat, chẳng hạn như lệnh awk trước đó.

Hàm

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

Ngôn ngữ truy vấn xác định một số hàm. Tên của hàm xác định số lượng và loại đối số mà hàm đó yêu cầu. Các hàm sau đây có sẵn:

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

Đóng bắc cầu các phần phụ thuộc: phần phụ thuộc

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

Toán tử deps(x) sẽ đánh giá biểu đồ được tạo thành từ đóng bắc cầu của các phần phụ thuộc của nhóm đối số x. Ví dụ: giá trị của deps(//foo) là biểu đồ phần phụ thuộc đã bị can thiệp vào hệ thống tại nút duy nhất foo, bao gồm tất cả các phần phụ thuộc của nút đó. Giá trị của deps(foo/...) là các biểu đồ phần phụ thuộc có gốc là tất cả quy tắc trong mọi gói bên dưới thư mục foo. Trong trường hợp này, "phần phụ thuộc" chỉ có nghĩa là quy tắc và mục tiêu tệp. Do đó, các tệp BUILD và Starlark cần để tạo các mục tiêu này không được đưa vào đây. Để làm được điều đó, bạn nên sử dụng toán tử buildfiles.

Biểu đồ thu được được sắp xếp theo mối quan hệ phụ thuộc. Để biết thêm thông tin chi tiết, hãy xem phần thứ tự biểu đồ.

Toán tử deps chấp nhận đối số thứ hai không bắt buộc, là một số nguyên cố định chỉ định giới hạn trên về độ sâu của lượt tìm kiếm. Vì vậy, deps(foo:*, 0) trả về tất cả mục tiêu trong gói foo, trong khi deps(foo:*, 1) bao gồm thêm các điều kiện tiên quyết trực tiếp của bất kỳ mục tiêu nào trong gói foo và deps(foo:*, 2) bao gồm thêm các nút có thể truy cập trực tiếp từ các nút trong deps(foo:*, 1), v.v. (Những con số này tương ứng với các thứ hạng hiển thị ở định dạng đầu ra minrank.) Nếu tham số depth bị bỏ qua, lượt tìm kiếm sẽ không bị ràng buộc: hệ thống tính toán việc đóng bắc cầu phản xạ cho các điều kiện tiên quyết.

Đóng bắc cầu các phần phụ thuộc ngược: rdeps

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

Toán tử rdeps(u, x) sẽ đánh giá các phần phụ thuộc ngược của tập hợp đối số x trong đóng bắc cầu của tập hợp vũ trụ u.

Biểu đồ kết quả được sắp xếp theo mối quan hệ phần phụ thuộc. Xem phần về thứ tự biểu đồ để biết thêm chi tiết.

Toán tử rdeps chấp nhận đối số thứ ba không bắt buộc, là một số nguyên cố định chỉ định giới hạn trên về độ sâu của lượt tìm kiếm. Biểu đồ kết quả chỉ bao gồm các nút trong khoảng cách chiều sâu đã chỉ định từ bất kỳ nút nào trong tập hợp đối số. Vì vậy, rdeps(//foo, //common, 1) sẽ đánh giá tất cả các nút trong tập hợp đóng bắc cầu của //foo trực tiếp phụ thuộc vào //common. (Những số này tương ứng với thứ hạng hiển thị trong định dạng đầu ra minrank.) Nếu tham số depth bị bỏ qua, thì lượt tìm kiếm sẽ không bị ràng buộc.

Đóng bắc cầu tất cả các phần phụ thuộc ngược: ardeps

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

Toán tử allrdeps hoạt động giống như toán tử rdeps, ngoại trừ việc "bộ vũ trụ" là bất kỳ cờ --universe_scope nào được đánh giá, thay vì được chỉ định riêng. Do đó, nếu --universe_scope=//foo/... được truyền, thì allrdeps(//bar) tương đương với rdeps(//foo/..., //bar).

Phần phụ thuộc đảo ngược trực tiếp trong cùng một gói: same_pkg_direct_rdeps

expr ::= same_pkg_direct_rdeps(expr)

Toán tử same_pkg_direct_rdeps(x) đánh giá cho tập hợp đầy đủ các mục tiêu nằm trong cùng một gói với mục tiêu trong tập hợp đối số và trực tiếp phụ thuộc vào mục tiêu đó.

Xử lý gói của mục tiêu: các gói đồng cấp

expr ::= siblings(expr)

Toán tử siblings(x) đánh giá cho tập hợp đầy đủ các mục tiêu nằm trong cùng một gói với mục tiêu trong tập hợp đối số.

Lựa chọn tuỳ ý: một số

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

Toán tử some(x, k) chọn tối đa k mục tiêu tuỳ ý từ tập hợp đối số x và đánh giá thành một tập hợp chỉ chứa các mục tiêu đó. Tham số k là không bắt buộc; nếu thiếu, kết quả sẽ là một tập hợp singleton chỉ chứa một mục tiêu được chọn tuỳ ý. Nếu kích thước của tập hợp đối số x nhỏ hơn k, thì toàn bộ tập hợp đối số x sẽ được trả về.

Ví dụ: biểu thức some(//foo:main union //bar:baz) đánh giá thành một tập hợp singleton chứa //foo:main hoặc //bar:baz, mặc dù tập hợp nào không được xác định. Biểu thức some(//foo:main union //bar:baz, 2) hoặc some(//foo:main union //bar:baz, 3) trả về cả //foo:main và //bar:baz.

Nếu đối số là một singleton, thì some sẽ tính toán hàm nhận dạng: some(//foo:main) tương đương với //foo:main.

Nếu bộ đối số được chỉ định bị trống, như trong biểu thức some(//foo:main intersect //bar:baz) thì sẽ là lỗi.

Toán tử đường dẫn: somepath, allpaths

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

Toán tử somepath(S, E) và allpaths(S, E) tính toán đường dẫn giữa hai nhóm mục tiêu. Cả hai truy vấn đều chấp nhận 2 đối số, một tập hợp S gồm các điểm xuất phát và một tập hợp E gồm các điểm kết thúc. somepath trả về biểu đồ các nút trên một số đường dẫn tuỳ ý từ một mục tiêu trong S đến một mục tiêu trong E; allpaths trả về biểu đồ các nút trên tất cả đường dẫn từ bất kỳ mục tiêu nào trong S đến bất kỳ mục tiêu nào trong E.

Các biểu đồ kết quả được sắp xếp theo mối quan hệ phần phụ thuộc. Hãy xem phần thứ tự biểu đồ để biết thêm thông tin.

Đường dẫn nào đó — `somepath(S1 + S2, E)`, 1 kết quả có thể có.

Lọc theo loại mục tiêu: loại

expr ::= kind(word, expr)

Toán tử kind(pattern, input) áp dụng một bộ lọc cho một tập hợp các mục tiêu và loại bỏ những mục tiêu không thuộc loại dự kiến. Tham số pattern chỉ định loại mục tiêu cần so khớp.

Ví dụ: các kiểu cho 4 mục tiêu được xác định bởi tệp BUILD (cho gói p) hiển thị dưới đây được minh hoạ trong bảng:

Mã	Mục tiêu	Loại
genrule( name = "a", srcs = ["a.in"], outs = ["a.out"], cmd = "...", )	`//p:a`	quy tắc gen
	`//p:a.in`	tệp nguồn
	`//p:a.out`	tệp đã tạo
	`//p:BUILD`	tệp nguồn

Do đó, kind("cc_.* rule", foo/...) sẽ đánh giá thành tập hợp tất cả cc_library, cc_binary, v.v., các mục tiêu quy tắc bên dưới foo và kind("source file", deps(//foo)) sẽ đánh giá thành tập hợp tất cả tệp nguồn trong tập hợp đóng bắc cầu của các phần phụ thuộc của mục tiêu //foo.

Bạn thường phải trích dẫn đối số pattern vì nếu không, nhiều biểu thức chính quy, chẳng hạn như source file và .*_test, sẽ không được trình phân tích cú pháp coi là từ.

Khi so khớp với package group, các mục tiêu kết thúc bằng :all có thể không trả về kết quả nào. Thay vào đó, hãy sử dụng :all-targets.

Lọc tên mục tiêu: bộ lọc

expr ::= filter(word, expr)

Toán tử filter(pattern, input) áp dụng bộ lọc cho một tập hợp mục tiêu và loại bỏ các mục tiêu có nhãn (ở dạng tuyệt đối) không khớp với mẫu; toán tử này sẽ đánh giá một tập hợp con của giá trị đầu vào.

Đối số đầu tiên, pattern là một từ chứa biểu thức chính quy thay vì tên mục tiêu. Biểu thức filter sẽ đánh giá tập hợp chứa tất cả các mục tiêu x sao cho x là một phần của tập hợp input và nhãn (ở dạng tuyệt đối, chẳng hạn như //foo:bar) của x chứa một kết quả trùng khớp (không neo) cho biểu thức chính quy pattern. Vì tất cả tên mục tiêu đều bắt đầu bằng //, nên bạn có thể sử dụng tên này thay cho neo biểu thức chính quy ^.

Toán tử này thường cung cấp một giải pháp thay thế nhanh và mạnh mẽ hơn nhiều so với toán tử intersect. Ví dụ: để xem tất cả các phần phụ thuộc bar của mục tiêu //foo:foo, bạn có thể đánh giá

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

Tuy nhiên, câu lệnh này sẽ yêu cầu phân tích cú pháp tất cả các tệp BUILD trong cây bar. Việc này sẽ chậm và dễ xảy ra lỗi trong các tệp BUILD không liên quan. Một cách khác là:

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

bộ lọc này sẽ tính toán tập hợp các phần phụ thuộc //foo rồi sau đó chỉ lọc các mục tiêu khớp với mẫu đã cung cấp — nói cách khác là các mục tiêu có tên chứa //bar dưới dạng chuỗi con.

Một cách sử dụng phổ biến khác của toán tử filter(pattern, expr) là lọc các tệp cụ thể theo tên hoặc đuôi của các tệp đó. Ví dụ:

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

sẽ cung cấp danh sách tất cả tệp .cc dùng để tạo //foo.

Lọc thuộc tính quy tắc: attr

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

Toán tử attr(name, pattern, input) áp dụng một bộ lọc cho một tập hợp mục tiêu và loại bỏ các mục tiêu không phải là quy tắc, mục tiêu quy tắc không xác định thuộc tính name hoặc mục tiêu quy tắc mà giá trị thuộc tính không khớp với biểu thức chính quy pattern đã cung cấp; toán tử này đánh giá thành một tập hợp con của dữ liệu đầu vào.

Đối số đầu tiên, name là tên của thuộc tính quy tắc cần so khớp với mẫu biểu thức chính quy đã cung cấp. Đối số thứ hai, pattern là một biểu thức chính quy trên các giá trị thuộc tính. Biểu thức attr đánh giá thành tập hợp chứa tất cả mục tiêu x sao cho x là một thành phần của tập hợp input, là một quy tắc có thuộc tính name được xác định và giá trị thuộc tính chứa một kết quả khớp (không liên kết) cho biểu thức chính quy pattern. Nếu name là thuộc tính không bắt buộc và quy tắc không chỉ định thuộc tính này một cách rõ ràng, thì giá trị thuộc tính mặc định sẽ được dùng để so sánh. Ví dụ:

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

sẽ chọn tất cả các phần phụ thuộc //foo được phép có thuộc tính liên kết (chẳng hạn như quy tắc cc_binary) và đặt thuộc tính đó một cách rõ ràng thành 0 hoặc không đặt nhưng giá trị mặc định là 0 (chẳng hạn như đối với các quy tắc cc_binary).

Các thuộc tính loại danh sách (chẳng hạn như srcs, data, v.v.) được chuyển đổi thành các chuỗi có dạng [value<sub>1</sub>, ..., value<sub>n</sub>], bắt đầu bằng dấu ngoặc [, kết thúc bằng dấu ngoặc ] và sử dụng "," (dấu phẩy, dấu cách) để phân định nhiều giá trị. Nhãn được chuyển đổi thành chuỗi bằng cách sử dụng nhãn tuyệt đối. Ví dụ: thuộc tính deps=[":foo", "//otherpkg:bar", "wiz"] sẽ được chuyển đổi thành chuỗi [//thispkg:foo, //otherpkg:bar, //thispkg:wiz]. Dấu ngoặc luôn xuất hiện, vì vậy, danh sách trống sẽ sử dụng giá trị chuỗi [] cho mục đích so khớp. Ví dụ:

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

sẽ chọn tất cả quy tắc trong số các phần phụ thuộc //foo có thuộc tính srcs trống, trong khi

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

sẽ chọn tất cả các quy tắc trong số các phần phụ thuộc //foo chỉ định ít nhất một giá trị trong thuộc tính data (mỗi nhãn có độ dài ít nhất là 3 ký tự do // và :).

Để chọn tất cả quy tắc trong số các phần phụ thuộc //foo có value cụ thể trong thuộc tính loại danh sách, hãy sử dụng

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

Cách này hiệu quả vì ký tự trước value sẽ là [ hoặc một dấu cách và ký tự sau value sẽ là dấu phẩy hoặc ].

Lọc chế độ hiển thị quy tắc: hiển thị

expr ::= visible(expr, expr)

Toán tử visible(predicate, input) áp dụng một bộ lọc cho một tập hợp các mục tiêu và loại bỏ các mục tiêu không có chế độ hiển thị bắt buộc.

Đối số đầu tiên, predicate, là một tập hợp các mục tiêu mà tất cả mục tiêu trong đầu ra phải hiển thị. Biểu thức visible đánh giá thành tập hợp chứa tất cả mục tiêu x sao cho x là một phần của input tập hợp và đối với tất cả mục tiêu y trong predicate x hiển thị với y. Ví dụ:

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

sẽ chọn tất cả các mục tiêu trong gói //bar mà //foo có thể phụ thuộc vào mà không vi phạm các quy định hạn chế về chế độ hiển thị.

Đánh giá các thuộc tính quy tắc của nhãn loại: nhãn

expr ::= labels(word, expr)

Toán tử labels(attr_name, inputs) trả về tập hợp các mục tiêu được chỉ định trong thuộc tính attr_name thuộc loại "nhãn" hoặc "danh sách nhãn" trong một số quy tắc trong tập hợp inputs.

Ví dụ: labels(srcs, //foo) trả về tập hợp các mục tiêu xuất hiện trong thuộc tính srcs của quy tắc //foo. Nếu có nhiều quy tắc có thuộc tính srcs trong tập hợp inputs, thì tập hợp hợp nhất của srcs sẽ được trả về.

Mở rộng và lọc test_suites: testing

expr ::= tests(expr)

Toán tử tests(x) trả về tập hợp tất cả quy tắc kiểm thử trong tập hợp x, mở rộng mọi quy tắc test_suite thành tập hợp các bài kiểm thử riêng lẻ mà chúng tham chiếu đến và áp dụng bộ lọc theo tag và size.

Theo mặc định, việc đánh giá truy vấn sẽ bỏ qua mọi mục tiêu không phải là mục tiêu kiểm thử trong tất cả các quy tắc test_suite. Bạn có thể thay đổi tuỳ chọn này thành lỗi bằng tuỳ chọn --strict_test_suite.

Ví dụ: truy vấn kind(test, foo:*) liệt kê mọi quy tắc *_test và test_suite trong gói foo. Tất cả kết quả (theo định nghĩa) đều là thành viên của gói foo. Ngược lại, truy vấn tests(foo:*) sẽ trả về tất cả các bài kiểm thử riêng lẻ sẽ được bazel test foo:* thực thi: có thể bao gồm các bài kiểm thử thuộc về các gói khác, được tham chiếu trực tiếp hoặc gián tiếp thông qua các quy tắc test_suite.

Tệp định nghĩa gói: tệp bản dựng

expr ::= buildfiles(expr)

Toán tử buildfiles(x) trả về tập hợp các tệp xác định gói của từng mục tiêu trong tập hợp x; nói cách khác, đối với mỗi gói sẽ có một tệp BUILD, cộng với mọi tệp .bzl mà nó tham chiếu qua load. Xin lưu ý rằng thao tác này cũng trả về các tệp BUILD của các gói chứa các tệp load này.

Toán tử này thường được dùng khi xác định tệp hoặc gói cần có để xây dựng mục tiêu đã chỉ định, thường kết hợp với tuỳ chọn --output package ở bên dưới). Ví dụ:

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

trả về tập hợp tất cả các gói mà //foo phụ thuộc một cách bắc cầu.

Tệp định nghĩa gói: rbuildfile

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

Toán tử rbuildfiles lấy danh sách các mảnh đường dẫn được phân tách bằng dấu phẩy và trả về tập hợp các tệp BUILD phụ thuộc bắc cầu vào các mảnh đường dẫn này. Ví dụ: nếu //foo là một gói, thì rbuildfiles(foo/BUILD) sẽ trả về mục tiêu //foo:BUILD. Nếu tệp foo/BUILD có chứa load('//bar:file.bzl'..., thì rbuildfiles(bar/file.bzl) sẽ trả về mục tiêu //foo:BUILD cũng như mục tiêu cho mọi tệp BUILD khác tải //bar:file.bzl

Phạm vi của toán tử rbuildfiles là vũ trụ do cờ --universe_scope chỉ định. Các tệp không tương ứng trực tiếp với tệp BUILD và tệp .bzl sẽ không ảnh hưởng đến kết quả. Ví dụ: các tệp nguồn (như foo.cc) sẽ bị bỏ qua, ngay cả khi các tệp này được đề cập rõ ràng trong tệp BUILD. Tuy nhiên, đường liên kết tượng trưng được tôn trọng, vì vậy, nếu foo/BUILD là đường liên kết tượng trưng đến bar/BUILD, thì rbuildfiles(bar/BUILD) sẽ đưa //foo:BUILD vào kết quả.

Toán tử rbuildfiles gần như là nghịch đảo của toán tử buildfiles. Tuy nhiên, sự đảo ngược đạo đức này lại có xu hướng mạnh mẽ hơn theo một hướng: đầu ra của rbuildfiles giống như đầu vào của buildfiles; đầu ra sẽ chỉ chứa các mục tiêu tệp BUILD trong gói và đầu vào có thể chứa các mục tiêu như vậy. Ở hướng ngược lại, mối tương ứng sẽ yếu hơn. Kết quả đầu ra của toán tử buildfiles là mục tiêu tương ứng với tất cả các gói vàCác tệp bzl cần thiết cho một dữ liệu đầu vào nhất định. Tuy nhiên, dữ liệu đầu vào của toán tử rbuildfiles không phải là các mục tiêu đó mà là các mảnh đường dẫn tương ứng với các mục tiêu đó.

Tệp định nghĩa gói: loadfiles

expr ::= loadfiles(expr)

Toán tử loadfiles(x) trả về tập hợp các tệp Starlark cần thiết để tải các gói của từng mục tiêu trong tập hợp x. Nói cách khác, đối với mỗi gói, hàm này sẽ trả về các tệp .bzl được tham chiếu từ các tệp BUILD của gói đó.

Định dạng đầu ra

bazel query sẽ tạo một biểu đồ. Bạn chỉ định nội dung, định dạng và thứ tự mà bazel query trình bày biểu đồ này thông qua tuỳ chọn dòng lệnh --output.

Khi chạy bằng Truy vấn Sky, bạn chỉ được phép sử dụng các định dạng đầu ra tương thích với đầu ra không theo thứ tự. Cụ thể, các định dạng đầu ra graph, minrank và maxrank bị cấm.

Một số định dạng đầu ra chấp nhận các tuỳ chọn bổ sung. Tên của từng tuỳ chọn đầu ra được thêm tiền tố là định dạng đầu ra tương ứng, vì vậy, --graph:factored chỉ áp dụng khi bạn sử dụng --output=graph; tuỳ chọn này không có hiệu lực nếu bạn sử dụng định dạng đầu ra không phải graph. Tương tự, --xml:line_numbers chỉ áp dụng khi --output=xml đang được sử dụng.

Theo thứ tự kết quả

Mặc dù biểu thức truy vấn luôn tuân theo "quy tắc bảo tồn thứ tự trong biểu đồ", nhưng việc trình bày kết quả có thể được thực hiện theo thứ tự phần phụ thuộc hoặc không theo thứ tự. Điều này không ảnh hưởng đến các mục tiêu trong tập hợp kết quả hoặc cách tính toán truy vấn. Giá trị này chỉ ảnh hưởng đến cách kết quả được in ra stdout. Hơn nữa, các nút tương đương trong thứ tự phần phụ thuộc có thể được sắp xếp theo thứ tự bảng chữ cái hoặc không. Bạn có thể sử dụng cờ --order_output để kiểm soát hành vi này. (Cờ --[no]order_results có một tập hợp con của chức năng của cờ --order_output và không còn được dùng nữa.)

Giá trị mặc định của cờ này là auto, giúp in kết quả theo thứ tự bảng chữ cái. Tuy nhiên, khi sử dụng somepath(a,b), kết quả sẽ được in theo thứ tự deps.

Khi cờ này là no và --output là một trong các giá trị build, label, label_kind, location, package, proto hoặc xml, thì kết quả sẽ được in theo thứ tự tuỳ ý. Đây thường là tuỳ chọn nhanh nhất. Tuy nhiên, định dạng này không được hỗ trợ khi --output là một trong các định dạng graph, minrank hoặc maxrank: với các định dạng này, Bazel luôn in kết quả theo thứ tự hoặc thứ hạng phần phụ thuộc.

Khi cờ này là deps, Bazel sẽ in kết quả theo một số thứ tự cấu trúc liên kết – tức là các phần phụ thuộc được ưu tiên. Tuy nhiên, các nút không được sắp xếp theo thứ tự phần phụ thuộc (vì không có đường dẫn giữa các nút này) có thể được in theo thứ tự bất kỳ.

Khi cờ này là full, Bazel sẽ in các nút theo thứ tự xác định đầy đủ (tổng). Trước tiên, tất cả các nút được sắp xếp theo thứ tự bảng chữ cái. Sau đó, mỗi nút trong danh sách được dùng làm điểm bắt đầu của một quá trình tìm kiếm theo thứ tự sau, trong đó các cạnh đi đến các nút chưa được truy cập được duyệt theo thứ tự bảng chữ cái của các nút kế tiếp. Cuối cùng, các nút được in theo thứ tự ngược lại với thứ tự mà các nút đó được truy cập.

Việc in các nút theo thứ tự này có thể chậm hơn, vì vậy, bạn chỉ nên sử dụng các nút này khi thuật toán tất định là quan trọng.

In biểu mẫu nguồn của các mục tiêu như sẽ xuất hiện trong BUILD

--output build

Với tuỳ chọn này, cách trình bày từng mục tiêu sẽ giống như thể mục tiêu đó được viết tay bằng ngôn ngữ BUILD. Tất cả biến và lệnh gọi hàm (chẳng hạn như glob, macro) đều được mở rộng. Điều này rất hữu ích khi xem hiệu ứng của macro Starlark. Ngoài ra, mỗi quy tắc hiệu quả sẽ báo cáo một giá trị generator_name và/hoặc generator_function, cho biết tên của macro đã được đánh giá để tạo ra quy tắc hiệu quả.

Mặc dù đầu ra sử dụng cùng cú pháp với tệp BUILD, nhưng không đảm bảo sẽ tạo ra tệp BUILD hợp lệ.

In nhãn của từng mục tiêu

--output label

Với tuỳ chọn này, tập hợp tên (hoặc nhãn) của mỗi mục tiêu trong biểu đồ thu được sẽ được in, mỗi dòng một nhãn, theo thứ tự tôpô (trừ phi bạn chỉ định --noorder_results, hãy xem ghi chú về thứ tự kết quả). (Thứ tự cấu trúc liên kết là thứ tự trong đó nút biểu đồ xuất hiện sớm hơn tất cả các nút kế tiếp.) Tất nhiên, có nhiều thứ tự cấu trúc liên kết có thể có của một biểu đồ (thứ tự đảo ngược chỉ là một thứ tự); thứ tự được chọn thì không được chỉ định.

Khi in kết quả của truy vấn somepath, thứ tự in các nút là thứ tự của đường dẫn.

Lưu ý: trong một số trường hợp góc, có thể có hai mục tiêu riêng biệt có cùng nhãn; ví dụ: quy tắc sh_binary và tệp srcs duy nhất (ngầm ẩn) có thể được gọi là foo.sh. Nếu kết quả của một truy vấn chứa cả hai mục tiêu này, thì kết quả (ở định dạng label) sẽ xuất hiện một mục trùng lặp. Khi sử dụng định dạng label_kind (xem bên dưới), sự khác biệt sẽ trở nên rõ ràng: hai mục tiêu có cùng tên, nhưng một mục tiêu có loại sh_binary rule và mục tiêu còn lại có loại source file.

In nhãn và loại của từng mục tiêu

--output label_kind

Giống như label, định dạng đầu ra này in nhãn của từng mục tiêu trong biểu đồ thu được, theo thứ tự topo, nhưng trước nhãn là loại của mục tiêu.

In mục tiêu ở định dạng vùng đệm giao thức

--output proto

In kết quả truy vấn dưới dạng vùng đệm giao thức QueryResult.

In các mục tiêu ở định dạng vùng đệm giao thức được phân tách độ dài

--output streamed_proto

In một luồng được phân tách theo độ dài của các vùng đệm giao thức Target. Điều này rất hữu ích để (i) khắc phục giới hạn về kích thước của vùng đệm giao thức khi có quá nhiều mục tiêu để vừa trong một QueryResult hoặc (ii) để bắt đầu xử lý trong khi Bazel vẫn đang xuất dữ liệu.

In các mục tiêu ở định dạng văn bản proto

--output textproto

Tương tự như --output proto, hãy in vùng đệm giao thức QueryResult nhưng ở định dạng văn bản.

In các mục tiêu ở định dạng ndjson

--output streamed_jsonproto

Tương tự như --output streamed_proto, hãy in luồng vùng đệm giao thức Target nhưng ở định dạng ndjson.

In nhãn của từng mục tiêu, theo thứ tự thứ hạng

--output minrank --output maxrank

Giống như label, định dạng đầu ra minrank và maxrank in nhãn của từng mục tiêu trong biểu đồ thu được, nhưng thay vì xuất hiện theo thứ tự topo, các nhãn này xuất hiện theo thứ tự thứ hạng, đứng trước là số thứ hạng. Các giá trị này không bị ảnh hưởng bởi cờ --[no]order_results sắp xếp kết quả (xem các lưu ý về việc sắp xếp kết quả).

Có 2 biến thể cho định dạng này: minrank xếp hạng từng nút theo độ dài của đường dẫn ngắn nhất từ một nút gốc đến nút đó. Các nút "Gốc" (những nút không có cạnh đến) có thứ hạng 0, các nút kế tiếp có thứ hạng 1, v.v. (Như mọi khi, các cạnh trỏ từ một mục tiêu đến các điều kiện tiên quyết của mục tiêu đó: các mục tiêu mà mục tiêu đó phụ thuộc vào.)

maxrank xếp hạng mỗi nút theo độ dài của đường dẫn dài nhất từ một nút gốc đến nút đó. Một lần nữa, "gốc" có thứ hạng 0, tất cả các nút khác đều có thứ hạng lớn hơn thứ hạng tối đa của tất cả các nút trước đó.

Tất cả các nút trong một chu kỳ được xem là có thứ hạng bằng nhau. (Hầu hết các biểu đồ đều không tuần hoàn, nhưng chu kỳ chỉ xảy ra do các tệp BUILD chứa chu kỳ lỗi.)

Các định dạng đầu ra này hữu ích để khám phá độ sâu của biểu đồ. Nếu được dùng cho kết quả của truy vấn deps(x), rdeps(x) hoặc allpaths, thì số thứ hạng bằng với độ dài của đường dẫn ngắn nhất (với minrank) hoặc dài nhất (với maxrank) từ x đến một nút ở thứ hạng đó. Bạn có thể dùng maxrank để xác định trình tự dài nhất gồm các bước tạo bản dựng cần thiết để tạo mục tiêu.

Ví dụ: biểu đồ ở bên trái sẽ tạo ra kết quả ở bên phải khi --output minrank và --output maxrank được chỉ định tương ứng.

      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

In vị trí của mỗi mục tiêu

--output location

Giống như label_kind, tuỳ chọn này sẽ in ra, đối với mỗi mục tiêu trong kết quả, loại và nhãn của mục tiêu, nhưng tuỳ chọn này được đặt trước bằng một chuỗi mô tả vị trí của mục tiêu đó, dưới dạng tên tệp và số dòng. Định dạng giống với kết quả của grep. Do đó, các công cụ có thể phân tích cú pháp phần sau (chẳng hạn như Emacs hoặc vi) cũng có thể sử dụng kết quả truy vấn để duyệt qua một loạt các kết quả khớp, cho phép sử dụng công cụ truy vấn Bazel làm "grep cho tệp BUILD" nhận biết phần phụ thuộc.

Thông tin vị trí sẽ khác nhau tuỳ theo loại mục tiêu (xem toán tử loại). Đối với các quy tắc, vị trí khai báo của quy tắc trong tệp BUILD sẽ được in. Đối với các tệp nguồn, vị trí của dòng 1 của tệp thực tế sẽ được in. Đối với tệp được tạo, vị trí của quy tắc tạo ra quy tắc đó sẽ được in. (Công cụ truy vấn không có đủ thông tin để tìm vị trí thực tế của tệp đã tạo và trong mọi trường hợp, tệp này có thể không tồn tại nếu bạn chưa tạo bản dựng.)

In tập hợp gói

--output package

Tuỳ chọn này in tên của tất cả các gói mà một số mục tiêu trong tập hợp kết quả thuộc về. Các tên được in theo thứ tự từ vựng; các tên trùng lặp sẽ bị loại trừ. Về mặt hình thức, đây là một mặt chiếu từ tập hợp nhãn (gói, mục tiêu) lên các gói.

Gói trong kho lưu trữ bên ngoài được định dạng là @repo//foo/bar, còn gói trong kho lưu trữ chính có định dạng foo/bar.

Cùng với truy vấn deps(...), bạn có thể dùng tuỳ chọn đầu ra này để tìm tập hợp các gói phải được thanh toán để tạo một tập hợp mục tiêu nhất định.

Hiển thị biểu đồ kết quả

--output graph

Tuỳ chọn này khiến kết quả truy vấn được in dưới dạng biểu đồ định hướng ở định dạng AT&T GraphViz phổ biến. Thông thường, kết quả sẽ được lưu vào một tệp, chẳng hạn như .png hoặc .svg. (Nếu chưa cài đặt chương trình dot trên máy trạm, bạn có thể cài đặt chương trình đó bằng lệnh sudo apt-get install graphviz.) Hãy xem phần ví dụ bên dưới để biết lệnh gọi mẫu.

Định dạng đầu ra này đặc biệt hữu ích cho các truy vấn allpaths, deps hoặc rdeps, trong đó kết quả bao gồm một nhóm đường dẫn không thể dễ dàng được trực quan hoá khi hiển thị ở dạng tuyến tính, chẳng hạn như với --output label.

Theo mặc định, biểu đồ hiển thị ở dạng được phân tích cú pháp. Điều này nghĩa là các nút tương đương về mặt cấu trúc được hợp nhất với nhau thành một nút duy nhất có nhiều nhãn. Điều này giúp biểu đồ nhỏ gọn và dễ đọc hơn, vì các biểu đồ kết quả thông thường chứa các mẫu lặp lại nhiều lần. Ví dụ: một quy tắc java_library có thể phụ thuộc vào hàng trăm tệp nguồn Java, tất cả đều do cùng một genrule tạo ra; trong biểu đồ phân tích, tất cả các tệp này được biểu thị bằng một nút duy nhất. Bạn có thể tắt hành vi này bằng tuỳ chọn --nograph:factored.

`--graph:node_limit n`

Tuỳ chọn này chỉ định độ dài tối đa của chuỗi nhãn cho một nút đồ thị trong đầu ra. Nhãn dài hơn sẽ bị cắt ngắn; -1 sẽ tắt tính năng cắt ngắn. Do biểu đồ thường được in ở dạng nhân tố, nên nhãn nút có thể rất dài. GraphViz không thể xử lý các nhãn vượt quá 1024 ký tự (đây là giá trị mặc định của tuỳ chọn này). Tuỳ chọn này không có hiệu lực trừ phi bạn sử dụng --output=graph.

`--[no]graph:factored`

Theo mặc định, biểu đồ được hiển thị ở dạng nhân, như đã giải thích ở trên. Khi --nograph:factored được chỉ định, đồ thị sẽ được in mà không cần nhân. Điều này khiến việc trực quan hoá bằng GraphViz không thực tế, nhưng định dạng đơn giản hơn có thể giúp các công cụ khác (chẳng hạn như grep) dễ dàng xử lý hơn. Tuỳ chọn này không có hiệu lực trừ phi bạn sử dụng --output=graph.

XML

--output xml

Tuỳ chọn này sẽ in các mục tiêu thu được ở dạng XML. Kết quả bắt đầu bằng một tiêu đề XML như sau

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

rồi tiếp tục với một phần tử XML cho từng mục tiêu trong biểu đồ kết quả, theo thứ tự cấu trúc liên kết (trừ phi yêu cầu kết quả không theo thứ tự), rồi kết thúc bằng việc chấm dứt

</query>

Các mục nhập đơn giản được phát cho các mục tiêu thuộc loại file:

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

Nhưng đối với các quy tắc, XML được cấu trúc và chứa các định nghĩa về mọi thuộc tính của quy tắc, bao gồm cả những thuộc tính có giá trị không được chỉ định rõ ràng trong tệp BUILD của quy tắc.

Ngoài ra, kết quả bao gồm các phần tử rule-input và rule-output để có thể xây dựng lại cấu trúc liên kết của biểu đồ phần phụ thuộc mà không cần biết rằng, ví dụ: các phần tử của thuộc tính srcs là phần phụ thuộc tiến lên (điều kiện tiên quyết) và nội dung của thuộc tính outs là các phần phụ thuộc ngược (người tiêu dùng).

Các phần tử rule-input cho các phần phụ thuộc ngầm ẩn sẽ bị chặn nếu bạn chỉ định --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>

Mỗi phần tử XML cho một mục tiêu đều chứa một thuộc tính name (có giá trị là nhãn của mục tiêu) và một thuộc tính location (có giá trị là vị trí của mục tiêu như được in bởi --output location).

`--[no]xml:line_numbers`

Theo mặc định, vị trí hiển thị trong dữ liệu đầu ra XML sẽ chứa số dòng. Khi chỉ định --noxml:line_numbers, số dòng sẽ không được in.

`--[no]xml:default_values`

Theo mặc định, đầu ra XML không bao gồm thuộc tính quy tắc có giá trị là giá trị mặc định cho loại thuộc tính đó (ví dụ: nếu thuộc tính này không được chỉ định trong tệp BUILD hoặc giá trị mặc định được cung cấp rõ ràng). Tuỳ chọn này sẽ đưa các giá trị thuộc tính đó vào đầu ra XML.

Cụm từ thông dụng

Biểu thức chính quy trong ngôn ngữ truy vấn sử dụng thư viện biểu thức chính quy Java, vì vậy, bạn có thể sử dụng cú pháp đầy đủ cho java.util.regex.Pattern.

Truy vấn bằng kho lưu trữ bên ngoài

Nếu bản dựng phụ thuộc vào các quy tắc từ kho lưu trữ bên ngoài, thì kết quả truy vấn sẽ bao gồm các phần phụ thuộc này. Chẳng hạn nếu //foo:bar phụ thuộc vào @other-repo//baz:lib, thì bazel query 'deps(//foo:bar)' sẽ liệt kê @other-repo//baz:lib là phần phụ thuộc.