Icon

You are viewing the documentation of TeamCity 9.x, which is not the most recently released version of TeamCity.
View this page in TeamCity 10.x and 2017.1 documentation or refer to the listing to choose the documentation corresponding to your TeamCity version.

 
Skip to end of metadata
Go to start of metadata

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, since TeamCity 9.1, by the external id of a build configuration.

On this page:

Search Query

In TeamCity you can search for builds using the Lucene query syntax; however, a TeamCity search query has two major differences described below.

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 this section of the page.

Differences from Lucene Syntax

When using a search query in TeamCity, mind the following major differences from the Lucene native syntax:

  1. By default, TeamCity uses the "AND" operator in a query. That is, if you type in the following query: "failed @agent123", then you will get a list of all builds that have the keyword "failed" in any of its search fields, and were run on the build agent named "agent123".
  2. 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.

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. In TeamCity, you can use AND, "+", OR, NOT and "-".

(info) When using Boolean operators, type them ALL CAPS.

  • AND (same as a plus sign). All words that are linked by the "AND" are included in the search results. This operator is used by default.
  • NOT (same as minus sign in front of a query word). Exclude a word or phrase from search results.
  • OR operator helps you to fetch the search terms that contain either of the terms you specify in the search field.

TeamCity also supports the "*" and "?" wildcards in a query.
(warning) It is not recommended to use 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)

file_revision

 

Find all builds that contain a file with the specified revision.

file_revision:5

files

 

Find all builds that include files with the specified file name.

files:

labels

l

Find all builds that include changes with the specified VCS label.

label: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 (e.g., you can search for builds with a specific changelist from Perforce, or revision number in Subversion, etc.).

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

Shortcuts

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

(info) Note that when you use these shortcuts, do not insert the colon after it. That is, the query syntax is as follows: <shortcut><value to search>

Shortcut

Description

Example

#

Search for the specified build number.

#<number>, e.g. #1234

@

Find all builds that were run on the specified agent.

@<agent's name>, e.g. @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, etc.

$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:

1. Set the tc.search.indexBuildLog=true TeamCity internal property
2. Reset the search cache on the Administration| Server Administration| Diagnostics, Caches tab or manually delete files from <TeamCity Data Directory>\system\caches\search. Please note that you might have to restart the server to let it pick up the updated search cache. Since TeamCity 9.0.1 restart is not required.

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