Open topic with navigation

eval

Displays events after evaluating the result of the specified expression. The expression can be a mathematical, string, or Boolean operation and is evaluated when the query is run. The resulting value of the expression is assigned to a field name (specified in the expression). Once a new field has been defined by the eval operator in a query, this field can be used in the query for further refining the search results (see Example Three below, in which a new field “Plus” is defined by the eval operator; this field is then used by the sort operator.)

Synopsis

...|eval <type> <newField>=function([<field>|<value>]*)

Where:

<newField> is a derived field displayed in the search results.

<type> is the datatype of the new field and can be int, bigint, long, float or double. If you do not include a data type, the default is string. Including a <type> is optional; include when you need some data type other than string. For example, if you do not include a type, the sort will be alphabetical. If you want to sort numerically, make <type> one of the number data types. The datatype you specify should match the data that will be displayed in the <newField>, according to standard datatype definitions. The temporary field is not part of the Logger schema and its data type does not have to match the Logger schema data type of <field>.

<function> is one of these: abs(X), case(X,"Y",...), ceil(X), ceiling(X), exp(X), floor(X), if(X,Y,Z), isfalse(X), istrue(X), len(X), ln(X), log(X), lower(X), tolower(X), mod(x,y), rand(), replace(X,Y,Z), round(X), sqrt(X), substr(X,Y,Z), sum(x,y,z,…), trim(X), ltrim(X), rtrim(X), upper(X)toupper(X), urldecode(X).

Note: These functions are described in detail in the usage notes below.

<field> is the name of the field that you want to evaluate. It can be either an event field available in the Logger schema or a user-defined field created using the rex or eval operator earlier in the query.

<value> can be a string or a number.

Operators supported for eval expressions
Operation Symbol
Addition, Subtraction +, -
Multiplication, Division *, /
Boolean And, Or, Not &&, ||, !
Equal, Not Equal ==, !=
Less Than, Greater Than <, >
Less Than or Equal, Greater Than or Equal <=, >=
Modulus, Power %, ^
Unary Plus, Unary Minus +x, -x

Usage Notes

Typically, a cef or rex operator (to extract fields from matching events) precedes the eval operator, as shown in the examples below. However, you can use the eval operator on a field that has been defined by a previous eval operator in a query.

Keep the following in mind when working with eval functions:

Functions supported for eval operations
Function Description Example
abs(X) Takes a number, X, and returns its absolute value.

The function assigns the evaluated value to the new field. If the value of X is 3 or -3, the function assigns the evaluated value of 3 to the field absnum.

... | eval absnum=abs(number)

case(X,"Y",...)

Takes pairs of arguments, X and Y.

The X arguments are Boolean expressions that are evaluated from first to last. When case encounters the first X expression that evaluates to true, it returns the corresponding Y. Subsequent arguments are ignored. If none are true, it returns NULL.

The following example returns outcome =Success or outcome =Failure, depending on whether deviceCustomNumber1 is 200.

... | eval outcome=case(deviceCustomNumber1== 200, "Success", deviceCustomNumber1 != 200, "Failure")

ceil(X), ceiling(X) Rounds a number, X, up to the next highest integer.

The following example returns n=2.

... | eval n=ceil(1.9)

exp(X) Takes a number, X, and returns eX.

The following example returns y=e3.

... | eval y=exp(3)

floor(X) Rounds a number, X, down to the nearest whole integer.

The following example returns 1.

... | eval n=floor(1.9)

if(X,Y,Z) Takes three arguments. The first argument, X, must be a Boolean expression. If X evaluates to TRUE, the result is the second argument, Y. If, X evaluates to FALSE, the result evaluates to the third argument, Z.

The following example looks at the values of deviceCustomNumber1 and returns outcome=Succeeded if outcome=200, otherwise returns outcome=Failed.

... | eval outcome=if(deviceCustomNumber1 == 200, "Succeeded", "Failed")

isfalse(X)

Checks whether expression X is false. Returns true if expression X is false, otherwise returns false.

Note: If X > 0, results are false. If X <=0, results are true.

The following example returns true because 4+4 is not equal to 9.

... | eval newField = isfalse(4+4==9)

istrue(X)

Checks whether expression X is true. Returns true if expression X is true, otherwise returns false.

Note: If X > 0, results are true, If X <=0, results are false.

The following example returns true because 8 is greater than 0.

... | eval newField = istrue(8)

len(X)

Returns the character length of a string, X.

The following example returns the length of (field). If the field is 256 characters long, it returns n=256,

... | eval n=len(field)

