Splunk® Cloud Services

SPL2 Search Reference

JSON functions

The following table describes the SPL2 functions that are available for you to use to create or manipulate JSON objects:

Description JSON function
Creates a new JSON object from key-value pairs. json_object
Evaluates whether a value can be parsed as JSON. If the value is in a valid JSON format returns the value. Otherwise, returns null. json
Appends elements to the contents of a valid JSON object. json_append
Creates a JSON array using a list of values. json_array
Maps the elements of a JSON array to a multivalued field. json_array_to_mv
Removes one or more keys and their corresponding values from the specified JSON object. json_delete
Extends the contents of a valid JSON object with the values of an array. json_extend
Returns either a JSON array or a Splunk software native type value from a field and zero or more paths.

json_extract

Returns Splunk software native type values from a piece of JSON by matching literal strings in the event and extracting the strings as keys. json_extract_exact
Returns the keys from the key-value pairs in a JSON object. The keys are returned as a JSON array. json_keys
Inserts or overwrites values for a JSON node with the values provided and return an updated JSON object. json_set
Generates or overwrites a JSON object using the key-value pairs specified. json_set_exact
Evaluates whether a JSON object uses valid JSON syntax and returns either TRUE or FALSE. json_valid
Iterates over the values in a JSON array and returns true if every value in the array matches the provided predicate.

all

Iterates over the values in a JSON array and returns true if any value in the array matches the provided predicate.

any

Iterates over the values in a JSON array and performs an operation on each value in the array.

filter

Iterates over the values in a JSON array and copies the values that match the specified <predicate> into a new array. map
Iterates over the values in a JSON array and performs an operation on each value in the array. reduce

JSON related functions

In addition, there are multivalue and conversion functions that create JSON arrays or objects:

json_object(<members>)

Creates a new JSON object from members of key-value pairs.

Usage

If you specify a string for a <key> or <value>, you must enclose the string in double quotation marks. A <key> must be a string. A <value> can be a string, number, Boolean, null, multivalue field, array, or another JSON object.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands. See the eval, where, and from commands.

Examples

These examples show different ways to use the json_object function to create JSON objects in your events.

1. Create a basic JSON object

The following example creates a basic JSON object { "name": "maria" }.

... | eval name = json_object("name", "maria")

2. Create a JSON object using a multivalue field

The following example creates a multivalue field called firstnames that uses the key name and contains the values "maria" and "arun". The JSON object created is { "name": ["maria", "arun"] } .

... | eval firstnames = json_object("name", mvappend("maria", "arun"))

3. Create a JSON object using a JSON array

The following example creates a JSON object that uses a JSON array for the values.

... | eval locations = json_object("cities", json_array("London", "Sydney", "Berlin", "Santiago"))

The result is the JSON object { "cities": ["London", "Sydney", "Berlin", "Santiago"] }.

4. Create a nested JSON object

The following example creates a nested JSON object that uses other JSON objects and a multivalue JSON array field called gamelist.

...| eval games = json_object("category", json_object("boardgames", json_object("cooperative", gamelist)))

The result is this JSON object:
{
  "games": {
    "category": {
      "boardgames": {
        "cooperative": [ "Pandemic", "Forbidden Island", "Castle Panic" ]
      }
    }
  }
}

json(<value>)

Evaluates whether a value can be parsed as JSON. If the value is in a valid JSON format, the function returns the value. Otherwise, the function returns null.

Usage

The <value> parameter can be any kind of value such as string, number, Boolean, null, or JSON array or object.

You can use this function with the eval command.

Examples

1. Identify a JSON value

This example shows how you can use the json function to confirm that a value is JSON. The following search verifies that {"animal" : "pony"} is a JSON value by returning its value, {"animal" : "pony"}.

... | eval animals = json_object("animal", "pony"), result = json(animals)

_time animals result
2023-02-22 14:39:50 {"animal":"pony"} {"animal":"pony"}

2. Compare multiple results to identify JSON values

The following example shows how to use the json function to determine if the values in a field are in a valid JSON format.

Consider the following search results:

Bridges City
[{"name":"Tower Bridge","length":801}, {"name":"Millennium Bridge","length":1066}] London
Golden Gate Bridge San Francisco
[{"name":"Rialto Bridge","length":157}, {"name":"Bridge of Sighs","length":36}, {"name":"Ponte della Paglia"}] Venice

When you add the json function to your search, the results in the bridgesAsJson field identifies which values in the Bridges field are JSON values.

... | eval bridgesAsJson = json(Bridges)

When the value is JSON, the value is returned. When the value is not JSON, NULL is returned. The results look like this:

Bridges City bridgesAsJson
[{"name":"Tower Bridge","length":801}, {"name":"Millennium Bridge","length":1066}] London [{"name":"Tower Bridge","length":801}, {"name":"Millennium Bridge","length":1066}]
Golden Gate Bridge San Francisco NULL
[{"name":"Rialto Bridge","length":157}, {"name":"Bridge of Sighs","length":36}, {"name":"Ponte della Paglia"}] Venice [{"name":"Rialto Bridge","length":157}, {"name":"Bridge of Sighs","length":36}, {"name":"Ponte della Paglia"}]

json_append(<json>, <path_value_pairs>)

This function appends values to the ends of indicated arrays within a JSON document. This function provides a JSON eval function equivalent to the multivalue mvappend function.

Usage

The json_append function always has at least three function inputs: <json> (the name of a valid JSON document such as a JSON object), and at least one <path> and <value> pair.

If <json> does not reference a valid JSON document, such as a JSON object, the function outputs nothing.

The json_append function evaluates <path_value_pairs> from left to right. When a path-value pair is evaluated, the function updates the <json> document. The function then evaluates the next path-value pair against the updated document.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Use <path> to designate a JSON document value

