DOCSEARCHbyAlgolia
Submit Docs

jql Documentation

repository·main·Indexed 23 days ago

https://github.com/yamafaktory/jql

A fast, lightweight JSON Query Language tool written in Rust designed to process JSON input and output JSON. It provides a command-line interface and Rust crates (jql, jql-parser, jql-runner) for selecting, flattening, and transforming data using tokens and operators such as key selectors, array/object ranges, flatten (..), and pipe operators.

Tokens
4.2K
Snippets
2
Records
26
Agent score
82%

What's inside jql

  2. What is a Lens selector in jql?

    main

    A Lens selector is a combination of one or more selectors with an optional value. A value can be any of boolean | null | number | string. It is used to filter elements based on specific criteria.

    Input:

    [
  { "a": 1, "b": { "d": 2 } },
  { "a": 2, "b": "some" },
  { "a": 2, "b": { "d": null } },
  { "a": 2, "b": true },
  { "c": 3, "b": 4 }
]

    Query: '|={ "b" "d"=2, "c" }'

    Output:

    [
  { "a": 1, "b": { "d": 2 } },
  { "c": 3, "b": 4 }
]

  3. How object selectors work in jql

    main

    You can select data from objects using keys, multiple keys, or index-based ranges.

    Key selector

    Any valid JSON key can be used (must be double-quoted).

    Input: { "a": 1, "b": 2, "c": 3 } Query: '"c"' Output: 3

    Multi key selector

    Keys can be used in arbitrary order.

    Input: { "a": 1, "b": 2, "c": 3 } Query: '{"c","a"}' Output: { "c": 3, "a": 1 }

    Object index selector

    Indexes can be used in arbitrary order.

    Input: { "a": 1, "b": 2, "c": 3 } Query: '{2,0}' Output: { "c": 3, "a": 1 }

    Object range selector

    Range can be in natural order {0:2}, reversed {2:0}, or use open bounds {:2} or {0:}.

    Input: { "a": 1, "b": 2, "c": 3 } Query: '{2:1}' Output: { "c": 3, "b": 2 }

  4. How operators work in jql

    main

    Flatten operator (..)

    Flattens arrays and objects. For objects, it produces a flattened map with dot-notation keys.

    Input (Array): [[[[{{"a": 1}}]]]] Query: '..' Output: [{"a": 1}]

    Input (Object): { "a": { "c": false }, "b": { "d": { "e": { "f": 1 } } } } Query: '..' Output: { "a.c": false, "b.d.e.f": 1 }

    Keys operator (@)

    Returns the keys of an object or the indices of an array. Other primitives are returned as is.

    Input: { "a": 1, "b": 2, "c": 3 } Query: '@' Output: ["a", "b", "c"]

    Pipe in operator (|> )

    Applies the next tokens in parallel on each element of an array.

    Input: { "a": [{ "b": { "c": 1 } }, { "b": { "c": 2 } }] } Query: '"a"|>"b""c"' Output: [1, 2]

    Pipe out operator (<| )

    Stops the parallelization initiated by the pipe in operator.

    Input: { "a": [{ "b": { "c": 1 } }, { "b": { "c": 2 } }] } Query: '"a"|>"b""c"<|[1]' Output: 2

    Truncate operator (!)

    Maps the output into simple JSON primitives: boolean | null | number | string | [] | {}.

    Input: { "a": [1, 2, 3] } Query: '"a"!' Output: []

  5. How array selectors work in jql

    main

    You can select elements from arrays using indexes or ranges.

    Array index selector

    Indexes can be used in arbitrary order.

    Input: [1, 2, 3] Query: '[2,1]' Output: [3, 2]

    Array range selector

    Ranges can be in natural order [0:2], reversed [2:0], or use open bounds like [:2] or [0:].

    Input: [1, 2, 3] Query: '[2:1]' Output: [3, 2]

  6. Install jql

    main

    You can install jql using various package managers depending on your operating system:

    • Alpine Linux: apk add jql
    • Archlinux: yay -S jql
    • Fedora: dnf install jql
    • FreeBSD: pkg install jql
    • Homebrew: brew install jql
    • Nix: nix-env -i jql
    • openSUSE: zypper install jql
    • Cargo: cargo install jql or cargo binstall jql

    Alternatively, you can download compiled binaries manually from the GitHub releases page.

    cargo install jql

  7. Use jql in the shell

    main

    To use jql, provide a query as a sequence of tokens. Because jql requires key selectors to be double-quoted to comply with JSON standards, you should enclose your queries in single quotes in the shell to avoid escaping issues.

    Basic usage patterns

    Save output to a file:

    jql '"a"' input.json > output.json

    Read from stdin:

    cat test.json | jql '"a"'
    jql '"a"' input.json > output.json

  8. Use the jql-runner library

    main

    The jql-runner crate provides the core execution logic for JQL (JSON Query Language). It is organized into several modules, primarily exposing runner for execution logic and errors for handling query-related failures.

    To use the runner programmatically, you will primarily interact with the runner module to execute queries against JSON data.

  9. How the Truncate operator works in JQL

    main

    The ! (TruncateOperator) is a special operator in JQL used to truncate results. It has strict usage rules enforced by the parser:

    1. Singularity: You cannot use more than one ! in a single query.
    2. Position: If used, the ! must be the last token in the query.

    If these rules are violated, the parser returns a JqlParserError::TruncateError containing the stringified tokens.

  10. Use the jql CLI to query JSON data

    main

    The jql binary allows you to query JSON data using a query language. It supports reading JSON from a file, from standard input (stdin), or via a stream of JSON lines. You can provide the query directly as an argument or read it from a file.

    Input Modes

    • File Mode: Provide a path to a JSON file using the --json-file flag.
    • Piped Mode: Pipe JSON content directly into jql via stdin. By default, it reads the entire piped content as a single JSON object/array.
    • Stream Mode: Use the --stream flag to process input line-by-line (NDJSON/JSONL format). Each line is treated as an independent JSON object.

    Output Formats

    • Pretty Print (Default): Outputs colorized, formatted JSON.
    • Inline Mode: Use --inline to output compact, colorized JSON.
    • Raw String Mode: Use --raw-string to output the result as a plain string if the query result is a JSON string.
    • Validation Mode: Use --validate to check if the input is valid JSON without executing a query.

  11. Use the JQL CLI

    main

    The jql command-line tool allows you to query JSON data using a specific query language. You can provide a query as a positional argument, read it from a file, or use it to validate JSON data.

    Basic Usage

    jql '"your_query"' input.json

    Command Line Arguments

    ArgumentShortLongDescription
    queryPositional argument. The query to apply to the JSON data. Must be enclosed in single quotes.
    json_filePositional argument. The JSON file to use.
    query_from_file-q--queryRead the query from a file instead of a positional argument.
    inline-i--inlineInline the JSON output.
    raw-string-r--raw-stringWrite to stdout without JSON double-quotes (string only).
    stream-s--streamRead a stream of JSON data line by line.
    validate-v--validateValidate the JSON data (does not require a query).

    Constraints

    • --query (file) and query (positional) are mutually exclusive with --validate.
    • The query positional argument is required unless --query (file) or --validate is provided.

  12. jql CLI flags reference

    main

    The following flags are available for the jql command:

    FlagLong FlagDescription
    -i--inlineInline the JSON output (disables pretty printing)
    -q--query <FILE>Read the query from a file instead of stdin
    -r--raw-stringWrite to stdout without JSON double-quotes (useful for string primitives)
    -s--streamRead a stream of JSON data line by line
    -v--validateValidate the JSON content and return a matching exit code
    -h--helpPrint help
    -V--versionPrint version