JSON Query Language

https://jsonquerylang.org/
Admin
JSON Query Language is a powerful language for querying and transforming JSON data using functions,...
Tokens:19,355
Snippets:233
Trust Score:7.3
Update:3 months ago
Show doc for...
Tokens:
Raw
### Function Usage Examples

Source: https://jsonquerylang.org/docs

Examples demonstrating sorting and chaining functions.

```text
sort(.age, "asc")
```

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

--------------------------------

### Operator Usage Examples

Source: https://jsonquerylang.org/docs

Examples showing how to apply operators for property testing and filtering.

```text
.age >= 18
```

```text
filter(.age >= 18)
```

```text
filter(.age >= 18 and .age <= 65)
```

--------------------------------

### Install JSON Query for Python

Source: https://jsonquerylang.org/implementations

Use pip to install the jsonquerylang package.

```bash
pip install jsonquerylang
```

--------------------------------

### Install JSON Query for JavaScript

Source: https://jsonquerylang.org/implementations

Use npm to install the official JSON Query package.

```bash
npm install @jsonquerylang/jsonquery
```

--------------------------------

### Install JSON Query for .NET

Source: https://jsonquerylang.org/implementations

Use the dotnet CLI to add the JsonQuery.Net package.

```bash
dotnet add package JsonQuery.Net
```

--------------------------------

### Reverse array example

Source: https://jsonquerylang.org/reference

Example of reversing an array of numbers.

```javascript
const data = [1, 2, 3]
jsonquery(data, 'reverse()')
// [3, 2, 1]
```

--------------------------------

### Pipe Usage Example

Source: https://jsonquerylang.org/docs

Example of filtering data by a nested property and sorting the result.

```text
filter(.address.city == "New York") | sort(.age)
```

--------------------------------

### Sort data examples

Source: https://jsonquerylang.org/reference

Examples of sorting objects by property and primitive values in ascending or descending order.

```javascript
const data = [
  { "name": "Chris", "age": 23, "address": { "city": "New York" } },
  { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } },
  { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } }
]

jsonquery(data, 'sort(.age)')
// [
//   { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } },
//   { "name": "Chris", "age": 23, "address": { "city": "New York" } },
//   { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } }
// ]

jsonquery(data, 'sort(.age, "desc")')
// [
//   { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } },
//   { "name": "Chris", "age": 23, "address": { "city": "New York" } },
//   { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } }  
// ]

jsonquery(data, 'sort(.address.city)')
// [
//   { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } },
//   { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } },
//   { "name": "Chris", "age": 23, "address": { "city": "New York" } }
// ]

const values = [7, 2, 9]

jsonquery(values, 'sort()') // [2, 7, 9]
jsonquery(values, 'sort(get(), "desc")') // [9, 7, 2]
```

--------------------------------

### Execute match queries

Source: https://jsonquerylang.org/reference

Examples demonstrating basic matching, named capturing groups, and mapping over arrays.

```javascript
jsonquery('Hello world!', 'match(get(), "[a-z]+", "i")')
```

```javascript
jsonquery(
  'Save the date: 2025-12-25!',
  'match(get(), "(?<year>[0-9]{4})-(?<month>[0-9]{2})-(?<date>[0-9]{2})")'
)
```

```javascript
const data = [
  { id: 1, message: 'Shall we meet at 2025-12-04?' },
  { id: 2, message: 'Beginning of next year, for example 2026-01-09, is most handy for me' },
  { id: 3, message: 'Can we plan something next week?' },
  { id: 4, message: 'Can we discuss the details on 2025-12-02, 2025-12-03, or 2025-12-05?' }
]

// map over an array, extracting matches from string inputs.
// Note that the regex for a digit \d must be escaped twice in this
// case because it is inside a JSON string inside a JavaScript string.
jsonquery(
  data,
  `map({ 
    id: .id, 
    firstDate: match(.message, "\\\\d{4}-\\\\d{2}-\\\\d{2}") | .value
  })`
)
```

--------------------------------

### Object Constructor Usage

Source: https://jsonquerylang.org/reference

Examples of creating objects to aggregate data or transform existing structures.

```javascript
const data = [
  { "name": "Chris", "age": 23, "address": { "city": "New York" } },
  { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } },
  { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } }
]

jsonquery(data, '{ names: map(.name), total: size() }')
// {
//   "names": ["Chris", "Emily", "Michelle"],
//   "total" 3
// }


jsonquery(data, 'map({ firstName: .name, city: .address.city})')
// [
//   { "firstName": "Chris", "city": "New York" },
//   { "firstName": "Emily", "city": "Atlanta" },
//   { "firstName": "Michelle", "city": "Los Angeles" }
// ]
```

--------------------------------

### Access Properties via get() Function

Source: https://jsonquerylang.org/docs

The get() function provides an alternative to dot notation for property access.

```json
get("age")
get("address", "city")
```

--------------------------------

### Retrieve data using jsonquery