Each <path> designates an array or value within the <json> document. The json_append function adds the corresponding <value> to the end of the value designated by the <path>. The following table explains what json_append does depending on what the <path> specifies.

If <path> specifies... ...This is what json_append does with the corresponding <value>
An array with one or more values. json_append adds the corresponding <value> to the end of that array.
An empty array json_append adds the corresponding <value> to that array, creating an array with a single value.
A scalar or object value json_append ignores scalar values and simply returns the <value> itself.

The json_append function ignores path-value pairs for which the <path> does not identify any valid value in the JSON document.

Append arrays as single elements

When the new <value> is an array, json_append appends the array as a single element. For example, if a json_array <path> leads to the array ["a", "b", "c"] and its <value> is the array ["d", "e", "f"], the result is ["a", "b", "c", ["d", "e", "f"]].

Appending arrays as single elements separates json_append from json_extend, a similar function that flattens arrays and objects into separate elements as it appends them. When json_extend takes the example in the preceding paragraph, it returns ["a", "b", "c", "d", "e", "f"].

Examples

The following examples show how you can use json_append to append values to arrays within a JSON document.

1. Add a string to an array

Say you have an object named ponies that contains an array named ponylist:["Minty", "Rarity", "Buttercup"]. This is the search you would run to append "Fluttershy" to ponylist.

... | eval ponies = json_object("ponylist", json_array("Minty", "Rarity", "Buttercup")), updatePonies = json_append(ponies, "ponylist", "Fluttershy")

The output of that eval statement is {"ponylist": ["Minty", "Rarity", "Buttercup", "Fluttershy"]}.

2. Append a string to a nested object

This example has a <path> with the value Fluttershy.ponySkills. Fluttershy.ponySkills references an array of an object that is nested within ponyDetails, the source object. The query uses json_append to add a string to the nested object array.

... | eval ponyDetails = json_object("Fluttershy", json_object("ponySkills", json_array("running", "jumping"))), ponyDetailsUpdated = json_append(ponyDetails, "Fluttershy.ponySkills", "codebreaking")

The output of this eval statement is ponyDetailsUpdated = {"Fluttershy":{"ponySkills":["running","jumping","codebreaking"]}}

json_array(<values>)

Creates a JSON array using a list of values.

Usage

A <value> can be any kind of value such as string, number, or Boolean. You can also use the json_object function to specify values.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Examples

These examples show different ways to use the json_array function to create JSON arrays in your events.

1. Create a basic JSON array

The following example creates a simple array ["buttercup", "fluttershy", "rarity"] .

... | eval ponies = json_array("buttercup", "fluttershy", "rarity")

2. Create an JSON array from a string and a JSON object

The following example uses a string dubois and the json_object function for the array values.

... | eval surname = json_array("dubois", json_object("name", "patel"))

