Node:Query expressions, Next:, Previous:Formatting query-pr output, Up:query-pr


Query expressions

Query expressions are used to select specific PRs based on their field contents. The general form is 

fieldname|"value" operator fieldname|"value" [booleanop ...]

value is a literal string or regular expression; it must be surrounded by double quotes, otherwise it is interpreted as a fieldname.

fieldname is the name of a field in the PR.

operator is one of:

=
The value of the left-hand side of the expression must exactly match the regular expression on the right-hand side of the expression. See Querying using regular expressions.
~
Some portion of the left-hand side of the expression must match the regular expression on the right-hand side.
==
The value of the left-hand side must be equal to the value on the right-hand side of the expression.

The equality of two values depends on what type of data is stored in the field(s) being queried. For example, when querying a field containing integer values, literal strings are interpreted as integers. The query expression 

Number == "0123"

is identical to 

Number == "123"

as the leading zero is ignored. If the values were treated as strings instead of integers, then the two comparisons would return different results.

!=
The not-equal operator. Produces the opposite result of the == operator.
<,>
The left-hand side must have a value less than or greater than the right-hand side. Comparisons are done depending on the type of data being queried; in particular, integer fields and dates use a numeric comparison, and enumerated fields are ordered depending on the numeric equivalent of their enumerated values.

booleanop is either | (logical or), or & (logical and). The query expression 

Category="baz" | Responsible="blee"

selects all PRs with a Category field of baz or a Responsible field of blee.

The not operator ! may be used to negate a test: 

! Category="foo"

searches for PRs where the category is not equal to the regular expression foo.

Parentheses may be used to force a particular interpretation of the expression: 

!(Category="foo" & Submitter-Id="blaz")

skips PRs where the Category field is equal to foo and the Submitter-Id field is equal to blaz. Parentheses may be nested to any arbitrary depth.

Fieldnames can be specified in several ways. The simplest and most obvious is just a name: 

Category="foo"

which checks the value of the category field for the value foo.

A fieldname qualifier may be prepended to the name of the field; a colon is used to separate the qualifier from the name. To refer directly to a builtin field name: 

builtin:Number="123"

In this case, Number is interpreted as the builtin name of the field to check. (This is useful if the fields have been renamed. For further discussion of builtin field names, see The dbconfig file.

To scan all fields of a particular type, the fieldtype qualifier may be used: 

fieldtype:Text="bar"

This searches all text fields for the regular expression bar.

Note that it is not required that the right-hand side of the expression be a literal string. To query all PRs where the PR has been modified since it was closed, the expression 

Last-Modified != Closed-Date

will work; for each PR, it compares the value of its Last-Modified field against its Closed-Date field, and returns those PRs where the values differ. However, this query will also return all PRs with empty Last-Modified or Closed-Date fields. To further narrow the search: 

Last-Modified != Closed-Date & Last-Modified != "" & Closed-Date != ""

In general, comparing fields of two different types (an integer field against a date field, for example) will probably not do what you want.

Also, a field specifier may be followed by the name of a subfield in braces: 

State[type] != "closed"

or even 

builtin:State[type] != "closed"

Subfields are further discussed in The dbconfig file.