Source: https://jsonquerylang.org/reference

Examples of extracting values from objects and arrays using dot notation and the get function. Returns null if the property does not exist.

```javascript
const data = { 
  "name": "Joe", 
  "age": 32, 
  "address": { 
    "city": "New York" 
  } 
}

jsonquery(data, '.name') // "Joe"
jsonquery(data, '.address.city') // "New York"
jsonquery(data, 'get("address", "city")') // "New York"

jsonquery(["A", "B", "C"], 'get(2)') // "C"
jsonquery(["A", "B", "C"], '.2') // "C"
```

--------------------------------

### matchAll Usage Examples

Source: https://jsonquerylang.org/reference

Demonstrates basic matching, named capturing groups, and usage within a map operation.

```javascript
jsonquery('Hello world!', 'matchAll(get(), "[a-z]+", "i")')
// [
//   { "value": "Hello" },
//   { "value": "world" }
// ]

// an example with named capturing groups 
jsonquery(
  'We will be on holiday from 2026-08-14 till 2026-08-28',
  'matchAll(get(), "(?<year>[0-9]{4})-(?<month>[0-9]{2})-(?<date>[0-9]{2})")'
)
// [
//   {
//     "value": "2026-08-14",
//     "groups": ["2026", "08", "14"],
//     "namedGroups": {"year": "2026", "month": "08", "date": "14"}
//   },
//   {
//     "value": "2026-08-28",
//     "groups": ["2026", "08", "28"],
//     "namedGroups": {"year": "2026", "month": "08", "date": "28"}
//   }
// ]

const data = [
  { id: 1, message: 'Shall we meet at 2025-12-04?' },
  { id: 2, message: 'Beginning of next year, for example 2026-01-09, is most handy for me' },
  { id: 3, message: 'Can we plan something next week?' },
  { id: 4, message: 'Can we discuss the details on 2025-12-02, 2025-12-03, or 2025-12-05?' }
]

// Note that the regex for a digit \d must be escaped
// twice in this case because it is inside a JSON string inside a JavaScript string.
jsonquery(
  data,
  `map({ 
    id: .id, 
    allDates: matchAll(.message, "\\\\d{4}-\\\\d{2}-\\\\d{2}") | map(.value)
  })`
)
// [
//   { "id": 1, "allDates": ["2025-12-04"] },
//   { "id": 2, "allDates": ["2026-01-09"] },
//   { "id": 3, "allDates": [] },
//   { "id": 4, "allDates": ["2025-12-02", "2025-12-03", "2025-12-05"] }
// ]
```

--------------------------------

### Access properties and array items with get

Source: https://jsonquerylang.org/reference

Syntax for retrieving values from objects or indices from arrays using dot notation or the get function.

```text
.prop1
.prop1.prop2
."prop1"
get("prop1", "prop2", ...)
```

--------------------------------

### Array Constructor Usage

Source: https://jsonquerylang.org/reference

Examples of using arrays for filtering and transforming data into nested structures.

```javascript
const data = [
  { "name": "Chris", "age": 16 },
  { "name": "Emily", "age": 32 },
  { "name": "Joe", "age": 18 }
]

jsonquery(data, 'filter(.age in [16, 18])')
// [
//   { "name": "Chris", "age": 16 },
//   { "name": "Joe", "age": 18 }
// ]

const locations = [
  {"latitude": 52.33, "longitude": 4.01},
  {"latitude": 52.18, "longitude": 3.99},
  {"latitude": 51.97, "longitude": 4.05}
]

jsonquery(locations, 'map([.latitude, .longitude])')
// [
//   [52.33, 4.01],
//   [52.18, 3.99],
//   [51.97, 4.05]
// ]
```

--------------------------------

### Pipe Operator Usage

Source: https://jsonquerylang.org/reference

Example of sorting data and picking specific fields using the pipe operator.

```javascript
const data = [
  { "name": "Chris", "age": 23, "address": { "city": "New York" } },
  { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } },
  { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } }
]

jsonquery(data, 'sort(.age) | pick(.name, .age)')
// [
//   { "name": "Emily", "age": 19 },
//   { "name": "Chris", "age": 23 },
//   { "name": "Michelle", "age": 27 }
// ]
```

--------------------------------

### Less Than Operator Usage

Source: https://jsonquerylang.org/reference

Syntax for the less than operator and an example filtering an array of objects by age.

```text
a < b
lt(a, b)
```

```javascript
const data = [
  { "name": "Chris", "age": 16 },
  { "name": "Emily", "age": 32 },
  { "name": "Joe", "age": 18 }
]

jsonquery(data, 'filter(.age < 18)')
// [
//   { "name": "Chris", "age": 16 }
// ]
```

--------------------------------

### Text Format Query Example

Source: https://jsonquerylang.org/docs

A pipe-based query filtering data by age and sorting the results.

```text
filter(.age >= 18) | sort(.age)
```

--------------------------------

### Not Equal Operator Usage

