SODA Paths (Reference)

4 SODA Paths (Reference)

SODA filter specifications contain paths, each of which targets a value in a JavaScript Object Notation (JSON) document. A path is composed of a series of steps. A detailed definition of SODA paths is presented.

Note:

A SODA QBE is itself a JSON object. You must use strict JSON syntax in a QBE. In particular, you must enclose all field names in double quotation marks ("). This includes field names, such as address.zip, that act as SODA paths. For example, you must write {"address.zip" : 94088}, not {address.zip : 94088}.

The following characters can have special syntactic meaning in some SODA path steps, in which case their use in that context is called syntactic (they are used syntactically):

Brackets ([ and ]) delimit a JSON array
Comma (,) separates array elements or array index components
Wildcard (*) is a placeholder that matches any array index in an array step or any field name in a field step (defined below)
Period (.) separates a parent-object field name (or *) from a child-object field name (or *)

In any other path-expression context than those just listed, these same characters have no special syntactic meaning. For example, outside of its use in array syntax a comma is not used syntactically.

A character that is not used syntactically in a given context is ordinary in that context. For example, a comma is ordinary outside of its use in array syntax, and the character d is always ordinary.

There are two kinds of steps in a path: field steps and array steps.

A field step is one of the following:

The wildcard character * (by itself)
A sequence of characters that are always ordinary — for example, cat
A sequence of any characters that is enclosed in backquote characters (`) — for example, `dog` and `cat.dog`

Characters within a field step that is enclosed in backquote characters are not used syntactically; they are treated literally. If you intend for a character not to be used syntactically where it normally would be then you must enclose its step in backquote characters.

All of the characters in field name dog are always ordinary, so backquote characters are optional in `dog`. But the following field steps must be enclosed in backquote characters because each contains one or more characters that would otherwise be used syntactically:

`cat.dog`
`cat[dog]`
`*`

In the path a.*.b, the asterisk acts as a wildcard; it is a placeholder for a field name. But in the path a.`*`.b the asterisk does not act as a wildcard. Because it is escaped by backquotes it acts as an ordinary character — a field named *. (In both cases the unescaped periods are used syntactically.)

Besides using backquotes to inhibit special syntactic meaning, you can use them to escape a dollar-sign character ($) at the beginning of a field name, where it would otherwise be interpreted as introducing a SODA operator name. For example, because of the backquote characters, the field step `$eq` does not represent SODA operator $eq; it represents an ordinary JSON field that has the same name. (Needing to query data that has field names that begin with $ is rare.)

If a step that you enclose in backquote characters contains a backquote character, then you must represent that character using two consecutive backquote characters. For example: `Customer``s Comment`.

An unescaped period (.) must be followed by a field step. After the first step in a path, each field step must be preceded by a period.

An array step is delimited by brackets ([ and ]). Inside the brackets can be either:

The wildcard character * (by itself)
One or more of these array index (position) components:
- A single array index, which is an integer greater than or equal to zero
- An array index range, which has this syntax:
```
x to y
```
  x and y are integers greater than or equal to zero, and x is less than or equal to y. There must be at least one whitespace character between x and to and between to and y.
Multiple components must be separated by commas (,). In a list of multiple components, array indexes must be in ascending order, and ranges cannot overlap.

For example, these are valid array steps:

[*]
[1]
[1,2,3]
[1 to 3]
[1, 3 to 5]

The following are not valid array steps:

[*, 6]
[3, 2, 1]
[3 to 1]
[1 to 3, 2 to 4]