JSON functions

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

Description	JSON function
Create a new JSON object from key-value pairs.	json_object
Evaluate whether a value can be parsed as JSON. If the value is JSON, the function returns the value. Otherwise, the function returns null.	json
Append elements to the contents of a valid JSON object.	json_append
Create a JSON array using a list of values.	json_array
Map the elements of a JSON array to a multivalued field.	json_array_to_mv
Remove one or more keys and their corresponding values from the specified JSON object.	json_delete
Convert a field to an array of JSON objects with key and value fields.	json_entries
Extend the contents of a valid JSON object with the values of an array.	json_extend
Return either a JSON array or a Splunk software native type value from a field and zero or more paths.	json_extract
Return Splunk software native type values from a piece of JSON by matching literal strings in the event and extracting them as keys.	json_extract_exact
Returns TRUE if the field value is a JSON key in the provided JSON object.	json_has_key_exact
Returns the keys from the key-value pairs in a JSON object. The keys are returned as a JSON array.	json_keys
Insert or overwrite values for a JSON node with the values provided and return an updated JSON object.	json_set
Generate or overwrite a JSON object using the key-value pairs specified.	json_set_exact
Evaluate whether a JSON object uses valid JSON syntax and returns either TRUE or FALSE.	json_valid

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, and as part of evaluation expressions with other 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", json_array("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 or JSON array field called gamelist.

...| eval gamelist = json_array("Pandemic", "Forbidden Island", "Castle Panic"), 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

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

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)

The search results look something like this:

_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 JSON arrays or objects.

Consider the following search results:

_time	bridges	city
2023-04-26 21:10:45	["bridges",{"name":"Tower Bridge"},{"length":"801"},{"name":"Millennium Bridge"},{"length":"1066"}]	London
2023-04-26 21:10:45	["bridges",{"name":"Rialto Bridge"},{"length":"157"},{"name":"Bridge of Sighs"},{"length":"36"},{"name":"Ponte della Paglia"}]	Venice
2023-04-26 21:10:45	Golden Gate Bridge	San Francisco

When you add the json evaluation function to the following 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 in the bridgesAsJson field. When the value is not JSON, the function returns null. The results look like something like this:

_time	bridges	bridgesAsJson	city
2023-04-26 21:10:45	["bridges",{"name":"Tower Bridge"},{"length":"801"},{"name":"Millennium Bridge"},{"length":"1066"}]	[{"name":"Tower Bridge","length":801}, {"name":"Millennium Bridge","length":1066}]	London
2023-04-26 21:10:45	[{"name":"Rialto Bridge","length":157}, {"name":"Bridge of Sighs","length":36}, {"name":"Ponte della Paglia"}]	[{"name":"Rialto Bridge","length":157}, {"name":"Bridge of Sighs","length":36}, {"name":"Ponte della Paglia"}]	Venice
2023-04-26 21:10:45	Golden Gate Bridge		San Francisco

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, 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 autowraps the scalar or object value within an array and adds the corresponding <value> to the end of that array.

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

Example

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

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

Use json_delete to remove 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 arguments:

• The <object> argument identifies the JSON object from which you want to delete key-value pairs.
• The <keys> argument 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, and as part of evaluation expressions with other commands. See the eval and where 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 doesn't 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.

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

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

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.

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

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

Consider the following JSON object, which contains Buttercup Games supplier information including a nested object with address information.

{"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 uses the eval command with the json_delete function to remove the email key-value pair from the addresses nested object. A new JSON object is returned in a field called cleaned.

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

json_entries(<value>)

Description

This function takes a JSON object and returns an array that contains the top-level fields expressed in key-value pairs.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

This function is used by type tests to confirm that the format of an object is what is required and expected.

Basic examples

The following search returns [{"key":"a","value":1},{"key":"b","value":2}] in the entries field.

| makeresults | eval entries=json_entries("{\"a\": 1, \"b\": 2}")

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.

json_extend 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 autowraps the scalar or object value within an array and adds the corresponding array values to the end of that array.

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 of JSON and zero or more paths. The value is returned in either a JSON array, or a Splunk software native type value.

If a JSON object contains a value with a special character, such as a period, json_extract can't access it. Use the json_extract_exact function for those situations.

See json_extract_exact.

Usage

What is converted or extracted depends on whether you specify a 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, 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 extracted_cities = json_extract(cities,"{}")

Here are the results of the search:

Field	Results
extract_cities	{"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.

The {<num>} indexing demonstrated in this example search only works when the <path> maps to a JSON array. In this case the {0} maps to the "0" item in the array, which is London. If the example used {1} it would select Venice from the array.

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

Here are the results of the search:

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

Here are the results of the search:

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

Here are the results of the search:

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{}")

Here are the results of the search:

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

Here are the results of the search:

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

Here are the results of the search:

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

Here are the results of the search:

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, and as part of evaluation expressions with other commands.

Example

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_has_key_exact(json_object(<key>, <value>), <JSON object>)

Description

This function takes one argument and evaluates whether the field is an object. The function returns TRUE if a string is a valid JSON object and the valid JSON is an object.

Usage

You can use this function with the eval, fieldformat, and where commands, and as part of eval expressions.

Basic examples

The following searches returns the same result and indicate that the "charlie.garcia" key exists in the provided JSON object. The function treats the dot character ( . ) in "charlie.garcia" as a string literal, not as a nested object in JSON format.

| makeresults |eval test=if(json_has_key_exact(json_object("charlie.garcia", 1), "charlie.garcia"), "has key", "doesn't have key")

| makeresults | eval test=if(json_has_key_exact("{\"charlie.garcia\":10}", "charlie.garcia"), "has key", "doesn't have key")

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

Similar to the json_set_exact function. See json_set_exact

Usage

You can use this function with the eval and where commands, 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(json_object("name", "Settlers of Catan"), json_object("name", "Terraforming Mars"), json_object("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 the json_set_exact function with the eval and where commands, 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

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

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

To generate this object, you can use the makeresults command and the json_set_exact function as shown in the following search:

| makeresults | eval my_object=json_object(), splunk_path=json_set_exact(my_object, "system.splunk.path", "/opt/splunk")

You use json_set_exact for this instead of json_set 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 a 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, and as part of evaluation expressions with other commands.

Example

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

Because fields cannot hold Boolean values, the if function is used with the json_valid function to place the string value equivalents of the Boolean values into the isValid field.

... | eval IsValid = if(json_valid(firstnames), "true", "false")

See also

Function information

Evaluation functions quick reference

Related functions

mv_to_json_array function

Related commands

tojson

fromjson