Source: https://jsonquerylang.org/reference

Syntax for the not equal operator and examples demonstrating deep strict inequality checks.

```text
a != b
ne(a, b)
```

```javascript
const data = [
  { "name": "Chris", "age": 16 },
  { "name": "Emily", "age": 32 },
  { "name": "Joe", "age": 18 }
]

jsonquery(data, 'filter(.age != 16)')
// [
//   { "name": "Emily", "age": 32 },
//   { "name": "Joe", "age": 18 }
// ]

jsonquery({ a: 2 }, 'a != 2') // false
jsonquery({ a: 2 }, 'a != 3') // true
jsonquery({ a: 2 }, 'a != "2"') // true (since not strictly equal)
```

--------------------------------

### get(properties...)

Source: https://jsonquerylang.org/reference

Retrieves a path from an object or an item from an array. Returns null if the property does not exist.

```APIDOC
## get(properties...)

### Description
Retrieves a specific path from an object or an item from an array. Supports dot notation (e.g., .prop1.prop2) or function syntax (e.g., get("prop1")).

### Parameters
- **properties** (string/number) - Required - The path keys or array indices to traverse.

### Examples
jsonquery(data, '.name')
jsonquery(data, 'get("address", "city")')
jsonquery(["A", "B", "C"], '.2')
```

--------------------------------

### Apply filters to data collections

Source: https://jsonquerylang.org/reference

Examples of filtering an array of objects based on age, city, or combined logical conditions.

```javascript
const data = [
  { "name": "Chris", "age": 23, "address": { "city": "New York" } },
  { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } },
  { "name": "Joe", "age": 32, "address": { "city": "New York" } },
  { "name": "Kevin", "age": 19, "address": { "city": "Atlanta" } },
  { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } },
  { "name": "Robert", "age": 45, "address": { "city": "Manhattan" } },
  { "name": "Sarah", "age": 31, "address": { "city": "New York" } }
]

jsonquery(data, 'filter(.age > 30)')
// [
//   { "name": "Joe", "age": 32, "address": { "city": "New York" } },
//   { "name": "Robert", "age": 45, "address": { "city": "Manhattan" } },
//   { "name": "Sarah", "age": 31, "address": { "city": "New York" } }
// ]

jsonquery(data, 'filter(.address.city == "new York")')
// [
//   { "name": "Chris", "age": 23, "address": { "city": "New York" } },
//   { "name": "Joe", "age": 32, "address": { "city": "New York" } },
//   { "name": "Sarah", "age": 31, "address": { "city": "New York" } }
// ]

jsonquery(data, 'filter((.age > 30) and (.address.city == "New York"))')
// [
//   { "name": "Joe", "age": 32, "address": { "city": "New York" } },
//   { "name": "Sarah", "age": 31, "address": { "city": "New York" } }
// ]
```

--------------------------------

### Less Than or Equal To Operator Usage

Source: https://jsonquerylang.org/reference

Syntax for the less than or equal to operator and an example filtering an array of objects by age.

```text
a <= b
lte(a, b)
```

```javascript
const data = [
  { "name": "Chris", "age": 16 },
  { "name": "Emily", "age": 32 },
  { "name": "Joe", "age": 18 }
]

jsonquery(data, 'filter(.age <= 18)')
// [
//   { "name": "Chris", "age": 16 },
//   { "name": "Joe", "age": 18 }
// ]
```

--------------------------------

### Access Array Items

Source: https://jsonquerylang.org/docs

Retrieve array elements by index using get() or dot notation.

```json
get(2)
.2
```

--------------------------------

### Retrieve Current Value

Source: https://jsonquerylang.org/docs

Use the get() function without arguments to return the current value.

```json
get()
```

--------------------------------

### substring(text, start, end)

Source: https://jsonquerylang.org/reference

Extracts a substring from a given string. If the end parameter is omitted, the function extracts until the end of the string.

```APIDOC
## substring(text, start, end)

### Description
Extract a substring from a string. When `end` is not provided, the length of the string will be used as `end`.

### Signature
`substring(text, start)`
`substring(text, start, end)`
```

--------------------------------

### Sample Data Structure

Source: https://jsonquerylang.org/docs

The base dataset used for demonstrating query operations.

```json
[
  { "name": "Chris", "age": 23, "address": { "city": "New York" } },
  { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } },
  { "name": "Joe", "age": 32, "address": { "city": "New York" } },
  { "name": "Kevin", "age": 19, "address": { "city": "Atlanta" } },
  { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } },
  { "name": "Robert", "age": 45, "address": { "city": "Manhattan" } },
  { "name": "Sarah", "age": 31, "address": { "city": "New York" } }
]
```

--------------------------------

### Object Constructor Syntax

Source: https://jsonquerylang.org/reference

Syntax for creating new objects within a query.

```text
{ prop1: query1, prop2: query2, ...}
object({ prop1: query1, prop2: query2, ...})
```

--------------------------------

