Chapter 7. JSON Navigation

7.1. Object Navigation
7.2. Array Unboxing
7.3. Sequence Filtering
7.4. Array Navigation

Like in JavaScript or SQL or Java, it is possible to navigate through data.

JSONiq supports:

Looking up the value of a field (given its string key) in an object.
Looking up the item at a given position (integer) in an array.
Extracing all members of an array as a sequence of items.
Filtering items from a sequence, retaining only the items that match a given criterium.

7.1. Object Navigation

The simplest way to navigate an object is similar to JavaScript. This will work as soon as you do not push it too much: alphanumerical characters, dashes, underscores. The rule for unquoted names is similar to keys in object constructions, and to variable names. The empty sequence is returned if no key is found with the specified name.

Example 7.1. Object lookup.

{
  "question" : "What NoSQL technology should I use?"
}.question,
{
  "question" : "What NoSQL technology should I use?"
}.answer

Results:

"What NoSQL technology should I use?"

Since JSONiq expressions are composable, you can also use any expression for the left-hand side. You might need parentheses depending on the precedence.

Example 7.2. Lookup on a single-object collection.

collection("one-object").question

Results:

"What NoSQL technology should I use?"

The dot operator does an implicit mapping on the left-hand-side, i.e., it applies the lookup in turn on each item. Lookup on any item which is not an object (arrays and atomics) results in the empty sequence.

Example 7.3. Object lookup with an iteration on several objects.

({ "foo" : "bar" }, { "foo" : "bar2" } ).foo,
{ "ids" : collection("faqs").question_id }

Results:

"bar"
"bar2"
{
  "ids" : [ 4419499, 282783, 4720508, 5453872, 6183352 ]
}

Example 7.4. Object lookup on non-objects.

"foo".foo,
({
  "question" : "What NoSQL technology should I use?"
},
 [ "question", "answer" ],
 { "question" : "answer" },
 "question").question

Results:

"What NoSQL technology should I use?"
"answer"

Of course, unquoted keys will not work for strings that are not unquoted names, e.g., if the field contains a dot or begins with a digit. Then you will need quotes. If you use a more general expression on the right-hand side of the dot, it must always have parentheses.

Example 7.5. Quotes and parentheses for object lookup.

{
  "my question" : "What NoSQL technology should I use?"
}."my question",
{
  "my question" : "What NoSQL technology should I use?"
}.("my " || "question")

Results:

"What NoSQL technology should I use?"
"What NoSQL technology should I use?"

The value returned by the right-hand side expression is cast to string. An error is raised upon failure. This value may be the empty sequence, in which case the object lookup also returns the empty sequence.

Example 7.6. Object lookup with a nested expression.

{
  "question" : "What NoSQL technology should I use?"
}.(),
{
  "1" : "What NoSQL technology should I use?"
}.(1),
{
  "1" : "What NoSQL technology should I use?"
}."1"

Results:

"What NoSQL technology should I use?"
"What NoSQL technology should I use?"

Variables, or a context item reference, do not need parentheses. Variables are introduced in Section 10.1, “Variables”, but here is a sneak peek:

Example 7.7. Object lookup with a variable.

let $field := "my " || "question"
return { 
  "my question" : "What technology should I use?"
}.$field

Results:

"What technology should I use?"