API Reference

High-Level Python API (jonq.api)

compile_query(query)

Compile a jonq query string into a reusable CompiledQuery object.

  • Parameters: query (str)

  • Returns: CompiledQuery

query(source, query, …)

Execute a query and return parsed Python data by default.

  • Parameters: - source: Python object, raw JSON string, or file path - query (str or CompiledQuery) - format: "python" (default), "json", "jsonl", or "csv". The Python API does not render table or YAML output. - streaming: True for row-wise root-array file queries - limit: optional post-query limit - validate: validate field names against file input when possible

  • Returns: Parsed Python data by default, or raw text for json, jsonl, and csv formats

execute(source, query, …)

Execute a query and return a structured QueryResult object.

  • Parameters: - source: Python object, raw JSON string, or file path - query (str or CompiledQuery) - format: "json" (default), "jsonl", or "csv". The Python API does not render table or YAML output. - streaming: True for row-wise root-array file queries - limit: optional post-query limit - validate: validate field names against file input when possible

  • Returns: QueryResult with text, data, and compiled metadata

query_async(…) / execute_async(…)

Async variants of the high-level execution helpers.

Note

Streaming mode requires a filesystem path and supports row-wise queries only. It rejects aggregations, group by, sort, distinct, and limit because those need full-input state.

Main Module (jonq.main)

main()

The entry point for the jonq command-line tool.

Usage:

jonq <source> "<query>" [--format json|jsonl|csv|table|yaml] [--raw] [--stream] [--watch] [--jq] [--explain] [--pretty] [--no-color] [--ndjson] [--limit N] [--out PATH] [--version]

Query Parser (jonq.query_parser)

tokenize_query(query)

Tokenizes a query string into a list of tokens.

  • Parameters: query (str)

  • Returns: List of string tokens

  • Raises: ValueError if syntax is invalid

parse_query(tokens)

Parses tokens into structured query components.

  • Parameters: tokens (list)

  • Returns: Tuple (fields, condition, group_by, having, order_by, sort_direction, limit, from_path, distinct)

  • Raises: ValueError if syntax is invalid

JQ Filter (jonq.jq_filter)

generate_jq_filter(fields, condition, group_by, having, order_by, sort_direction, limit, from_path, distinct)

Generates a jq filter string from parsed query components.

  • Parameters: - fields (list): Field specifications - condition (str): Filter condition - group_by (list): Fields to group by - having (str): Condition for grouped results - order_by (str): Field to sort by - sort_direction (str): ‘asc’ or ‘desc’ - limit (str): Result limit - from_path (str): Path for FROM clause - distinct (bool): Whether to return unique results

  • Returns: jq filter string

Executor (jonq.executor)

run_jq(json_file, jq_filter)

Executes a jq filter against a JSON file, or executes a filter against raw JSON text when called as run_jq(jq_filter, json_text).

  • Parameters: - json_file (str): Path to JSON file - jq_filter (str): jq filter string

  • Returns: Tuple (stdout, stderr)

  • Raises: ValueError, FileNotFoundError

run_jq_async(json_file, jq_filter)

Async variant of run_jq.

  • Parameters: - json_file (str): Path to JSON file - jq_filter (str): jq filter string

  • Returns: Tuple (stdout, stderr)

CSV Utils (jonq.csv_utils)

flatten_json(data, parent_key=’’, sep=’.’)

Flattens nested JSON for CSV output.

  • Parameters: - data: JSON data - parent_key (str): Parent key for recursion - sep (str): Separator for nested keys

  • Returns: Flattened dictionary

json_to_csv(json_data)

Converts JSON data to CSV format.

  • Parameters: json_data (str or dict/list)

  • Returns: CSV string

Error Handler (jonq.error_handler)

validate_query_against_schema(json_file, query)

Validates query field names against the JSON file’s actual fields. Provides fuzzy suggestions when field names are close to valid ones.

  • Parameters: - json_file (str): Path to JSON file - query (str): The query string

  • Returns: Error message string with suggestions, or None if valid

handle_error_with_context(error, json_file, query, jq_filter)

Analyzes jq errors and provides user-friendly error messages with suggestions.

  • Parameters: - error: The exception - json_file (str): Path to JSON file - query (str): The query string - jq_filter (str): The generated jq filter