The following example returns n=3. (abc is a literal string, surrounded by double quotes.)

... | eval n=len("abc")

ln(X) Takes a number, X, and returns its natural log.

The following example returns the natural log of the value of "bytes". If "bytes" contains 100, it returns 4.605170186.

... | eval lnBytes=ln(bytes)

log(X) Evaluates the log of number X with base 10.

The following example returns 4.

... | eval num=log(10000).

lower(X)
tolower(X)

Takes a string argument, X, and returns the lowercase version.

The following example returns the value of the field username in lowercase. If the username field contains FRED BROWN, it returns name=fred brown.

... | eval name=lower("username")

mod(X,Y) Returns the modulo of X and Y. (X%Y; the remainder of X divided by Y.)

The following example returns 5.

... | eval newField = mod(25,10)

rand() Returns a random number between 0 and 1, inclusively.

The following example might return a number like 0.56789.

... | eval newField = rand()

replace(X,Y,Z) Returns a string formed by substituting string Z for every occurrence of regex string Y in string X. The third argument, Z, can also reference groups that are matched in the regex.

The following example replaces instances of the value "ArcSight" with the value "Micro Focus" in the deviceVendor field.

... | eval n=replace(deviceVendor, "ArcSight", "Micro Focus")

round(X) Rounds X to the nearest integer.

The following example returns 1.

... | eval n=round(1.4)

The following example returns 2.

... | eval n=round(1.5)

sqrt(X) Takes one numeric argument, X, and returns its square root.

The following example returns 3.

... | eval n=sqrt(9)

substr(X,Y,Z)

This function returns a new string that is a substring of string X. The substring begins with the character at index Y and extends up to the character at index Z-1.

Note: The index is a number that indicates the location of the characters in string X, from left to right, starting with zero.

The following example returns "g".

...| eval n=substr("ArcSight",5,6)

The following example returns "cSig".
...| eval n=substr("ArcSight",2,6)

The following example returns "ght".
...| eval n=substr("ArcSight",5,8)

The following example returns "ArcSight".
...| eval n=substr("ArcSight",0,8)

The following example returns "Sight".
...| eval n=substr("ArcSight",3,8)

The following example returns "Arc".
...| eval n=substr("ArcSight",0,3)
sum(X,Y,Z,…) Adds all the numbers together.

The following example returns the sum of the values in the baseEventCount, deviceCustomNumber1, and deviceCustomNumber2 fields.

... | eval newnum = sum(baseEventCount, deviceCustomNumber1, deviceCustomNumber2)

trim(X)
ltrim(X)
rtrim(X)

trim(X) removes all spaces from both sides of the string X.

ltrim(X) removes all spaces from the left side of the string X.

rtrim(X) removes all spaces from the right side of the string X.

For the sake of the example, assume that X is a literal string and _ represents any number of space characters.

The following example returns trimmed=
"string_".
... | eval trimmed=ltrim("_string_")

The following example returns trimmed="_string".
... | eval trimmed=rtrim("_string_")

The following example returns "string".
... | eval trimmed=trim("_string_")
upper(X)
toupper(X)

Takes one string argument and returns the uppercase version.

The following example returns the value of the field username in uppercase. If username contains fred brown, it returns name=FRED BROWN.

... | eval name=upper("username")

urldecode(X) Takes one URL string argument X and returns the unescaped or decoded URL string.

The following example returns "https://www.microfocus.com/download?r=header".

... | eval n=urldecode("http%3A%2F%2Fwww.microfocus.com%2Fdownload%3Fr
%3Dheader")

If the Category Behavior is “Communicate”, then assign the value “communicate” to a new field “cat”; otherwise, assign the value “notCommunicate” to it.

_storageGroup IN [“Default Storage Group”] | cef categoryBehavior | eval cat=if(categoryBehavior== “/Communicate”, “communicate”, “notCommunicate”)

Append the word, “END”, at the end of extracted event name. For example, if event name is “Logger Internal Event”, after the eval operation it is “Logger Internal EventEND” and is assigned to a new field, “fullname”.

logger | cef msg name | eval fullname=name + “END”

Add 100 to the value of bytes In and assign it to a new field, “Plus”. Then, sort the values assigned to “Plus” in ascending order.

_storageGroup IN [“Default Storage Group”] | cef bytesIn bytesOut name | eval Plus=bytesIn +100 | sort Plus

Find the longest URLs from the vendor ArcSight. 

deviceVendor = ArcSight |eval (int)urllength=len(requestUrl) |sort urllength

Concept Link IconSee Also