Command Reference jmespath

jmespath

Use a JMESpath query to extract and process elements from a JSON document. Simple extractions are comparable to spath but advanced queries can often reduce a Splunk search by removing the need for additional post-processing search commands.

Syntax

jmespath "<jmespath-string>" (input=<field>)? (output=<wc-field>)? (default=<string>)?

Description

Extract and pre-process data from a JSON document using the standard JMESPath query syntax If no input field is specified, then raw event will be assumed.

Syntax help and tutorials available at jmespath.org

Custom Functions

In addition to the default functions offered by JMESpath, the following functions were added to simplify common Splunk use cases:

Function	Arguments	Description
items(@)	Object	Return a hash as a set of key,value pairs
to_hash(@)	Array	Create a hash object from a list of key,value pairs (inverse of the items() function)
from_string(@)	Any	Parse a nested JSON string into its own object
unroll(@,key,value)	Array, String, String	Creates a hash from a list of hashes with key/value pairs. The names of the key and value fields must be passed to this function

Special considerations

Output wildcards

The output field can be a wild-carded field which changes the behavior of the jmespath search command to extract fields based on a given pattern rather than extracting everything to a single field. This can be quite helpful to extract multiple keys from a JSON object at once. This topic is covered completely in the Jmespath Output Modes page.

Quoting paths in JMESPath

Use double quotes to reference keys that contain unusual characters. This allows the use of symbols that would otherwise interfere with the JMESPath syntax. These double quotes typically need to be escaped because <jmespath-string> is often already quoted on the Splunk command line. Examples are provided on the Quoting page.

Converting from SPATH?

If you're already fairly familiar with the spath syntax that Splunk's native JSON extraction tool uses, than you can often convert an spath query to a jmespath query.

Example	spath syntax	jmespath syntax
Simple object mapping	cve.affects.vendor	cve.affects.vendor
Array references	cve.affects.vendor.vendor_data{}	"cve.affects.vendor.vendor_data[]"
Array index reference	cve.affects.vendor.vendor_data{0}	"cve.affects.vendor.vendor_data[0]"

Tips:

• Use a . between keys, like in spath.
• Convert {} to [] for array syntax. This works for both indicating an array and referencing a specific offset.
• Jmespath queries should generally be quoted because otherwise [] is interpreted as a subsearches. Avoid misleading error messages.

Often the translation is rather simple. But keep in mind that jmespath really excels at the more complex use cases, which cannot be expressed in spath at all. So the table above is really just to help you get started.

When to use jmespath vs spath?

There are many things spath can do that jmespath cannot, like process XML or recursively extract all fields from an event. As a native command, spath will always have a performance advantage over jmespath. When return a complex JSON object, spath will return the original string preserving spaces and key order, whereas jmsepath may reorder keys and change spacing. (The goal of the jmespath command is to provide a solution for complex JSON field extraction needs, not to replace spath.

So which should I use? Well, if switching to jmespath can simplify your search and replace a half-dozen commands, then do it. If spath is getting the job done, then great; there's no value in a one to one replacement for simple field extractions.

Examples

Extract all the URLs from the relatedContent object

jmespath output=url "relatedContent[].url"

Unroll a list of nested hashes

Unroll a list of nested hashes into a set of fields with a custom prefix. In this example an input like:

{ "config" : [ {"Name": "ip", "Value": "10.1.1.9"}, ...] }

Will extract a new field: cfg.ip="10.1.1.9"

Command:

jmespath output=cfg.* "config[] | unroll(@,'Name','Value')

Extract nested JSON

Extract nested JSON from additionalTagets contained within an Office 365 Azure AD management event

jmespath output=additionalTargets "ExtendedProperties[?Name=='additionalTargets'].Value | from_string(@)"

Tutorial

Additional content and run-anywhere examples are available on Search Examples: jmespath.