Access expressions for arrays and objects

You access array and object values by using expressions and specific notations.

You can specify these expressions in the SELECT clause of the from command, with the eval command, or as part of evaluation expressions with other commands.

There are two notations that you can use to access values, the dot ( . ) notation and the square bracket [ ] notation. The notation you use depends on the type of value you want to access:


Type of value	Notation you can use
array values	square bracket
object values	dot square bracket

Keys and values are case sensitive in expressions

You must specify keys and values in expressions in the case in which the values appear in the data. For example, if you are searching for Games you cannot specify games.

Accessing values in arrays

Consider the following array of competitive board games:

{
  "games": ["Settlers of Catan","Terraforming Mars","Ticket to Ride"]
}

To access Ticket to Ride in the array, you specify the index position using square bracket [ ] notation. Ticket to Ride is in the third position. Because the index count starts with 0, the third position is 2.

Here's an example:

...| eval competitive=games[2]

Here is another set of data that consists of a set of nested objects and an array of game names:

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

To return Forbidden Island from the array of cooperative boardgames, you must specify the path and index position of the game in the array. Here's the expression to use in your search:

...| eval name=games.category.boardgames.cooperative[1]

For the path, use dots ( . ) between each key in the path.
For the array that lists the names of the games, use the square bracket [ ] notation.

Accessing values in objects

Consider this set of data about famous bridges in various 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 }
      ]
    }
  ]
}]

To access the values in objects, you can use either the dot ( . ) notation or the square bracket ( [ ] ) notation in the expressions

Using dot ( . ) notation

Using the city bridges array, here's an example of the dot ( . ) notation expression you use to access information about the Millennium Bridge:

...| eval bridge_info=cities[0].Bridges[1]

This expression specifies the first object inside the cities array, followed by the second object in the Bridges array.

This example returns {"name": "Millennium Bridge", "length": 1066}.

To return only the name of the bridge, use this expression:

...| eval bridge_info=cities[0].Bridges[1].name

This example returns Millennium Bridge.

Using square bracket ( [ ] ) notation

You can also use the square bracket ( [ ] ) notation expression to access information about the Millennium Bridge. Here's an example:

...| eval bridge_name=cities[0]["Bridges"][1]

This expression returns {"name": "Millennium Bridge", "length": 1066}.

To specify the path to the name of the bridge, use this expression:

...| eval bridge_name=cities[0]["Bridges"][1]["name"]

This example returns Millennium Bridge.

Note: If the value you want to access is a string, you must enclose the value in double quotation marks. If the value is a field name, you don't need to use quotation marks.

Expression examples

When specifying the position index, you can use any type of expression.

For example, the following search uses the field name expression index and the numeric expression 5-4 with the the dot ( . ) notation:

...| eval index=0, bridge_name=cities[index].Bridges[5 - 4]

For types of valid expressions, see Types of expressions.

Keys that are reserved words

If a key in a key-value path is a reserved word, such as a command or function name, or a keyword, you must enclose the key in single quotation marks. See Reserved words in the SPL2 Search Reference.

Consider this set of data which uses group as the key for an array:

{
  "boardgames": {
     "group": {
         "cooperative": [ "Pandemic", "Forbidden Island", "Castle Panic" ],
         "competitive": [ "Settlers of Catan", "Terraforming Mars", "Ticket to Ride"]
    }
  }
}

Because group is a reserved word, you must enclose it in single quotation marks when you use the key in an expression:

...| eval game_name=boardgames.'group'.competitive[2]

This eval command returns a new field called game_name with the value Ticket to Ride.

Documentation