where

Description

The where command uses eval expressions to filter search results. The search keeps only the results for which the evaluation was successful (that is, the Boolean result was true).

Syntax

where <eval-expression>

Required arguments

eval-expression

Syntax: <eval-mathematical-expression> | <eval-concatenate-expression> | <eval-comparison-expression> | <eval-boolean-expression> | <eval-function-call>

Description: A combination of values, variables, operators, and functions that represent the value of your destination field. See Usage.

The syntax of the eval expression is checked before running the search, and an exception is thrown for an invalid expression.

The following table describes characteristics of eval expressions that require special handling.

Expression characteristics	Description	Example
Boolean results	The result of the eval expression cannot be boolean. If the expression cannot be successfully evaluated for a particular event at search-time, eval erases the value in the result field.
Field names starting with numeric characters	If the expression references a field name that starts with a numeric character, the field name must be surrounded by single quotation marks.	'5minutes'="late"
Field names with non-alphanumeric characters	If the expression references a field name that contains non-alphanumeric characters, the field name must be surrounded by single quotation marks.	new=count+'server-1'
Literal strings with non-alphanumeric characters	If the expression references a literal string that contains non-alphanumeric characters, the string must be surrounded by double quotation marks.	new="server-"+count

Usage

The where command uses the same expression syntax as the eval command. Also, both commands interpret quoted strings as literals. If the string is not quoted, it is treated as a field name. Because of this, you can use the where command to compare two different fields, which you cannot use the search command to do.

Functions

You can use a wide range of functions with the where command. For general information about using functions, see Evaluation functions.

The following table lists the supported functions by type of function. Use the links in the table to learn more about each function, and to see examples.

Type of function	Supported functions and syntax
Comparison and Conditional functions	case(X,"Y",...) cidrmatch("X",Y) coalesce(X,...) false()	if(X,Y,Z) like(TEXT, PATTERN) match(SUBJECT, "REGEX") null()	nullif(X,Y) searchmatch(X) true() validate(X,Y,...)
Conversion functions	tonumber(NUMSTR,BASE)	tostring(X,Y)
Cryptographic functions	md5(X) sha1(X)	sha256(X)	sha512(X)
Date and Time functions	now() relative_time(X,Y)	strftime(X,Y) strptime(X,Y)	time()
Informational functions	isbool(X) isint(X) isnotnull(X)	isnull(X) isnum(X)	isstr(X) typeof(X)
Mathematical functions	abs(X) ceiling(X) exact(X) exp(X)	floor(X) ln(X) log(X,Y) pi()	pow(X,Y) round(X,Y) sigfig(X) sqrt(X)
Multivalue eval functions	commands(X) mvappend(X,...) mvcount(MVFIELD) mvdedup(X)	mvfilter(X) mvfind(MVFIELD,"REGEX") mvindex(MVFIELD,STARTINDEX,ENDINDEX) mvjoin(MVFIELD,STR)	mvrange(X,Y,Z) mvsort(X) mvzip(X,Y,"Z")
Statistical eval functions	max(X,...)	min(X,...)	random()
Text functions	len(X) lower(X) ltrim(X,Y) replace(X,Y,Z)	rtrim(X,Y) spath(X,Y) split(X,"Y") substr(X,Y,Z)	trim(X,Y) upper(X) urldecode(X)
Trigonometry and Hyperbolic functions	acos(X) acosh(X) asin(X) asinh(X) atan(X)	atan2(X,Y) atanh(X) cos(X) cosh(X) hypot(X,Y)	sin(X) sinh(X) tan(X) tanh(X)

Examples

1. Use the where command to match IP addresses or a subnet

Return "CheckPoint" events that match the IP or is in the specified subnet.

host="CheckPoint" | where like(src, "10.9.165.%") OR cidrmatch("10.9.165.0/25", dst)

2. Use the where command to specify a calculation

Return "physicsjobs" events with a speed is greater than 100.

sourcetype=physicsjobs | where distance/time > 100

See also

eval, search, regex

Answers

Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the where command.