Search string syntax

A search string can contain words, phrases, name=value pairs, and search commands. Each search string expression can be enclosed in parentheses. In the absence of parentheses, the parentheses are assumed from right to left.

The search string syntax comprises two portions, initial keywords followed by search commands, as in the following example:

Search string = Keywords | Search command1 | Search command2

In this example, the following values apply:

The first portion (keywords) refers to particular words, phrases, and name=value pairs with which you start your search.
The second portion (search commands) can be run only on the output of the first portion. You can chain multiple search commands so that the output of one command is consumed as the input of the subsequent command.

Related topics

Performing a simple search

Understanding fields and tags

Search string examples and their results

Getting started with search

Refining searches

Best practice on choosing search terms

Broad search scopes is one of the factors that affect search performance. BMC recommends that you use specific keywords for searching rather than a wildcard character (*) piped by search commands. Using specific key words helps you reduce data that is irrelevant. Therefore, BMC recommends you to search for specific data sources, data pattern types, data collectors, application tags, and specific errors instead of searching for the wildcard asterisk (*). For more information, see Variables that impact product performance.

This topic contains the following information:

Kinds of search string syntax

The following table describes the various kinds of syntax that you can use in your search string. For a list of examples with the appropriate search results that are expected to be highlighted, see Search string examples and their results.

Note

You can use the less than, less than or equal to, greater than, or greater than or equal to (<, <=, >, or >=) operators only on event data stored with the LONG field type (at the time of data-pattern creation). For more information about field types, see Setting up data patterns to extract fields.

Kinds of search syntax

