Understand Eval Functions

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

• Comparison and Conditional Functions
• Boolean 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.

  ... | 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.
  

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

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

Boolean Functions

and (&&), or (||), not (|), and like

• Results of boolean expressions are binary, meaning they satisfy conditions that are true/false, etc.

• You can connect and nest keywords. For example, (boolean_check_a) and (boolean_check_b).

• Use parentheses to group boolean operations.

• Each parenthesis should only do one binary "and/or" operation.

• Do not use more two boolean operators to connect keyword clauses. Instead, use parentheses to nest clauses. For example:

  Not allowed: (boolean_check_a) and (boolean_check_b) and (boolean_check_c)

  Allowed: ((boolean_check_a) and (boolean_check_b)) and (boolean_check_c)

  | eval test_auto = (Agent Severity equals 4) and (Agent Severity equals 0)

  | eval test_auto = (( Agent Severity equals 4 ) and ( Agent Severity equals 0 )) and ( Agent Severity equals 2 )

  Cryptographic Function

  md5(X)

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

• X must be a string.

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

  The md5(X) function is not supported in a FIPS environment.

Informational Function

isnull(X)

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

  ... | 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.

  ... | 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.

  .. | 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.

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

Text Functions

length(X)

• Returns the character length of a string, X.

  ... | 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.

  ... | 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.

  ...| 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.

  For the sake of these following 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.

  ... | 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.

 

For more information about syntax requirements that the query must meet, see Understand the Query Syntax.