{"id":9055,"library":"jsonquerylang","title":"JSON Query Language for Python","description":"jsonquerylang is a lightweight, flexible, and expandable JSON query language implemented in Python. It allows users to query JSON data using a human-friendly text format or an intermediate JSON format. The library is currently at version 2.1.0 and is actively maintained with a focus on feature richness and interoperability.","status":"active","version":"2.1.0","language":"en","source_language":"en","source_url":"https://github.com/jsonquerylang/jsonquery-python","tags":["JSON","query","data processing","filtering","sorting"],"install":[{"cmd":"pip install jsonquerylang","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The official module name changed from 'jsonquery' to 'jsonquerylang' to avoid conflict with an older, unrelated library. Always use 'jsonquerylang'.","wrong":"from jsonquery import jsonquery","symbol":"jsonquery","correct":"from jsonquerylang import jsonquery"},{"symbol":"parse","correct":"from jsonquerylang import parse"},{"symbol":"compile","correct":"from jsonquerylang import compile"},{"symbol":"stringify","correct":"from jsonquerylang import stringify"}],"quickstart":{"code":"from jsonquerylang import jsonquery\nfrom pprint import pprint\n\ndata = {\n    \"friends\": [\n        {\"name\": \"Chris\", \"age\": 23, \"city\": \"New York\"},\n        {\"name\": \"Emily\", \"age\": 19, \"city\": \"Atlanta\"},\n        {\"name\": \"Joe\", \"age\": 32, \"city\": \"New York\"},\n        {\"name\": \"Kevin\", \"age\": 19, \"city\": \"Atlanta\"},\n        {\"name\": \"Michelle\", \"age\": 27, \"city\": \"Los Angeles\"},\n        {\"name\": \"Robert\", \"age\": 45, \"city\": \"Manhattan\"},\n        {\"name\": \"Sarah\", \"age\": 31, \"city\": \"New York\"}\n    ]\n}\n\n# Query using text format\noutput_text = jsonquery(data, \"\"\"\n.friends | filter(.city == \"New York\") | sort(.age) | pick(.name, .age)\n\"\"\")\nprint(\"Text Query Result:\")\npprint(output_text)\n\n# Query using JSON format\noutput_json = jsonquery(data, [\n    \"pipe\",\n    [\"get\", \"friends\"],\n    [\"filter\", [\"eq\", [\"get\", \"city\"], \"New York\"]],\n    [\"sort\", [\"get\", \"age\"]],\n    [\"pick\", \"get\", \"name\"], [\"get\", \"age\"]\n])\nprint(\"\\nJSON Query Result:\")\npprint(output_json)\n\n# Example of parsing and stringifying\nfrom jsonquerylang import parse, stringify\ntext_query = '.friends | filter(.age > 20)'\nparsed_query = parse(text_query)\nprint(f\"\\nParsed query: {parsed_query}\")\nround_tripped_text = stringify(parsed_query)\nprint(f\"Round-tripped text: {round_tripped_text}\")\n","lang":"python","description":"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."},"warnings":[{"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']]`.","message":"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']`).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Incorrect: `.myArray[0]`. Correct: `.myArray.0` or `.myArray | get(0)`.","message":"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)`).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Fix: Use `(a and b) and c` or set the `left_associative` option to `True` when defining custom operators that support such chaining.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Change your import statement from `from jsonquery import ...` to `from jsonquerylang import ...`.","cause":"Attempting to import from the old or conflicting `jsonquery` module name.","error":"ModuleNotFoundError: No module named 'jsonquery'"},{"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)`.","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.","error":"Error: Cannot read properties of null (reading 'city')"},{"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)`.","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.","error":"QueryParseError: Syntax error: Unexpected token ')'"}]}