The result is the JSON array [ "dubois", {"name": "patel}" ].

json_array_to_mv(<json_array>, <boolean>)

This function maps the elements of a proper JSON array into a multivalue field.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

If the <json array> input to the function is not a valid JSON array, the function outputs nothing.

Use the <Boolean> input to specify that the json_array_to_mv function should preserve bracketing quotes on JSON-formatted strings. The <Boolean> input defaults to false().

Syntax Description
json_array_to_mv(<json_array>, false()) or
json_array_to_mv(<json_array>) 		By default (or when you explicitly set it to false()), the json_array_to_mv function removes bracketing quotes from JSON string data types when it converts an array into a multivalue field.
json_array_to_mv(<json_array>, true()) When set to true(), the json_array_to_mv function preserves bracketing quotes on JSON string data types when it converts an array into a multivalue field.

There is also a function that maps multivalue fields to JSON arrays. See mv_to_json_array.

Example

This example demonstrates usage of the json_array_to_mv function to create multivalue fields out of JSON data.

1. Create a simple multivalue field

The following example creates a simple array: ["Buttercup", "Fluttershy", "Rarity"]. Then it maps that array into a multivalue field named my_little_ponies with the values Buttercup, Fluttershy, and Rarity. The function removes the quote characters when it converts the array elements into field values.

... | eval ponies = json_array("Buttercup", "Fluttershy", "Rarity"), my_sweet_ponies = json_array_to_mv(ponies)

If you change this search so it has my_sweet_ponies = json_array_to_mv(ponies,true()), you get an array with the values "Buttercup", "Fluttershy", and "Rarity". Setting the function to true causes the function to preserve the quote characters when it converts the array elements into field values.

json_delete(<object>, <keys>)

Removes one or more keys and their corresponding values from the specified JSON object.

The original JSON object is not modified. Instead, a new object is returned.

Usage

The json_delete function uses two parameters:

  • The <object> parameter identifies the JSON object that you want to delete key-value pairs from.
  • The <keys> parameter identifies one or more keys that you want delete. The corresponding values are also deleted.

Array indexing is not supported.

You can use this function with the eval and where commands, in the SELECT and WHERE clause of the from command, and as part of evaluation expressions with other commands. See the eval, where, and from commands.

Specifying keys

You can specify the <keys> in 2 ways, as shown in the following table:

Method Example
A comma-separated list json_delete(object, "SSN", "accounts")
An array json_delete(object, ["SSN", "accounts"]

Nested keys

You can delete key-value pairs from nested keys. However deleting key names that contain the dot character ( . ) is not supported.

For example, suppose you have the key student.name which has the value Claudia. Using json_delete(obj, "student.name") looks for the nested object name under the key student, which does not exist.

Examples

1. Delete key-value pairs in an object

The following search deletes several key-value pairs from a JSON object. A new JSON object is returned in a field called sales_account.

  • This search uses the eval command to create a JSON object literal in a field called object.
  • Another eval command is used with the json_delete function to remove several key-value pairs from the JSON object literal, including the values in an array.

$delete_pii = from [{}] | eval object = {"name":"Wei Zhang", "SSN":"123-45-6789", "city":"Seattle", "accounts":["Hagal Quartz", "Caladan Water", "Arrakis Spices"]} | eval sales_account = json_delete(object, "SSN", "accounts")

The results look like this:

object sales_account
{"name":"Wei Zhang", "SSN":"123-45-6789", "city":"Seattle", "accounts":["Hagal Quartz", "Caladan Water", "Arrakis Spices"]} {"name":"Wei Zhang", "city":"Seattle"}

You don't have to use 2 separate eval commands for this search example. You can specify multiple eval command operations separated by commas. For example:

$delete_pii = from [{}] | eval object = {"name":"Wei Zhang", "SSN":"123-45-6789", "city":"Seattle", "accounts":["Hagal Quartz", "Caladan Water", "Arrakis Spices"]}, sales_account = json_delete(object, "SSN", "accounts")

2. Delete a key-value pair in a nested object in a pipeline

Suppose your incoming pipeline data contains a JSON object with sensitive information about your contacts in a nested object. For example:

Contact
{"name":"Celestino Paulo", "company":"Isthmus Pastimes", "addresses": {"email":"celestino@sample.com", "office":"edificio 890 Avenida Demetrio Panama City Panama"}}
{"name":"David Mayer", "company":"Euro Games", "addresses": {"email":"david@sample.com", "office":"567 Pariser Platz 2 10117 Berlin Germany "}}
{"name":"Wei Zhang", "company":"Tiger Fun", "addresses": {"email":"wei@sample.com", "office":"678 Chome-10-5 Akasaka Minato City Tokyo 107-8420 Japan"}}
{"name":"Rutherford Sullivan", "company":"Blarney Games", "addresses": {"email":"rutherford@sample.com", "office":"789 Market St Sleveen Kinsale Co. Cork P17 E068 Ireland"}}

The following pipeline removes the email key-value pair from the addresses nested object.

$pipeline = from $source | eval contacts = json_delete(contacts, ["addresses.email"]) | into $destination

The values in the existing field contacts are replaced with the updated objects which have the sensitive data removed.

3. Delete a key-value pair in a nested object in a search

The following search removes a key-value pair from the addresses nested object. A new JSON object is returned in a field called result.

  • This search uses the eval command to create a JSON object literal in a field called employee.
  • The search then uses another eval command with the json_delete function to remove the email key-value pair from the addresses nested object.

$delete_nested = from [{}] | eval employee = {"name":"Celestino Paulo", "company":"Isthmus Pastimes", "addresses": {"email":"celestino@sample.com", "office":"edificio 890 Avenida Demetrio Panama City Panama"}} | eval result = json_delete(employee, "addresses.email")

The results look like this:

employee results
{"name":"Celestino Paulo", "company":"Isthmus Pastimes", "addresses": {"email":"celestino@sample.com", "office":"edificio 890 Avenida Demetrio Panama City Panama"}} {"name":"Celestino Paulo", "company":"Isthmus Pastimes", "addresses": {"office":"edificio 890 Avenida Demetrio Panama City Panama"}}

json_extend(<json>, <path_value_pairs>)

Use json_extend when you want to append multiple values at once to an array. json_extend flattens arrays into their component values and appends those values to the ends of indicated arrays within a valid JSON document.

Usage

The json_extend function always has at least three function inputs: <json> (the name of a valid JSON document such as a JSON object), and at least one <path> and <value> pair. The <value> must be an array. When given valid inputs, json_extend always outputs an array.

If <json> does not reference a valid JSON document, such as a JSON object, the function outputs nothing.

The json_extend function evaluates <path_value_pairs> from left to right. When json_extend evaluates a path-value pair, it updates the <json> document. json_extend then evaluates the next path-value pair against the updated document.

You can use json_extend with the eval and where commands, and as part of evaluation expressions with other commands.

Use <path> to designate a JSON document value

Each <path> designates an array or value within the <json> document. The json_extend function adds the values of the corresponding <array> after the last value of the array designated by the <path>. The following table explains what json_extend does depending on what the <path> specifies.

If <path> specifies... ...This is what json_extend does with the corresponding array values
An array with one or more values. json_extend adds the corresponding array values to the end of that array.
An empty array json_extend adds the corresponding array values to that array.
A scalar or object value json_extend ignores scalar values and simply returns the value itself.

json_extend ignores path-value pairs for which the <path> does not identify any valid value in the JSON document.

How json_extend flattens arrays before it appends them

The json_extend function flattens arrays as it appends them to the specified value. "Flattening" refers to the act of breaking the array down into its component values. For example, if a json_extend <path> leads to the array ["a", "b", "c"] and its <value> is the array ["d", "e", "f"], the result is ["a", "b", "c", "d", "e", "f"].

Appending arrays as individual values separates json_extend from json_append, a similar function that appends the <value> as a single element. When json_append takes the example in the preceding paragraph, it returns ["a", "b", "c", ["d", "e", "f"]].

Examples

The following examples show how you can use json_extend to append multiple values at once to arrays within a JSON document.

1. Extend an array with a set of string values

You start with an object named fakeBandsInMovies that contains an array named fakeMovieBandList: ["The Blues Brothers", "Spinal Tap", "Wyld Stallyns"]. This is the search you would run to extend that list with three more names of fake bands from movies.

... | eval fakeBandsInMovies = json_object("fakeMovieBandList", json_array("The Blues Brothers", "Spinal Tap", "Wyld Stallyns")), updateBandList = json_extend(fakeBandsInMovies, "fakeMovieBandList", json_array("The Soggy Bottom Boys", "The Weird Sisters", "The Barden Bellas"))

The output of this eval statement is {"fakeMovieBandList": ["The Blues Brothers", "Spinal Tap", "Wyld Stallyns", "The Soggy Bottom Boys", "The Weird Sisters", "The Barden Bellas"]}

2. Extend an array with an object

This example has an object named dndChars that contains an array named characterClasses. You want to update this array with an object from a secondary array. Here is a search you could run to achieve that goal.

... | eval dndChars = json_object("characterClasses", json_array("wizard", "rogue", "barbarian")), array2 = json_array(json_object("artifact", "deck of many things")), updatedParty = json_extend(dndChars, "characterClasses", array2)

The output of this eval statement is {updatedParty = ["wizard", "rogue", "barbarian", {"artifact":"deck of many things"}]}. Note that when json_extend flattens array2, it removes the object from the array. Otherwise the output would be {updatedParty = ["wizard", "rogue", "barbarian", [{"artifact":"deck of many things"}]]}.

json_extract(<json>, <paths>)

This function returns a value from a piece JSON and zero or more paths. The value is returned in either a JSON array, or a Splunk software native type value.

Usage

What is converted or extracted depends on whether you specify piece of JSON, or JSON and one or more paths.

Syntax Description
json_extract(<json>) Converts a JSON field to the Splunk software native type. For example:
  • Converts a JSON string to a string
  • Converts a JSON Boolean to a Boolean
  • Converts a JSON null to a null
json_extract(<json>, <path>) Extracts the value specified by <path> from <json>, and converts the value to the native type. This can be a JSON array if the path leads to an array.
json_extract(<json>, <path>, <path>, ...) Extracts all of the paths from <json> and returns it as a JSON array.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Examples

These examples use this JSON object, which is in a field called cities in an event: 

[{
  "cities": [
    {
      "name": "London",
      "Bridges": [
        { "name": "Tower Bridge", "length": 801 },
        { "name": "Millennium Bridge", "length": 1066 }
      ]
    },
    {
      "name": "Venice",
      "Bridges": [
        { "name": "Rialto Bridge", "length": 157 },
        { "name": "Bridge of Sighs", "length": 36 },
        { "name": "Ponte della Paglia" }
      ]
    },
    {
      "name": "San Francisco",
      "Bridges": [
        { "name": "Golden Gate Bridge", "length": 8981 },
        { "name": "Bay Bridge", "length": 23556 }
       ]
     }
   ]
 }
]



1. Extract the entire JSON object in a field

The following example returns the entire JSON object from the cities field. The cities field contains only one object. The key is the entire object. This extraction can return any type of value.

... | eval extract_cities = json_extract(cities, "{}")

Field Results
extract_cities [{"name":"London","Bridges":[{"name":"Tower Bridge","length":801},{"name":"Millennium Bridge","length":1066}]},{"name":"Venice","Bridges":[{"name":"Rialto Bridge","length":157},{"name":"Bridge of Sighs","length":36},{"name":"Ponte della Paglia"}]},{"name":"San Francisco","Bridges":[{"name":"Golden Gate Bridge","length":8981},{"name":"Bay Bridge","length":23556}]}]

2. Extract the first nested JSON object in a field

The following example extracts the information about the city of London from the JSON object. This extraction can return any type of value.

... | eval London=json_extract(cities,"{0}")

Field Results
London {"name":"London","Bridges":[{"name":"Tower Bridge","length":801},{"name":"Millennium Bridge","length":1066}]}

3. Extract the third nested JSON object in a field

The following example extracts the information about the city of San Francisco from the JSON object. This extraction can return any type of value.

... | eval San_Francisco=json_extract(cities,"{2}")

Field Results
San_Francisco {"name":"San Francisco","Bridges":[{"name":"Golden Gate Bridge","length":8981},{"name":"Bay Bridge","length":23556}]}

4. Extract a specific key from each nested JSON object in a field

The following example extracts the names of the cities from the JSON object. This extraction can return any type of value.

... | eval my_cities=json_extract(cities,"{}.name")

Field Results
my_cities ["London","Venice","San Francisco"]

5. Extract a specific set of key-value pairs from each nested JSON object in a field

The following example extracts the information about each bridge from every city from the JSON object. This extraction can return any type of value.

... | eval Bridges=json_extract(cities,"{}.Bridges{}")

Field Results
Bridges [{"name":"Tower Bridge","length":801},{"name":"Millennium Bridge","length":1066},{"name":"Rialto Bridge","length":157},{"name":"Bridge of Sighs","length":36},{"name":"Ponte della Paglia"},{"name":"Golden Gate Bridge","length":8981},{"name":"Bay Bridge","length":23556}]

6. Extract a specific value from each nested JSON object in a field

The following example extracts the names of the bridges from all of the cities from the JSON object. This extraction can return any type of value.

... | eval Bridge_names=json_extract(cities,"{}.Bridges{}.name")

Field Results
Bridge_names ["Tower Bridge","Millennium Bridge","Rialto Bridge","Bridge of Sighs","Ponte della Paglia","Golden Gate Bridge","Bay Bridge"]

7. Extract a specific key-value pair from a specific nested JSON object in a field

The following example extracts the name and length of the first bridge from the third city from the JSON object. This extraction can return any type of value.

... | eval GG_Bridge=json_extract(cities,"{2}.Bridges{0}")

Field Results
GG_Bridge {"name":"Golden Gate Bridge","length":8981}

8. Extract a specific value from a specific nested JSON object in a field

The following example extracts the length of the first bridge from the third city from the JSON object. This extraction can return any type of value.

... | eval GG_Bridge_length=json_extract(cities,"{2}.Bridges{0}.length")

Field Results
GG_Bridge_length 8981

json_extract_exact(<json>, <keys>)

Like the json_extract function, this function returns a Splunk software native type value from a piece of JSON. The main difference between these functions is that the json_extract_exact function does not use paths to locate and extract values, but instead matches literal strings in the event and extracts those strings as keys.

See json_extract.

Usage

The json_extract_exact function treats strings for key extraction literally. This means that the function does not support explicitly nested paths. You can set paths with nested json_array/json_object function calls.

Syntax Description
json_extract_exact(<json>) Converts a JSON field to the Splunk software native type. For example:
  • Converts a JSON string to a string
  • Converts a JSON Boolean to a Boolean
  • Converts a JSON null to a null
json_extract_exact(<json>, <string>) Extracts the key specified by <string> from <json>, and converts the key to the Splunk software native type. This can be a JSON array if the path leads to an array.
json_extract_exact(<json>, <string>, <string>, ...) Extracts all of the strings from <json> and returns them as a JSON array of keys.

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Example

1. Extract a value that contains special characters

Suppose you have a JSON event that looks like this: {"system.splunk.path":"/opt/splunk/"}

If you want to extract system.splunk.path from that event, you can't use the json_extract function because of the period characters. Instead, you would use json_extract_exact, as shown in the following search:

... | eval extracted_path=json_extract_exact(splunk_path, "system.splunk.path")

json_keys(<json>)

Returns the keys from the key-value pairs in a JSON object. The keys are returned as a JSON array.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

The json_keys function cannot be used on JSON arrays.

Examples

1. Return a list of keys from a JSON object

Consider the following JSON object, which is in the bridges field:
bridges
{"name": "Clifton Suspension Bridge", "length": 1352, "city": "Bristol", "country": "England"}
This example extracts the keys from the JSON object in the bridges field:

... | eval bridge_keys = json_keys(bridges)

Here are the results of the search:
bridge_keys
["name", "length", "city", "country"]

2. Return a list of keys from multiple JSON objects

Consider the following JSON objects, which are in separate rows in the bridges field:
bridges
{"name": "Clifton Suspension Bridge", "length": 1352, "city": "Bristol", "country": "England"}
{"name":"Rialto Bridge","length":157, "city": "Venice", "region": "Veneto", "country": "Italy"}
{"name": "Helix Bridge", "length": 918, "city": "Singapore", "country": "Singapore"}
{"name": "Tilikum Crossing", "length": 1700, "city": "Portland", "state": "Oregon", "country": "United States"}
This example extracts the keys from the JSON objects in the bridges field:

... | eval bridge_keys = json_keys(bridges)

Here are the results of the search:
bridge_keys
["name", "length", "city", "country"]
["name", "length", "city", "region", "country"]
["name", "length", "city", "country"]
["name", "length", "city", "state", "country"]

json_set(<json>, <path_value_pairs>)

Inserts or overwrites values for a JSON node with the values provided and returns an updated JSON object.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

  • If the path contains a list of keys, all of the keys in the chain are created if the keys don't exist.
  • If there's a mismatch between the JSON object and the path, the update is skipped and doesn't generate an error. For example, for object {"a": "b"}, json_set(.., "a.c", "d") produces no results since "a" has a string value and "a.c" implies a nested object.
  • If the value already exists and is of a matching non-value type, the json_set function overwrites the value by default. A value type match isn't enforced. For example, you can overwrite a number with a string, Boolean, null, and so on.

Examples

These examples use this JSON object, which is in a field called games in an event: 

{
  "category": {
    "boardgames": {
      "cooperative": [
        {
          "name": "Pandemic"
        },
        {
          "name": "Forbidden Island"
        },
        {
          "name": "Castle Panic"
        }
      ]
    }
  }
}

1. Overwrite a value in an existing JSON array

The following example overwrites the value "Castle Panic" in the path [category.boardgames.cooperative] in the JSON object. The value is replaced with "name":"Sherlock Holmes: Consulting Detective". The results are placed into a new field called my_games.
The position count starts with 0. The third position is 2, which is why the example specifies {2} in the path.

... | eval my_games = json_set(games,"category.boardgames.cooperative{2}", {"name":"Sherlock Holmes: Consulting Detective"})

Here are the results of the search:
Field Results
my_games {"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: Consulting Detective"]}}}