### Map properties over an array

Source: https://jsonquerylang.org/docs

Demonstrates the correct usage of map and pick functions when processing arrays, contrasting them with an incorrect syntax.

```text
.friends | { firstName: .name, age: .age }        WRONG 
.friends | map({ firstName: .name, age: .age })   RIGHT 
.friends | pick(.name, .age)                      RIGHT 
```

--------------------------------

### Array Constructor Syntax

Source: https://jsonquerylang.org/reference

Syntax for creating new arrays within a query.

```text
[query1, query2, ...]
array(query2, query2, ...)
```

--------------------------------

### Basic JSON Query Execution

Source: https://jsonquerylang.org/docs

The primary function takes input data and a query string to produce a result.

```text
output = jsonquery(data, query)
```

--------------------------------

### Extract Substring with JSONQuery

Source: https://jsonquerylang.org/reference

Extracts a portion of a string using start and optional end indices.

```text
substring(text, start)
substring(text, start, end)
```

```javascript
const events = [
  {"type": "start", "time": "2024-11-06 23:14:00" },
  {"type": "initialize", "time": "2025-11-08 09:00:00" },
  {"type": "end", "time": "2025-11-24 10:27:00" }
]

jsonquery(events, 'map(substring(.time, 0, 10))')
// [
//   "2024-11-06",
//   "2025-11-08",
//   "2025-11-24"
// ]
```

--------------------------------

### Pipe Syntax

Source: https://jsonquerylang.org/docs

General syntax for chaining multiple query operations.

```text
query1 | query2 | ...
```

--------------------------------

### prod()

Source: https://jsonquerylang.org/reference

Calculates the product of all values in an array.

```APIDOC
## prod()

### Description
Calculate the product of the values in an array. The function throws an error in case of an empty array.

### Signature
`prod()`
```

--------------------------------

### Transform data with objects

Source: https://jsonquerylang.org/

Objects use property keys and query values to transform data or execute multiple pipelines in parallel.

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

--------------------------------

### matchAll Function Signatures

Source: https://jsonquerylang.org/reference

Defines the available function signatures for matchAll.

```text
matchAll(text, expression)
matchAll(text, expression, options)
```

--------------------------------

### object

Source: https://jsonquerylang.org/reference

Constructs a new object from query results.

```APIDOC
## object

### Description
Creates a new object using the provided property-query mappings.

### Syntax
`{ prop1: query1, prop2: query2, ...}`
`object({ prop1: query1, prop2: query2, ...})
```

--------------------------------

### Chain queries with pipes

Source: https://jsonquerylang.org/

Pipes execute a series of queries sequentially, passing the output of one as the input to the next.

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

--------------------------------

### pick(property1, property2, ...)

Source: https://jsonquerylang.org/reference

Selects one or multiple properties or paths from an object or array and creates a new, flat object for each.

```APIDOC
## pick(property1, property2, ...)

### Description
Pick one or multiple properties or paths, and create a new, flat object for each of them. Can be used on both an object or an array.

### Usage
`jsonquery(data, 'pick(.property1, .property2)')`
```

--------------------------------

### Function Call Syntax

Source: https://jsonquerylang.org/docs

General syntax for invoking functions in the query language.

```text
name(argument1, argument2, ...)
```

--------------------------------

### size()

Source: https://jsonquerylang.org/reference

Returns the size of an array or the length of a string.

```APIDOC
## size()

### Description
Return the size of an array or the length of a string.

### Signature
`size()`
```

--------------------------------

### Execute functions in a chain

Source: https://jsonquerylang.org/

Functions are executed as methods in a chain, where the output of one operation serves as the input for the next.

```text
sort(.address.city, "asc")
```

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

--------------------------------

### Define match function signatures

Source: https://jsonquerylang.org/reference

The function accepts text, a regular expression string, and optional flags.

```text
match(text, expression)
match(text, expression, options)
```

--------------------------------

### mapKeys(callback)

Source: https://jsonquerylang.org/reference

Maps over an object and creates a new object with keys returned by the callback, retaining the original values.

```APIDOC
## mapKeys(callback)

### Description
Maps over an object, and creates a new object with the keys returned by the callback having the value of the original key.

### Parameters
- **callback** (string) - Required - The expression to generate new keys.

### Example
```javascript
const data = { "a": 2, "b": 3 }
jsonquery(data, 'mapKeys("#" + get())')
// { "#a": 2, "#b": 3 }
```
```

--------------------------------

### reverse()

Source: https://jsonquerylang.org/reference

Creates a new array with the items in reverse order.

```APIDOC
## reverse()

### Description
Creates a new array with the items in reverse order.
```

--------------------------------

### regex(text, expression, options)

Source: https://jsonquerylang.org/reference

Tests a string against a regular expression.

```APIDOC
## regex(text, expression, options)

### Description
Tests the provided text against a regular expression. Returns true if a match is found, false otherwise.

### Signature
`regex(text, expression)` or `regex(text, expression, options)`

