Map

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

contains_key

Checks a map for a specified key.

Function Input

input: map<string, T>

key: string

Function Output

boolean

SPL2 example

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

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

create_map

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 example

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

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

flatten(X,Y)

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

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

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

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

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"]); 

map_get

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 example

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");

map_keys

Returns a list of keys in a map.

Function Input

map<string,any>

Function Output

collection<string>

SPL2 example

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

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

map_set

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

Function Input

field_name: map

keys_and_values:collection<expression<any>>

Function Output

map<K,V>

SPL2 example

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

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

map_values

Returns a list of values in a map.

Function Input

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