2. Insert a list of values in an existing JSON object

The following example inserts a list of popular games ["name":"Settlers of Catan", "name":"Terraforming Mars", "name":"Ticket to Ride"] into the path [category.boardgames.competitive] in the JSON object.
Because the key competitive doesn't exist in the path, the key is created. The json_array function is used to append the value list to the boardgames JSON object.

...| eval my_games = json_set(games,"category.boardgames.competitive", json_array("name":"Settlers of Catan", "name":"Terraforming Mars", "name":"Ticket to Ride"))

Here are the results of the search:
Field Results
my_games {"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: Consulting Detective"],"competitive": ["name":"Settlers of Catan", "name":"Terraforming Mars", "name":"Ticket to Ride"]}}}
The JSON object now looks like this:
{
  "category": {
    "boardgames": {
      "cooperative": [
        {
          "name": "Pandemic"
        },
        {
          "name": "Forbidden Island"
        },
        {
          "name": "Castle Panic"
        }
      ]
    },
    "competitive": [
      {
        "name": "Settlers of Catan"
      },
      {
        "name": "Terraforming Mars"
      },
      {
        "name": "Ticket to Ride"
      }
    ]
  }
}

3. Insert a set of key-value pairs in an existing JSON object

The following example inserts a set of key-value pairs that specify if the game is available using a Boolean value. These pairs are inserted into the path [category.boardgames.competitive] in the JSON object. The json_array function is used to append the key-value pairs list to the boardgames JSON object.