### Parameters
- **text** (string) - The input text to test.
- **expression** (string) - The regular expression pattern.
- **options** (string) - Optional regular expression flags (e.g., 'i').
```

--------------------------------

### Operator Syntax

Source: https://jsonquerylang.org/docs

General syntax for using operators between two values.

```text
left operator right
```

--------------------------------

### Access object properties

Source: https://jsonquerylang.org/

Use dot notation to retrieve properties. Consecutive dots access nested properties, and quotes are required for keys with spaces.

```text
.age
```

```text
.address.city
```

```text
."first name"
```

```text
get()
```

```text
get("address", "city")
```

--------------------------------

### string(number)

Source: https://jsonquerylang.org/reference

Formats a numeric value as a string.

```APIDOC
## string(number)

### Description
Format a number as a string.

### Signature
`string(number)`

### Examples
`jsonquery({"value": 2.4 }, 'string(.value)') // "2.4"`
`jsonquery(42, 'string(get())') // "42"`
```

--------------------------------

### Pick properties with pick()

Source: https://jsonquerylang.org/reference

Extracts specific properties into a new flat object. Works on both objects and arrays.

```javascript
pick(property1, property2, ...)
```

```javascript
const data = [
  { "name": "Chris", "age": 23, "address": { "city": "New York" } },
  { "name": "Emily", "age": 19, "address": { "city": "Atlanta" } },
  { "name": "Michelle", "age": 27, "address": { "city": "Los Angeles" } }
]

jsonquery(data, 'pick(.age)')
// [
//   { "age": 23 },
//   { "age": 19 },
//   { "age": 27 }
// ]

jsonquery(data, 'pick(.name, .address.city)')
// [
//   { "name": "Chris", "city": "New York" },
//   { "name": "Emily", "city": "Atlanta" },
//   { "name": "Michelle", "city": "Los Angeles" }
// ]

const item = { "price": 25 }

jsonquery(item, 'pick(.price)') // 25
```

--------------------------------

### Access Properties and Nested Paths

Source: https://jsonquerylang.org/docs

Retrieve values using dot notation for simple or nested properties.

```json
.age
```

```json
.address.city
```

--------------------------------

### and

Source: https://jsonquerylang.org/reference

Tests whether two or more values are truthy. Throws an error if zero arguments are provided.

```APIDOC
## and

### Description
Tests whether two or more values are truthy. A non-truthy value is any of false, 0, "", null, or undefined. The function throws an error in case of zero arguments.

### Syntax
- a and b
- a and b and c and ...
- and(a, b)
- and(a, b, c, ...)
```

--------------------------------

### limit(size)

Source: https://jsonquerylang.org/reference

Creates a copy of an array truncated to the specified size.

```APIDOC
## limit(size)

### Description
Create a copy of an array cut off at the selected limit.

### Signature
`limit(size)`

### Parameters
- **size** (number) - Required - The maximum number of elements to include in the resulting array.
```

--------------------------------

### array

Source: https://jsonquerylang.org/reference

Constructs a new array from query results.

```APIDOC
## array

### Description
Creates a new array containing the results of the provided queries.

### Syntax
`[query1, query2, ...]`
`array(query1, query2, ...)`
```

--------------------------------

### min()

Source: https://jsonquerylang.org/reference

Returns the minimum value in an array.

```APIDOC
## min()

### Description
Return the minimum of the values in an array. The function returns null in case of an empty array.

### Signature
`min()`
```

--------------------------------

### Logical AND operator syntax

Source: https://jsonquerylang.org/reference

Syntax for testing if multiple values are truthy.

```jsonquery
a and b
a and b and c and ...
and(a, b)
and(a, b, c, ...)
```

--------------------------------

### sum()

Source: https://jsonquerylang.org/reference

Calculates the sum of all values in an array.

```APIDOC
## sum()

### Description
Calculate the sum of all values in an array. The function returns 0 in case of an empty array.

### Signature
`sum()`
```

--------------------------------

### exists

Source: https://jsonquerylang.org/reference

Checks if a property exists at the provided path.

```APIDOC
## exists

### Description
Returns true if the property at the provided path exists. Returns true too when the properties value contains a value null, false or 0.

### Syntax
- exists(path)
```

--------------------------------

### Calculate product

Source: https://jsonquerylang.org/reference

Multiplies all values in an array. Throws an error if the array is empty.

```javascript
prod()
```

```javascript
jsonquery([2, 3], 'prod()') // 6
jsonquery([2, 3, 2, 7, 1, 1], 'prod()') // 84
```

--------------------------------

### Define mapKeys transformation

Source: https://jsonquerylang.org/reference

Defines the signature for the mapKeys function.

```text
mapKeys(callback)
```

--------------------------------

### map(callback)

Source: https://jsonquerylang.org/reference

Iterates over an array and applies the provided callback query to each item.

```APIDOC
## map(callback)

