String manipulation

concat(values)

Combines string values. This function accepts a variable number of arguments.

Function Input

values: collection<string>

Function Output

string

1. SPL2 example

Returns Jane A Smith in the host field.

When working in the SPL View, you can write the function by using the following syntax.

...| eval host=concat("Jane", " ", "A", " ", "Smith");

2. SPL2 example

Prepends "asa_" to the value of "source_type".

When working in the SPL View, you can write the function by using the following syntax.

...| eval source_type=concat("asa_", "source_type");

3. SPL2 example

Alternatively, you can use named arguments.

...| eval host=concat(values: ["Jane", " ", "A", " ", "Smith"]);

extract_grok(input, pattern)

Extracts matching groups with a Grok-compatible pattern and returns a map of group names to matching groups when the pattern is matched against the input. It returns null if the input is null or the pattern is invalid.

Function Input

input: string

pattern: string

Function Output

map<string, string>

SPL2 examples

Returns "IPV4": "10.10.10.10" in ip_address.

When working in the SPL View, you can write the function by using the following syntax.

... | eval ip_address=extract_grok("FOO 10.10.10.10 BAR", "%{IPV4}");

Alternatively, you can use named arguments to list the arguments in any order.

... | eval ip_address=extract_grok(pattern: "%{IPV4}", input: "FOO 10.10.10.10 BAR");

extract_key_value(input, key_value_delimiter, pair_delimiter)

Extracts the key-value pairs and returns a map of the key-value pairs. The keys and values are separated with a key value delimiter, and pairs are separated with a pair delimiter. It returns null if the input is null or the key value delimiter is null or empty.

Function Input

input: string

key_value_delimiter: string

pair_delimiter: string

Function Output

map<string, string>

1. SPL2 example

Returns {"key1":"value1","key2":"value2","key3":"value3"}.

When working in the SPL View, you can write the function by using the following syntax.

| eval n=extract_key_value("key1=value1;key2=value2;key3=value3", "=", ";");

2. SPL2 example

Extracts key-value pairs from body.

When working in the SPL View, you can write the function by using the following syntax.

...| eval extracted_body=extract_key_value(cast(body, "string"), "=", " ");

3. SPL2 example

Alternatively, you can use named arguments to list the arguments in any order.

| eval n=extract_key_value(key_value_delimiter: "=", pair_delimiter: ";", input: "key1=value1;key2=value2;key3=value3");

extract_regex(input, pattern)

Extracts capturing groups from inputs with regular expressions and returns a map of all extracted, matched fields in the format: {"capture_group_1": "matching_expression_1", "capture_group_N":"matching_expression_N"}. If you do not name the capturing group, the group names are returned as "1", "2", "3", "N", etc. For example, extract_regex with the regex (?<host>[^\.]+) returns a map with the key host whose value is the value of the extracted capture group. For a non-named capture group, extract_regex with the regex ([^\.]+) will return a map with key 1 whose value is the value of the extracted capture group. To name your capturing group, start your regular expression pattern with ?<capturing-group-name>, as shown in the SPL2 examples. Use this function if you want your extracted data to be nested in a single field.

Function Input

input: string

pattern: regular expression pattern

Function Output

map<string, string>

1. SPL2 example

Extracts ASA-x-xxxxxx values from the body field using a named capturing group.

When working in the SPL View, you can write the function by using the following syntax.

...| eval asa=extract_regex(cast(body, "string"), /(?<ASA>ASA-\d-\d{6})/i);

2. SPL2 example

Extracts a six digit number from value and places that value in the field numbers.

When working in the SPL View, you can write the function by using the following syntax.

...| select extract_regex(to_string(value), /\d{6}/) AS numbers;

3. SPL2 example

Alternatively, you can use named arguments to list the arguments in any order.

...| eval asa=extract_regex(pattern: /(?<ASA>ASA-\d-\d{6})/i, input: cast(body, "string"));

len(str)

Returns the character length of a string str.

Function Input

str: string

Function Output

integer

SPL2 examples

Filters records by source character limit.

When working in the SPL View, you can write the function by using the following syntax.

...| where 6=len(source);

Alternatively, you can use named arguments.

...| where 6=len(str: source);

lower(str)

Converts a string to lowercase.

Function Input

str: string

Function Output

string

SPL2 examples

Filters records by source bar.

When working in the SPL View, you can write the function by using the following syntax.

