=head1 Introduction

The Query Builder is RT's search engine. It lets you find tickets matching
some (potentially very complex) criteria. There are loads of criteria you can
specify in order to perform a search. Strategies for narrowing your searches
to find exactly what you're looking for (and no more) are discussed below.

The Query Builder is the heart of reporting in RT, which is covered in the
L<Dashboard and Reports|docs/dashboards_reporting.pod> document.

=head1 Basic Ticket Searches

Let's look for tickets in the "RT" queue (RT's bugtracker for itself) that have
been resolved in the last year. (These examples assume it's currently mid June,
2015). To do that, we specify the search criteria (Queue is RT, Status is
resolved, and Resolved after 2014-06-15) in the upper left hand section of the
Query Builder.

=for html <img alt="Search Criteria"
src="images/search-criteria.png">

=for :text [Search Criteria F<docs/images/search-criteria.png>]

=for :man [Search Criteria F<docs/images/search-criteria.png>]

RT also has two meta-statuses, 'active' and 'inactive'. By selecting either of
these from the status dropdown of the query builder, you will no longer need
to explicitly list all of the active or inactive statuses or manually enter
the queries: "Status = '__Active__'" or "Status = '__Inactive__'".

The sets of active and inactive statuses for a queue are defined by the
associated lifecycle. Active tickets are those listed for the 'active' and
'initial' configurations. Inactive tickets are those defined as 'inactive'.
For the default RT lifecycle, for example, the active statuses are new, open,
and stalled, and the inactive statuses are resolved, rejected and deleted. See
F<docs/customizing/lifecycles.pod> for more information.

Now that I've selected some criteria, I can click either Add These Terms or
Add These Terms and Search. I'll click the former:

=for html <img alt="Added Terms"
src="images/added-terms.png">

=for :text [Added Terms F<docs/images/added-terms.png>]

=for :man [Added Terms F<docs/images/added-terms.png>]

The upper right hand side presents all the logic we've specified. This view is
a nice way proofread your search: Have you captured everything you want? Are
there things you'd maybe prefer to leave out for now?

It turns out I've changed my mind. I actually don't want to restrict the search
to just the RT queue. I want to see all the tickets in issues.bestpractical.com
(which also includes feature requests, RTIR, etc) that have been resolved
within the past year. To adjust the search, click on 'AND Queue = RT' and press
Delete:

=for html <img alt="Delete Term"
src="images/delete-term.png">

=for :text [Delete Term F<docs/images/delete-term.png>]

=for :man [Delete Term F<docs/images/delete-term.png>]

Your search should now look like this:

=for html <img alt="Deleted Term"
src="images/deleted-term.png">

=for :text [Deleted Term F<docs/images/deleted-term.png>]

=for :man [Deleted Term F<docs/images/deleted-term.png>]

Now, finally, to make the search go, you can either press 'Add these terms and
Search' (provided there's no new content in the Query Builder), or scroll all
the way down and press 'Update format and Search'. This search should turn up
a full page of tickets. Here's the top portion of the list:

=for html <img alt="Search Results"
src="images/search-results.png">

=for :text [Search Results F<docs/images/search-results.png>]

=for :man [Search Results F<docs/images/search-results.png>]

This is the default view of your results. However, like nearly everything in RT,
it's configurable. You can select additional columns to appear in your results,
eliminate columns you don't find useful, or reorder them. To start, notice that
at the bottom of the query builder page there are two panes: Sorting and Display
Columns.

=for html <img alt="Sorting and Display Columns"
src="images/sorting-display-columns.png">

=for :text [Sorting and Display Columns
F<docs/images/sorting-display-columns.png>]

=for :man [Sorting and Display Columns F<docs/images/sorting-display-columns.png>]

There is more than one option for Sorting so that you can break apart tickets
with the same search values into a meaningful order. For example, let's say you
start off by sorting tickets in a search by their owner. Since you've only
specified to sort by owner, RT doesn't order the tickets owned by the same user
in a meaningful way. This is where the multiple sort criteria comes in handy.
You can use a second sorting criteria to sort within the set of tickets owned by
a single user. For example, you could add a sort by due date to see tickets
sorted first by owner, and then tickets with the same order are ordered by due
date.

The Display Columns tab allows you to add or eliminate information displayed in
the results of your search. NEWLINE indicates a line break, or new row, in how
the results are displayed. NBSP for adding an empty column (such as what shows
up underneath id in the following screenshot).

Here is a search with NEWLINE where it is by default:

=for html <img alt="With NEWLINE"
src="images/with-newline.png">

=for :text [With NEWLINE F<docs/images/with-newline.png>]

=for :man [With NEWLINE F<docs/images/with-newline.png>]

Notice that the structure of the data that's displayed is stacked: Subject on
top of Requestor, Status on top of Created, etc.. Because we're displaying a
lot of information (10 fields for each ticket), having the NEWLINE is
important for the results more comprehensible.

Here is that same search but without the NEWLINE:

=for html <img alt="Without NEWLINE"
src="images/without-newline.png">

=for :text [Without NEWLINE F<docs/images/without-newline.png>]

=for :man [Without NEWLINE F<docs/images/without-newline.png>]

The same pieces of information are now spread across the display next to one
another, which can be harder to read. So when you tell RT to display a lot of
columns, it's usually worth adding a well-placed NEWLINE.

=head1 Searching for Users on Tickets

