Splunk® Enterprise

Search Reference

Download manual as PDF

Download topic as PDF



The spath command enables you to extract information from the structured data formats XML and JSON. The command stores this information in one or more fields. The command also highlights the syntax in the displayed events list.

You can also use the spath() function with the eval command. For more information, see the evaluation functions.


spath [input=<field>] [output=<field>] [path=<datapath> | <datapath>]

Optional arguments

Syntax: input=<field>
Description: The field to read in and extract values.
Default: _raw
Syntax: output=<field>
Description: If specified, the value extracted from the path is written to this field name.
Default: If you do not specify an output argument, the value for the path argument becomes the field name for the extracted value.
Syntax: path=<datapath> | <datapath>
Description: The location path to the value that you want to extract. The location path can be specified as path=<datapath> or as just datapath. If you do not specify the path=, the first unlabeled argument is used as the location path. A location path is composed of one or more location steps, separated by periods. An example of this is 'foo.bar.baz'. A location step is composed of a field name and an optional index surrounded by curly brackets. The index can be an integer, to refer to the position of the data in an array (this differs between JSON and XML), or a string, to refer to an XML attribute. If the index refers to an XML attribute, specify the attribute name with an @ symbol.


The spath command is a distributable streaming command. See Command types.

Location path omitted

When used with no path argument, the spath command runs in "auto-extract" mode. In the "auto-extract" mode, the spath command finds and extracts all the fields from the first 5000 characters in the input field. These fields default to _raw if another input source is not specified. If a path is provided, the value of this path is extracted to a field named by the path or to a field specified by the output argument, if the output argument is provided.

A location path contains one or more location steps

A location path contains one or more location steps, each of which has a context that is specified by the location steps that precede it. The context for the top-level location step is implicitly the top-level node of the entire XML or JSON document.

The location step is composed of a field name and an optional array index

The location step is composed of a field name and an optional array index indicated by curly brackets around an integer or a string.

Array indices mean different things in XML and JSON. For example, JSON uses zero-based indexing. In JSON, foo.bar{3} refers to the fourth element of the bar child of the foo element. In XML, this same path refers to the third bar child of foo.

Using wildcards in place of an array index

The spath command lets you use wildcards to take the place of an array index in JSON. Now, you can use the location path entities.hashtags{}.text to get the text for all of the hashtags, as opposed to specifying entities.hashtags{0}.text, entities.hashtags{1}.text, and so on. The referenced path, here entities.hashtags, has to refer to an array for this to make sense. Otherwise, you get an error just like with regular array indices.

This also works with XML. For example, catalog.book and catalog.book{} are equivalent. Both get you all the books in the catalog.

Alternatives to the spath command

If you are using autokv or index-time field extractions, the path extractions are performed for you at index time.

You do not need to explicitly use the spath command to provide a path.

If using indexed_extractions=JSON or using KV_MODE=JSON in the props.conf file, then the spath command is not necessary to explicitly use.

Basic examples

1. Specify an output field and path

This example shows how to specify a output field and path.

... | spath output=myfield path=foo.bar.baz

2. Specify just the <datapath>

For the path argument, you can specify the location path with or without the path=. In this example the <datapath> is server.name.

... | spath output=myfield server.name

3. Specify an output field and path based on an array

For example, you have this array.

   "foo" : [1,2]

To specify the output field and path, use this syntax.

... | spath output=myfield path=foo{1}

4. Specify an output field and a path that uses a nested array

