JSON Query Language for Python

Common errors

• ModuleNotFoundError: No module named 'jsonquery'

  cause Attempting to import from the old or conflicting `jsonquery` module name.
  fix Change your import statement from `from jsonquery import ...` to `from jsonquerylang import ...`.

• Error: Cannot read properties of null (reading 'city')

  cause Attempting to access a nested property on a null or non-existent parent property. JSON Query properties support optional chaining, returning null for non-existent intermediate properties, but subsequent operations on this null will fail.
  fix Ensure that all intermediate properties in a path exist, or use `filter()` to remove objects where the path would resolve to null before attempting further access. For example, `.users | filter(.address.city != null) | map(.address.city)`.

• QueryParseError: Syntax error: Unexpected token ')'

  cause Often caused by incorrect parentheses usage, such as an unmatched parenthesis or an attempt to use parentheses for array indexing (e.g., `array(0)` instead of `array.0` or `get(0)`), or missing parentheses around complex conditions.
  fix Review the query syntax for correct parentheses balancing, especially in filters or complex expressions. Remember array item access is `.index` or `get(index)`, not `(index)`.

Warnings

• gotcha When using relational operators (e.g., `==`, `>`, `<`), a string on the right-hand side is interpreted as a literal text value, not a property path. To compare against a property, explicitly use `get()` or bracket notation (`['get', 'property']`).
  Fix: Incorrect (compares 'city' to literal string 'other_city_property'): `.city == "other_city_property"`. Correct (compares 'city' to value of 'other_city_property'): `.city == get('other_city_property')` or `['eq', ['get', 'city'], ['get', 'other_city_property']]`.
• gotcha Functions like `max()` or `sum()` operate on the piped input. Do not pass the property name directly as an argument if you intend to apply the function to values within the data stream; instead, pipe the desired values to the function.
  Fix: Incorrect: `.myValues | max(.value)`. Correct: `.myValues | map(.value) | max()`. The `map` function is often needed to extract values from an array of objects before aggregation.
• gotcha Direct square bracket notation for array item access (e.g., `array[2]`) is not supported. Use dot notation for numeric indices (`.2`) or the `get()` function (`get(2)`).
  Fix: Incorrect: `.myArray[0]`. Correct: `.myArray.0` or `.myArray | get(0)`.
• gotcha When chaining multiple operators without parentheses (e.g., `a and b and c`), parsing might throw an exception due to ambiguity in operator precedence. Explicitly define precedence with parentheses.
  Fix: Fix: Use `(a and b) and c` or set the `left_associative` option to `True` when defining custom operators that support such chaining.

Install

• pip install jsonquerylang Install latest version

Imports

• jsonquery
  wrong:

  from jsonquery import jsonquery

  correct:

  from jsonquerylang import jsonquery

  The official module name changed from 'jsonquery' to 'jsonquerylang' to avoid conflict with an older, unrelated library. Always use 'jsonquerylang'.
• parse

  from jsonquerylang import parse

• compile

  from jsonquerylang import compile

• stringify

  from jsonquerylang import stringify

Quickstart

This quickstart demonstrates how to use `jsonquery` with both text-based and JSON-formatted queries. It also shows basic usage of `parse` and `stringify` to convert between query formats.

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"}
    ]
}

# Query using text format
output_text = jsonquery(data, """
.friends | filter(.city == "New York") | sort(.age) | pick(.name, .age)
""")
print("Text Query Result:")
pprint(output_text)

# Query using JSON format
output_json = jsonquery(data, [
    "pipe",
    ["get", "friends"],
    ["filter", ["eq", ["get", "city"], "New York"]],
    ["sort", ["get", "age"]],
    ["pick", "get", "name"], ["get", "age"]
])
print("\nJSON Query Result:")
pprint(output_json)

# Example of parsing and stringifying
from jsonquerylang import parse, stringify
text_query = '.friends | filter(.age > 20)'
parsed_query = parse(text_query)
print(f"\nParsed query: {parsed_query}")
round_tripped_text = stringify(parsed_query)
print(f"Round-tripped text: {round_tripped_text}")