The Query Builder provides ways to search for tickets based on how a
given user is related to the ticket. This works for all ticket roles,
so you can find all active tickets where a given user is the Requestor,
meaning they opened the ticket. You can also search for all tickets
with a given user as the owner, meaning that's what they are working on.

=head2 Groups on Roles

Ticket roles, except for Owner, can also accept a group as a value.
When you search for a user, by default the Query Builder does a
recursive or "deep" search, meaning it searches the role and it checks
the membership of any groups it finds in the role as well.

For example, assume you have a group "Helpdesk", the staff1 user is a
member, and Helpdesk is set as an AdminCc on a ticket. If you perform
this search:

    AdminCc.Name = 'staff1'

the results will contain that ticket.

You can also search for group names on roles. For core roles, you can
select from the dropdown with group names containing "Owner Group", etc.
Following the example above, if you wanted to find tickets with
the Helpdesk group assigned to the AdminCc role, you can use this search:

    AdminCCGroup = 'Helpdesk'

You can also search for groups on custom roles using the Name value.
A search for a group on a custom role looks like:

    CustomRole.{Department}.Name = 'Helpdesk'

Note that if you also have a user with the name 'Helpdesk', the custom
role search will return all matches, so you will see tickets with both
username 'Helpdesk' and the group 'Helpdesk' assigned.

=head2 Shallow Searches

In some cases you may want to see tickets only when the user you are
searching for is a direct member of a role and not if they are in
any groups. For that case, use the "shallow" options, like "shallow is"
to generate a search like this:

    AdminCc.Name SHALLOW = 'staff1'

That will show tickets where 'staff1' is directly in the AdminCc role,
but not the ticket from the previous example where staff1 is in the
Helpdesk group on the AdminCc role.

=head1 Searching Custom Fields on Tickets

If you use custom fields on your tickets, you might initially load the Query
Builder and not see them listed. If your custom fields are applied to
individual queues and not globally, they won't show up as options on a
new search. However, once you add a queue to your search, as shown above, the
custom fields applied to the queue or queues in your search will be displayed.
You can then add custom field values to your search just like other fields.

In addition to exact queue name searches like "Queue = 'RT'", the query builder
also allows 'LIKE' searches. This can be useful if you have several queues that
follow some naming pattern, like "IT Support", "Printer Support", and "Email Support".
To include all of these, you can use "Queue LIKE 'Support'".

Using the Advanced tab, you can also type one other criteria to search for queues
by their lifecycle. TicketSQL supports "Lifecycle = 'support'" if you type it
directly into the Advanced search box.

=head2 Basic Custom Field Searches

Once you add a queue to your search using one of the options above, you'll see
any custom fields applied to those queues at the bottom of the list of values in
the Add Criteria section. To search for all tickets with a custom field that
has some value, pick the comparision ("matches", "is", etc.), add a value,
and click "Add these terms" to build the search.

If you have a custom field named "Transport Type", for example, that has
the values, "Car", "Bus" or "Train", you can search for all tickets that
reference cars by picking "is" next to "Transport Type", typing "Car"
and clicking Add these terms. You should then see a search term like:

    'CF.{Transport Type}' = 'Car'

For custom fields that have a dropdown with values to pick from a list,
the Query Builder will show the available values as a dropdown and
you can pick from the options without typing a value.

When searching for custom fields, you can also add them as a column in
your search results as described above.

=head2 Searching for Empty Custom Fields

Sometimes you want to search for all tickets where a given custom
field doesn't have a particular value. For example, you might search
for all tickets where "Transport Type" is not set to "Car" using the
"isn't" option, and that would create:

    'CF.{Transport Type}' != 'Car'

The search would contain all tickets in that queue with "Transport Type"
values of "Bus", "Train", and no value.

To remove tickets where Transport Type has no set value, add the
following to your query:

    AND 'CF.{Transport Type}' IS NOT NULL

Similarly, to see all tickets where "Transport Type" hasn't be set,
you can search for :

    'CF.{Transport Type}' IS NULL

=cut

=head1 Advanced

In addition to the graphical query builder, RT also has an Advanced page
where you can write and modify queries and formats directly. For example,
you can type the following query directly in the Query box:

    Status = 'resolved' AND Resolved > '2019-04-01' AND Queue = 'RT'

and then click "Apply" to let RT validate it. RT will display any syntax errors
if you make any mistakes so you can fix them.

=head2 Valid Search Values

In the above example, search values like C<'resolved'>, C<'2019-04-01'>,
and C<'RT'> are all literal search terms: a status, a date, and a string
representing the name of a queue. These are all static values that will then
return matching tickets. However, sometimes you want to compare 2 columns
in RT tables without knowing exact values. This is also supported, for
example:

=over

=item Search tickets where LastUpdated is after (later than) Resolved

    LastUpdated > Resolved

This finds tickets that have been commented on or otherwise updated after
they were resolved. Note that C<Resolved> is not quoted, indicating that it's
the relative date value from a ticket instead of the literal string "Resolved".

=item Search tickets where the Requestor is also the Owner

    Requestor.id = Owner

=item Search tickets where custom fields Foo and Bar have the same value

    CF.Foo = CF.Bar

This is equal to:

    CF.{Foo} = CF.{Bar}
    CF.Foo = CF.Bar.Content

To compare LargeContent instead:

    CF.IP = CF.IPRange.LargeContent

=back

=head1 Learn More

To use the query builder to build and save reports, see
L<Dashboard and Reports|docs/dashboards_reporting.pod>. For definitions of
RT metadata, see L<Ticket Metadata|docs/ticket_metadata.pod>.

=cut