...| where source=lower("BAR");

Alternatively, you can use named arguments.

...| where source=lower(str: "BAR");

ltrim(str, strip_chars)

This function takes two arguments. The required argument is str, a string. This function also takes an optional argument strip_chars, also a string. This function returns either str with whitespaces removed from the left side or str with the characters in strip_chars trimmed from the left side.

Function Input

str: string

(Optional) strip_chars: string

Function Output

string

1. SPL2 example

Returns "abcZZ ".

When working in the SPL View, you can write the function by using the following syntax.

...| eval n=ltrim(" ZZZZabcZZ ", " Z");

2. SPL2 example

Returns "abc ".

When working in the SPL View, you can write the function by using the following syntax.

...| eval n=ltrim(" abc ");

3. SPL2 example

Alternatively, you can use named arguments to list the arguments in any order.

...| eval n=ltrim(strip_chars: " Z", str: " ZZZZabcZZ ");

match_regex(input, pattern)

Checks if a string field contains a specified string using a regular expression pattern. Since this function takes a regular expression as input, you need to enclose the pattern argument in /. Returns true if the regular expression finds a match in the input string, otherwise returns false.

If you want to do a string match and your input contains a lot of special characters that require special escaping, consider using the match_wildcard function instead.

The match_regex function does a substring match by default. In order to do a full string match, you must use the regular expression anchors ^ and $.

Function Input

input: string

pattern: regular expression

Function Output

boolean

1. SPL2 example

Filters records that contain an ASA number in body.

When working in the SPL View, you can write the function by using the following syntax.

...| where match_regex(cast(body, "string"), /%ASA-\d-\d{6}/);

Alternatively, you can use named arguments to list the arguments in any order.

...| where match_regex(pattern: /%ASA-\d-\d{6}/, input: cast(body, "string"));

2. SPL2 example

Assume that your data contains abc and abbbbbc. Returns true for abc but not abbbbc.

When working in the SPL View, you can write the function by using the following syntax.

...| eval n = match_regex(cast(body, "string"), /a.c/); 

3. SPL2 example

Returns true.

When working in the SPL View, you can write the function by using the following syntax.

... | eval n = match_regex("myPay", /Pay/);

4. SPL2 example

Returns false.

When working in the SPL View, you can write the function by using the following syntax.

... | eval n = match_regex("myPay", /^Pay/);

match_wildcard(input, pattern)

Checks if a string field contains a specified substring without using regular expressions, except for the wildcard character *. Returns true if the substring has been found, otherwise returns false.

The match_wildcard function is a convenience function for the commonly used regular expression pattern .*. When you use match_wildcard, characters aside from * that are normally considered to be special characters in a regular expression are automatically escaped. Therefore, use match_wildcard when your input has a large number of special characters that would normally need special escaping.

The match_wildcard function always does a substring match. If you want to do a full string match, use match_regex with anchors instead.

Function Input

input: string

pattern: string

Function Output

boolean

1. SPL2 example

Returns true in sensitive_info when Credit is anywhere in the body field.

When working in the SPL View, you can write the function by using the following syntax.

...| eval sensitive_info=match_wildcard(cast(body, "string"), "Credit");

Alternatively, you can use named arguments to list the arguments in any order.

...| eval sensitive_info=match_wildcard(pattern: "Credit", input: cast(body, "string"));

2. SPL2 example

Assume that your data contains abc and abbbbbc. Returns true for both abc and abbbbc.

When working in the SPL View, you can write the function by using the following syntax.

... | eval n=match_wildcard(cast(body, "string"), a*c);

3. SPL2 example

Returns true when the strings switched from...to... are found in the body field.

When working in the SPL View, you can write the function by using the following syntax.

...| eval n=match_wildcard(cast(body, "string"), "switched from * to *");

4. SPL2 example

Returns false, because the anchor ^ and pattern \\d are treated as the literal string characters ^ and \d. Note that the backslash character \ is a special character in SPL2, and therefore needs to be explicitly escaped in order for the pipeline to validate.

When working in the SPL View, you can write the function by using the following syntax.

... | eval n=match_wildcard("event5", "^event\\d");

replace(str, pattern, rep)

This function returns a string formed by substituting string rep for every occurrence of regex string pattern in string str. The third argument rep can also reference groups that are matched in the regex.

Function Input

str: string