### Description
Map over an array and apply the provided callback query to each of the items in the array.

### Usage
`jsonquery(data, 'map(callback)')`
```

--------------------------------

### matchAll(text, expression, options)

Source: https://jsonquerylang.org/reference

Finds all matches of a regular expression in a given text string. Returns an array of objects containing the matched value, optional capturing groups, and optional named capturing groups.

```APIDOC
## matchAll(text, expression, options)

### Description
Finds all occurrences of the provided regular expression in the input text. Returns an array of objects, each containing the matched value and optionally capturing groups or named capturing groups.

### Parameters
- **text** (string) - Required - The input string to search.
- **expression** (string) - Required - The regular expression pattern to match.
- **options** (string) - Optional - Regular expression flags (e.g., "i" for case-insensitive).

### Return Type
- **Array<{value: string, groups?: string[], namedGroups?: {[name: string]: string}}>** - An array of match objects, or an empty array if no matches are found.

### Example
```json
jsonquery('Hello world!', 'matchAll(get(), "[a-z]+", "i")')
// [
//   { "value": "Hello" },
//   { "value": "world" }
// ]
```
```

--------------------------------

### keys()

Source: https://jsonquerylang.org/reference

Returns an array containing the keys of an object.

```APIDOC
## keys()

### Description
Returns an array containing the keys of an object.

### Signature
`keys()`
```

--------------------------------

### Functions

Source: https://jsonquerylang.org/

Functions are operations applied to data inputs, often used in chains. They follow the syntax name(argument1, argument2, ...).

```APIDOC
## Functions

### Description
Functions are defined as a function name followed by comma separated arguments wrapped in round brackets. They can be executed as a method in a chain where the operation is applied to the data input and forwarded to the next method.

### Available Functions
- 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)
- match(text, expression, options)
- matchAll(text, expression, options)
- round(value, digits)
- abs(value)
- number(text)
- string(number)
```

--------------------------------

### Query JSON Data in JavaScript

Source: https://jsonquerylang.org/implementations

Import the jsonquery function and apply a query string to filter, sort, and pick fields from a data object.

```javascript
import { jsonquery } from '@jsonquerylang/jsonquery'

const data = {
  "friends": [
    { "name": "Chris", "age": 23, "city": "New York" },
    { "name": "Emily", "age": 19, "city": "Atlanta" },
    { "name": "Joe", "age": 32, "city": "New York" },
    { "name": "Kevin", "age": 19, "city": "Atlanta" },
    { "name": "Michelle", "age": 27, "city": "Los Angeles" },
    { "name": "Robert", "age": 45, "city": "Manhattan" },
    { "name": "Sarah", "age": 31, "city": "New York" }
  ]
}

// Get the array containing the friends from the object, filter the friends that live in New York,
// sort them by age, and pick just the name and age out of the objects.
const output = jsonquery(data, `
  .friends 
    | filter(.city == "New York") 
    | sort(.age) 
    | pick(.name, .age)
`)
// output = [
//   { "name": "Chris", "age": 23 },
//   { "name": "Sarah", "age": 31 },
//   { "name": "Joe", "age": 32 }
// ]
```

--------------------------------

### mapObject(callback)

Source: https://jsonquerylang.org/reference

Maps over an object and creates a new object based on the key/value pairs returned by the callback.

```APIDOC
## mapObject(callback)

### Description
Map over an object, and create a new object with the entry { key, value } returned by the callback for every input entry.

### Usage
`jsonquery(data, 'mapObject(callback)')`
```

--------------------------------

### Execute Parallel Queries

Source: https://jsonquerylang.org/docs

Run multiple queries simultaneously to produce a single object result.

```json
{
  names: map(.name),
  count: size(),
  averageAge: map(.age) | average()
}
```

--------------------------------

### or

Source: https://jsonquerylang.org/reference

Tests whether at least one of the values is truthy. Throws an error if zero arguments are provided.

```APIDOC
## or

### Description
Test whether at least one of the values is truthy. A non-truthy value is any of false, 0, "", null, or undefined. The function throws an error in case of zero arguments.

### Syntax
- a or b
- a or b or c or ...
- or(a, b)
- or(a, b, c, ...)
```

--------------------------------

### average()

Source: https://jsonquerylang.org/reference

Calculates the average of all values in an array.

```APIDOC
## average()

### Description
Calculate the average of the values in an array. The function throws an error in case of an empty array.

### Signature
`average()`
```

--------------------------------

### pipe (|)

Source: https://jsonquerylang.org/reference

The pipe operator executes a series of query operations one by one, where the output of the first is the input for the next.

```APIDOC
## pipe (|)

### Description
Executes a series of query operations sequentially. The output of one operation serves as the input for the next.

### Syntax
`query1 | query2 | ...`
`pipe(query1, query2, ...)`
```

--------------------------------

### gt (>)

Source: https://jsonquerylang.org/reference

Tests whether the first value is greater than the second value.

```APIDOC
## gt (>)

