aboutsummaryrefslogtreecommitdiffhomepage
path: root/site/versions/master/docs/query.html
blob: c3802b4133a0a20c264f06f0c9ece9f40e6099b5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
---
layout: documentation
title: Query Language
---
<h1>The Bazel Query Reference</h1>

<p>
  When you use <code>bazel query</code> to analyze build
  dependencies, you use a little language, the <em>Bazel Query
  Language</em>.  This document is the reference manual for that
  language.  This document also describes the output
  formats <code>bazel query</code> supports.
</p>

<h2>Examples</h2>

<p>
  How do people use <code>bazel query</code>?  Here are typical examples:
</p>

<p>
  Why does the <code>//foo</code> tree depend on <code>//bar/baz</code>?
  Show a path:</p>
  <pre>somepath(foo/..., //bar/baz:all)</pre>


<p>
  What C++ libraries do all the <code>foo</code> tests depend on that
  the <code>foo_bin</code> target does not?</p>
  <pre>kind("cc_library", deps(kind(".*test rule", foo/...)) except deps(//foo:foo_bin))</pre>


<h2>Tokens: the lexical syntax</h2>

<p>
  Expressions in the query language are composed of the following
  tokens:</p>
  <ul>
    <li>
      <p>
        <b>Keywords</b>, such as <code>somepath</code> or
        <code>let</code>.  Keywords are the reserved words of the
        language, and each of them is described below.  The complete set
        of keywords is:
      </p>

<code><!-- keep this alphabetically sorted -->
<a href="#path-operators">allpaths</a><br/>
<a href="#attr">attr</a><br/>

<a href="#buildfiles">buildfiles</a><br/>

<a href="#deps">deps</a><br/>
<a href="#set-operations">except</a><br/>
<a href="#filter">filter</a><br/>
<a href="#variables">in</a><br/>
<a href="#set-operations">intersect</a><br/>
<a href="#kind">kind</a><br/>
<a href="#labels">labels</a><br/>
<a href="#variables">let</a><br/>
<a href="#loadfiles">loadfiles</a><br/>
<a href="#rdeps">rdeps</a><br/>
<a href="#set">set</a><br/>
<a href="#some">some</a><br/>
<a href="#path-operators">somepath</a><br/>
<a href="#tests">tests</a><br/>
<a href="#set-operations">union</a><br/>
</code>
    </li>

    <li>
      <p>
        <b>Words</b>, such as <code>foo/...</code> or
        <code>".*test rule"</code> or
        <code>//bar/baz:all</code>.
        If a character sequence is "quoted" (begins and ends with a
        single-quote <code>'</code>, or begins and ends with a
        double-quote <code>&quot;</code>), it is a word.
        If a character sequence is not quoted, it may still be parsed as a word.
        Unquoted words are sequences of characters drawn from
        the set of alphabet characters, numerals, slash <code>/</code>,
        hyphen <code>-</code>, underscore <code>_</code>, star <code>*</code>, and
        period <code>.</code>. Unquoted words may not start with a
        hyphen or period.
      </p>

    <p>We chose this syntax so that quote marks aren't needed in most cases.
      The (unusual) <code>".*test rule"</code> example needs quotes: it
      starts with a period and contains a space.
      Quoting <code>"cc_library"</code> is unnecessary but harmless.
    </p>

    <p>
      Quoting <em>is</em> necessary when writing scripts that
      construct Bazel query expressions from user-supplied values.

    </p>
    <pre>
      //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.
    </pre>
    <p>
      Note that this quoting is in addition to any quoting that may
      be required by your shell. e.g.
    </p>
    <pre>% bazel query ' "//foo:bar=wiz" '     # single-quotes for shell, double-quotes for Bazel.</pre>

    <p>
      Keywords, when quoted, are treated as ordinary words, thus
      <code>some</code> is a keyword but <code>"some"</code> is a word.
      Both <code>foo</code> and <code>"foo"</code> are words.
    </p>

    <li><b>Punctuation</b>, such as parens <code>()</code>, period
    <code>.</code> and comma <code>,</code>, etc.  Words containing
    punctuation (other than the exceptions listed above) must be quoted.
  </ul>

<p>
  Whitespace characters outside of a quoted word are ignored.
</p>

<h2 id='concepts'>Bazel Query Language Concepts</h2>
<p>
  The Bazel query language is a language of expressions.  Every
  expression evaluates to a <b>partially-ordered set</b> of targets,
  or equivalently, a <b>graph</b> (DAG) of targets.  This is the only
  datatype.
</p>
<p>
  In some expressions, the partial order of the graph is
  not interesting; In this case, we call the values
  "sets". In cases where the partial order of elements
  is significant, we call values "graphs".  Note
  that both terms refer to the same datatype, but merely emphasize
  different aspects of it.
</p>

<h3>Cycles in the dependency graph</h3>
<p>
  Build dependency graphs should be acyclic.

  The algorithms used by the query language are intended for use in
  acyclic graphs, but are robust against cycles.  The details of how
  cycles are treated are not specified and should not be relied upon.
</p>

<h3 id='implicit_deps'>Implicit dependencies</h3>

<p>
  In addition to build dependencies that are defined explicitly in BUILD files,
  Bazel adds additional <em>implicit</em> dependencies to rules. For example
  every Java rule implicitly depends on the JavaBuilder. Implicit dependencies
  are established using attributes that start with <code>$</code> and they
  cannot be overridden in BUILD files.

</p>

<p>
  Per default <code>bazel query</code> takes implicit dependencies into account
  when computing the query result. This behavior can be changed with
  the <code>--[no]implicit_deps</code> option.
</p>

<h3 id='soundness'>Soundness</h3>

<p>
  Bazel query language expressions operate over the build
  dependency graph, which is the graph implicitly defined by all
  rule declarations in all BUILD files.  It is important to understand
  that this graph is somewhat abstract, and does not constitute a
  complete description of how to perform all the steps of a build.  In
  order to perform a build, a <em>configuration</em> is required too;
  see the <a href='bazel-user-manual.html#configurations'>configurations</a>
  section of the User's Guide for more detail.
</p>

<p>
  The result of evaluating an expression in the Bazel query language
  is true <em>for all configurations</em>, which means that it may be
  a conservative over-approximation, and not exactly precise.  If you
  use the query tool to compute the set of all source files needed
  during a build, it may report more than are actually necessary
  because, for example, the query tool will include all the files
  needed to support message translation, even though you don't intend
  to use that feature in your build.
</p>

<h3 id='graph-order'>On the preservation of graph order</h3>

<p>
  Operations preserve any ordering
  constraints inherited from their subexpressions.  You can think of
  this as "the law of conservation of partial order".  Consider an
  example: if you issue a query to determine the transitive closure of
  dependencies of a particular target, the resulting set is ordered
  according to the dependency graph.  If you filter that set to
  include only the targets of <code>file</code> kind, the same
  <em>transitive</em> partial ordering relation holds between every
  pair of targets in the resulting subset&mdash;even though none of
  these pairs is actually directly connected in the original graph.
  (There are no file&ndash;file edges in the build dependency graph).
</p>

<p>
  However, while all operators <em>preserve</em> order, some
  operations, such as the <a href='#set-operations'>set operations</a>
  don't <em>introduce</em> any ordering constraints of their own.
  Consider this expression:
</p>

<pre>deps(x) union y</pre>

<p>
  The order of the final result set is guaranteed to preserve all the
  ordering constraints of its subexpressions, namely, that all the
  transitive dependencies of <code>x</code> are correctly ordered with
  respect to each other.  However, the query guarantees nothing about
  the ordering of the targets in <code>y</code>, nor about the
  ordering of the targets in <code>deps(x)</code> relative to those in
  <code>y</code> (except for those targets in
  <code>y</code> that also happen to be in <code>deps(x)</code>).
</p>

<p>
  Operators that introduce ordering constraints include:
  <code>allpaths</code>,
  <code>deps</code>,
  <code>rdeps</code>,
  <code>somepath</code>,
  and the target pattern wildcards
  <code>package:*</code>,
  <code>dir/...</code>, etc.
</p>

<h2>Expressions: syntax and semantics of the grammar</h2>

<p>
  This is the grammar of the Bazel query language, expressed in EBNF
  notation:
</p>


<pre>expr ::= <var>word</var>
       | let <var>name</var> = <var>expr</var> in <var>expr</var>
       | (<var>expr</var>)
       | <var>expr</var> intersect <var>expr</var>
       | <var>expr</var> ^ <var>expr</var>
       | <var>expr</var> union <var>expr</var>
       | <var>expr</var> + <var>expr</var>
       | <var>expr</var> except <var>expr</var>
       | <var>expr</var> - <var>expr</var>
       | deps(<var>expr</var>)
       | deps(<var>expr</var>, <var>depth</var>)
       | rdeps(<var>expr</var>, <var>expr</var>)
       | rdeps(<var>expr</var>, <var>expr</var>, <var>depth</var>)
       | some(<var>expr</var>)
       | somepath(<var>expr</var>, <var>expr</var>)
       | allpaths(<var>expr</var>, <var>expr</var>)
       | kind(<var>word</var>, <var>expr</var>)
       | labels(<var>word</var>, <var>expr</var>)
       | filter(<var>word</var>, <var>expr</var>)
       | set(<var>word</var> *)
       | attr(<var>word</var>, <var>word</var>, <var>expr</var>)
</pre>

<p>
  We will examine each of the productions of this grammar in order.
</p>

<h3 id="target-patterns">Target patterns</h3>
<pre>expr ::= <var>word</var></pre>
<p>
  Syntactically, a <em>target pattern</em> is just a word. It
  is interpreted as an (unordered) set of targets.  The simplest
  target pattern is a label,
  which identifies a single target (file or rule).  For example, the
  target pattern <code>//foo:bar</code> evaluates to a set
  containing one element, the target, the <code>bar</code>
  rule.
</p>

<p>
  Target patterns generalize labels to include wildcards over packages
  and targets.  For example, <code>foo/...:all</code> (or
  just <code>foo/...</code>) is a target pattern that evaluates to a
  set containing all <em>rules</em> in every package recursively
  beneath the <code>foo</code> directory;
  <code>bar/baz:all</code> is a target pattern that
  evaluates to a set containing all the rules in the
  <code>bar/baz</code> package, but not its subpackages.
</p>

<p>
  Similarly, <code>foo/...:*</code> is a target pattern that evaluates
  to a set containing all <em>targets</em> (rules <em>and</em> files) in
  every package recursively beneath the <code>foo</code> directory;
  <code>bar/baz:*</code> evaluates to a set containing
  all the targets in the
  <code>bar/baz</code> package, but not its subpackages.
</p>

<p>
  Because the <code>:*</code> wildcard matches files as well as rules,
  it is often more useful than <code>:all</code> for queries.
  Conversely, the <code>:all</code> wildcard (implicit in target
  patterns like <code>foo/...</code>) is typically more useful for
  builds.
</p>

<p>
  <code>bazel query</code> target patterns work the same as
  <code>bazel build</code> build targets do;
  refer to <a href='bazel-user-manual.html#target-patterns'>Target Patterns</a>
  in the Bazel User Manual for further details, or type <code>bazel
  help target-syntax</code>.

</p>

<p>
  Target patterns may evaluate to a singleton set (in the case of a
  label), to a set containing many elements (as in the case of
  <code>foo/...</code>, which has thousands of elements) or to the
  empty set, if the target pattern matches no targets.
</p>

<p>
  All nodes in the result of a target pattern expression are correctly
  ordered relative to each other according to the dependency relation.
  So, the result of <code>foo:*</code> is not just the set of targets
  in package <code>foo</code>, it is also the <em>graph</em> over
  those targets.  (No guarantees are made about the relative ordering
  of the result nodes against other nodes.)  See the section
  on <a href='#graph-order'>graph order</a> for more details.
</p>

<h3 id="variables">Variables</h3>
<pre>expr ::= let <var>name</var> = <var>expr</var><sub>1</sub> in <var>expr</var><sub>2</sub>
       | <var>$name</var></pre>
<p>
  The Bazel query language allows definitions of and references to
  variables.  The
  result of evaluation of a <code>let</code> expression is the same as
  that of <var>expr</var><sub>2</sub>, with all free occurrences of
  variable <var>name</var> replaced by the value of
  <var>expr</var><sub>1</sub>.
</p>

<p>
  For example, <code>let v = foo/... in allpaths($v, //common)
  intersect $v</code> is equivalent to the <code>allpaths(foo/...,
  //common) intersect foo/...</code>.
</p>

<p>
  An occurrence of a variable reference <code>name</code> other than in
  an enclosing <code>let <var>name</var> = ...</code> expression is an
  error.  In other words, toplevel query expressions cannot have free
  variables.
</p>

<p>
  In the above grammar productions, <code>name</code> is like
  <em>word</em>, but with the additional constraint that it be a legal
  identifier in the C programming language. References to the variable
  must be prepended with the "$" character.
</p>

<p>
  Each <code>let</code> expression defines only a single variable,
  but you can nest them.
</p>

<p>
  (Both <a
  href='#target-patterns'>target patterns</a> and variable references
  consist of just a single token, a word, creating a syntactic
  ambiguity.  However, there is no semantic ambiguity, because the
  subset of words that are legal variable names is disjoint from the
  subset of words that are legal target patterns.)
</p>

<p>
  (Technically speaking, <code>let</code> expressions do not increase
  the expressiveness of the query language: any query expressible in
  the language can also be expressed without them.  However, they
  improve the conciseness of many queries, and may also lead to more
  efficient query evaluation.)
</p>

<h3 id="parentheses">Parenthesized expressions</h3>
<pre>expr ::= (<var>expr</var>)</pre>

<p>
  Parentheses associate subexpressions to force an
  order of evaluation.
  A parenthesized expression evaluates
  to the value of its argument.
</p>

<h3 id="set-operations">Algebraic set operations:
                        intersection, union, set difference</h3>

<pre>expr ::= <var>expr</var> intersect <var>expr</var>
       | <var>expr</var> ^ <var>expr</var>
       | <var>expr</var> union <var>expr</var>
       | <var>expr</var> + <var>expr</var>
       | <var>expr</var> except <var>expr</var>
       | <var>expr</var> - <var>expr</var>
</pre>

<p>
  These three operators compute the usual set operations over their
  arguments.  Each operator has two forms, a nominal form such
  as <code>intersect</code> and a symbolic form such
  as <code>^</code>.  Both forms are equivalent;
  the symbolic forms are quicker to type.  (For clarity, the rest of
  this manual uses the nominal forms.)  For example,
</p>

<pre>foo/... except foo/bar/...</pre>

  evaluates to the set of targets that match
  <code>foo/...</code> but not
  <code>foo/bar/...</code>&nbsp;.  Equivalently:

<pre>foo/... - foo/bar/...</pre>

  The <code>intersect</code> (<code>^</code>)
  and <code>union</code> (<code>+</code>) operations are commutative
  (symmetric); <code>except</code> (<code>-</code>) is
  asymmetric.  The parser treats all three operators as
  left-associative and of equal precedence, so you might want parentheses.
  For example, the first two of these expressions are
  equivalent, but the third is not:

<pre>x intersect y union z
(x intersect y) union z
x intersect (y union z)</pre>

<p>
  (We strongly recommend that you use parentheses where there is
  any danger of ambiguity in reading a query expression.)
</p>

<h3 id="set">Read targets from an external source: set</h3>
<pre>expr ::= set(<var>word</var> *) </pre>
<p>
  The <code>set(<var>a</var> <var>b</var> <var>c</var> ...)</code>
  operator computes the union of a set of zero or
  more <a href='#target-patterns'>target patterns</a>, separated by
  whitespace (no commas).
</p>

<p>
  In conjunction with the Bourne shell's <code>$(...)</code>
  feature, <code>set()</code> provides a means of saving the results
  of one query in a regular text file, manipulating that text file
  using other programs (e.g. standard UNIX shell tools), and then
  introducing the result back into the query tool as a value for
  further processing.  For example:
</p>
<pre>
  % bazel query deps(//my:target) --output=label | grep ... | sed ... | awk ... &gt; foo
  % bazel query "kind(cc_binary, set($(&lt;foo)))"
</pre>
<p>
  In the next example, <code>kind(cc_library,
  deps(//some_dir/foo:main, 5))</code> is effectively computed
  by filtering on the <code>maxrank</code> values using
  an <code>awk</code> program.
</p>
<pre>
  % bazel query 'deps(//some_dir/foo:main)' --output maxrank |
        awk '($1 &lt; 5) { print $2;} ' &gt; foo
  % bazel query "kind(cc_library, set($(&lt;foo)))"
</pre>
<p>
  In these examples, <code>$(&lt;foo)</code> is a shorthand
  for <code>$(cat foo)</code>, but shell commands other
  than <code>cat</code> may be used too&mdash;such as
  the previous <code>awk</code> command.
</p>

<p>
  Note, <code>set()</code> introduces no graph ordering constraints,
  so path information may be lost when saving and reloading sets of
  nodes using it.  See the <a href='#graph-order'>graph order</a>
  section below for more detail.
</p>

<h3 id="deps">Transitive closure of dependencies: deps</h3>
<pre>expr ::= deps(<var>expr</var>)
       | deps(<var>expr</var>, <var>depth</var>)</pre>
<p>
  The <code>deps(<var>x</var>)</code> operator evaluates to the graph
  formed by the transitive closure of dependencies of its argument set
  <var>x</var>. For example, the value of <code>deps(//foo)</code> is
  the dependency graph rooted at the single node <code>foo</code>,
  including all its dependencies. The value of
  <code>deps(foo/...)</code> is the dependency graphs whose roots are
  all rules in every package beneath the <code>foo</code> directory.
  Please note that 'dependencies' means only rule and file targets
  in this context, therefore the BUILD,

  and Skylark files needed to
  create these targets are not included here. For that you should use the
  <a href="#buildfiles"><code>buildfiles</code></a> operator.
</p>

<p>
  The resulting graph is ordered according to the dependency relation.
  See the section on <a href='#graph-order'>graph order</a> for more
  details.
</p>

<p>
  The <code>deps</code> operator accepts an optional second argument,
  which is an integer literal specifying an upper bound on the depth
  of the search.  So <code>deps(foo:*, 1)</code> evaluates to all the
  direct prerequisites of any target in the <code>foo</code> package,
  and <code>deps(foo:*, 2)</code> further includes the nodes directly
  reachable from the nodes in <code>deps(foo:*, 1)</code>, and so on.
  (These numbers correspond to the ranks shown in
  the <a href='#output-ranked'><code>minrank</code></a> output
  format.)  If the <var>depth</var> parameter is omitted, the search
  is unbounded, i.e. it computes the reflexive transitive closure of
  prerequsites.
</p>

<h3 id="rdeps">Transitive closure of reverse dependencies: rdeps</h3>
<pre>expr ::= rdeps(<var>expr</var>, <var>expr</var>)
       | rdeps(<var>expr</var>, <var>expr</var>, <var>depth</var>)</pre>
<p>
  The <code>rdeps(<var>u</var>, <var>x</var>)</code> operator evaluates
  to the reverse dependencies of the argument set <var>x</var> within the
  transitive closure of the universe set <var>u</var>.
</p>

<p>
  The resulting graph is ordered according to the dependency relation.  See the
  section on <a href='#graph-order'>graph order</a> for more details.
</p>

<p>
  The <code>rdeps</code> operator accepts an optional third argument,
  which is an integer literal specifying an upper bound on the depth of the
  search.  The resulting graph will only include nodes within a distance of the
  specified depth from any node in the argument set.  So
  <code>rdeps(//foo, //common, 1)</code> evaluates to all nodes in the
  transitive closure of <code>//foo</code> that directly depend on
  <code>//common</code>.  (These numbers correspond to the ranks shown in the
  <a href='#output-ranked'><code>minrank</code></a> output format.)  If the
  <var>depth</var> parameter is omitted, the search is unbounded.
</p>

<h3 id="some">Arbitrary choice: some</h3>
<pre>expr ::= some(<var>expr</var>)</pre>
<p>
  The <code>some(<var>x</var>)</code> operator selects one target
  arbitrarily from its argument set <var>x</var>, and evaluates to a
  singleton set containing only that target.  For example, the
  expression <code>some(//foo:main union //bar:baz)</code>
  evaluates to a set containing either <code>//foo:main</code> or
  <code>//bar:baz</code>&mdash;though which one is not defined.
</p>

<p>
  If the argument is a singleton, then <code>some</code>
  computes the identity function: <code>some(//foo:main)</code> is
  equivalent to <code>//foo:main</code>.

  It is an error if the specified argument set is empty, as in the
  expression <code>some(//foo:main intersect //bar:baz)</code>.
</p>

<h3 id="path-operators">Path operators: somepath, allpaths</h3>
<pre>expr ::= somepath(<var>expr</var>, <var>expr</var>)
       | allpaths(<var>expr</var>, <var>expr</var>)</pre>
<p>
  The <code>somepath(<var>S</var>, <var>E</var>)</code> and
  <code>allpaths(<var>S</var>, <var>E</var>)</code> operators compute
  paths between two sets of targets.  Both queries accept two
  arguments, a set <var>S</var> of starting points and a set
  <var>E</var> of ending points.  <code>somepath</code> returns the
  graph of nodes on <em>some</em> arbitrary path from a target in
  <var>S</var> to a target in <var>E</var>; <code>allpaths</code>
  returns the graph of nodes on <em>all</em> paths from any target in
  <var>S</var> to any target in <var>E</var>.
</p>

<p>
  The resulting graphs are ordered according to the dependency relation.
  See the section on <a href='#graph-order'>graph order</a> for more
  details.
</p>

<table style='margin: auto'><tr>
<td style='text-align: center'>
<div class='graphviz dot'><!--
digraph somepath1 {
  graph [size="4,4"]
  node [label="",shape=circle];
  n1;
  n2 [fillcolor="pink",style=filled];
  n3 [fillcolor="pink",style=filled];
  n4 [fillcolor="pink",style=filled,label="E"];
  n5; n6;
  n7 [fillcolor="pink",style=filled,label="S1"];
  n8 [label="S2"];
  n9;
  n10 [fillcolor="pink",style=filled];

  n1 -> n2;
  n2 -> n3;
  n7 -> n5;
  n7 -> n2;
  n5 -> n6;
  n6 -> n4;
  n8 -> n6;
  n6 -> n9;
  n2 -> n10;
  n3 -> n10;
  n10 -> n4;
  n10 -> n11;
}
--></div>
<p><code>somepath(S1 + S2, E)</code>,<br/>one possible result.</p>
</td>
<td style='padding: 40px; text-align: center'>
<div class='graphviz dot'><!--
digraph somepath2 {
  graph [size="4,4"]
  node [label="",shape=circle];

  n1; n2; n3;
  n4 [fillcolor="pink",style=filled,label="E"];
  n5;
  n6 [fillcolor="pink",style=filled];
  n7 [label="S1"];
  n8 [fillcolor="pink",style=filled,label="S2"];
  n9; n10;

  n1 -> n2;
  n2 -> n3;
  n7 -> n5;
  n7 -> n2;
  n5 -> n6;
  n6 -> n4;
  n8 -> n6;
  n6 -> n9;
  n2 -> n10;
  n3 -> n10;
  n10 -> n4;
  n10 -> n11;
}
--></div>
<p><code>somepath(S1 + S2, E)</code>,<br/>another possible result.</p>
</td>
<td style='text-align: center'>
<div class='graphviz dot'><!--
digraph allpaths {
  graph [size="4,4"]
  node [label="",shape=circle];
  n1;
  n2 [fillcolor="pink",style=filled];
  n3 [fillcolor="pink",style=filled];
  n4 [fillcolor="pink",style=filled,label="E"];
  n5 [fillcolor="pink",style=filled];
  n6 [fillcolor="pink",style=filled];
  n7 [fillcolor="pink",style=filled, label="S1"];
  n8 [fillcolor="pink",style=filled, label="S2"];
  n9;
  n10 [fillcolor="pink",style=filled];

  n1 -> n2;
  n2 -> n3;
  n7 -> n5;
  n7 -> n2;
  n5 -> n6;
  n6 -> n4;
  n8 -> n6;
  n6 -> n9;
  n2 -> n10;
  n3 -> n10;
  n10 -> n4;
  n10 -> n11;
}
--></div>
<p><code>allpaths(S1 + S2, E)</code>.</p>
</td>
</tr></table>

<h3 id="kind">Target kind filtering: kind</h3>
<pre>expr ::= kind(<var>word</var>, <var>expr</var>) </pre>
<p>
  The <code>kind(<var>pattern</var>, <var>input</var>)</code> operator
  applies a filter to a set of targets, and discards those targets
  that are not of the expected kind. The <var>pattern</var> parameter specifies
  what kind of target to match.
</p>
<ul>
<li><b>file</b> patterns can be one of:
  <ul>
    <li><code>source file</code>
    <li><code>generated file</code>
  </ul>
<li><b>rule</b> patterns can be one of:
  <ul>
    <li><code><var>ruletype</var> rule</code>
    <li><code><var>ruletype</var></code><br>
    Where <var>ruletype</var> is a build rule.  The difference between these
    forms is that including "rule" causes the regular expression match for
    <var>ruletype</var> to be anchored.
  </ul>
<li><b>package group</b> patterns should simply be:
  <ul>
    <li><code>package group</code>
  </ul>
</ul>
<p>
  For example, the kinds for the four targets defined by the BUILD file
  (for package <code>p</code>) shown below are illustrated in the
  table:
</p>

<table style='margin: auto'><tr><td style='padding-right:10px'>
<pre style='margin-left: 0em;'>
genrule(
    name = "a",
    srcs = ["a.in"],
    outs = ["a.out"],
    cmd = "...",
)
</pre>
</td><td>
   <table class="grid">
     <tr><th>Target</th><th>Kind</th></tr>
     <tr class='tt'><td>//p:a</td><td>genrule rule</td></tr>
     <tr class='tt'><td>//p:a.in</td><td>source file</td></tr>
     <tr class='tt'><td>//p:a.out</td><td>generated file</td></tr>
     <tr class='tt'><td>//p:BUILD</td><td>source file</td></tr>
   </table>
</td></tr></table>

<p>
  Thus, <code>kind("cc_.* rule", foo/...)</code> evaluates to the set
  of all <code>cc_library</code>, <code>cc_binary</code>, etc,
  rule targets beneath
  <code>foo</code>, and <code>kind("source file", deps(//foo))</code>
  evaluates to the set of all source files in the transitive closure
  of dependencies of the <code>//foo</code> target.
</p>

<p>
  Quotation of the <var>pattern</var> argument is often required
  because without it, many regular expressions, such as <code>source
  file</code> and <code>.*_test</code>, are not considered words by
  the parser.
</p>

<p>
  When matching for <code>package group</code>, targets ending in
  <code>:all</code> may not yield any results.
  Use <code>:all-targets</code> instead.
</p>

<h3 id="filter">Target name filtering: filter</h3>
<pre>expr ::= filter(<var>word</var>, <var>expr</var>) </pre>
<p>
  The <code>filter(<var>pattern</var>, <var>input</var>)</code> operator
  applies a filter to a set of targets, and discards targets whose
  labels (in absolute form) do not match the pattern; it
  evaluates to a subset of its input.
</p>

<p>
  The first argument, <var>pattern</var> is a word containing a
  regular expression over target names.  A <code>filter</code> expression
  evaluates to the set containing all targets <var>x</var> such that
  <var>x</var> is a member of the set <var>input</var> and the
  label (in absolute form, e.g. <code>//foo:bar</code>)
  of <var>x</var> contains an (unanchored) match
  for the regular expression <var>pattern</var>.  Since all
  target names start with <code>//</code>, it may be used as an alternative
  to the <code>^</code> regular expression anchor.
</p>

<p>
  This operator often provides a much faster and more robust alternative to the
  <code>intersect</code> operator. For example, in order to see all
  <code>bar</code> dependencies of the <code>//foo:foo</code> target, one could
  evaluate
</p>
<pre>deps(//foo) intersect //bar/...</pre>
<p>
  This statement, however, will require parsing of all BUILD files in the
  <code>bar</code> tree, which will be slow and prone to errors in
  irrelevant BUILD files. An alternative would be:
</p>
<pre>filter(//bar, deps(//foo))</pre>
<p>
  which would first calculate the set of <code>//foo</code> dependencies and
  then would filter only targets matching the provided pattern&mdash;in other
  words, targets with names containing <code>//bar</code> as a
  substring.
</p>

<p>
  Another common use of the <code>filter(<var>pattern</var>,
  <var>expr</var>)</code> operator is to filter specific files by their
  name or extension. For example,
</p>
<pre>filter("\.cc$", deps(//foo))</pre>
<p>
  will provide a list of all <code>.cc</code> files used to build
  <code>//foo</code>.
</p>

<h3 id="attr">Rule attribute filtering: attr</h3>
<pre>expr ::= attr(<var>word</var>, <var>word</var>, <var>expr</var>) </pre>
<p>
  The <code>attr(<var>name</var>, <var>pattern</var>, <var>input</var>)</code>
  operator applies a filter to a set of targets, and discards targets that
  are not rules, rule targets that do not have attribute <var>name</var>
  defined or rule targets where the attribute value does not match the provided
  regular expression <var>pattern</var>; it evaluates to a subset of its input.
</p>

<p>
  The first argument, <var>name</var> is the name of the rule attribute that
  should be matched against the provided regular expression pattern. The second
  argument, <var>pattern</var> is a regular expression over the attribute
  values. An <code>attr</code> expression evaluates to the set containing all
  targets <var>x</var> such that  <var>x</var> is a member of the set
  <var>input</var>, is a rule with the defined attribute <var>name</var> and
  the attribute value contains an (unanchored) match for the regular expression
  <var>pattern</var>. Please note, that if <var>name</var> is an optional
  attribute and rule does not specify it explicitly then default attribute
  value will be used for comparison. For example,
</p>
<pre>attr(linkshared, 0, deps(//foo))</pre>
<p>
  will select all <code>//foo</code> dependencies that are allowed to have a
  linkshared attribute (e.g., <code>cc_binary</code> rule) and have it either
  explicitly set to 0 or do not set it at all but default value is 0 (e.g. for
  <code>cc_binary</code> rules).
</p>

<p>
  List-type attributes (such as <code>srcs</code>, <code>data</code>, etc) are
  converted to strings of the form <code>[value<sub>1</sub>, ..., value<sub>n</sub>]</code>,
  starting with a <code>[</code> bracket, ending with a <code>]</code> bracket
  and using "<code>, </code>" (comma, space) to delimit multiple values.
  Labels are converted to strings by using the absolute form of the
  label.  For example, an attribute <code>deps=[":foo",
  "//otherpkg:bar", "wiz"]</code> would be converted to the
  string <code>[//thispkg:foo, //otherpkg:bar, //thispkg:wiz]</code>.
  Brackets
  are always present, so the empty list would use string value <code>[]</code>
  for matching purposes. For example,
</p>
<pre>attr("srcs", "\[\]", deps(//foo))</pre>
<p>
  will select all rules among <code>//foo</code> dependencies that have an
  empty <code>srcs</code> attribute, while
</p>
<pre>attr("data", ".{3,}", deps(//foo))</pre>
<p>
  will select all rules among <code>//foo</code> dependencies that specify at
  least one value in the <code>data</code> attribute (every label is at least
  3 characters long due to the <code>//</code> and <code>:</code>).
</p>

<h3 id="visible">Rule visibility filtering: visible</h3>
<pre>expr ::= visible(<var>expr</var>, <var>expr</var>) </pre>
<p>
  The <code>visible(<var>predicate</var>, <var>input</var>)</code> operator
  applies a filter to a set of targets, and discards targets without the
  required visibility.
</p>

<p>
  The first argument, <var>predicate</var>, is a set of targets that all targets
  in the output must be visible to. A <var>visible</var> expression
  evaluates to the set containing all targets <var>x</var> such that <var>x</var>
  is a member of the set <var>input</var>, and for all targets <var>y</var> in
  <var>predicate</var> <var>x</var> is visible to <var>y</var>. For example:
</p>
<pre>visible(//foo, //bar:*)</pre>
<p>
  will select all targets in the package <code>//bar</code> that <code>//foo</code>
  can depend on without violating visibility restrictions.
</p>

<h3 id="labels">Evaluation of rule attributes of type label: labels</h3>
<pre>expr ::= labels(<var>word</var>, <var>expr</var>) </pre>
<p>
  The <code>labels(<var>attr_name</var>, <var>inputs</var>)</code>
  operator returns the set of targets specified in the
  attribute <var>attr_name</var> of type "label" or "list of label" in
  some rule in set <var>inputs</var>.
</p>

<p>
  For example, <code>labels(srcs, //foo)</code> returns the set of
  targets appearing in the <code>srcs</code> attribute of
  the <code>//foo</code> rule.  If there are multiple rules
  with <code>srcs</code> attributes in the <var>inputs</var> set, the
  union of their <code>srcs</code> is returned.
</p>

<p>
  Please note, <code>deps</code> is a reserved word in the query
  language, so you must quote it if you wish to query the rule
  attribute of that name in a <code>labels</code> expression:
  <code>labels("deps", //foo)</code>.
</p>

<h3 id="tests">Expand and filter test_suites: tests</h3>
<pre>expr ::= tests(<var>expr</var>)</pre>
<p>
  The <code>tests(<var>x</var>)</code> operator returns the set of all test
  rules in set <var>x</var>, expanding any <code>test_suite</code> rules into
  the set of individual tests that they refer to, and applying filtering by
  <code>tag</code> and <code>size</code>.

  By default, query evaluation
  ignores any non-test targets in all <code>test_suite</code> rules. This can be
  changed to errors with the <code>--strict_test_suite</code> option.
</p>

<p>
  For example, the query <code>kind(test, foo:*)</code> lists all
  the <code>*_test</code> and <code>test_suite</code> rules
  in the <code>foo</code> package.  All the results are (by
  definition) members of the <code>foo</code> package.  In contrast,
  the query <code>tests(foo:*)</code> will return all of the
  individual tests that would be executed by <code>bazel test
  foo:*</code>: this may include tests belonging to other packages,
  that are referenced directly or indirectly
  via <code>test_suite</code> rules.
</p>


<h3 id="buildfiles">Package definition files: buildfiles</h3>
<pre>expr ::= buildfiles(<var>expr</var>)</pre>
<p>
  The <code>buildfiles(<var>x</var>)</code> operator returns the set
  of files that define the packages of each target in
  set <var>x</var>; in other words, for each package, its BUILD file,
  plus any files it references

  via <code>load</code>.  Note that this also returns the BUILD files of the
  packages containing these <code>load</code>ed files.
</p>

<p>
  This operator is typically used when determining what files or
  packages are required to build a specified target, often in conjunction with
  the <a href='#output-package'><code>--output package</code></a>
  option, below).  For example,
</p>
<pre>bazel query 'buildfiles(deps(//foo))' --output package</pre>
<p>
  returns the set of all packages on which <code>//foo</code> transitively
  depends.
</p>

<p>
  (Note: a naive attempt at the above query would omit
  the <code>buildfiles</code> operator and use only <code>deps</code>,
  but this yields an incorrect result: while the result contains the
  majority of needed packages, those packages that contain only files
  that are <code>load()</code>'ed

  will be missing.
</p>

<h3 id="loadfiles">Package definition files: loadfiles</h3>
<pre>expr ::= loadfiles(<var>expr</var>)</pre>
<p>
  The <code>loadfiles(<var>x</var>)</code> operator returns the set of
  Skylark files that are needed to load the packages of each target in
  set <var>x</var>. In other words, for each package, it returns the
  .bzl files that are referenced from its BUILD files.
</p>

<h2>Output formats</h2>

<p>
  <code>bazel query</code> generates a graph.
  You specify the content, format, and ordering by which
  <code>bazel query</code> presents this graph
  by means of the <code>--output</code>
  command-line option.
 </p>

<p>
  Some of the output formats accept additional options.  The name of
  each output option is prefixed with the output format to which it
  applies, so <code>--graph:factored</code> applies only
  when <code>--output=graph</code> is being used; it has no effect if
  an output format other than <code>graph</code> is used. Similarly,
  <code>--xml:line_numbers</code> applies only when <code>--output=xml</code>
  is being used.
</p>

<h3 id='result-order'>On the ordering of results</h3>

<p>
  Although query expressions always follow the "<a href='#graph-order'>law of
  conservation of graph order</a>", <i>presenting</i> the results may be done
  in either a dependency-ordered or unordered manner. This does <b>not</b>
  influence the targets in the result set or how the query is computed. It only
  affects how the results are printed to stdout. Moreover, nodes that are
  equivalent in the dependency order may or may not be ordered alphabetically.
  The <code>--order_output</code> flag can be used to control this behavior.
  (The <code>--[no]order_results</code> flag has a subset of the functionality
  of the <code>--order_output</code> flag and is deprecated.)
</p>
<p>
  The default value of this flag is <code>auto</code>, which is equivalent to
  <code>full</code> for every output format except for <code>proto</code>,
  <code>graph</code>, <code>minrank</code>, and <code>maxrank</code>, for which
  it is equivalent to <code>deps</code>.
</p>
<p>
  When this flag is <code>no</code> and <code>--output</code> is one of
  <code>build</code>, <code>label</code>, <code>label_kind</code>,
  <code>location</code>, <code>package</code>, <code>proto</code>,
  <code>record</code> or <code>xml</code>, the outputs will be printed in
  arbitrary order. <b>This is generally the fastest option</b>. It is not
  supported though when <code>--output</code> is one of <code>graph</code>,
  <code>min_rank</code> or <code>max_rank</code>: with these formats, bazel will
  always print results ordered by the dependency order or rank.
</p>
<p>
  When this flag is <code>deps</code>, bazel will print results ordered by the
  dependency order. However, nodes that are unordered by the dependency order
  (because there is no path from either one to the other) may be printed in any
  order.
</p>
<p>
  When this flag is <code>full</code>, bazel will print results ordered by the
  dependency order, with unordered nodes ordered alphabetically or reverse
  alphabetically, depending on the output format. This may be slower than the
  other options, and so should only be used when deterministic results are
  important &mdash; it is guaranteed with this option that running the same query
  multiple times will always produce the same output.
</p>

<h3 id="output-build">Print the source form of targets as they would appear in BUILD</h3>
<pre>--output build</pre>
<p>
  With this option, the representation of each target is as if it were
  hand-written in the BUILD language. All variables and function calls
  (e.g. glob, macros) are expanded, which is useful for seeing the effect
  of Skylark macros. Additionally, each effective rule is annotated with
  the name of the macro (if any, see <code>generator_name</code> and
  <code>generator_function</code>) that produced it.
</p>
<p>
  Although the output uses the same syntax as BUILD files, it is not
  guaranteed to produce a valid BUILD file.
</p>

<h3 id="output-label">Print the label of each target</h3>
<pre>--output label</pre>
<p>
  With this option, the set of names (or <em>labels</em>) of each target
  in the resulting graph is printed, one label per line, in
  topological order (unless <code>--noorder_results</code> is specified, see
  <a href='#result-order'>notes on the ordering of results</a>).
  (A topological ordering is one in which a graph
  node appears earlier than all of its successors.)  Of course there
  are many possible topological orderings of a graph (<em>reverse
  postorder</em> is just one); which one is chosen is not specified.

  When printing the output of a <code>somepath</code> query, the order
  in which the nodes are printed is the order of the path.
</p>

<p>
  Caveat: in some corner cases, there may be two distinct targets with
  the same label; for example, a <code>sh_binary</code> rule and its
  sole (implicit) <code>srcs</code> file may both be called
  <code>foo.sh</code>.  If the result of a query contains both of
  these targets, the output (in <code>label</code> format) will appear
  to contain a duplicate.  When using the <code>label_kind</code> (see
  below) format, the distinction becomes clear: the two targets have
  the same name, but one has kind <code>sh_binary rule</code> and the
  other kind <code>source file</code>.
</p>

<h3 id="output-label_kind">Print the label and kind of each target</h3>
<pre>--output label_kind</pre>
<p>
  Like <code>label</code>, this output format prints the labels of
  each target in the resulting graph, in topological order, but it
  additionally precedes the label by
  the <a href='#kind'><em>kind</em></a> of the target.
</p>

<h3 id="output-ranked">Print the label of each target, in rank order</h3>
<pre>--output minrank
--output maxrank</pre>
<p>
  Like <code>label</code>, the <code>minrank</code>
  and <code>maxrank</code> output formats print the labels of each
  target in the resulting graph, but instead of appearing in
  topological order, they appear in rank order, preceded by their
  rank number. These are unaffected by the result ordering
  <code>--[no]order_results</code> flag (see <a href='#result-order'>notes on
  the ordering of results</a>).
</p>

<p>
  There are two variants of this format: <code>minrank</code> ranks
  each node by the length of the shortest path from a root node to it.
  "Root" nodes (those which have no incoming edges) are of rank 0,
  their successors are of rank 1, etc.  (As always, edges point from a
  target to its prerequisites: the targets it depends upon.)
</p>

<p>
  <code>maxrank</code> ranks each node by the length of the longest
  path from a root node to it.  Again, "roots" have rank 0, all other
  nodes have a rank which is one greater than the maximum rank of all
  their predecessors.
</p>

<p>
  All nodes in a cycle are considered of equal rank.  (Most graphs are
  acyclic, but cycles do occur
  simply because BUILD files contain erroneous cycles.)
</p>

<p>
  These output formats are useful for discovering how deep a graph is.
  If used for the result of a <code>deps(x)</code>, <code>rdeps(x)</code>,
  or <code>allpaths</code> query, then the rank number is equal to the
  length of the shortest (with <code>minrank</code>) or longest
  (with <code>maxrank</code>) path from <code>x</code> to a node in
  that rank.  <code>maxrank</code> can be used to determine the
  longest sequence of build steps required to build a target.
</p>

<p>
  Please note, the ranked output of a <code>somepath</code> query is
  basically meaningless because <code>somepath</code> doesn't
  guarantee to return either a shortest or a longest path, and it may
  include "transitive" edges from one path node to another that are
  not direct edges in original graph.
</p>

<p>
  For example, the graph on the left yields the outputs on the right
  when <code>--output minrank</code> and <code>--output maxrank</code>
  are specified, respectively.
</p>

<table style='margin: auto'><tr><td>
<div class='graphviz dot'><!--
digraph mygraph {
  node [shape=box];
"//a:a" -> "//a:a.cc"
"//b:b" -> "//a:a"
"//b:b" -> "//b:b.cc"
"//c:c" -> "//b:b"
"//c:c" -> "//a:a"
}
--></div>
</td><td>
<pre>
minrank

0 //c:c
1 //b:b
1 //a:a
2 //b:b.cc
2 //a:a.cc
</pre>
</td><td>
<pre>
maxrank

0 //c:c
1 //b:b
2 //a:a
2 //b:b.cc
3 //a:a.cc
</pre>
</td></tr></table>

<h3 id="output-location">Print the location of each target</h3>
<pre>--output location</pre>
<p>
  Like <code>label_kind</code>, this option prints out, for each
  target in the result, the target's kind and label, but it is
  prefixed by a string describing the location of that target, as a
  filename and line number.  The format resembles the output of
  <code>grep</code>. Thus, tools that can parse the latter (such as Emacs
  or vi) can also use the query output to step through a series of
  matches, allowing the Bazel query tool to be used as a
  dependency-graph-aware "grep for BUILD files".
</p>

<p>
  The location information varies by target kind (see the <a
  href='#kind'>kind</a> operator).  For rules, the
  location of the rule's declaration within the BUILD file is printed.
  For source files, the location of line 1 of the actual file is
  printed.  For a generated file, the location of the rule that
  generates it is printed.  (The query tool does not have sufficient
  information to find the actual location of the generated file, and
  in any case, it might not exist if a build has not yet been
  performed.)
</p>

<h3 id="output-package">Print the set of packages</h3>
<pre>--output package</pre>
<p>
  This option prints the name of all packages to which
  some target in the result set belongs.  The names are printed in
  lexicographical order; duplicates are excluded.  Formally, this
  is a <em>projection</em> from the set of labels (package, target) onto
  packages.
</p>

<p>
  In conjunction with the <code>deps(...)</code> query, this output
  option can be used to find the set of packages that must be checked
  out in order to build a given set of targets.
</p>

<h3 id="output-graph">Display a graph of the result</h3>
<pre>--output graph</pre>
<p>
  This option causes the query result to be printed as a directed
  graph in the popular AT&amp;T GraphViz format.  Typically the
  result is saved to a file, such as <code>.png</code> or <code>.svg</code>.
  (If the <code>dot</code> program is not installed on your workstation, you
  can install it using the command <code>sudo apt-get install graphviz</code>.)
  See the example section below for a sample invocation.
</p>

<p>
  This output format is particularly useful for <code>allpath</code>,
  <code>deps</code>, or <code>rdeps</code> queries, where the result
  includes a <em>set of paths</em> that cannot be easily visualized when
  rendered in a linear form, such as with <code>--output label</code>.
</p>

<p>
  By default, the graph is rendered in a <em>factored</em> form.  That is,
  topologically-equivalent nodes are merged together into a single
  node with multiple labels.  This makes the graph more compact
  and readable, because typical result graphs contain highly
  repetitive patterns.  For example, a <code>java_library</code> rule
  may depend on hundreds of Java source files all generated by the
  same <code>genrule</code>; in the factored graph, all these files
  are represented by a single node.  This behavior may be disabled
  with the <code>--nograph:factored</code> option.
</p>

<h4><code>--graph:node_limit <var>n</var></code></h4>
<p>
  The option specifies the maximum length of the label string for a
  graph node in the output.  Longer labels will be truncated; -1
  disables truncation.  Due to the factored form in which graphs are
  usually printed, the node labels may be very long.  GraphViz cannot
  handle labels exceeding 1024 characters, which is the default value
  of this option.  This option has no effect unless
  <code>--output=graph</code> is being used.
</p>

<h4><code>--[no]graph:factored</code></h4>
<p>
  By default, graphs are displayed in factored form, as explained
  <a href='#output-graph'>above</a>.
  When <code>--nograph:factored</code> is specified, graphs are
  printed without factoring.  This makes visualization using GraphViz
  impractical, but the simpler format may ease processing by other
  tools (e.g. grep).  This option has no effect
  unless <code>--output=graph</code> is being used.
</p>

<h3 id="output-xml">XML</h3>
<pre>--output xml</pre>
<p>
  This option causes the resulting targets to be printed in an XML
  form.  The output starts with an XML header such as this
</p>
<pre>
  &lt;?xml version="1.0" encoding="UTF-8"?&gt;
  &lt;query version="2"&gt;
</pre>
<!-- The docs should continue to document version 2 into perpetuity,
     even if we add new formats, to handle clients synced to old CLs. -->
<p>
  and then continues with an XML element for each target
  in the result graph, in topological order (unless
  <a href='#result-order'>unordered results</a> are requested),
  and then finishes with a terminating
</p>
<pre>
&lt;/query&gt;
</pre>
<p>
  Simple entries are emitted for targets of <code>file</code>
  kind:
</p>
<pre>
  &lt;source-file name='//foo:foo_main.cc' .../&gt;
  &lt;generated-file name='//foo:libfoo.so' .../&gt;
</pre>
<p>
  But for rules, the XML is structured and contains definitions of all
  the attributes of the rule, including those whose value was not
  explicitly specified in the rule's BUILD file.
</p>
<p>
  Additionally, the result includes <code>rule-input</code> and
  <code>rule-output</code> elements so that the topology of the
  dependency graph can be reconstructed without having to know that,
  for example, the elements of the <code>srcs</code> attribute are
  forward dependencies (prerequisites) and the contents of the
  <code>outs</code> attribute are backward dependencies (consumers).

  <code>rule-input</code> elements for <a
  href='#implicit_deps'>implicit dependencies</a> are suppressed if
  <code>--noimplicit_deps</code> is specified.
</p>
<pre>
  &lt;rule class='cc_binary rule' name='//foo:foo' ...&gt;
    &lt;list name='srcs'&gt;
      &lt;label value='//foo:foo_main.cc'/&gt;
      &lt;label value='//foo:bar.cc'/&gt;
      ...
    &lt;/list&gt;
    &lt;list name='deps'&gt;
      &lt;label value='//common:common'/&gt;
      &lt;label value='//collections:collections'/&gt;
      ...
    &lt;/list&gt;
    &lt;list name='data'&gt;
      ...
    &lt;/list&gt;
    &lt;int name='linkstatic' value='0'/&gt;
    &lt;int name='linkshared' value='0'/&gt;
    &lt;list name='licenses'/&gt;
    &lt;list name='distribs'&gt;
      &lt;distribution value="INTERNAL" /&gt;
    &lt;/list&gt;
    &lt;rule-input name="//common:common" /&gt;
    &lt;rule-input name="//collections:collections" /&gt;
    &lt;rule-input name="//foo:foo_main.cc" /&gt;
    &lt;rule-input name="//foo:bar.cc" /&gt;
    ...
  &lt;/rule&gt;
</pre>

<p>
  Every XML element for a target contains a <code>name</code>
  attribute, whose value is the target's label, and
  a <code>location</code> attribute, whose value is the target's
  location as printed by the <a href='output-location'><code>--output
  location</code></a>.
</p>

<h4><code>--[no]xml:line_numbers</code></h4>
<p>
  By default, the locations displayed in the XML output contain line numbers.
  When <code>--noxml:line_numbers</code> is specified, line numbers are not
  printed.
</p>

<h4><code>--[no]xml:default_values</code></h4>
<p>
  By default, XML output does not include rule attribute whose value
  is the default value for that kind of attribute (e.g. because it
  were not specified in the BUILD file, or the default value was
  provided explicitly).  This option causes such attribute values to
  be included in the XML output.
</p>


<h3 id="external-repos">Querying with external repositories</h3>

<p>
  If the build depends on rules from external repositories (defined in the
  WORKSPACE file) then query results will include these dependencies. For
  example, if <code>//foo:bar</code> depends on <code>//external:some-lib</code>
  and <code>//external:some-lib</code> is bound to
  <code>@other-repo//baz:lib</code>, then
  <code>bazel query 'deps(//foo:bar)'</code>
  will list both <code>@other-repo//baz:lib</code> and
  <code>//external:some-lib</code> as dependencies.
</p>

<p>
  External repositories themselves are not dependencies of a build. That is, in
  the example above, <code>//external:other-repo</code> is not a dependency. It
  can be queried for as a member of the <code>//external</code> package, though,
  for example:
<p>

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

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