len ↗

Use the len() function to return the number of characters contained in a specified string.

Syntax

len (<string>)

Parameters

Name Type Required Description
<string> string Yes The string field or literal you want to evaluate.

Returns

The len() function returns an integer representing the count of characters.

Usage notes

  • If the input string is empty (""), len() will return 0.
  • If a NULL value is passed to len(), the function will return NULL.
  • This function is typically used within the alter stage to create new fields or modify existing ones by calculating string lengths.
  • The function can also be used in filter stages to narrow down results based on string length.

Examples

Example 1: Calculating the length of an existing string field

Goal: Calculate the character count of an existing string field.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter description_length = len(event_description)
| fields event_id, event_description, description_length
| limit 3

Explanation: This query creates a new field, description_length, by calculating the character count of each event_description.

Output:

EVENT_ID EVENT_DESCRIPTION DESCRIPTION_LENGTH
101 "User login successful" 23
102 "File access attempt" 20
103 "Network connection established" 30

Example 2: Calculating the length of a literal string

Goal: Calculate the length of a direct string literal provided in the query.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter literal_length = len("Palo Alto Networks")
| fields event_id, literal_length
| limit 3

Explanation: This query adds a new field, literal_length, which contains the constant length of the string "Palo Alto Networks" (18 characters, including spaces).

Output:

EVENT_ID LITERAL_LENGTH
101 18
102 18
103 18

Example 3: Calculating the length of a string derived from a numerical field

Goal: Calculate the length of a numerical field by first converting it to a string.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter event_id_string = to_string(event_id)
| alter id_string_length = len(event_id_string)
| fields event_id, event_id_string, id_string_length
| limit 3

Explanation: This query first converts the numerical event_id to its string representation (for example, 101 becomes "101") and then calculates the length of that string.

Output:

EVENT_ID EVENT_ID_STRING ID_STRING_LENGTH
101 "101" 3
102 "102" 3
103 "103" 3

Example 4: Calculating the length of a string extracted from JSON data

Goal: Extract a string value from a JSON field and calculate its length.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter status_string = simple_json_data -> status
| alter status_length = len(status_string)
| fields event_id, simple_json_data, status_string, status_length
| limit 3

Explanation: This query extracts the status value from simple_json_data as a string and then finds its length. For event_id 103, because simple_json_data does not contain a status key, status_string becomes NULL, and subsequently, status_length also becomes NULL.

Output:

EVENT_ID SIMPLE_JSON_DATA STATUS_STRING STATUS_LENGTH
101 {"status": "ok", "code": 200} "ok" 2
102 {"status": "fail", "error": "access_denied"} "fail" 4
103 {"connection_id": "CONN-001", "protocol": "TCP"} NULL NULL

Example 5: Handling empty strings and NULL values

Goal: Demonstrate the behavior of the function with empty strings and NULL inputs.

XQL code:

config timeframe = 1d
| dataset = sample_xql_raw
| alter empty_string_test = ""
| alter empty_string_length = len(empty_string_test)
| alter dst_domain_length = len(dst_domain)
| fields event_id, empty_string_test, empty_string_length, dst_domain, dst_domain_length
| limit 5

Explanation: For all events, empty_string_test is an empty string, so empty_string_length is 0. For event_id 105, dst_domain is NULL, resulting in dst_domain_length also being NULL. For other events with non-NULL dst_domain, their respective string lengths are calculated.

Output:

EVENT_ID EMPTY_STRING_TEST EMPTY_STRING_LENGTH DST_DOMAIN DST_DOMAIN_LENGTH
101 "" 0 "ec2.amazonaws.com" 19
102 "" 0 "sts.amazonaws.com" 19
103 "" 0 "www.google.com" 14
104 "" 0 "dropbox.com" 11
105 "" 0 NULL NULL