...| eval my_games = json_set(games,"category.boardgames.competitive{}.available", true())

Here are the results of the search:
Field Results
my_games {"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: Consulting Detective"],"competitive": ["name":"Settlers of Catan", "available":true, "name":"Terraforming Mars", "available":true, "name":"Ticket to Ride", "available":true]}}}
The JSON object now looks like this:
{
  "category": {
    "boardgames": {
      "cooperative": [
        {
          "name": "Pandemic"
        },
        {
          "name": "Forbidden Island"
        },
        {
          "name": "Castle Panic"
        }
      ]
    },
    "competitive": [
      {
        "name": "Settlers of Catan",
        "available": true
      },
      {
        "name": "Terraforming Mars",
        "available": true
      },
      {
        "name": "Ticket to Ride",
        "available": true
      }
    ]
  }
}
If the Settlers of Catan game is out of stock, you can overwrite the value for the available key with the value false().
For example:

... | eval my_games = json_set(games,"category.boardgames.competitive{0}.available", false())

Here are the results of the search:
Field Results
my_games {"category":{"boardgames":{"cooperative":["name":"Pandemic", "name":"Forbidden Island", "name":"Sherlock Holmes: Consulting Detective"],"competitive": ["name":"Settlers of Catan", "available":false, "name":"Terraforming Mars", "available":true, "name":"Ticket to Ride", "available":true]}}}
The JSON object now looks like this:
{
  "category": {
    "boardgames": {
      "cooperative": [
        {
          "name": "Pandemic"
        },
        {
          "name": "Forbidden Island"
        },
        {
          "name": "Castle Panic"
        }
      ]
    },
    "competitive": [
      {
        "name": "Settlers of Catan",
        "available": false
      },
      {
        "name": "Terraforming Mars",
        "available": true
      },
      {
        "name": "Ticket to Ride",
        "available": true
      }
    ]
  }
}

