Splunk® Data Stream Processor

Function Reference

Acrobat logo Download manual as PDF

Acrobat logo Download topic as PDF

Map

The following topic contains the functions that you can use on maps or return maps.

contains_key(input, key)

Checks a map for a specified key.

Function Input
input: map<string, T>
key: string
Function Output
boolean

SPL2 examples

Checks the inputted map to see if the key "foo" exists.

...| eval n=contains_key(from_json_object("{\"foo\": [{\"bar\": \"baz\"}]}"), "foo");

Alternatively, you can use named arguments to list the arguments in any order. See SPL2 syntax for more details.

...| eval n=contains_key(key: "foo", input: from_json_object("{\"foo\": [{\"bar\": \"baz\"}]}"));


create_map(keys_and_values)

Creates a new map object at runtime. Returns a map of key-value pairs. Use create_map if you want to create a map whose keys are determined by the output of another scalar function. See the SPL2 example.

Function Input
keys_and_values: collection<expression<any>>
Function Output
map<string, T>

SPL2 examples

Creates a map with the value of host in uppercase and value, for example: {"MYHOST":"value"}.

...| eval my_map=create_map([upper(host), "value"]) |...;

Alternatively, you can use named arguments to list the arguments in any order. See SPL2 syntax for more details.

...| eval my_map=create_map(keys_and_values: [upper(host), "value"]) |...;

flatten(input, separator)

Flattens a list or a map. If used to flatten a map, takes an optional second argument (Y) as a delimiter. Flattening fields with nested values can simplify SPL2 syntax and field extraction.

This function flattens either a list or a map. If you pass a list to flatten that is a list of nested maps, only the list will be flattened, not the maps. Similarly, if you pass in a map with nested lists, the map is flattened but the lists are not. See the fourth row in the table for an example.

Function Input
input: collection<any> or map<string,any>
This function accepts one of two different data types. It either accepts a collection of lists, where the list can be of any type, including a list of lists. Or, it accepts maps, where the data type of the map is <string, any>.
separator: string
If you are flattening a map, you can optionally pass in a delimiter to separate the keys in a map.
Function Output
collection<any> if a list was passed in, where all nested lists are flattened to a single list.
map<string,any> if a map was passed in, where all nested maps are flattened to a single top-level map.

The following table shows the original nested list or map, the flattened version of that list or map, and an accompanying SPL2 example.

Incoming, nested data Outgoing, flattened data SPL2 example Notes
[1, null, "foo", ["1-deep", ["2-deep"]], [], 100] [1, null, "foo", "1-deep", "2-deep", 100] eval flattened_list= flatten(list_field); Returns the flattened list in a new top-level field called flattened_list.
{"baz": {"foo": 1, "bar": "thing"}, "quux": 3} {"quux":3,"baz.foo":1,"baz.bar":"thing"} eval flattened_map=flatten(map_field); Returns the flattened map in a new top-level field called flattened_map.
{"baz": {"foo": 1, "bar": "thing"}, "quux": 3} {"quux":3,"baz::bar":"thing","baz::foo":1} eval flattened_map=flatten({"baz": {"foo": 1, "bar": "thing"}, "quux": 3}, "::"); Returns the flattened map in a new top-level field called flattened_map. Also, delimits the keys in the map with ::.
[[1, 2, 3], [{"key1": {"innerkey1": "innerval1"}}]] [1,2,3,{"key1":{"innerkey1":"innerval1"}}] eval flattened_map=flatten([[1, 2, 3], [{"key1": {"innerkey1": "innerval1"}}]]); Returns the flattened lists in a new top-level field called flattened_list_with_nested_map. Does not flatten the nested maps that are included in the original list.

Alternatively, you can also use named arguments to list the arguments in any order. See SPL2 syntax for more details.

...| eval flattened_map=flatten(separator: "::", input: {"baz": {"foo": 1, "bar": "thing"}, "quux": 3});

length(input)

Returns the character length of the provided input. The input can be a map, collection, bytes, or a string.

Function Input
type<any>
Function Output
integer

SPL2 example

Returns 3.

...| eval n=length({"1": "bar", "2": "baz", "3": "foo"});


map_delete(input, key)

Deletes a given key from a map.

Function Input
input: map<string,T>
keys: collection<string>
Function Output
map<string,T>

SPL2 example

If your data has a field called defaults containing the following map, {"name":"read_throughput","unit":"MBps","type":"metrics","value":null}, then remove the key-value pairs unit and value from the data and output the new map {"name":"read_throughput","type":"metrics"} in a newmap field.

... | eval newmap=map_delete(defaults, ["unit", "value"]); 

Alternatively, you can also use named arguments to list the arguments in any order. See SPL2 syntax for more details.

... | eval newmap=map_delete(keys: ["unit", "value"], input: defaults); 

map_get(input, key)

Returns the value corresponding to a key in the map input.

Function Input
input: map<string, T>
This function inputs a map between a key and a value of any specific data type, T.
key: string
Function Output
type: T

This function outputs the value, which can be of any specific data type T, of the inputted key.

SPL2 examples

Returns the value of the key "index" from the attributes field map. Use that value to determine the value of the index field.

... | to_splunk_json index=cast(map_get(attributes, "index"), "string");

Alternatively, you can also use named arguments to list the arguments in any order. See SPL2 syntax for more details.