### Description
Tests whether `a` is greater than `b`. Supports comparing two numbers, two strings, or two booleans. Returns `false` for unsupported or mixed data types.

### Syntax
`a > b`
`gt(a, b)`
```

--------------------------------

### sort()

Source: https://jsonquerylang.org/reference

Sorts a list of objects or values. Values are ordered by type, and strings are compared alphabetically.

```APIDOC
## sort(property, direction)

### Description
Sorts a list of objects or values. The function orders values by type (boolean, number, string) and compares strings alphabetically. Objects and arrays are not re-ordered.

### Parameters
- **property** (string) - Optional - The property path to sort by.
- **direction** (string) - Optional - The sort order, either 'asc' or 'desc'.
```

--------------------------------

### join(separator)

Source: https://jsonquerylang.org/reference

Concatenates array items into a single string using an optional separator.

```APIDOC
## join(separator)

### Description
Concatenates array items into a string with an optional separator.

### Signature
`join()`
`join(separator)`
```

--------------------------------

### Apply comparison operators

Source: https://jsonquerylang.org/

Operators require both left and right operands. Parentheses can be used to override default operator precedence.

```text
.age >= 18
```

```text
filter(.age >= 18 and .age <= 65)
```

--------------------------------

### Map over arrays with map()

Source: https://jsonquerylang.org/reference

Applies a callback query to each item in an array.

```javascript
map(callback)
```

```javascript
const data = [
  { "name": "Chris", "scores": [5, 7, 3] },
  { "name": "Emily", "scores": [8, 5, 2, 5] },
  { "name": "Joe", "scores": [1, 1, 5, 6] }
]

jsonquery(data, `map({
  firstName: .name,
  maxScore: .scores | max()
})`)
// [
//   {"firstName": "Chris", "maxScore": 7},
//   {"firstName": "Emily", "maxScore": 8},
//   {"firstName": "Joe"  , "maxScore": 6}
// ]

const cart = [
  {"name": "bread", "price": 2.5, "quantity": 2},
  {"name": "milk" , "price": 1.2, "quantity": 3}
]
jsonquery(data, 'map(.price * .quantity)')
// 8.6
```

--------------------------------

### Calculate size or length

Source: https://jsonquerylang.org/reference

Returns the number of elements in an array or the character count of a string.

```javascript
size()
```

```javascript
jsonquery([1, 2], 'size()') // 2
jsonquery([1, 2, 3, 4], 'size()') // 4
jsonquery("hello", 'size()') // 5
```

--------------------------------

### Define arrays

Source: https://jsonquerylang.org/

Arrays are defined using square brackets with comma-separated items.

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

--------------------------------

### Define groupBy transformation

Source: https://jsonquerylang.org/reference

Defines the signature for the groupBy function.

```text
groupBy(property)
```

--------------------------------

### Query JSON Data in Python

Source: https://jsonquerylang.org/implementations

Use the jsonquery function to process data and print the results using pprint.

```python
from jsonquerylang import jsonquery
from pprint import pprint

data = {
    "friends": [
        {"name": "Chris", "age": 23, "city": "New York"},
        {"name": "Emily", "age": 19, "city": "Atlanta"},
        {"name": "Joe", "age": 32, "city": "New York"},
        {"name": "Kevin", "age": 19, "city": "Atlanta"},
        {"name": "Michelle", "age": 27, "city": "Los Angeles"},
        {"name": "Robert", "age": 45, "city": "Manhattan"},
        {"name": "Sarah", "age": 31, "city": "New York"}
    ]
}

# Get the array containing the friends from the object, filter the friends that live in New York,
# sort them by age, and pick just the name and age out of the objects.
output = jsonquery(data, """
    .friends 
        | filter(.city == "New York") 
        | sort(.age) 
        | pick(.name, .age)
""")
pprint(output)
# [{'age': 23, 'name': 'Chris'},
#  {'age': 31, 'name': 'Sarah'},
#  {'age': 32, 'name': 'Joe'}]
```

--------------------------------

### Sort function signatures

Source: https://jsonquerylang.org/reference

Available signatures for the sort function.

```text
sort()
sort(property)
sort(property, direction)
```

--------------------------------

### Exists operator syntax

Source: https://jsonquerylang.org/reference

Syntax for checking if a property exists at a given path.

```jsonquery
exists(path)
```

--------------------------------

### lt (<)

Source: https://jsonquerylang.org/reference

Tests whether a is less than b. Supports numbers, strings, or booleans.

```APIDOC
## lt (<)

### Description
Tests whether `a` is less than `b`. The operator supports comparing two numbers, two strings, or two booleans. In case of unsupported data types or mixed data types, the function returns `false`.

### Syntax
`a < b`
`lt(a, b)`