json_set_exact(<json>, <key_value_pairs>)

Generates or overwrites a JSON object using the key-value pairs that you specify.

Similar to the json_set function. See json_set

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

  • The json_set_exact function interprets the keys as literal strings, including special characters. This function does not interpret strings separated by period characters as keys for nested objects.
  • If you supply multiple key-value pairs to json_set_exact, the function outputs an array.
  • The json_set_exact function does not support or expect paths. You can set paths with nested json_array or json_object function calls.

Example

1. Specify a value that contains special characters

Suppose you want to have a JSON object that looks like this: 

{"system.splunk.path":"/opt/splunk"}

To generate this object, you can use an empty dataset literal in the from command and the json_set_exact function as shown in the following search:

from [{}] | eval my_object=json_object(), splunk_path=json_set_exact(my_object, "system.splunk.path", "/opt/splunk")

You use the json_set_exact function instead of the json_set function because the json_set function interprets the period characters in {"system.splunk.path"} as nested objects. If you use json_set in the preceding search you get this JSON object: 

{"system":{"splunk":{"path":"/opt/splunk"}}}

Instead of this object: 

{"system.splunk.path":"/opt/splunk"}

json_valid(<json>)

Evaluates whether piece of JSON uses valid JSON syntax and returns either TRUE or FALSE.

Usage

You can use this function with the eval and where commands, in the WHERE clause of the from command, and as part of evaluation expressions with other commands.

Example

1. Validate a JSON object

The following example validates a JSON object { "names": ["maria", "arun"] } in the firstnames field.

... | eval name = json_valid(firstnames)

all(<values>, <predicate>)

The all function iterates over the values in a JSON array and returns true if every element in the array matches the provided predicate.

This function returns false if no element matches the <predicate>.

Usage

The all function uses two parameters:

  • The <values> parameter must be either the name of a field that contains a JSON array or a JSON array literal.
  • The <predicate> parameter must be a lambda expression that returns a Boolean.

You can use this function with the eval and where commands, in the SELECT and WHERE clauses of the from command, and as part of evaluation expressions with other commands. See the eval, where, and from commands.

Examples

1. Determine if all array values are even numbers

The following example uses the eval command to check if every element of the numbers array is an even number, and returns either true or false.

... eval allNums all(numbers, $num -> $num % 2 == 0)

2. Sum array values if all values are numbers

The following example uses the eval command to check if every element of the numbers array is a number, and returns either the sum of the numbers or zero ( 0 ).

... eval sumOrZero = if(all(numbers, $num -> isnum($num)), sum(numbers), 0)

3. Filter array values to return a specific set of values

Consider the following array: 

releases = [
  {majorVersion:8, minorVersion:1},
  {majorVersion:7, minorVersion:9},
  {majorVersion:7, minorVersion:1},
  ...
]

The following example uses the WHERE clause of the from command to find all release versions that are 7.2 and above:

... WHERE all(releases, $release -> $release.majorVersion >= 7 AND $release.minorVersion >= 2)

any(<values>, <predicate>)

The any function iterates over the values in a JSON array and returns true if any element of the array values match the provided predicate.

This function returns false if <values> is empty or no element matches the <predicate>.

Usage

The any function uses two parameters:

  • The <values> parameter must be either the name of a field that contains a JSON array or a JSON array literal.
  • The <predicate> parameter must be a lambda expression that returns a Boolean.

You can use this function with the eval and where commands, in the SELECT and WHERE clauses of the from command, and as part of evaluation expressions with other commands. See the eval, where, and from commands.

Examples

1. Determine if the array contains a specific value

The following example uses the any function to determine if any of the values in the JSON arrays in the bridges field specify that the country is "Canada".

... | eval result = any(bridges, $bridge -> $bridge.country=="Canada")

Using this array, the any function returns true: 

[
   {name: "Tower Bridge", city: "London", country: "England"}, 
   {name: "Rialto Bridge", city: "Venice", country: "Italy"}, 
   {name: "Lions Gate Bridge", city: "Vancouver", country: "Canada"}, 
   {name: "Golden Gate Bridge", city: "San Francisco", country: "United States"}
]