Search syntax	Description	Example
*	You can perform a wildcard search by specifying the asterisk mark (*) in your search criteria (without changing the time range) to return data that was indexed in the last 60 minutes. The asterisk can also be used to substitute for one or more unspecified characters in your search string.	Searching for the word `error` returns data that starts with the word `error`. Searching for the word `error` returns data that ends with the word `error`. Searching for the word `error` returns data that contains the word `error`.
`word`	You can search for a particular word to see data containing that word. Enter the particular word in your search string.	Searching for the word `error` returns data containing the word `error`.
`"phrase"`	You can search for a specific phrase to see data containing the entire phrase (or the exact search string). Enter the particular phrase in double quotes (") in your search string.	Searching for the phrase `"error and exception"` returns data containing the entire phrase `error and exception`.
`word && word`	You can search for multiple words to see data containing all of the words specified. Enter the words in your search string by separating them with two ampersand characters (&&).	Searching for the words `warning && exception` returns data containing both the words `warning` and `exception`. Searching for the string `(stringliteral1) && (stringliteral2)` returns data containing both the words `stringliteral1` and `stringliteral2`.
word && fieldName=fieldValue	You can search for a combination of the word or phrase along with the field name=value pairs to see data containing both the word (or phrase) and the name=value pair. Enter the word (or phrase) and the name=value pair separated by two ampersand characters (&&).	Searching for `warning && HOST=HOUCOMP` returns data containing both the word `warning` and the `HOST` field with the `HOUCOMP` value.
`word \|\| word`	You can search for multiple words to see data containing one of the words specified. Enter the words in your search string by separating them with two pipe characters (\|\|).	Searching for the words `warning \|\| error` returns data containing either `warning` or `error`.
`word \|\| fieldName=fieldValue`	You can search for a combination of the word or phrase along with the field name=value pairs to see data containing either the word (or phrase) or the name=value pairs. Enter the word (or phrase) along with the name=value pair separated by two pipe characters (\|\|).	Searching for `warning \|\| HOST=HOUCOMP` returns data containing either the word `warning` or the `HOST` field with the `HOUCOMP` value.
`fieldName=fieldValue`	You can search for the field name=value pairs to see data containing that field and the value specified. Enter the field name and its corresponding value that you want to search for, in the format `fieldName=fieldValue`.	Searching for `HOST=HOUCOMP` returns data containing the `HOST` field and the `HOUCOMP` value. Searching for `HOST=HOU` returns data containing the `HOST` field and the value starting with `HOU`. Searching for `HOST=COMP` returns data containing the `HOST` field and the value ending with `COMP`.
fieldName=fieldValue && fieldName=fieldValue	You can search for multiple field name=value pairs to see data containing all of the name=value pairs specified. Enter the name=value pairs in your search string by separating them with two ampersand characters (&&).	Searching for the string `key1=value1 && key2=value2` returns data containing both `key1=value1` and `key2=value2`.
`fieldName <> fieldValue`	You can exclude fields from appearing in your search results. Enter the field name and its corresponding value that you want to search for, in the format `fieldName <> fieldValue`.	Searching for `HOST <> HOUCOMP` returns search results by excluding the `HOST` field and its corresponding value, HOUCOMP.
`fieldName < fieldValue`	You can search for fields with values less than a specified number. Enter the field name and a specified value (condition) that you want to search for, in the format `fieldName < fieldValue`.	Searching for `error < 500` returns search results with the `error` field having values less than 500.
`fieldName <= fieldValue`	You can search for fields with values less than or equal to a specified number. Enter the field name and a specified value (condition) that you want to search for, in the format `fieldName <= fieldValue`.	Searching for `error <= 500` returns search results with the `error` field having values less than or equal to 500.
`fieldName > fieldValue`	You can search for fields with values greater than a specified number. Enter the field name and a specified value (condition) that you want to search for, in the format `fieldName > fieldValue`.	Searching for `error > 500` returns search results with the `error` field having values greater than 500.
`fieldName >= fieldValue`	You can search for fields with values greater than or equal to a specified number. Enter the field name and a specified value (condition) that you want to search for, in the format `fieldName >= fieldValue`.	Searching for `error >= 500` returns search results with the `error` field having values greater than or equal to 500.

About phrases

The term phrase refers to a combination of alphanumeric characters separated by space. When you search for a phrase, the product matches the exact sequence as it occurs in the search string excluding the delimiters (if any).

If you search for a phrase without enclosing it in double quotes ("), the product finds all data containing one or more of the words that constitute the phrase. Conversely, if you enclose the phrase in double quotes, the search mechanism looks for data containing the entire phrase as specified.

Examples

If you search for error and exception, you can find data containing the word error or and or exception.
If you search for "error and exception", you can find data containing the entire phrase error and exception.

Phrases can also be referred to as string literals.

You can also search for field values containing spaces or blank field values by treating them as a phrase.

Examples

To find COLLECTOR_NAME=Win DC1, search for COLLECTOR_NAME="Win DC1".
To find Name= , search for Name="".

Case-sensitive search and case-insensitive search

When you search, TrueSight IT Data Analytics ignores the case for all the search terms except field and tag names. Field names (including default fields) and tag names are case-sensitive. All other kinds of search including plain text, field values, tag values, search command names, search command operators and functions are treated in a case-insensitive way.

You can apply case-sensitivity to field and tag values by using the CASE function. To make searches on field and tag values case-sensitive, you need to enclose the field value in parenthesis and place the CASE function in front of the field value (outside the parenthesis) in the format, <fieldName>=CASE(<fieldValue>). For example, OS=CASE(WINDOWS). While specifying the CASE function, case is not important. The CASE function applied on numeric field values is ignored.

Note

You can apply the CASE function on field and tag values only before specifying search commands, this means before the pipe character.

You can also apply case sensitivity when you add a field or tag value from the search results area or from the Filters panel. For more information, see Filtering your search results.

Note

By default, all manually added search strings are treated in a case-insensitive way. Therefore, field and tag values included in a manually added search string are treated in a case-insensitive way. You can make these values case-sensitive by using the CASE function.

When you add a field or tag value from the search results area or from the Filters panel on the Search page, it is assumed that you want to narrow down your search to the particular value selected. Therefore, by default, such field or tag values added to the search criteria (displayed under the search bar) are treated in a case-sensitive way. You can make it case-insensitive by toggling CASE to NOT CASE, under the search bar. For more information, see Filtering your search results

The following table provides examples of case-sensitive and case-insensitive search terms.

Search term	Case sensitivity	Example
Plain text	Case-insensitive	`Error` is the same as `error`.
Plain text	Case-insensitive	`exception` is the same as `Exception`.
Field name	Case-sensitive	`FUNCTION=Execute` is not the same as `function=Execute`. `FUNCTION` is case-sensitive.
		`COLLECTOR_NAME=CollectionMetrics` is not the same as `Collector_Name=CollectionMetrics`. `COLLECTOR_NAME` is case-sensitive.
		`DATA_PATTERN=ApacheLogs` is not the same as `data_pattern=ApacheLogs`. `DATA_PATTERN` is case-sensitive.
Field value	Case-insensitive	`HOST=HoStA.bmc.com` is the same as `HOST=HostA.bmc.com`. The field value, `HoStA.bmc.com` is case-insensitive.
Field value	Case-sensitive	`COLLECTOR_NAME=CollA && rtype=case(Ref)` The field value, `Ref` is case-sensitive because the `case` function is applied to it.
Tag name	Case-sensitive	`Location=HOUSTON` is not the same as `location=HOUSTON`. `Location` is case-sensitive.
Tag value	Case-insensitive	`OS=WINDOWS` is the same as `OS=Windows`. The tag value, `WINDOWS` is case-insensitive.
Tag value	Case-sensitive	`OS=CASE(WINDOWS)` The tag value, `WINDOWS` is case-sensitive because the `CASE` function is applied to it.
Search command names and associated functions and operators	Case-insensitive	`Difftime` is the same as `difftime`.
		`STATS` is the same as `stats`.
		`TaBle` is the same as `table`.
		`... \| rare limit=1 RequestType` is the same as `... \| rare LiMit=1 RequestType` The parameter `limit` is case-insensitive.
		`... \| group maxevents=2 maxspan=2m` is the same as `... \| group MaxEvents=2 MaxSpan=2m` The functions `maxevents` and `maxspan` are case-insensitive.
		`...\| rare limit=5 DATA_PATTERN BY HOST` is the same as `...\| rare limit=5 DATA_PATTERN by HOST.` The `by` operator is case-insensitive.

Search command chaining

You can run search commands on the output of a particular search that you have already performed. For example, the search string, key1=value1 && stringliteral | tail 5 results in the following actions:

Firstly, the product searches for data that contains both key1=value1 and stringliteral.
Secondly, the tail search command is run on the output of the search performed in step 1.

In the course of your data investigation, you can chain a set of commands so that the output of one command is consumed as the input to the subsequent command. You can chain multiple commands by using the pipe (|) operator:

Syntax: searchString | Searchcommand1 | SearchCommand2

For more information about best practices for chaining multiple search commands, see Search commands.

Search string syntax samples

The following table lists search string syntax samples and describes how they are interpreted by the product.

Search string syntax samples

Sample search string	What does it mean?
`key1=value1 && key2=value2 && stringliteral1 && stringliteral2`	`(key1=value1 && (key2=value2 && (stringliteral1 && stringliteral2)))`
`logged off`	`(logged \|\| off )`
`logged off && Event`	`(logged \|\| (off && Event))`
`logged off ldap pdap`	`(logged \|\| (off \|\| (ldap \|\| pdap)))`
`(ldap pdap cdap)`	`(ldap \|\| (cdap \|\| cdap))`
`logged off && (EventCode="4624")`	`(logged \|\| (off && (EventCode = "4624")))`
`logged off && Event "Logged "`	`(logged \|\| (off && (Event \|\| "Logged")))`
`logged off logged && Event =4624`	`(logged \|\| ( off \|\| (logged && (Event ="4624"))))`
`"logged off" event`	`("logged off" \|\| event)`

Special characters and their effect on search

You cannot search for special characters literally. During search, special characters are automatically ignored and results are returned based on the remaining terms in your search string. Results are returned irrespective of where the special character occurs in the search string (in the beginning, middle, or end).

The following examples illustrate how search functions when your search string contains special characters:

Example 1

Sample data

Record 1	`OP^Q`
Record 2	`^OPR`

Search Scenario 1

Search string	`^`
Search results	No results found

Search Scenario 2

Search string	`OP^Q`
Search results	Returns the sample data record 1

Example 2

Sample data

Record 1	`abc@gmail.com`
Record 2	`x@bmc.com`
Record 3	`abc logged off`

Search scenario 1

Search string	`@`
Search results	No results found

Search scenario 2

Search string	`abc@`
Search results	Returns the sample data records 1 and 3

Search scenario 3

Search string	`@gmail`
Search results	Returns the sample data record 1.

Some special characters carry a special meaning in TrueSight IT Data Analytics.

The following table lists the special characters that carry a special meaning:

Special character	Symbol	Usage
Pipe	\|	Used while specifying search commands.
Asterisk	*	Used as a wildcard for searching.
Parenthesis	( )	Used to enclose expressions.
Equals sign	=	Used to separate a field-value pair.
Double quotes	"	Used to search for phrases.

If your search string contains one or more special characters included in the preceding table, then to be able to find results, you need to escape them. You can escape these special characters by enclosing the search string in double quotes (in other words, treating the search string as a phrase). However, if your search string contains double quotes, then you need to escape it by placing a backward slash (\) before the double quotes, in your search string.

The following examples illustrate how search functions when your search string contains special characters that carry a special meaning:

Example 1

Sample data

Record 1	`clmHost*bmc`
Record 2	`clmHost bmc`

Search scenario 1

Search string	`clmHost*bmc`
Search results	No results found

Search scenario 2

Search string	`"clmHost*bmc"`
Search results	Returns the sample data records 1 and 2

Example 2

Record 1	`XY\|Z`
Record 2	`XY\|A`

Search scenario 1

Search string	`XY\|Z`
Search results	No results found

Search scenario 2

Search string	`"XY\|Z"`
Search results	Returns the sample data record 1.

Example 3

Sample data

Record 1	`"000`
Record 2	`000`

Search scenario 1

Search string	`"000`
Search results	No results found

Search scenario 2

Search string	`\"000`
Search results	Returns the sample data records 1 and 2.

Delimiters and their effect on search

When you perform a search, all special characters in your data act as delimiters. Delimiters are characters that separate text strings (letters and numbers) and mark the beginning or the end of a particular text string. The common delimiters are period (.), space ( ), comma (,), semicolon (;), pipe (|), underscore (_), slashes (/ \), and so on.

Delimiters affect the way your search works and which part of the data is highlighted.

The following table provides a list of search strings and their effect on the search results that are displayed, with the text highlighted in blue:

Search string	Result highlighted	Delimiters
`error and exception`	`error.and.exception`	Period (.)
`log*`	`logger appender logged` `logged_off` `log.bmc.logger`	Underscore (_) Period (.)
`log`	`log.bmc.logger`	Period (.)
`WIFI* && "192.168.81.100"`	`WIFIMacAddress, blocking 192.168.81.100` `WIFIINetAddress blocking 192.168.81.100` `wifi security policy applied on 192.168.81.100` `routing policy applied on WIFIaddress 192.168.81.100`	Period (.) Comma (,)
`"192.168.81.100"`	`routing 192 policy applied on 192.168.81.100`	Period (.)
`192.168.81.100`	`routing 192 policy applied on 192.168.81.100`	Period (.)

Syntax for searching the product metrics file

If you want to perform a search on the log files generated by the product (for the Collection Station and Search components), your search string must be in the following format:

_index=metrics searchCriteria

Example

_index=metrics engine=COLLECTION_STATION

For more information, see Monitoring the product metric files.

Search string syntax

Kinds of search string syntax

About phrases

Case-sensitive search and case-insensitive search

Search command chaining

Search string syntax samples

Special characters and their effect on search

Delimiters and their effect on search

Syntax for searching the product metrics file

Comments