2.4 Querying the database

Obtain information from the database by using the program query-pr. query-pr uses search parameters you provide to find matching Problem Reports in the database. You can invoke query-pr from the shell or from within Emacs. query-pr uses the same arguments whether it is invoked from the shell or from Emacs.

PRs may be selected via the use of the --expr option, directly by number, or by the use of the (now deprecated) field-specific query operators.

By default, query options are connected with a logical AND. For example,

query-pr --category=foo --responsible=bar

only prints PRs which have a Category field of ‘foo’ and a Responsible field of ‘bar’.

The --or option may be used to connect query options with a logical OR. For example,

query-pr --category=baz --or --responsible=blee

prints PRs which have either a Category field of ‘baz’ or a Responsible field of ‘blee’.

It should be emphasized, however, that the use of these field-specific options is strongly discouraged, since they exist only for compatibility with older versions of GNATS and are likely to be deleted in the next release. The expressions specified by the --expr option are much more flexible (see below).

2.4.1 Invoking query-pr

From the shell, simply type query-pr, followed by any search parameters you wish to exercise. From Emacs, type M-x query-pr. query-pr prompts you for search parameters in the minibuffer.

query-pr can also be accessed by electronic mail, if your version of GNATS is configured for this. To use this feature, simply send mail to the address ‘query-pr@your-site’ with command line arguments or options in the Subject line of the mail header. GNATS replies to your mail with the results of your query. The default settings for the query-pr mail server are

--restricted --state="open|analyzed|feedback|suspended"

To override the --state parameter, specify --state=state in the Subject line of the mail header. You can not query on confidential Problem Reports by mail.

The usage for query-pr is:

query-pr [--debug | -D] [--help | -h] [--version | -V]
         [--output file | -o file] [--list-databases]
         [--list-fields] [--list-input-fields]
         [--responsible-address name] [--field-type field]
         [--field-description field]
         [--field-flags field]
         [--adm-field field] [--adm-subfield subfield]
         [--adm-key key]
         [--valid-values field]
         [--format format | -f format]
         [--full | -F] [--summary | -q]
         [--database database | -d database] [--and | -&]
         [--or | -|] [--expr expr] [PR Number]

Non-network-mode options:

         [--print-sh-vars] [--print-directory-for-database]

Network-mode-only options:

         [--host host | -H host] [--port port]
         [--user user | -v user] [--passwd passwd | -w passwd]
         [--print-server-addr]

Deprecated Options:

         [--list-categories | -j] [--list-states | -T]
         [--list-responsible | -k] [--list-submitters | -l]
         [--category category | -c category]
         [--synopsis synopsis | -y synopsis]
         [--confidential confidential | -C confidential]
         [--multitext multitext | -m multitext]
         [--originator originator | -O originator]
         [--release release | -A release]
         [--class class | -L class] [--cases cases | -E cases]
         [--quarter quarter | -Q quarter]
         [--keywords keywords | -K keywords]
         [--priority priority | -p priority]
         [--responsible responsible | -r responsible]
         [--restricted | -R] [--severity severity | -e severity]
         [--skip-closed | -x] [--sql | -i] [--sql2 | -I]
         [--state state | -s state]
         [--submitter submitter | -S submitter]
         [--text text | -t text]
         [--required-before date | -u date]
         [--required-after date | -U date]
         [--arrived-before date | -b date]
         [--arrived-after date | -a date]
         [--modified-before date | -B date]
         [--modified-after date | -M date]
         [--closed-before date | -z date]
         [--closed-after date | -Z date]

The options have the following meaning:

--help, -h

Prints a help message.

--version, -V

Displays the program version to stdout.

--output file, -o file

The results of the query will be placed in this file.

--database database, -d database

Specifies the database to be used for the query. If no database is specified, the database named default is assumed. (This option overrides the database specified in the GNATSDB environment variable; see Environment variables and GNATS tools for more information.)

--list-categories, -j

Lists the available PR categories for the selected database.

--list-states, -T

Lists the valid PR states for PRs in this database.

--list-responsible, -k

Lists the users that appear in the database’s responsible list.

--list-submitters, -l

Lists the valid submitters for this database.

The previous –list-* options are deprecated and may be removed in future releases of GNATS; their functionality can be replaced with

query-pr --valid-values field

where field is one of Category, Class, Responsible, Submitter-Id, or State.

--list-databases

Lists the known databases.

--list-fields

Lists the entire set of field names for PRs in the selected database.

--list-input-fields

Lists the fields that should be provided when creating a new PR for the currently-specified database. The fields are listed in an order that would make sense when used in a template or form.

--field-type field

Returns the data type contained in PR field field. The current set of data types includes ‘text’, ‘multitext’, ‘enum’, ‘multienum’, ‘enumerated-in-file’, ‘multi-enumerated-in-file’, ‘date’ and ‘integer’.

--field-description field

Returns a human-readable description of the intended purpose of field.

--field-flags field

Returns the flags set for the field in the ‘dbconfig’ file associated with the database, such as textsearch and readonly. See section Individual field configuration.

--adm-field field

