Advanced search in TeamCity with SearchQL plugin

Have you ever tried to search for something in the TeamCity settings? TeamCity has a basic search functionality that helps you find projects and build configurations. However, to use more elaborate and complex criteria, you would have to resort to REST API.

The new SearchQL plugin allows issuing composite queries directly from the Administration panel. The plugin provides a simple yet expressive query language for this purpose. The autocomplete feature makes it easy to use.

To install the plugin, download it from the Marketplace and then upload it to your TeamCity server in Administration | Plugins. The Search QL section will appear in the Administration panel.

Query syntax

The SearchQL query has the following syntax:

find <entity type> [in <project id>] with <condition>

Here, <entity type> can be one of the following: project, template, configuration (build configuration), or vcsRoot. <condition> is a logical expression with filters on properties of various entities.

Examples of use

The following examples illustrate how various SearchQL features can be used.

Filter by ID

Here is a query that will return projects with IDs containing Deploy or Launch:

find project in MyMainProject with id *Deploy* or id *Launch*

In this example, id is a string filter. Wildcards can be used in string filters for matching substrings. Currently, such substring matches are limited to one substring only: prefix*, *infix*, and *suffix are allowed, while expressions like one*two* or *one*two* will be supported in the future versions of the plugin.

Use subfilters

The following query will find all build configurations that have at least one build trigger of type vcsTrigger:

find configuration with trigger type vcsTrigger

There are two filters in this query: trigger and type, and type is a subfilter of the trigger filter.

The trigger filter can have multiple subfilters. For example, the param subfilter finds all build triggers that have a certain property with a certain value:

find configuration with trigger param branchFilter = master

Combine filters

It is possible to combine subfilters in logical expressions by putting them in parentheses:

find configuration with trigger (type vcsTrigger and param branchFilter = master)

The parentheses are important. If we remove them from the example above, the resulting query would apply the parameter filter to the build configuration parameters rather than to the properties of build triggers:

find configuration with trigger type vcsTrigger and param branchFilter = master

The logical not operator can also be used in an expression, as shown in the following query that searches for configurations with build steps that match certain criteria:

find configuration with step (type JPS and not param target.jdk.home = "%env.JDK_18%")

In the current version of the plugin, logical expressions with a single not have to be surrounded with parentheses:

• find configuration with step (not param *="%env.JDK_18%") — WRONG

• find configuration with step not param *="%env.JDK_18%" — CORRECT

All string constants in the previous examples are also subfilters. They can be a part of logical expressions:

find configuration with feature param (providerType or publisherId) = (github or githubStatusPublisher)

Modifiers

Filters support modifiers that instruct the SearchQL engine to change the behavior of a filter. For example, most of the filters have the all modifier. The following query returns configurations where all build steps are of the JPS type:

find configuration with step[all] type JPS

The configurations with no build steps will not be included in the result.

By default, filters ignore inherited parameters and settings. Only those defined (or overridden) in the entity (for example, in a build configuration) are taken into account. To include inherited properties, use the withInherited modifier:

find configuration with trigger[withInherited] type vcsTrigger

You can use several modifiers for one filter:

find configuration with trigger[all, withInherited] type vcsTrigger

Other filters

You can find more details, including the list of all filters and more info about strings, in the plugin documentation. Note that this documentation is a work in progress. Feel free to leave your comments to this post if you have any questions.

Performance

Execution of especially elaborate SearchQL queries may significantly load a TeamCity server. To avoid that, the plugin imposes a time limit (10 seconds) on the query execution.

To keep your queries fast, we recommend to narrow down the scope of each query by specifying the part of the project hierarchy. For example, instead of:

find configuration with param path=abc

use

find configuration in Project1 with param path=abc

or

find configuration with project id Project1 and param path=abc

Autocomplete

It is not necessary to remember all the filter names. The SearchQL plugin supports two modes of autocomplete to help you with that.

The fast autocomplete works as you type your query. It relies on a prebuild index and doesn’t consider the context of your query.

For example, if you have typed find configuration in MyProject with trigger , the plugin will suggest the following subfilter options: val, type, param, and enabled. So far, so good.
Yet if you continue as follows: find configuration in MyProject with trigger type , it will suggest to you all the possible trigger types used in your TeamCity instance, not taking into account that you have limited the scope of your search to MyProject.
Note that in this mode the autocomplete of objects’ names is available only for System Administrators.

The context-sensitive autocomplete must be invoked manually by typing ? (a question mark). Please be aware that this mode utilizes more computational resources.

Here are some examples:

• find configuration in Project1 and param ? — only parameter names present in the build configurations of Project1 will be suggested.
• find configuration in Project1 and param path = ? — only values for a parameter with the name "path" that occur in Project1.
• find configuration with param path.to.jps = * and step type ? — only step types from configurations that have the path.to.jps parameter set.

You can also use this autocomplete to get some properties of the objects instead of the objects themselves. For example, get the names of build configurations that satisfy some condition:

find configuration in Project1 with (step type JPS and trigger type vcsTrigger) and name ?

Further development

Here are our plans for the future updates of the SearchQL plugin:

• Extend search functionality beyond project settings. For example, search builds, tests, logs.
• Add a possibility to search parts of entities. For example, search configuration features instead of configurations themselves.

Any kind of user feedback would be very useful. Feel free to create feature requests and bug reports on YouTrack with the SearchQL tag.

• Download plugin
• Source code
• Issues (YouTrack)
• Plugin documentation (draft version)

Happy building!