... | to_splunk_json index=cast(map_get(key: "index", input: attributes), "string");

map_keys(input)

Returns a list of keys in a map.

Function Input
input: map<string, any>
Function Output
collection<string>

SPL2 examples

Outputs a list of keys from the attributes field in a new top-level field called keys.

...| eval keys=map_keys(attributes);

Alternatively, you can also use named arguments. See SPL2 syntax for more details.

...| eval keys=map_keys(input: attributes);

map_merge(maps, mode)

This function takes two or more maps and merges them together to return a single map using a specified merge mode. The available merge modes are left, top, or recursive.

Function Input
maps: collection<map<string, any>>
mode: string (one of "left", "top", or "recursive")
Function Output
map<string, any>
Argument Input Description
maps collection<map<string, any>> This function accepts a collection of maps where the data type of the map is <string, any>.
mode left, top, or recursive Specifies the merging behavior for the incoming maps. Defaults to left. See the SPL2 examples section to see the different ways to use the map_merge function to merge two or more maps.
  • Left: Merges using left-hand precedence. If two keys conflict, the left-most map's key-value pair is chosen.
  • Top: Merges top-level fields only.
  • Recursive: Merges all nested fields.

1. SPL2 example

Merges two maps using left-hand precedence. Returns {"a" : [17, 33]}.

... | eval n = map_merge([{"a" : [17, 33]}, {"a" : [100]}], "left") |...;

2. SPL2 example

Merges only the top-level fields of two maps. Returns {"a":[{"abc":123},{"abc":456,"xyz":890}]}.

... | eval n = map_merge([{"a" : {"abc" : 123 } }, {"a" : { "abc" : 456 , "xyz" : 890 } }], "top") |...;

3. SPL2 example

Merges two maps, including all nested fields within the maps. Returns {"a":{"abc":[123,456],"xyz":890}} .

... | eval n = map_merge([{"a" : {"abc" : 123 } }, {"a" : {"abc" : 456 , "xyz" : 890 } }], "recursive") |...;

4. SPL2 example

In the following example, the fields m1 and m2 both contain a map. This example uses the map_merge function to merge the two fields together to return a single map in a new field called n1. Assume that m1 contains {"a":{"abc":[123,456],"xyz":890}} and m2 contains {"a":[17,33]} , then n1 returns {"a":[17,33,{"abc":[123,456],"xyz":890}]}.

... | eval n1 = map_merge([m1, m2], "top") |...;

map_set(map, keys_and_values)

Insert new key-value pairs or overwrite existing key-value pairs in a map. Returns an updated map.

Function Input
map: map<K,V>
keys_and_values: collection<expression<any>>
Function Output
map<K,V>

SPL2 examples

This example adds the key-value pair "some_key": "some_value" to the attributes map.

...| eval attributes=map_set(attributes, "some_key", "some_value") |...;

Alternatively, you can also use named arguments. See SPL2 syntax for more details.

...| eval attributes=map_set(keys_and_values: ["some_key", "some_value"], map: attributes) |...;


map_values(input)

Returns a list of values in a map.

Function Input
map: map<string,T>
Function Output
collection<T>

SPL2 example

In this example, if your attributes field contains a map with key-value pairs {"_splunk_connection_id":"rest_api:all","foo":"bar"}, then the following example would return the values in the map in a new field called n: ["rest_api:all","bar"].

...| eval n=map_values(attributes) |...;

Alternatively, you can also use named arguments. See SPL2 syntax for more details.

...| eval n=map_values(input: attributes) |...;

spath(input, path)

This function extracts a value from a map or collection. Use this function to extract a value from a nested map or collection. To extract a value from a JSON string, convert your JSON string to a map. See the from_json_object scalar function and the SPL2 example below.

The Data Stream Processor spath function does not have an auto-extract mode and does not accept JSON or XML strings.

Function Input
input: union<collection<any>, map<string,any>>
path: string
The location path to the value that you want to extract. If you do not specify the path=, the first unlabeled argument is used as the location path. A location path is composed of one or more location steps, separated by periods. An example of this is 'foo.bar.baz'.
Function Output
union<string, bytes, boolean, integer, long, float, double, collection<any>, map<string,any>>

1. SPL2 example

Returns baz.

spath(from_json_object("{\"foo\": [{\"bar\": \"baz\"}]}"), "foo{0}.bar");

2. SPL2 example

Extracts forwarder_channel_id from attributes.

... | eval forwarder_channel_id_spath=spath(attributes, "spl_forwarder_channel_info.forwarder_channel_id");

3. SPL2 example

Alternatively, you can use named arguments to list the arguments in any order. See SPL2 syntax for more details.

... | eval forwarder_channel_id_spath=spath(path: "spl_forwarder_channel_info.forwarder_channel_id", input: attributes);
Last modified on 25 October, 2020
PREVIOUS
List
  NEXT
Mathematical

This documentation applies to the following versions of Splunk® Data Stream Processor: 1.2.0


Was this documentation topic helpful?

You must be logged into splunk.com in order to post comments. Log in now.

Please try to keep this discussion focused on the content covered in this documentation topic. If you have a more general question about Splunk functionality or are experiencing a difficulty with Splunk, consider posting a question to Splunkbase Answers.

0 out of 1000 Characters