For example, you have this nested array.

   "foo" : {
      "bar" : [
         {"zoo" : 1},
         {"baz" : 2}

To specify the output and path from this nested array, use this syntax.

... | spath output=myfield path=foo.bar{}.baz

5. Specify the output field and a path for an XML attribute

Use the @ symbol to specify an XML attribute. Consider the following XML list of books and authors.

<?xml version="1.0">
         <author>Martin, George R.R.</author>
         <title yearPublished=1996>A Game of Thrones</title>
         <title yearPublished=1998>A Clash of Kings</title>
         <author>Clarke, Susanna</author>
         <title yearPublished=2004>Jonathan Strange and Mr. Norrell</title>
         <author>Kay, Guy Gavriel</author>
         <title yearPublished=1990>Tigana</title>
         <author>Bujold, Lois McMasters</author>
         <title yearPublished=1986>The Warrior's Apprentice</title>

Use this search to return the path for the book and the year it was published.

... | spath output=dates path=purchases.book.title{@yearPublished} | table dates

In this example, the output is a single multivalue result that lists all of the years the books were published.

Extended examples

1: GitHub

As an administrator of a number of large Git repositories, you want to:

  • See who has committed the most changes and to which repository
  • Produce a list of the commits submitted for each user

Suppose you are Indexing JSON data using the GitHub PushEvent webhook. You can use the spath command to extract fields called repository, commit_author, and commit_id:

... | spath output=repository path=repository.url

... | spath output=commit_author path=commits{}.author.name

... | spath output=commit_id path=commits{}.id

To see who has committed the most changes to a repository, run the search.

... | top commit_author by repository

To see the list of commits by each user, run this search.

... | stats values(commit_id) by commit_author

2: Extract a subset of a XML attribute

This example shows how to extract values from XML attributes and elements.

<vendorProductSet vendorID="2">
            <product productID="17" units="mm" >
                <prodName nameGroup="custom">
                    <locName locale="all">APLI 01209</locName>
                <desc descGroup="custom">
                    <locDesc locale="es">Precios</locDesc>
                    <locDesc locale="fr">Prix</locDesc>
                    <locDesc locale="de">Preise</locDesc>
                    <locDesc locale="ca">Preus</locDesc>
                    <locDesc locale="pt">Preços</locDesc> 

To extract the values of the locDesc elements (Precios, Prix, Preise, etc.), use:

... | spath output=locDesc path=vendorProductSet.product.desc.locDesc

To extract the value of the locale attribute (es, fr, de, etc.), use:

... | spath output=locDesc.locale path=vendorProductSet.product.desc.locDesc{@locale}

To extract the attribute of the 4th locDesc (ca), use:

... | spath path=vendorProductSet.product.desc.locDesc{4}{@locale}

3: Extract and expand JSON events with multi-valued fields

The mvexpand command only works on one multivalued field. This example walks through how to expand a JSON event with more than one multivalued field into individual events for each field's values. For example, given this event with sourcetype=json:

{"widget": {
    "text": {
        "data": "Click here",
        "size": 36,
        "data": "Learn more",
        "size": 37,
        "data": "Help",
        "size": 38,

First, start with a search to extract the fields from the JSON. Because no path argument is specified, the spath command runs in "auto-extract" mode and extracts all of the fields from the first 5000 characters in the input field. The fields are then renamed and placed in a table.

sourcetype=json | spath | rename widget.text.size AS size, widget.text.data AS data | table _time,size,data

           _time            size    data
--------------------------- ---- -----------
2018-10-18 14:45:46.000 BST   36 Click here
                              37 Learn more
                              38 Help

Then, use the eval function, mvzip(), to create a new multivalued field named x, with the values of the size and data:

sourcetype=json | spath | rename widget.text.size AS size, widget.text.data AS data | eval x=mvzip(data,size) | table _time,data,size,x

           _time                data    size        x
--------------------------- ----------- ----- --------------
2018-10-18 14:45:46.000 BST Click here   36   Click here,36
                            Learn more   37   Learn more,37
                            Help         38   Help,38

Now, use the mvexpand command to create individual events based on x and the eval function mvindex() to redefine the values for data and size.

sourcetype=json | spath | rename widget.text.size AS size, widget.text.data AS data | eval x=mvzip(data,size)| mvexpand x | eval x = split(x,",") | eval data=mvindex(x,0) | eval size=mvindex(x,1) | table _time,data, size

           _time                data   size
--------------------------- ---------- ----
2018-10-18 14:45:46.000 BST Click here  36
2018-10-18 14:45:46.000 BST Learn more  37
2018-10-18 14:45:46.000 BST Help        38

(Thanks to Splunk user G. Zaimi for this example.)

See also

extract, kvform, multikv, regex, rex, xmlkv, xpath


Have questions? Visit Splunk Answers and see what questions and answers the Splunk community has using the spath command.


This documentation applies to the following versions of Splunk® Enterprise: 6.0, 6.0.1, 6.0.2, 6.0.3, 6.0.4, 6.0.5, 6.0.6, 6.0.7, 6.0.8, 6.0.9, 6.0.10, 6.0.11, 6.0.12, 6.0.13, 6.0.14, 6.0.15, 6.1, 6.1.1, 6.1.2, 6.1.3, 6.1.4, 6.1.5, 6.1.6, 6.1.7, 6.1.8, 6.1.9, 6.1.10, 6.1.11, 6.1.12, 6.1.13, 6.1.14, 6.2.0, 6.2.1, 6.2.2, 6.2.3, 6.2.4, 6.2.5, 6.2.6, 6.2.7, 6.2.8, 6.2.9, 6.2.10, 6.2.11, 6.2.12, 6.2.13, 6.2.14, 6.2.15, 6.3.0, 6.3.1, 6.3.2, 6.3.3, 6.3.4, 6.3.5, 6.3.6, 6.3.7, 6.3.8, 6.3.9, 6.3.10, 6.3.11, 6.3.12, 6.3.13, 6.3.14, 6.4.0, 6.4.1, 6.4.2, 6.4.3, 6.4.4, 6.4.6, 6.4.8, 6.4.10, 6.4.11, 6.5.1, 6.5.1612 (Splunk Cloud only), 6.5.2, 6.5.3, 6.5.4, 6.5.5, 6.5.6, 6.5.7, 6.5.8, 6.5.9, 6.5.10, 6.6.0, 6.6.1, 6.6.2, 6.6.3, 6.6.4, 6.6.5, 6.6.6, 6.6.7, 6.6.8, 6.6.9, 6.6.10, 6.6.11, 6.6.12, 7.0.0, 7.0.1, 7.0.2, 7.0.3, 7.0.4, 7.0.5, 7.0.6, 7.0.7, 7.0.8, 7.0.9, 7.0.10, 7.0.11, 7.1.0, 7.1.1, 7.1.2, 7.1.3, 7.1.4, 7.1.5, 7.1.6, 7.1.7, 7.1.8, 7.1.9, 7.2.0, 7.2.1, 7.2.2, 7.2.3, 7.2.4, 7.2.5, 7.2.6, 7.2.7, 7.2.8, 7.3.0, 7.3.1, 7.3.2, 8.0.0, 6.4.5, 6.4.7, 6.4.9, 6.5.0


How can i use this command?
| spath output=type path=phoneNumbers{?(@.isbn=="0-395-19395-8")}.type

For this JSON:
"firstName": "John",
"lastName" : "doe",
"age" : 26,
"address" : {
"streetAddress": "naist street",
"city" : "Nara",
"postalCode" : "630-0192"
"phoneNumbers": [
"type" : "iPhone",
"number": "0123-4567-8888",
"isbn": "0-395-19395-8"
"type" : "home",
"number": "0123-4567-8910"

December 16, 2018

Thanks for the feedback on example #4. There were several problems with this example. I determined that the XML was missing an end </book> tag, the path specified was not correct, and that the search example did not include an XML attribute, so using the @ symbol did not return anything.
I have corrected the example. There is a more detailed example of extracting attributes in example #6.

Lstewart splunk, Splunker
August 15, 2017

The example #4 (XML - books and authors) doesn't work. The spath command shown returns zero results. I haven't yet figured out the proper syntax.

Sowings, Splunker
August 10, 2017

Thank you for pointing out the zero-based indexing. I've corrected the description.

Lstewart splunk, Splunker
September 1, 2016

Your documentation says, " foo.bar{3} refers to the third element of the bar child of the foo element.". That is not true. The indexing is (thankfully) zero-based, so "foo.bar{3}" actually refers to the *fourth* element.

July 15, 2016

I have fixed the typo. I don't know who came up with that example, but thanks for pointing out the problems. I'll look in this and get the example corrected.

Lstewart splunk, Splunker
May 23, 2016


> fields's values.


Regarding your example JSON:

{"widget": {
"text": {
"data": "Click here",
"size": 36,
"data": "Learn more",
"size": 37,
"data": "Help",
"size": 38,

Setting aside the missing closing brace and the trailing comma...

From RFC 7159 (https://tools.ietf.org/html/rfc7159#section-4):

> The names within an object SHOULD be unique.

(There's more, but I'll leave the rest to the link.)

Your thoughts? Did you confect that JSON - with its multiple "data" and "size" object names - yourself, or did you base it on JSON generated by an application (which one)?

Graham Hannington
May 23, 2016

Would also like to know a way to use SPATH in transforms, I am using input="field" and can't figure out how to do that using KV_MODE=json.

September 18, 2014

How do I put spath in transforms.conf to enable the auto extractions of the fields instead of manual retrieval ?

June 6, 2014

Example are good, but to me it is not clear why in : "Example 3: Extract and expand JSON events with multvalued fields" you first concatenate all values in X, then made an vmexpand, and then split it to have seperate values... ?<br />Could you explain a little more that part ?

November 21, 2012

Example of the JSON payload would help.

July 20, 2012

Was this documentation topic helpful?

Enter your email address, and someone from the documentation team will respond to you:

Please provide your comments here. Ask a question or make a suggestion.

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