2. Determine if any array value is an even number

The following example uses the eval command to check if any element of the numbers array is an even number and returns either true or false.

... | eval even = any(numbers, $num -> $num % 2 == 0)

filter(<values>, <predicate>)

Iterates over the values in a JSON array and copies the values that match the specified <predicate> into a new array. The values can be either in an array in a field or an array literal.

This function returns a JSON array with the copied values.

Usage

The filter function uses two parameters:

  • The <values> parameter must be either a field that contains a JSON array or an array literal.
  • The <predicate> parameter must be a lambda expression that returns a Boolean value. See Lambda expressions in the SPL2 Search Manual.

You can use this function with the eval and where commands, in the SELECT and WHERE clauses of the from command, and as part of evaluation expressions with other commands. See the eval, where, and from commands.

Examples

1. Creating an array of even numbers

This example checks if any of the values in the array in the numbers field is an even number and appends the even numbers to a new array called even_numbers.

This example shows how to use this function in the SELECT clause of the from command. The modulo mathematical operator ( % ) is used to divide the array values by 2. If there is no remaining number after the division, then the number is an even number and added to the even_numbers array.

| select filter(numbers, $num -> ($num % 2) == 0 AS even_numbers from main


2. Filtering a simple array of objects

The following example shows a dataset literal called $bridges that is created using the eval command. The dataset literal is an object with set of arrays that contain information about some famous bridges.

This example uses the filter function to return an array with the information about the bridge in Canada:

$CAN = from [{}] | eval bridges = [{name: "Tower Bridge", city: "London", country: "England"}, {name: "Rialto Bridge", city: "Venice", country: "Italy"}, {name: "Lions Gate Bridge", city: "Vancouver", country: "Canada"}, {name: "Golden Gate Bridge", city: "San Francisco", country: "United States"}] | eval result = filter(bridges, $obj -> $obj.country=="Canada")

The results look like this:

bridges result
[{"name": "Tower Bridge", "city": "London", "country": "England"}, {"name": "Rialto Bridge", "city": "Venice", "country": "Italy"}, {"name": "Lions Gate Bridge", "city": "Vancouver", "country": "Canada"}, {"name": "Golden Gate Bridge", "city": "San Francisco", "country": "United States"}] ["{\"name\": \"Lions Gate Bridge\", \"city\": \"Vancouver\", \"country\": \"Canada\"}"]

3. Filtering arrays nested in objects

The following example shows a dataset literal called $bridges that is a series of arrays of famous bridges. Each array contains a list of bridges for a specific country.

$bridges = FROM [ {famous_bridges: [{name: "Forth Bridge", city: "South Queensferry", country: "United Kingdom"}, {name: "Gateshead Millennium Bridge", city: "Gateshead", country: "United Kingdom"}, {name: "Clifton Suspension Bridge", city: "Bristol", country: "United Kingdom"}]}, {famous_bridges: [{name: "Rialto Bridge", city: "Venice", country: "Italy"}, {name: "Ponte Vecchio Bridge", city: "Florence", country: "Italy"}]}, {famous_bridges: [{name: "Helix Bridge", country: "Singapore"}]}, {famous_bridges: [{name: "Golden Gate Bridge", city:"San Francisco", country: "United States"}, {name: "Brooklyn Bridge", city:"New York City", country: "United States"}, {name: "Tilikum Crossing", city: "Portland", country: "United States"}]} ]

Each of the arrays becomes a separate event in the dataset, as shown here:

famous_bridges
[{"name": "Forth Bridge", "city": "South Queensferry", "country": "United Kingdom"}, {"name": "Gateshead Millennium Bridge", "city": "Gateshead", "country": "United Kingdom"}, {"name": "Clifton Suspension Bridge", "city": "Bristol", "country": "United Kingdom"}]
[{"name": "Rialto Bridge", "city": "Venice", "country": "Italy"}, {"name": "Ponte Vecchio Bridge", "city": "Florence", "country": "Italy"}]
[{"name": "Helix Bridge", "country": "Singapore"}]
[{"name": "Golden Gate Bridge", "city":"San Francisco", "country": "United States"}, {"name": "Brooklyn Bridge", "city":"New York City", "country": "United States"}, {"name": "Tilikum Crossing", "city": "Portland", "country": "United States"}]

You can use the filter function to return only the bridges in a specific country, such as Italy. The values for the country key in each object are compared to the value Italy in the lambda expression. Those objects that match that comparison are returned in an array.

$bridges = FROM [ {famous_bridges: [{name: "Forth Bridge", city: "South Queensferry", country: "United Kingdom"}, {name: "Gateshead Millennium Bridge", city: "Gateshead", country: "United Kingdom"}, {name: "Clifton Suspension Bridge", city: "Bristol"}]}, {famous_bridges: [{name: "Rialto Bridge", city: "Venice", country: "Italy"}, {name: "Ponte Vecchio Bridge", city: "Florence", country: "Italy"}]}, {famous_bridges: [{name: "Helix Bridge", country: "Singapore"}]}, {famous_bridges: [{name: "Golden Gate Bridge", city:"San Francisco", country: "United States"}, {name: "Brooklyn Bridge", city:"New York City", country: "United States"}, {name: "Tilikum Crossing", city: "Portland", country: "United States"}]} ] | eval italian_bridges = filter(famous_bridges, $bridge_object -> $bridge_object.country == "Italy")

The results look like this:

famous_bridges italian_bridges
[{"name": "Forth Bridge", "city": "South Queensferry", "country": "United Kingdom"}, {"name": "Gateshead Millennium Bridge", "city": "Gateshead", "country": "United Kingdom"}, {"name": "Clifton Suspension Bridge", "city": "Bristol", "country": "United Kingdom"}] []
[{"name": "Rialto Bridge", "city": "Venice", "country": "Italy"}, {"name": "Ponte Vecchio Bridge", "city": "Florence", "country": "Italy"}] [{\"name\": \"Rialto Bridge\", \"city\": \"Venice\", \"country\": \"Italy\"}, {\"name\": \"Ponte Vecchio Bridge\", \"city\": \"Florence\", \"country\": \"Italy\"}"]
[{"name": "Helix Bridge", "country": "Singapore"}] []
[{"name": "Golden Gate Bridge", "city":"San Francisco", "country": "United States"}, {"name": "Brooklyn Bridge", "city":"New York City", "country": "United States"}, {"name": "Tilikum Crossing", "city": "Portland", "country": "United States"}] []



map(<values>, <mapper>)

Iterates over the values in a JSON array and performs an operation on each value in the array. The array can be either in a field or an array literal.

This function returns a JSON array with the new values.

Usage

The map function uses two parameters:

  • The <values> parameter must be either a field that contains a JSON array or an array literal.
  • The <mapper> parameter must be a lambda expression. See Lambda expressions in the SPL2 Search Manual.

The map function can't evaluate fields specified in the mapper lambda expression.
For example, $a -> '${$a}' = "bar" is invalid.

You can use this function with the eval and where commands, in the SELECT and WHERE clauses of the from command, and as part of evaluation expressions with other commands. See the eval, where, and from commands.

How is the SPL2 map function different than the SPL map command?

The SPL2 map function is not the same as the SPL map command.

  • The SPL2 map function performs an operation over each value in a JSON array.
  • The SPL map command runs a search over each event or search result. The SPL map command is not supported in SPL2.

Example

1. Multiplying array values by a fixed number

Consider this set of data:

_time results
13 Apr 2023 13:02:45.000 PM [5,10,15]
13 Apr 2023 10:52:41.000 AM [10,20,30]
13 Apr 2023 06:23:48.000 AM [20,40,80]

The following search loops through the array values in the results field and multiplies each array value by 10. This example uses a lambda expression where $r represents the current element in the array.

... | eval new_results = map(results, $r -> $r*10)

The results look like this:

_time new_results results
13 Apr 2023 13:02:45.000 PM [50,100,150] [5,10,15]
13 Apr 2023 10:52:41.000 AM [100,200,300] [10,20,30]
13 Apr 2023 06:23:48.000 AM [200,400,800] [20,40,80]

reduce(<values>, <initialValue>, <accumulator>, <finalizer>)

Iterates over the values in a JSON array and performs an accumulation operation. The array can be either in a field or an array literal.

This function returns a single value.

Usage

The reduce function uses 4 parameters:

  • The <values> parameter is the name of field that contains JSON arrays or a literal JSON array.
  • The <initialValue> parameter specifies the initial value to pass to the accumulator parameter, such as 0 or {}.
  • The <accumulator> parameter is a lambda expression with 2 parameters, the first is the accumulated value and the second is the current element in the array. For example: ($acc, $it) -> $acc + $it.
  • Optional. The <finalizer> parameter is a lambda expression with 1 parameter that you can use to apply a calculation to the final value produced by the <accumulator> parameter.

See Lambda expressions in the SPL2 Search Manual.

You can use this function with the eval and where commands, in the SELECT and WHERE clauses of the from command, and as part of evaluation expressions with other commands. See the eval, where, and from commands.

Example

1. Compute the total of the values in a set of arrays

Consider this set of data:

_time numbers
12 Jul 2023 13:02:45.000 PM [5,10,15]
12 Jul 2023 10:52:41.000 AM [10,20,30]
12 Jul 2023 06:23:48.000 AM [20,40,80]

The following example computes a total for each array in the numbers field. The <initialValue> is 0. This example uses a lambda expression where $acc represents the accumulated value in the array and $it represents the current element that is being added to the accumulated value.

... | eval total = reduce(numbers, 0, ($acc, $it) -> $acc + $it)

The results look like this:

_time total numbers
12 Jul 2023 13:02:45.000 PM 30 [5,10,15]
12 Jul 2023 10:52:41.000 AM 60 [10,20,30]
12 Jul 2023 06:23:48.000 AM 140 [20,40,80]

2. Compute the average of the values in a set of arrays using the <finalizer> parameter

Consider this set of data:

_time numbers
12 Jul 2023 13:02:45.000 PM [5,10,15]
12 Jul 2023 10:52:41.000 AM [10,20,30]
12 Jul 2023 06:23:48.000 AM [20,40,80]

The following example computes the the average of each array in the numbers field. The example uses 2 calculations, sum and count to compute the average.

  • The <initialValue> for the sum and count calculations is 0.
  • The <accumulator> lambda expression computes the sum and count.
  • The <finalizer> lambda expression takes the accumulated sum $acc.sum and divides that number by the accumulated count $acc.count to compute the average value.

... | eval average = reduce(numbers, {sum: 0, count: 0}, ($acc, $it) -> {sum: $acc.sum + $it, count: $acc.count + 1}, $acc -> $acc.sum / $acc.count)

The results look like this:

_time total numbers
12 Jul 2023 13:02:45.000 PM 10 [5,10,15]
12 Jul 2023 10:52:41.000 AM 20 [10,20,30]
12 Jul 2023 06:23:48.000 AM 46.67 [20,40,80]

See also

Function information
Quick Reference for SPL2 eval functions
Overview of SPL2 eval functions
Naming function arguments in the SPL2 Search Manual
Related functions
mv_to_json_array
tojson
Related information
Access expressions for arrays and objects in the SPL2 Search Manual
Last modified on 03 October, 2024
Informational functions   Mathematical functions

This documentation applies to the following versions of Splunk® Cloud Services: current

Acrobat logo Download manual
Acrobat logo Download this page

Was this topic useful?







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