pattern: regular expression pattern

rep: string

Function Output

string

1. SPL2 example

Returns the body field with phone numbers redacted.

When working in the SPL View, you can write the function by using the following syntax.

...| eval body=replace(cast(body, "string"), /[0-9]{3}[-.][0-9]{3}[-.][0-9]{4}/, "<redacted>");

2. SPL2 example

This example uses a capture group to format the replacement string. The result "foobar" is placed in a new top-level field called newfield.

When working in the SPL View, you can write the function by using the following syntax.

... | eval newfield=replace("bar", /(bar)/, "foo$1");

3. SPL2 example

Alternatively, you can use named arguments to list the arguments in any order.

...| eval body=replace(str: cast(body, "string"), rep: "<redacted>", pattern: /[0-9]{3}[-.][0-9]{3}[-.][0-9]{4}/);

rtrim(str, strip_chars)

This function takes two arguments. The required argument is str, a string. This function also takes an optional argument strip_chars, also a string. This function returns either str with whitespaces removed from the right side or str with the characters in strip_chars trimmed from the right side.

Function Input

str: string

(Optional) strip-chars: string

Function Output

string

1. SPL2 example

Returns " ZZZZabc".

When working in the SPL View, you can write the function by using the following syntax.

... | eval n=rtrim(" ZZZZabcZZ", " Z");

2. SPL2 example

Returns " abc".

When working in the SPL View, you can write the function by using the following syntax.

... | eval n= rtrim(" abc ");

3. SPL2 example

Alternatively, you can use named arguments to list the arguments in any order.

... | eval n=rtrim(strip_chars: " Z", str: " ZZZZabcZZ");

spath(input, path)

For documentation on the spath function, see spath.

substr(str, start, length)

This function takes three arguments. The required arguments are str, a string, and start, an integer. This function also takes an optional argument length, also an integer. This function returns a substring of str, starting at the index specified by start with the number of characters specified by length.

Function Input

str: string

start: integer

(Optional) length: integer

Function Output

string

SPL2 examples

Returns "foo".

When working in the SPL View, you can write the function by using the following syntax.

...| eval n=substr("foobar", 1, 3);

Alternatively, you can use named arguments to list the arguments in any order.

...| eval n=substr(str: "foobar", length: 3, start: 1);

trim(str, strip_chars)

This function takes two arguments. The required argument is str, a string. This function also takes an optional argument strip_chars, also a string. This function returns either str with whitespaces removed from both sides or str with the characters in strip_chars trimmed from both sides.

Function Input

str: string

(Optional) strip_chars: string

Function Output

string

1. SPL2 example

Returns "abc".

When working in the SPL View, you can write the function by using the following syntax.

...| eval n=trim(" ZZZZabcZZ ", " Z");

2. SPL2 example

Returns "abc".

When working in the SPL View, you can write the function by using the following syntax.

...| eval n=trim(" abc ");

3. SPL2 example

Alternatively, you can use named arguments to list the arguments in any order.

...| eval n=trim(strip_chars: "Z", str: " ZZZZabcZZ ");

upper(str)

Converts a string to uppercase.

Function Input

str: string

Function Output

string

SPL2 examples

Returns USERNAME.

When working in the SPL View, you can write the function by using the following syntax.

...| eval n=upper(username);

Alternatively, you can use named arguments.

...| eval n=upper(str: username);

url_decode(str)

Takes a URL string and returns the unescaped or decoded URL string.

Function Input

str: string

Function Output

string

SPL2 examples

Returns http://www.splunk.com/download?r=header.

When working in the SPL View, you can write the function by using the following syntax.

url_decode("http%3A%2F%2Fwww.splunk.com%2Fdownload%3Fr%3Dheader");

Alternatively, you can use named arguments.

...| eval n=url_decode(str: "http%3A%2F%2Fwww.splunk.com%2Fdownload%3Fr%3Dheader");

url_encode(str)

Encodes a string for the query string parameters in a URL. Use this function when you want to include user-supplied string data in a URL.

Function Input

str: string

Function Output

string

SPL2 examples

Filters records by Jane+A+Smith.

When working in the SPL View, you can write the function by using the following syntax.

| where "Jane+A+Smith"=url_encode("Jane A Smith");

Alternatively, you can use named arguments.

| where "Jane+A+Smith"=url_encode(str: "Jane A Smith");