### Example
`jsonquery(data, 'filter(.age < 18)')`
```

--------------------------------

### JSON Format Query Equivalent

Source: https://jsonquerylang.org/docs

The intermediate JSON representation of the pipe-based query, using function call arrays.

```json
[
  "pipe",
  ["filter", ["gte", ["get", "age"], 18]],
  ["sort", ["get", "age"]]
]
```

--------------------------------

### Query JSON Data in .NET

Source: https://jsonquerylang.org/implementations

Parse JSON data and apply a query using the IJsonQueryable interface.

```csharp
using JsonQuery.Net.Queryables;

JsonNode jsonData = JsonNode.Parse("""
    {
      "friends": [
        { "name": "Chris", "age": 23, "city": "New York" },
        { "name": "Emily", "age": 19, "city": "Atlanta" },
        { "name": "Joe", "age": 32, "city": "New York" },
        { "name": "Kevin", "age": 19, "city": "Atlanta" },
        { "name": "Michelle", "age": 27, "city": "Los Angeles" },
        { "name": "Robert", "age": 45, "city": "Manhattan" },
        { "name": "Sarah", "age": 31, "city": "New York" }
      ]
    }
    """)!;

// Get the array containing the friends from the object, filter the friends that live in New York,
// sort them by age, and pick just the name and age out of the objects.
IJsonQueryable jsonQueryable = JsonQueryable.Parse("""
    .friends 
    | filter(.city == "New York") 
    | sort(.age) 
    | pick(.name, .age)
    """);

JsonNode output = jsonQueryable.Query(jsonData)!;

// output = [
//   { "name": "Chris", "age": 23 },
//   { "name": "Sarah", "age": 31 },
//   { "name": "Joe", "age": 32 }
// ]
```

--------------------------------

### match(text, expression, options)

Source: https://jsonquerylang.org/reference

Finds the first match of a regular expression in the provided text. Returns an object containing the matched value, and optionally groups or named groups if defined in the expression.

```APIDOC
## match(text, expression, options)

### Description
Finds the first match of the provided regular expression in the input text. Returns null if no match is found, or an object containing the matched value and any captured groups.

### Parameters
- **text** (string) - Required - The input string to search.
- **expression** (string) - Required - The regular expression pattern to match.
- **options** (string) - Optional - Regular expression flags (e.g., "i").

### Return Value
- **value** (string) - The text of the first occurrence.
- **groups** (string[]) - Optional - List of captured groups.
- **namedGroups** (object) - Optional - Map of named capturing groups.

### Example
jsonquery('Hello world!', 'match(get(), "[a-z]+", "i")')
// Returns: { "value": "Hello" }
```

--------------------------------

### mapValues(callback)

Source: https://jsonquerylang.org/reference

Maps over an object and creates a new object with values updated by the return value of the callback.

```APIDOC
## mapValues(callback)

### Description
Maps over an object, and creates a new object with the values updated by the return value of callback.

### Parameters
- **callback** (string) - Required - The expression to transform values.

### Example
```javascript
const data = { "a": 2, "b": 3 }
jsonquery(data, 'mapValues(get() * 2)')
// { "a": 4, "b": 6 }
```
```

--------------------------------

### Logical OR operator syntax

Source: https://jsonquerylang.org/reference

Syntax for testing if at least one value is truthy.

```jsonquery
a or b
a or b or c or ...
or(a, b)
or(a, b, c, ...)
```

--------------------------------

### gte (>=)

Source: https://jsonquerylang.org/reference

Tests whether the first value is greater than or equal to the second value.

```APIDOC
## gte (>=)

### Description
Tests whether `a` is greater than or equal to `b`. Supports comparing two numbers, two strings, or two booleans. Returns `false` for unsupported or mixed data types.

### Syntax
`a >= b`
`gte(a, b)`
```

--------------------------------

### values()

Source: https://jsonquerylang.org/reference

Returns an array containing the values of an object.

```APIDOC
## values()

### Description
Returns an array containing the values of an object.

### Signature
`values()`
```

--------------------------------

### Regular expression regex function

Source: https://jsonquerylang.org/reference

Tests text against a regex pattern, optionally supporting flags like case-insensitivity.

```javascript
regex(text, expression)
regex(text, expression, options)
```

```javascript
const data = [
  { "id": 1, "message": "I LIKE it!" },
  { "id": 2, "message": "It is awesome!" },
  { "id": 3, "message": "Was a disaster" },
  { "id": 4, "message": "We like it a lot" }
]

jsonquery(data, 'filter(regex(.message, "like|awesome"))')
// [
//   { "id": 2, "message": "It is awesome!" },
//   { "id": 4, "message": "We like it a lot" }
// ]

jsonquery(data, 'filter(regex(.message, "like|awesome", "i"))')
// [
//   { "id": 1, "message": "I LIKE it!" },
//   { "id": 2, "message": "It is awesome!" },
//   { "id": 4, "message": "We like it a lot" }
// ]
```

--------------------------------

### Filter lists with filter

Source: https://jsonquerylang.org/reference

Syntax for filtering collections based on a provided condition.

```text
filter(condition)
```
Tokens:
Raw