Used together with the --adm-key option, this returns a record from the administrative file (if any) associated with the field. For more material on administrative files, see Enumerated field administrative files.

--adm-subfield subfield

Used together with the --adm-field and --adm-key options, this returns the contents of a particular subfield from the record specified by --adm-field and --adm-key. Subfields are treated in Enumerated field administrative files.

--adm-key key

Used together with --adm-field to select a record from the administrative file associated with the field specified by --adm-field. See Enumerated field administrative files.

--valid-values field

For fields of type ‘enum’, a list of valid values (one per line) is returned. Otherwise, a regular expression is returned that describes the legal values in field.

--responsible-address name

The mail address of name is returned; name is assumed to be a name either appearing in the database’s responsible list, or is otherwise a user on the system.

--print-sh-vars

A set of ‘/bin/sh’ variables is returned that describe the selected database. They include:

GNATSDB

The name of the currently-selected database.

GNATSDB_VALID

Set to 1 if the selected database is valid.

GNATSDBDIR

The directory where the database contents are stored.

DEBUG_MODE

Set to 1 if debug mode has been enabled for the database.

DEFAULTCATEGORY

The default category for PRs in the database.

DEFAULTSTATE

The default state for PRs in the database.

--print-server-addr

Prints the information about a remote server database in the format suitable for the GNATSDB environment variable. This option works only in the network mode.

--print-directory-for-database

Returns the directory where the selected database is located.

--format format, -f format

Used to specify the format of the output PRs, See Formatting query-pr output for a complete description.

--full, -F

When printing PRs, the entre PR is displayed. This is exactly equivalent to

query-pr --format full

--summary, -q

When printing PRs, a summary format is used. This is exactly equivalent to

query-pr --format summary

--debug, -D

Enables debugging output for network queries.

--host host, -H host

Specifies the hostname of the gnatsd server to communicate with. This overrides the value in the GNATSDB environment variable.

--port port

Specifies the port number of the gnatsd server to communicate with. This overrides the value in the GNATSDB environment variable.

--user user, -v user

Specifies the username to login with when connecting to the gnatsd server. This overrides the value in the GNATSDB environment variable.

--passwd passwd, -w passwd

Specifies the password to login with when connecting to the gnatsd server. This overrides the value in the GNATSDB environment variable.

--and, -&, --or, -|

These options are used when connecting multiple query operators together. They specify whether the previous and subsequent options are to be logically ANDed or logically ORed.

--expr expr

Specifies a query expression to use when searching for PRs. See section Query expressions.

The remaining deprecated options are not described here, since their use is fairly obvious and their functionality is completely replaced by the use of the --expr option.

2.4.2 Formatting query-pr output

Printing formats for PRs are in one of three forms:

formatname

This is a named format which is described by the database (specifically, these formats are described in the ‘dbconfig’ file associated with the database). The default configuration contains five such formats: ‘standard’, ‘full’, ‘summary’, ‘sql’, and ‘sql2’.

The first three are the ones most commonly used when performing queries. standard is the format used by default if no other format is specified.

Use of the latter two are discouraged; they are merely kept for historical purposes. Other named formats may have been added by the database administrator.

fieldname

A single field name may appear here. Only the contents of this field will be displayed.

’"printf string" fieldname fieldname ...’

This provides a very flexible mechanism for formatting PR output. (The formatting is identical to that provided by the named formats described by the database configuration, See section Named query definitions. The printf string can contain the following % sequences:

%[positionalspecifiers]s: Prints the field as a string. The positional specifiers are similar to those of printf, as +, - and digit qualifiers can be used to force a particular alignment of the field contents.

%[positionalspecifiers]S: Similar to %s, except that the field contents are terminated at the first space character.

%[positionalspecifiers]d: Similar to %s, except that the field contents are written as a numeric value. For integer fields, the value is written as a number. For enumerated fields, the field is converted into a numeric equivalent (i.e. if the field can have two possible values, the result will be either 1 or 2). For date fields, the value is written as seconds since Jan 1, 1970.

%F: The field is written as it would appear within a PR, complete with field header.

%D: For date fields, the date is written in a standard GNATS format.

%Q: For date fields, the date is written in an arbitrary "SQL" format.

An example formatted query looks as follows (note that the whole format specification should be quoted):

query-pr --format '"%s, %s" Synopsis State'

2.4.3 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 section 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.

2.4.4 Example queries

The following simple query:

query-pr --expr 'Category~"rats" & State~"analyzed"
                 & Responsible~"fred"'

yields all PRs in the database which contain the field values:

>Category:     rats         and
>Responsible:  fred         and
>State:        analyzed

The following query:

query-pr --expr 'State~"open|analyzed"'

yields all PRs in the database whose State values match either ‘open’ or ‘analyzed’ (see section Querying using regular expressions. This search is useful as a daily report that lists all Problem Reports which require attention.

The following query:

query-pr --expr 'fieldtype:Text="The quick.*brown fox"'

yields all PRs whose TEXT fields contain the text ‘The quick’ followed by ‘brown fox’ within the same field. See section Querying using regular expressions, which also contains further useful examples of query expressions.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.