JSON Query

A function is defined as a function name followed by comma separated arguments wrapped in round brackets. it is important to understand functions like filter, sort, and max are executed as a method in a chain: the operation is applied to the data input, and forwarded to the next method in the chain (if any).

Examples:

sort(.address.city, "asc")

filter(.age >= 21) | sort(.age, "asc")

Documentation: Functions

Function reference:

• get(prop1, prop2)
• filter(condition)
• sort(property, direction)
• reverse()
• pick(property1, property2, ...)
• map(callback)
• mapObject(callback)
• mapKeys(callback)
• mapValues(callback)
• pipe(query1, query2, ...)
• object({ prop1: query1, prop2: query2, ...)
• array(query1, query2, ...)
• groupBy(property)
• keyBy(property)
• keys()
• values()
• flatten()
• join(separator)
• split(text, separator)
• substring(text, start, end)
• uniq()
• uniqBy(property)
• limit(size)
• size()
• sum()
• min()
• max()
• prod()
• average()
• not(value)
• exists(property)
• if(condition, valueIfTrue, valueIfFalse)
• regex(text, expression, options)
• round(value, digits)
• abs(value)
• number(text)
• string(number)

JSON Query supports all basic operators. When composing multiple operators, it is necessary to use parentheses. Operators do not have precedence since parentheses are required.

Examples:

(.age >= 18)

(.age >= 18) and (.age <= 65))

Documentation: Operators

Operator reference:

• a == b
• a > b
• a >= b
• a < b
• a <= b
• a != b
• a and b
• a or b
• a in [value1, value2, ...]
• a not in [value1, value2, ...]
• a + b
• a - b
• a * b
• a / b
• a ^ b
• a % b

A pipe is an array containing a series of queries. The queries in the pipeline are executed one by one, and the output of the first is the input for the next.

Example:

filter(.age >= 18) | sort(.name)

Documentation: Pipes

An object is defined as a regular JSON object with a property name as key, and a query as value. Objects can be used to transform data or to execute multiple query pipelines in parallel.

Example:

{
  names: map(.name),
  numberOfNames: size()
}

Documentation: Objects

An array is defined as a regular JSON array: enclosed in square brackets, with items separated by a comma.

Example:

filter(.city in ["New York", "Atlanta"])

Documentation: Arrays

A property retrieves a property from an object. Multiple consecutive properties will retrieve a nested property.

Examples:

.age

.address.city

"first name"

get()

get("address", "city")

Documentation: Properties

JSON Query supports the following primitive values, the same as in JSON: "string", number, boolean, null.

Examples:

"Hello world"

"Multi line text\nwith \"quoted\" contents"

42

2.74

-1.2e3

true

false

null

Documentation: Values