Search command summary

This topic provides a summary of all search commands available with the product. You can use this information for reference purposes.

To save an offline copy of this page, download the Search command summary PDF.

For detailed information about the individual search commands, see Search commands.

Related topics

Search commands

Getting started with search

Search string syntax

chgname

This search command changes the name of one or more fields with new names that you specify. You can use this command to simplify your troubleshooting tasks by changing complex field names to meaningful names. By using this command, you can rename a given field or multiple fields. Multiple fields can be separated by using a comma (,) or a space.

Syntax

chgname <Source-Field> with <Target-Field>+

chgname <Source-Field> with "<Phrase>"+

In the preceding syntax, the following definitions apply:

+ indicates one or more similar expressions separated by a comma (,) or space.
<Source-Field> refers to the field that you want to rename.
<Target-Field> refers to the new field name with which you want to replace the existing field name.
"<Phrase>" refers to the phrase with which you want to replace the existing field name. You must enclose a phrase in double quotes (").

Examples

Example 1: Rename the COMPID field with ComponentID:

... | chgname COMPID with ComponentID

Example 2: Rename the COMPID field with the phrase Component ID:

... | chgname COMPID with "Component ID"

For more details, see the long example at chgname search command.

Back to top ↑

chgvalue

This search command replaces the value of a specified field (or field list) with new values. This command is useful when you have multiple fields with the same value and you want to change that value to a new value.

Syntax

chgvalue <Existing-String> with <New-String>

chgvalue <Existing-String> with <New-String> [in <Field-List>]+

In the preceding syntax, the following definitions apply:

+ indicates one or more similar expressions separated by a comma (,).
[Expression] indicates it is optional.
<Existing-String> refers to the existing value of the specified field or fields that you want to change.

<New-String> refers to the new value with which you want to replace the existing value. If the new string is a phrase, enclose it in double quotes (").
<Field-List> refers to a comma- or space-separated list of field names. If you do not specify a list of field names, by default the command replaces the value of all fields with the existing string.

Examples

Example 1: Replace a value with a new value in a single specified field:

... | chgvalue INFO with info in debuglevel

Example 2: Replace a value with a new value in multiple specified fields:

... | chgvalue INFO with info in debuglevel, errorlevel

Example 3: Replace multiple values of a field with more descriptive names in single specified fields:

... | chgvalue INFO with info , ERRROR with error in debuglevel

Example 4: Replace multiple values of a field with more descriptive names in multiple specified fields:

... | chgvalue INFO with info , ERRROR with error in debuglevel, errorlevel

Example 5: Replace multiple values with new values in all fields:

... | chgvalue INFO with info , ERRROR with error

Example 6: Replace a phrase value with a new value in a single specified field:

... | chgvalue "Error log " with error in debuglevel

For more details, see the long examples at chgvalue search command.

Back to top ↑

concat

This search command concatenates field values (or string values) and assigns the result to the target field that you specify. The string value can consist of a phrase containing non-alphanumeric characters (string literals) that you specify in double quotes ("), or a field name (source field) whose value must be used as the value of the target field. You can specify multiple fields separated by a space. You can also specify a combination of fields and phrases.

Syntax

concat <Source-Fields+> <Target-Field>

In the preceding syntax, the following definitions apply:

+ indicates one ore more similar expressions separated by a space.
<Source-Fields> refer to a list of fields or a combination of fields and phrases (enclosed in double quotes) to use for concatenating.
<target-Field> refers to the target field to which you want to assign the concatenated string of field values and specified phrases. This target field must always be defined after the list of source fields (or phrases).

Examples

Example 1: Create a target field, email address, that combines the value of the field username, the string "@" and value of the field host.

... | concat username "@" host "email address"

Example 2: Create a target field, address, that combines the HOST and port field values and the string ":" in the format <HOST>:<port>.

... | concat HOST ":" port address

Example 3: Create a target field, message, that combines the string "Request of type," the value of the field RequestType, the string "from client," the value of the field Client Ip, the string "to server," and the value of the field HOST.

... | concat "Request of type" RequestType "from client" ClientIp "to server" HOST 
message

For more details, see the long example at concat search command.

Back to top ↑

dedup

This search command removes data records that contain fields with duplicate values.

Records are removed based on the field names specified. Depending on the field name, the first instance(s) of the record(s) is kept, while the rest of the records are removed. You can specify a number (N) as the count of records (with duplicate field values) to be kept. For example, you can keep the first three records with the same value and remove the remaining duplicate records.

You can also see the number of duplicate records removed. This can be done by specifying the showDetails option. By doing this, the DuplicatesRemoved field is added to each record kept. The value of this field is a number that indicates the count of the records removed. Specifying the showDetails option is required for running the sortby and the multiple parameters.

If you want to sort the search results, then you can specify the sortby parameter based on a field. By default the sorting happens in a lexicographical order. If you want to sort the results based on a field with numeric values, then you also sort the results numerically.

If you want to further analyze your data to see values of another field in the removed records, then you can use the multiple parameter. This can help you see multiple values of the field for the records returned by the dedup command.

Syntax

dedup [N] [showDetails] <field>+ [sortby <sort-by-option>(<field>)] [multiple <field>]

In the preceding syntax, the following definitions apply:

N indicates a number that represents the count of records with duplicate field values to be kept. By default, this number is 1.
+ indicates one or more similar expressions separated by a space
[Expression] indicates it is optional.
showDetails indicates whether you want to know the number of duplicate records removed for each unique field value. If you specify this option, the DuplicatesRemoved field is added to each record.
<field> refers to field name on which you want to run this command or the field name on which you want to run the sortby or the multiple parameter.
sortby indicates an optional parameter that you can run on a field name. You can add this parameter to sort the search results based on the value of the field specified. You can use one of the following options for sorting the search results:
Option Description
num Sorts the search results in a numerical order.
str Sorts the search results in a lexicographical order.
Notes
- Even if you do not specify the str option and only specify the field name, by default the search results are sorted in a lexicographical order.
- This parameter can be used only when your command syntax uses the showDetails option.
multiple <field> indicates an optional parameter that you run on a field name to see the unique values of that field occurring in the records returned by running this command.
Note

This parameter can be used only when your command syntax uses the showDetails option.

Example

Example 1: Remove duplicate search results with the same ClientIp field value.

... | dedup ClientIp

Example 2: Remove duplicate search results containing the same values, for both the ClientIp and ResponseCode fields.

... | dedup ClientIp ResponseCode

Example 3: Remove duplicate search results with the same RequestType field value. Additionally, see the number of duplicate records removed and see the unique values of the ResponseSize field in the duplicate records removed.

... | dedup showDetails RequestType multiple ResponseSize

Example 4: Remove duplicate search results with the same RequestType field value. Additionally, see the number of duplicate records removed and sort the search results by the ResponseSize field in an ascending order.

... | dedup showDetails RequestType sortby num(ResponseSize)

For more details, see the long example at dedup search command.

Back to top ↑

difftime

This search command computes the difference between the current time stamp and the event time stamp and assigns the value to a new field called "difftime". This new field is a virtual field that provides an easy-to-read value such as "1 day ago," "2 minutes ago," "4 seconds ahead," and so on.

Syntax

difftime

Example

Example 1: Create a new difftime field that provides the difference between the current time stamp and the event time stamp.

... | difftime

For more details, see the long example at difftime search command.

Back to top ↑

eval

This search command evaluates an expression (a field name along with a specified function) and assigns the resulting value to a new field that you specify. When you specify a field, the product runs specified functions on the value of that field and then assigns the resulting value to a new field so that you can further analyze it.

You can perform the following functions:

Changing the case of a field value to lowercase or uppercase
Splitting the value of a field into multiple parts depending on the delimiters specified
Copying portions of a field value

Delimiters can be alphanumeric characters, special characters, or Java regular expressions. When you run the split function, the resulting values are assigned to the new field. Because fields with multiple values are displayed as a comma-separated list, the resulting values from a split function are also displayed as a comma-separated list.

You can also use the split function with a copy function (mvindex) in the command syntax, so that one of the values received by running the split function is copied to the new field.

You can copy portions (a range of values) by specifying a starting index and ending index so that a range of values is copied from the source field and assigned to the new field. The value of the index indicates the particular portion of the field value that must be copied. For example, if the source field has a list of five values and you specify the starting index as 0 and the ending index as 3, then a range of values from the first to the fourth portions is copied and assigned to the new field.

Syntax

eval <New-Field>=<Expression>

In the preceding syntax, the following definitions apply:

<New-Field> refers to the name of the new field to which you want to assign the value that was received as a result of running the specified function.

<Expression> refers to a combination of the specified function and the name of the source field on which you want to run the function.

The following table lists the functions supported:

Function	Syntax	Description
lower	`lower(<Source-Field>)`	Changes the case of the source field value to lowercase
`upper`	`upper(<Source-Field>)`	Changes the case of the source field value to uppercase
split	split(<Source-Field>, "<Delimiter>")	Splits the source field value depending on the delimiter specified. The delimiters can be alphanumeric characters, special characters or Java regular expressions and must always be enclosed in double quotes ("). Note: If you want to use special characters such as period (.) or asterisk (*) as a normal delimiter and not as a Java regular expression, you must use an escaping backslash character (\) before the special character.
mvindex	`mvindex(<Source-Field>, <Start-Index>[,<End-Index>])` where, [Expression] indicates it is optional	Copies portions of the source field value depending on the index specified. You can specify a starting index and an ending index so that a comma-separated range of values is copied from the source field and assigned to the new field. Specifying the ending index is optional. Index is a number starting from 0 to 9 (read from left to right) and -1 to -10 (read from right to left), indicating the portion of the field that must be copied. Zero indicates the first portion and -1 indicates the last portion. The end index must be greater than the start index.

Examples

Example 1: Create a new field, req_type_low with the value of the RequestType field that appears in lowercase.

... | eval req_type_low = lower(RequestType)

Example 2: Create a new field, host_name_up, with the value of the HOST field that appears in uppercase.

... | eval host_name_up = upper(HOST)

Example 3: Create a new field, broken_url, with the value of the RequestURL field such that the new field value shows as a list of values split by the delimiter "/".

... | eval broken_url=split(RequestURL, "/")

Example 4: Create a new field, broken_url, with the value of the RequestURL field split by the delimiter "/". After this, create a new field, resource_root, with the first portion (index 1) of the broken_url value.

... | eval broken_url=split(RequestURL, "/") | eval resource_root=mvindex(broken_url, 1)

Example 5: Create a new field, broken_url, with the value of the RequestURL field split by the delimiter "/" and then create a new field, resource_param, with the second-to-last portion of the broken_url value.

... | eval broken_url=split(RequestURL, "/") | eval resource_param=mvindex(broken_url, -2)

Example 6: Create a new field, broken_url, with the value of the RequestURL field split by the delimiter "/" and then create a new field, resource_params, with a range of values (third-to-last portion to the last portion) of the broken_url value.

... | eval broken_url=split(RequestURL, "/") 
| eval resource_params=mvindex(broken_url, -3,-1)

For more details, see the long examples at eval search command.

Back to top ↑

extract

This search command can be used to extract field values or raw event data that it then assigns to new fields by using the Java regular expression capturing groups. The extract command can be used to specify a regular expression in such a way that it matches the target field value (or raw event data) that you want to extract and then assigns the extracted values to the new fields specified. The regular expression specified must exactly match the field value (or raw event data) in the search results.

Syntax

extract field=[<Source-Field>] "<Regex-Expression>"

In the preceding syntax, the following definitions apply:

<Source-Field> refers to the source field name that you want to use to extract particular information. Specifying this information is optional. If you do not specify a field name, the raw event data is used to extract particular information.
<Regex-Expression> refers to the Java regular expression (capturing groups) that you want to specify. This expression must be a combination of the regular expression and the new field or fields to which you want to assign the extracted information. This expression must be enclosed in double quotes (").
[Expression] indicates it is optional.

Examples

Example 1: Extract the the log level data entry (example warning), and the corresponding component action data entry (example, VpxUtil_InvokeWithOpId) and assign the values to new fields, LogLevel and ComponentAction respectively.

... | extract field=".*?\[\d+\s+(?<LogLevel>\w+).*?\]\s+(?<ComponentAction>\w+).*"

Example 2: Extract two portions (host name and domain name) of the value of the HOST field and assign those values to two new fields, Hostname and Domainname.

... | extract field=HOST "(?<Hostname>[A-Za-z-]+)\.(?<Domainname>.+)"

For more details, see the long examples at extract search command.

Back to top ↑

extractkv

This search command extracts name=value pairs from raw event data depending on the delimiters specified. By default, name=value pairs are automatically extracted by the product, assuming the equals sign (=) as the separator. But when you run this command, name=value pairs are extracted depending on the options specified (kvdelim and pairdelim). Specifying these options is optional.

Note

If you run the command without specifying an option, even though the search results look unchanged, the name=value pairs are overridden and are displayed as virtual fields.

You can use this command to extract name=value pairs using other delimiters. A delimiter can be any character by which you extract name=value pairs (kvdelim) and name=value pair sets (pairdelim). You can use multiple characters as delimiters for extracting name=value pairs and name=value pair sets.

If you specify an option without its value, then by default a space ( ) is assumed as the delimiter for extracting name=value pair sets and the equals sign (=) is assumed as the delimiter for extracting name=value pairs. You can optionally limit the number of name=value pair sets to be extracted by using the limit parameter (the default is 50).

Syntax

extractkv [pairdelim="<Delimiters>"] [kvdelim="<Delimiters>"] [limit=<int>]

In the preceding syntax, the following definitions apply:

[Expression] indicates it is optional.
pairdelim="<Delimiters>" indicates the option for specifying the delimiters that separate name=value pair sets.
kvdelim="<Delimiters>" indicates the option for specifying the delimiters that separate name=value pairs.
limit=<int> indicates the integer value to use for limiting the number of name=value pairs and name=value pair sets.

Examples

Example 1: Extract name=value pairs where the name=value pair delimiter and name=value pair sets delimiter are set to default.

... | extractkv

Example 2: Extract name=value pair sets separated by pipe and semi-colon (|;), where the delimiter for pairdelim (name=value pair sets) and limit options are set to default.

... | extractkv pairdelim="|;"

Example 3: Extract name=value pairs separated by colon (:), where the delimiter for kvdelim option (name=value pairs) is set to default.

... | extractkv kvdelim=":"

Example 4: Extract a maximum of ten name=value pairs where the delimiter for kvdelim (name=value pairs) and the delimiter for pairdelim (name=value pair sets) are set to default.

... | extractkv limit=10

Example 5: Extract name=value pairs separated by colon and equals sign (:=) and name=value pair sets separated by comma and semi-colon (,;).

... | extractkv pairdelim=",;" kvdelim=":="

For more details, see the long examples at extractkv search command.

Back to top ↑

fields

This search command retains (+) or removes (-) fields from search results based on the field list specified.

This command uses the following conventions:

If you specify a plus sign (+), fields that match one of the fields specified in the command are retained.
If you specify a minus sign (-), fields that match one of the fields specified in the command are removed.
If you do not specify a plus (+) or a minus sign (-), the command assumes a plus sign (+).

Syntax

fields [+] <Field-List>

fields [-] <Field-List>

In the preceding syntax, the following definitions apply:

[expression] indicates it is optional.
<Field-List> refers to a comma-separated list of fields.

Examples

Example 1: Remove the fields destHost and ip from the search results.

... | fields - destHost, ip

Example 2: Remove the fields username, protocol, rfc931, and RequestURL from the search results.

... | fields - username, protocol, rfc931, RequestURL

Example 3: Retain the field RequestType and ResponseCode in the search results.

... | fields RequestType, ResponseCode

For more details, see the long examples at fields search command.

Back to top ↑

filter

This command displays search results that match the specified filter function.

Syntax

filter <filter-function>

In the preceding syntax, <filter-function> can be one of the functions described in the following table:

Function	Syntax	Description
isNotNull	isNotNull (<field>)	Uses the field name as an argument and returns true if the field specified is not null (the field exists). Note: This function is expected to be deprecated in a future release of the TrueSight IT Data Analytics product. If you are using this function in one of your saved searches, ensure that you update the saved searches and replace the `isNotNull` function with the `fieldexists` function.
fieldexists	fieldexists (<field>)	Uses the field name as an argument and returns true if the field specified is present in the data indexed. In other words, if the field specified exists in the data indexed, data containing the field is displayed as search results. On the other hand, if the field specified does not exist, no results are displayed.
match	match (<field>, "<string>")	Uses two arguments: the field name as the first argument and a quoted string as the second argument. Returns true if the field value matches the second argument value irrespective of case.
matchcase	`matchcase (<field>, "<string>")`	Uses two arguments: the field name as the first argument and a quoted string as the second argument. Returns true if the field value matches the exact argument value (case is important).
isNumeric	isNumeric (<field>)	Uses the field name as an argument and returns true if the field value is numeric. This function works only for numeric values stored as a string at the time of data-pattern creation.
greaterthan	greaterthan (<field>, "<numeric-value>")	Uses the field name as an argument and returns true if the field value is greater than the value specified.
lessthan	lessthan (<field>, "<numeric-value>")	Uses the field name as an argument and returns true if the field value is less than the value specified.
regex	`regex` `(<field>, "<regex>")`	Uses two arguments: the field name as the first argument and a quoted string (a Java regular expression) as the second argument. Returns true if the field value matches the second argument value.
where, `<field>` refers to the field name. `"<string>`" refers to a regular string literal enclosed in double quotes. `"<numeric-value>`" refers to a number enclosed in double quotes. `"<regex>`" refers to a Java regular expression enclosed in double quotes.

Examples

Example 1: Filter search results containing numeric values for the field ResponseCode.

... | filter isNumeric(ResponseCode)

Example 2: Filter search results that do not contain the field Thread.

... | filter fieldexists(Thread)

Example 3: Filter search results matching the field RequestType with the value GET in a case-insensitive way.

... | filter match(RequestType, "GET")

Example 4: Filter search results matching the field RequestType with the value GET in a case-sensitive way.

... | filter matchcase(RequestType, "GET")

Example 5: Filter search results to display the field RequestType with the value matching the regular expression "....".

... | filter regex(RequestType, "....")

Example 6: Filter search results for the field ResponseCode with a value greater than 400.

... | filter greaterThan(ResponseCode, "400")

Example 7: Filter search results for the field ResponseCode with a value less than 400.

... | filter lessThan(ResponseCode, "400")

For more details, see the long examples at filter search command.

Back to top ↑

group

This search command groups events depending on the group options (conditions) specified to create a transaction of events. This command can help you correlate event data based on specific fields and provide a single transaction entry containing related event data from multiple systems, tiers, and so on.

Syntax

group [<field-list>] <group-options>*

In the preceding syntax, the following definitions apply:

* indicates zero or more similar expressions.
[expression] indicates it is optional.
<field-list> refers to field names used for grouping the events into a single transaction. The field names can be separated by comma (,) or space.

<group-options> refers to the following group options to specify for creating the grouped transaction. These group options are used as conditions for distributing transaction entries.

Item	Syntax	Description
maxspan	`maxspan=<int>(<timescale>)?`	Maximum time span (in seconds, minutes, hours) for grouping the transaction event entries. Default: 600 seconds (10 minutes) with a maximum of 7200 seconds (2 hours)
maxpause	`maxpause=<int>(<timescale>)?`	Maximum interval (in seconds, minutes, hours) between the grouped transaction entries. Default: No limit, but cannot be greater than value of the maxspan option
maxevents	`maxevents=<int>`	Maximum number of entries in a transaction. Default: 100 with a maximum limit of 10,000 events
startswith	`startswith=<filter-string>`	Any string in the raw event data that must mark the start of the grouped transaction.
endswith	`endswith=<filter-string>`	Any string in the raw event data that must mark the end of the grouped transaction.
where, `?` indicates zero or more similar expressions `<int>` refers to an integer value `<timescale>` refers to a time scale such as seconds, minutes, or hours. You can use one of the following time scale options in the command syntax: Seconds: `s` \| `sec` \| `secs` \| `second` \| `seconds` Minutes: `m` \| `min` \| `mins` \| `minute` \| `minutes` Hours: `h` \| `hr` \| `hrs` \| `hour` \| `hours`

Examples

Example 1: Group events occurring in the span of a maximum of 2 minutes.

... | group maxspan=2m

Example 2: Group events occurring with a time gap of 1 minute but limited to a maximum of two event entries.

... | group maxpause=1m maxevents=2

Example 3: Group data entries with the same HOST field value and with no gaps of longer than 5 seconds between two entries.

...| group HOST maxpause=5s

Example 4: Group data entries with a unique combination of userid and sessionid fields. The first and last entries are within the 25-second time gap. All sessions tied with some user ID are also associated in related transactions and the user ID is not required to be present in such log entries.

...| group userid sessionid maxspan=25s

Example 5: Group data entries with the HOST field where the first entry contains signon and the last entry contains purchase. The startswith and endswith options mark the transaction boundary for log events.

...| group HOST startswith=signon endswith=purchase

Example 6: Create multiple groups based on a transaction that starts with the login entry and ends with the logout entry.

... | group startswith=login endswith=logout

For more details, see the long examples at group search command.

Back to top ↑

head

This search command provides the first N number of search results. When you run this command, the events that were indexed first (the earliest records) are displayed in ascending order. You can specify a limit in the syntax to return the maximum number (N) of search results. If you run this command without specifying a limit, by default the product returns the first 10 results.

Syntax

head n

OR

head limit=<integer>

In the preceding syntax, n or <integer> refers to an integer value that indicates the maximum number of records that you want to see.

Examples

Example 1: Return the first 10 records.

... | head

Example 2: Return the first 20 records.

... | head limit=20

Example 2: Return the first 2 records.

... | head 2

For more details, see the long example at head search command.

Back to top ↑

rare

This search command creates a table of statistics and a corresponding chart to display the least frequent values of a field. The command also supports the optional group by parameter to display the least frequent values for each distinct tuple of values of the group by field.

Syntax

rare limit=<int> <field> [by <field>]

In the preceding syntax, the following definitions apply:

[expression] indicates it is optional.
<int> refers to an integer value that represents the maximum number of results to return.
by <field> refers to the group by parameter that can be optionally used to group the result set by the specified field.

Examples

Example 1: Return the 10 least common values of the HOST field.

... | rare limit=10 HOST

Example 2: Return the least common data pattern values for each host.

... | rare limit=5 DATA_PATTERN by HOST

Example 3: Return the least common request type.

... | rare limit=1 RequestType

Example 4: Return the least common request type per client IP.

... | rare limit=1 RequestType by ClientIp

For more details, see the long examples at rare search command.

Back to top ↑

stats

This search command creates an aggregate representation of data in the form of a table of statistics and a corresponding chart based on the field or fields specified. The command also supports the optional group by parameter, to apply aggregate functions on the distinct value of a specified field. For example, you can plot the aggregate count of data occurring from a particular host depending on the data-collector names. Similarly, you can run other aggregate functions such as sum, avg, min, and max to find the sum, average, minimum (smallest), and maximum (highest) values of a field.

Additionally, you can perform the following functions:

Limit the number of results: You can limit the results displayed by using the limit parameter.
Sort the results: You can sort the results in an ascending or descending way based on one of the following options:
- One of the aggregate functions that you specify.
- The group by parameter that you specify.

This command is similar to the timechart command, except that it does not represent data on the basis of a specified time span; instead, it provides an aggregate representation.

Syntax

stats (<aggregate-function>)+

stats (<aggregate-function> [as <alias>])+

stats (<aggregate-function>)+ [by <field>]

stats (<aggregate-function> [as <alias>])+ [by <field>]

stats (<aggregate-function> [as <alias>])+ [by <field> [limit=<int>]]

stats (<aggregate-function> [as <alias>])+ [by <field> [sortby <option>]]

stats (<aggregate-function> [as <alias>])+ [by <field> [sortby <option>] 
[limit=<int>]]

In the preceding syntax, the following definitions apply:

+ indicates one or more similar expressions separated by a comma (,) or space.

<aggregate-function> refers to the aggregate function used for creating the chart; for example, count, sum, or average.

The following table describes the aggregate functions that can be used in the command syntax:

Function	Syntax	Description
Count	count (<field>)	Uses field name as an argument and returns the number of occurrences of that field in the search results.
Sum	sum (<field>)	Uses field name as an argument and returns the sum of values of that field in the search results.
Average	avg (<field>)	Uses field name as an argument and returns the average of values of that field in the search results.
Minimum	min (<field>)	Uses field name as an argument and returns the smallest value of that field in the search results.
Maximum	max (<field>)	Uses field name as an argument and returns the highest value of that field in the search results.
Standard deviation	`stddev (<field>)`	Uses field name as an argument and returns the standard deviation of the values of that field in the search results.
where, `<field>` can be a field name or a tag name

[as <alias>] refers to the as parameter used for optionally renaming a field with an alternate field name (an alias).
[by <field>] refers to a group by parameter that is optionally used in conjunction with the aggregate functions, to group the result set by the specified field.
[limit=<int>] refers to the limit parameter that can be optionally used to limit the number of results by the integer value specified. <int> refers to the integer value that represents the maximum number of results to return. This parameter must be used in conjunction with the aggregate functions and the by parameter. If you specify both the limit parameter and the sortby parameter, then you must specify the limit parameter only after the sortby parameter.
[sortby=<option>] refers to the sortby parameter that can be optionally used to sort the results displayed by using one of the following options:
- One of the aggregate functions that you specify.
- The group by parameter that you specify.
This parameter must be used in conjunction with the aggregate functions and the by parameter. By default, this parameter sorts results in the ascending order based on the by parameter field.
If you want to sort results in the ascending way, it is optional to specify ASC after specifying the sortby parameter. However, if you want to sort results in the descending way, you must specify DESC after specifying the sortby parameter.
The following table provides the syntax and examples for sorting results:
Sorting order Syntax Example
(Default) Ascending sortby=<option> ASC
sortby count(HOST) ASC
Descending sortby=<option> DESC
sortby count(HOST) DESC

Examples

Example 1: Return the number of occurrences of the RequestType field in the search results.

... | stats count(RequestType)

Example 2: Return the number of occurrences of the RequestType field grouped by the ClientIp field.

... | stats count(RequestType) by ClientIp

Example 3: Return the number of occurrences of the events field and the sum of the values of the bytes-read field in the search results.

... | stats count(events) as Count, sum(bytes-read) as Total

Example 4: Return the number of occurrences of the events field and the sum of the values of the bytes-read field, grouped by the HOST field.

... | stats count(events) as Count, sum(bytes-read) as Total by HOST

Example 5: Return the sum of values and the average of values of the ResponseSize field, grouped by the ClientIp field, and sorted by the aggregate function for average.

... | stats sum(ResponseSize), avg(ResponseSize) by ClientIp sortby avg(ResponseSize)

Example 6: Return the minimum (smallest), maximum (highest), average, and standard deviation of the ResponseSize field values, grouped by the ClientIp field.

... | stats min(ResponseSize), max(ResponseSize), avg(ResponseSize) 
stddev(ResponseSize) by ClientIp

Example 7: Return the average of values of the ResponseSize field, grouped by the ClientIp field, and limit the number of results to 1.

... | stats avg(ResponseSize) by ClientIp limit=1

For more details, see the long examples at stats search command.

Back to top ↑

table

This search command extracts fields from events with information in a tabular format. A new event is created for each table row. Field names are derived from the title row of the table. Optionally, you can specify a list of fields that you want to further extract and keep from the given list of all fields. You can also filter search results to keep records that match the specified filter criteria.

If you do not specify fields, all fields extracted are displayed. Furthermore, if you do not specify a filter criterion, all data extracted is displayed along with the extracted fields.

Syntax

table [fields <field-list>+] [filter <filter-criterion>+]

In the preceding syntax,the following definitions apply:

+ indicates one or more similar expressions separated by a comma (,) or space.
[expression] indicates it is optional.
<field-list> refers to a list of space-separated fields that you want to keep in the search results. This parameter is optional.
<filter-criterion> refers to a list of space-separated values (data entry) by which you want to filter, to show in the search results. This parameter is optional.

Examples

Example 1: Extract the column headings that appear in the raw data as fields and create a new data entry for each row.

... | table

Example 2: Extract the PID, USER, %CPU, and CMD fields.

... | table fields PID USER %CPU CMD

Example 3: Extract the PID, USER, %CPU, and CMD fields when they occur in rows that contain the "itda" raw-data entry.

... | table fields PID USER %CPU CMD filter itda

For more details, see the long examples at table search command.

Back to top ↑

tail

This search command provides the last N number of search results. When you run this command, the events that were indexed last (most recently) are displayed in ascending order.

You can specify a limit in the syntax to return the maximum number (N) of search results. If you run this command without specifying a limit, by default the product returns the first 10 results.

Syntax

tail N

OR

tail limit=<integer>

In the preceding syntax, N or <integer> refers to an integer value that indicates the maximum number of records that you want to see.

Examples

Example 1: Return the last 10 records.

... | tail

Example 2: Return the last 20 records.

... | tail limit=20

Example 2: Return the last 2 records.

... | tail 2

For more details, see the long example at tail search command.

Back to top ↑

timechart

This command creates a time-series representation of data in the form of a table of statistics and a corresponding chart based on the field or fields specified.

You can run this command with:

Time span in days, minutes, or hours
Aggregate functions such as count, sum, or average

The starting and ending points to create the chart are defined by the time range used before you run the command. The time span defined as a part of the command acts as a bucketing option to specify the number of buckets into which you want to divide the data to plot a data point.

You can perform advanced analysis by running this command to group data by a field so that each distinct value of the field acts as an additional grouping. For example, you can plot the count of data occurring from a particular host depending on the data-collector names for the time span specified.

Syntax

timechart span=<duration><timescale> <aggregate-function>+

timechart span=<duration><timescale> (<aggregate-function> [as <alias>])+

timechart span=<duration><timescale> (<aggregate-function> [as <alias>])+ [by <field>]

In the preceding syntax, the following definitions apply:

+ indicates one or more similar expressions separated by a comma (,) or space.
[expression] indicates it is optional.
<duration> refers to an integer value to indicate the time-span bucket.
<timescale> refers to a time scale such as days, hours, or minutes.
The following table describes the time scale options that can be used in the command syntax:
Item Syntax
Minutes m | min | mins | minute | minutes
Hours h | hr | hrs | hour | hours
Days d | day | days

<aggregate-function> refers to the aggregate function used for creating the chart; for example, count, sum, or average.

The following table describes the aggregate functions that can be used in the command syntax:

Function	Syntax	Description
Count	count (<field>)	Uses field name as an argument and returns the number of occurrences of that field in the search results.
Sum	sum (<field>)	Uses field name as an argument and returns the sum of values of that field in the search results.
Average	avg (<field>)	Uses field name as an argument and returns the average of values of that field in the search results.
Minimum	min (<field>)	Uses field name as an argument and returns the smallest value of that field in the search results.
Maximum	max (<field>)	Uses field name as an argument and returns the highest value of that field in the search results.
Standard deviation	`stddev (<field>)`	Uses field name as an argument and returns the standard deviation of the values of that field in the search results.
where, `<field>` can be a field name or a tag name.

[as <alias>] refers to the as parameter used for optionally renaming a field with an alternate field name (an alias).
by <field> refers to the group by parameter optionally used in conjunction with the aggregate functions to group the result set by the specified field.

Examples

Example 1: Display a table of statistics (and a multiseries chart) displaying an aggregation of the distinct HOST field values against each day.

... | timechart span=1d count(HOST) by HOST

Example 2: Display a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour.

... | timechart span=1hr count(RequestType)

Example 3: Display a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour and grouped by the ClientIp field. Also, rename the field RequestType to NumberOfRequestTypes.

... | timechart span=1hr count(RequestType) as NumberOfRequestTypes by ClientIp

Example 4: Display a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour, plus a sum and average of the ResponseSize field values.

... | timechart span=1hr count(RequestType), sum(ResponseSize), avg(ResponseSize)

Example 5: Display a table of statistics (and a multiseries chart) displaying an aggregation of the RequestType field values that occurred in the span of 1 hour, plus the sum and average of the ResponseSize field values, grouped by the ClientIP field.

... | timechart span=1hr count(RequestType), sum(ResponseSize), avg(ResponseSize) by ClientIp

Example 6: Display the minimum (smallest), maximum (highest), average, and standard deviation of the ResponseSize field values, grouped by the ClientIp field.

... | timechart span=1h min(ResponseSize), max(ResponseSize), avg(ResponseSize), 
stddev(ResponseSize) by ClientIp

Example 7: Display the minimum (smallest), maximum (highest), average, and standard deviation of the ResponseSize field values.

... | timechart span=1h min(ResponseSize), max(ResponseSize), avg(ResponseSize), 
stddev(ResponseSize)

For more details, see the long examples at timechart search command.

Back to top ↑

top

This search command creates a table of statistics and a corresponding chart to display the most frequent values of a field. The command also supports the optional group by parameter to display the most frequent values for each distinct tuple of values of the group by field.

Syntax

top limit=<int> <field> [by <field>]

In the preceding syntax,the following definitions apply:

[expression] indicates it is optional.
<int> refers to an integer value that represents the maximum number of results to return.
by <field> refers to the group by parameter that can be optionally used to group the result set by the specified field.

Examples

Example 1: Return the 10 most common values of the HOST field.

... | top limit=10 HOST

Example 2: Return the most common data-pattern values for each host.

... | top limit=5 DATA_PATTERN by HOST

Example 3: Return the most common request types based on the client IP address.

... | top limit=5 RequestType by ClientIp

Example 4: Return the most common request type.

... | top limit=1 RequestType

For more details, see the long examples at top search command.

Back to top ↑

valmap

This search command classifies numeric field values with a specified category name depending on the range specified. This command adds a new field, range, that is assigned the category name if the numeric values fall in the specified range.

The ranges that you specify can overlap. If you have overlapping values, all relevant categories are displayed as the value of the range field. For example, if light=1-12, heavy=7-15, and the input field value specified in the search command is 10, then range=light,heavy.

You can also categorize a value if it does not fall into the range specified by using the default parameter.

Syntax

valmap field=<fieldName> (<CategoryName1>=<StartingRange>-<EndingRange>)+ [default=<string>]

In the preceding syntax, the following definitions apply:

+ indicates one or more similar expressions separated by a space ( ).
[expression] indicates it is optional.

<fieldName> refers to the field (with numeric value) to be used for categorizing the value.
<CategoryName1> refers to the category name that you want to display as the value of the range field when the range criteria is met. The range field is newly added when you run this command.
<StartingRange> refers to the starting integer value in the range.
<EndingRange> refers to the ending integer value in the range.
[default=<DefaultCategory>] refers to the default category. If the field value does not fall in the specified range, then you can replace the value of the range field with the specified (default) category name.

Examples

Example 1: Depending on the value of the ResponseSize field, assign the following categories:

light_load: If the value is between 100-149.
mid_load: If the value is between 150-199.
heavy_load: If the value is between 200-400.

... | valmap field=ResponseSize light_load=100-149 mid_load=150-199 heavy_load=200-400

Example 2: Depending on the value of the ResponseSize field, assign the following categories:

light_load: If the value is between 100-129.
mid_load: If the value is between 130-159.
heavy_load: If the value is between 160-199.
unknown_load: If no range matches (for example, if ResponseSize=10).

... | valmap field=ResponseSize light_load=100-129 mid_load=130-159 heavy_load=160-199 
default=unknown_load

Example 3: Depending on the value of the ResponseSize field, assign the following categories:

light_load: If the value is between 100-200.
mid_load: If the value is between 150-300.
heavy_load: If the value is between 300-400.

... | valmap field=ResponseSize light_load=100-200 mid_load=150-300 heavy_load=300-400

For more details, see the long example at valmap search command.

Back to top ↑

Option	Description
`num`	Sorts the search results in a numerical order.
`str`	Sorts the search results in a lexicographical order.

Sorting order	Syntax	Example
(Default) Ascending	`sortby=<option> ASC`	sortby count(HOST) ASC
Descending	`sortby=<option> DESC`	sortby count(HOST) DESC

Item	Syntax
Minutes	`m` \| `min` \| `mins` \| `minute` \| `minutes`
Hours	`h` \| `hr` \| `hrs` \| `hour` \| `hours`
Days	`d` \| `day` \| `days`

Search command summary

chgname

Syntax

Examples

chgvalue

Syntax

Examples

concat

Syntax

Examples

dedup

Syntax

Example

difftime

Syntax

Example

eval

Syntax

Examples

extract

Syntax

Examples

extractkv

Syntax

Examples

fields

Syntax

Examples

filter

Syntax

Examples

group

Syntax

Examples

head

Syntax

Examples

rare

Syntax

Examples

stats

Syntax

Examples

table

Syntax

Examples

tail

Syntax

Examples

timechart

Syntax

Examples

top

Syntax

Examples

valmap

Syntax

Examples

Comments