Understand Eval Functions

Eval allows you to define and name an expression that is returned in the search. To build an eval expression, you can use the following functions:

• Comparison and Conditional Functions
• Cryptographic Function
• Informational Function
• Statistical Functions
• Text Functions

For more information about other operators, functions, and syntax requirements, see eval.

Comparison and Conditional Functions

coalesce(X, [Y, Z, N, ...])

• Returns the value of the first non-null expression in the list. If all expressions evaluate to null, then coalesce returns null. The list is up to 20 elements long.

• In the list of expressions, all elements must be of same type.

• Parameters are the values used in the test.

• The only supported types are numeric and string. X can be a number, field or expression.

Example

... | eval username = coalesce (Source Username, Destination Username)
Returns: Username

nullif(X,Y)

• Compares two expressions. If the expressions are not equal, the function returns the first expression (expression1). If the expressions are equal, the function returns null.

• X and Y can be a number, field or expression. Y must have same data type that X

Example

... | eval newField = nullif(2, 3)
Returns: 2
... | eval newField = nullif(2, 2)
Returns: null

Cryptographic Function

md5(X)

• Calculates the MD5 hash of string, returning the result as a string in hexadecimal.

• X must be a string.

Example

... | eval usermd5 = md5 (Destination Username)
Returns: 202cb962ac59075b964b07152d234b70

Informational Function

isnull(X)

• Returns true if the X is null otherwise returns false.

Example

... | eval newField = isnull(2)
Returns: false

Statistical Functions

greatest(X,Y[,Z,N, ...])

• Returns the largest value in a list of expressions. The list is up to 20 elements long.

• In the list of expressions all elements must be of same type.

• The only supported types are numeric and string. X can be a number, field or expression.

Examples

... | eval newField = greatest(7, 5, 9)
Returns: 9

... | eval newField = greatest('sit', 'site', 'sight')
Returns: site

... | eval newField = greatest(bytesIn, 100)
Returns: 100, when bytesIn is less than 100

least(X,Y[,Z,N, ...])

• Returns the smallest value in a list of expressions. The list is up to 20 elements long.

• In the list of expressions all elements must be of same type.

• The only supported types are numeric and string. X can be a number, field or expression.

Examples

.. | eval newField = least(bytesIn, bytesOut)
Returns: 5

... | eval newField = least('sit', 'site', 'sight')
Returns: sight

... | eval newField = least(bytesIn, 100)
Returns: 100, when bytesIn is greater than 100

randomint(X)

• Returns a random number between 0 and X-1.

• X can be any positive integer between the values 1 and 9,223,372,036,854,775,807.

Example

... | eval newField = randomint(10)
Returns: a random number between 0 and 9

Text Functions

length(X)

• Returns the character length of a string, X.

Examples

... | eval n=length(field)
Returns: the length of (field). If the field is 256 characters long, it returns n=256.

... | eval n=length(“abc”)
Returns: n=3 (abc is a literal string, surrounded by double quotes)

lower(X)

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

Example

... | eval name=lower("USERNAME" )
... | eval name=tolower("USERNAME" )
Returns: the value of the field username in lowercase. If the username field contains FRED BROWN, it returns name=fredbrown.

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.

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

• Y can be negative.

• Z cannot be negative.

Examples

...| eval n=substr("ArcSight", 5, 6)
Returns: “g”

...| eval n=substr("ArcSight", 2, 6)
Returns: “cSig”

...| eval n=substr("ArcSight", 0, 3)
Returns: “Arc”

trim(X)

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

ltrim(X)

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

rtrim(X)

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

Examples

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

... | eval trimmed=ltrim(“_string_”)
Returns: trimmed=“string_”

... | eval trimmed=rtrim(“_string_”)
Returns: trimmed=“_string”

... | eval trimmed=trim(“_string_”)
Returns: “string”

upper(X)

• Takes one string argument and returns the uppercase version.

Example

... | eval name=upper(“username”)
... | eval name=toupper(“username”)
Returns: the value of the field username in uppercase. If username contains fred brown, it returns name=FRED BROWN.