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.
The SearchQL query has the following syntax:
find <entity type> [in <project id>] with <condition>
<entity type> can be one of the following:
configuration (build configuration), or
<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
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:
*suffix are allowed, while expressions like
*one*two* will be supported in the future versions of the plugin.
The following query will find all build configurations that have at least one build trigger of type
find configuration with trigger type vcsTrigger
There are two filters in this query:
type is a subfilter of 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
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
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)
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
find configuration with trigger[withInherited] type vcsTrigger
You can use several modifiers for one filter:
find configuration with trigger[all, withInherited] type vcsTrigger
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.
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
find configuration in Project1 with param path=abc
find configuration with project id Project1 and param path=abc
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:
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
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
Project1will be suggested.
find configuration in Project1 and param path = ?— only values for a parameter with the name "path" that occur in
find configuration with param path.to.jps = * and step type ?— only step types from configurations that have the
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 ?
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