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 |
Create a JSON array using a list of values. | json_array |
Return either a JSON array or a Splunk software native type value from a field and zero or more paths. | json_extract |
Insert or overwrite values for a JSON node with the values provided and return an updated JSON object. | json_set |
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.
To use named arguments, you must specify the pairs of arguments in an array, enclosing the values in square brackets. The syntax for named arguments is json_object(members: [<key>, <value>,...])
. For example:
... json_object(members: ["name", "maria", "surname", "dubois"])
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 keyname
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 or 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_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.
To use named arguments, you must specify the values in an array, enclosing the values in square brackets. The syntax for named arguments is json_array(values: [<value>, <value>...])
. For example:
... json_array(values: ["buttercup", "fluttershy", "rarity"])
Examples
These examples show different ways to use the json_array
function to create JSON arrays in your events.
Create a basic JSON array
- The following example creates a simple array
["buttercup", "fluttershy", "rarity"]
.
... | eval ponies = json_array("buttercup", "fluttershy", "rarity")
Create an JSON array from a string and a JSON object
- The following example uses a string
dubois
and thejson_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_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:
|
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.
To use named arguments, you must specify the paths in an array, enclosing the values in square brackets. The syntax for named arguments is json_extract(json:<json>, paths:[<path>, <path>...])
. For example:
... json_extract(json: cities, paths:["cities{}.name", "cities{}.Bridges{}"])
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. Thecities
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 {"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,"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,"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,"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,"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,"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,"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,"cities{2}.Bridges{0}.length")
Field Results GG_Bridge_length 8981
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, 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.
To use named arguments, you must specify the path value pairs in an array, enclosing the pairs in square brackets. The syntax for named arguments is json_set(json:<json>, path_value_pairs:[<path>, <value>...])
. For example:
... json_set(json:games, path_value_pairs:["category.boardgames.cooperative{2}", "name":"Sherlock Holmes: Consulting Detective"])
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 calledmy_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. Thejson_array
function is used to append the value list to theboardgames
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. Thejson_array
function is used to append the key-value pairs list to theboardgames
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 theavailable
key with the valuefalse()
.
- 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_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, and as part of evaluation expressions with other commands.
To use named arguments, you must specify the argument name before the argument value. For example:
... json_valid(json:names)
Example
Validate a JSON object
- The following example validates a JSON object
{ "names": ["maria", "arun"] }
in thefirstnames
field.
- Because fields cannot hold Boolean values, the
if
function is used with thejson_valid
function to place the string value equivalents of the Boolean values into theisValid
field. ... | eval IsValid = if(json_valid(firstnames), "true", "false")
See also
- Functions
- Evaluation functions quick reference
Informational functions | Mathematical functions |
This documentation applies to the following versions of Splunk® Enterprise: 8.0.0, 8.0.1, 8.0.2, 8.0.3, 8.0.4, 8.0.5, 8.0.6, 8.0.7, 8.0.8, 8.0.9, 8.0.10
Feedback submitted, thanks!