Search Syntax

After you have installed and started running TeamCity, it collects the information on builds, tests and so on and indexes it. You can search builds by build number, tag, build configuration name, and other different parameters specifying one or several keywords. You can also search for builds by text in build logs, and by the external ID of a build configuration.

By default, TeamCity stores a search index locally, but you can switch to the Elasticsearch mode so the index is stored on your Elastic host. Both modes support the Lucene syntax described in this article.

Search Query

In TeamCity you can search for builds using the Lucene query syntax. Note that there is a major difference with the default Lucene syntax: by default, TeamCity uses the "prefix search" — not the exact matching like Lucene. For example, if you search for c:main, TeamCity will find all builds of the build configuration whose name starts with the main string.

As Lucene, TeamCity uses the OR operator in a query by default: if there is no Boolean operator between the two terms, OR will be used. The OR operator links two terms and finds a matching entry if either of these terms exist in it.

To narrow your search and get more precise results, use the available search fields — indexed parameters of each build. For complete list of available search fields (keywords), refer to the related section.

Performing Fuzzy Search

You also have a possibility to perform fuzzy search using the tilde (~) symbol at the end of a single word term to search for items with similar spelling.

Boolean Operators and Wildcards Support

You can combine multiple terms with Boolean operators to create more complex search queries. TeamCity Search supports the OR, NOT, and - operators. The AND operator only works in the scope of the same field (for example, tags:EAP AND tags:Production).

When using Boolean operators, type them ALL CAPS.

OR operator helps fetch the search terms that contain either of the terms you specify in the search field. This operator is used by default.
NOT (same as - in front of a query word). Exclude a word or phrase from search results.

TeamCity also supports the * and ? wildcards in a query. It is not recommended using the asterisk (*) at the beginning of the search term as it may require a significant amount of time for TeamCity to search its database. For example, the *onfiguration search term is incorrect.

Complete List of Available Search Fields, Shortcuts, and Keywords

Search Fields

When using search keywords, use the following query syntax:

Search Field	Shortcut	Description	Example
agent		Find all builds that were run on the specified agent.	`agent:unit-77`, or `agent:agent14*`
build		Find all builds that include changes with the specified string.	`build:254` or `build:failed`
buildLog		Find all builds that include certain text in build logs. It is disabled by default.	`buildLog: "NUnit report"`
changes		Find all builds that include changes with the specified string.	`changes:(fix test)`
committers		Find all build that include changes committed by the specified developer.	`committers:ivan_ivanov`
configuration	c	Find all builds from the specified build configuration.	`configuration:IPR` `c:(Nightly Build)`
labels	l	Find all builds that include changes with the specified VCS label.	`labels:EAP` `l:release`
pin_comment		Find all builds that were pinned and have the specified word (string) in the pin comment.	`pin_comment:publish`
project	p	Find all builds from the specified project.	`project:Diana` `p:Calcutta`
revision		Find all builds that include changes with the specified revision (for example, you can search for builds with a specific changelist from Perforce, or revision number in Subversion).	`revision:4536`
stamp		Find all builds that started at the specified time (search by timestamp).	`stamp:200811271753`
status		Find all builds with the specified text in the build status text.	`status:"Compilation failed"`
tags	t	Find all builds with the specified tag.	`tags:buildserver` `t:release`
tests		Find all builds that include specified tests.	`tests:`
triggerer		Find all builds that were triggered by the specified user.	`triggerer:ivan.ivanov`
vcs		Find builds that have the specified VCS.	`vcs:perforce`
build problem		Find builds with the specified build problem	`buildProblem:Compilation failed`

Shortcuts

In addition to above mentioned search fields, you can the following shortcuts in your query:

Shortcut	Description	Example
`#`	Search for the specified build number.	`#<number>`, for example, `#1234`
`@`	Find all builds that were run on the specified agent.	`@<agent's name>`, for example, `@buildAgent1`

Using Double-Colon

You can use the double-colon sign (::) to search for a project and/or build configuration by name:

pro::best — search for builds of configurations with the names starting with best, and in the projects with the names starting with pro.
mega:: — search for builds in all projects with names starting with mega.
::super — search for builds of build configurations with names starting with "super".

"Magic" Keywords

TeamCity also provides "magic" keywords (see table below for the complete list). These magic keywords are formed with the $ sign and a word itself. The word can be shortened up to one (first) syllable, that is, the $labeled, $l, and $lab keywords will be equal in a query. For example, to search for pinned builds of the "Nightly build" configuration in the "Mega" project you can use any of the following queries:

configuration:nightly project:Mega $pinned
c:nigh p:mega $pin
M::night $pin

Magic word	Description
`$tagged`	Search for builds with tags. For example, `Calcutta::Master $t` query will result in a list of all builds marked with any tag of build configurations whose name starts with `Master` from projects with names beginning with `Calcutta`.
`$pinned`	Search for pinned builds.
`$labeled`	Search for builds that have been labels in VCS. For example, to find labeled builds of the Main project you can use following queries: `p:Main $labeled`, or `project:Mai $l`, or `m:: $lab`, and so on.
`$commented`	Search for builds that have been commented.
`$personal`	Search for personal builds. For example, using `-$p` expression in your query will exclude all personal builds from search results.

Search by Build Log

By default, TeamCity does not search for builds by a certain text in build logs.

To enable search by the build logs, perform the following:

Since the logic will increase server memory usage, you need to increase memory size in the -Xmx JVM option on at least 5 Gb (more if you have large build logs/many builds).
Set the tc.search.indexBuildLog=true TeamCity internal property.
Reset the search index.

After reindexing, TeamCity will be able to perform searching by specified text in the build logs and will list the relevant builds.

Resetting Search Index

The search uses an "index" cached on the disk. Only the data previously added to the index is searchable and appears in the search results. Typically, data updates (such as new builds) cause only incremental updates to the index. This means that when some indexing setting is changed and the cached index on the disk gets out of sync, the index needs to be reset to reindex all the builds anew.

To reset the cached search index, click reset for the "search" entry on the Administration | Server Administration | Diagnostics, Caches tab or manually delete files from <TeamCity Data Directory>\system\caches\search while the server is not running. After that, reindexing will start which is a resource-intensive operation on the server and can take hours (depending on the number and "size" of builds, as well as the server machine and database performance). You can monitor the progress in the UI on the Search page or in the server logs.

Last modified: 26 April 2022