Welcome to jonq’s documentation!

PyPI Version Skylos Grade

jonq is a command-line JSON tool for exploring, extracting, and reshaping payloads with readable jq-powered queries. It keeps familiar select / if syntax for common cases, accepts where as a filter alias, and stays focused on JSON-native terminal workflows.

Important

jonq is not a database, ETL system, or full jq replacement. Use it to understand and shape JSON quickly from the shell.

Key Features

  • Readable jq syntax: select name, age if age > 30

  • DISTINCT, LIMIT, IN, NOT, LIKE, IS NULL operators

  • CASE/WHEN: conditional expressions inline

  • COALESCE: null fallback with nested function support

  • String concat: || or + for concatenation

  • String functions: upper, lower, length, trim

  • Math functions: round, abs, ceil, floor

  • Type casting: int, float, str, type

  • Date/time: todate, fromdate, date

  • Aggregations: sum, avg, min, max, count, count(distinct ...)

  • GROUP BY with HAVING

  • Table output: -t for aligned terminal tables

  • JSONL / YAML output: --format jsonl and --format yaml

  • Raw scalar output: -r for unquoted values in shell pipelines

  • Smart Inspect: run jonq data.json to see fields, samples, and suggested queries

  • Profile: jonq profile data.json for field presence, nulls, missing counts, and type conflicts

  • Diff: jonq diff old.json new.json to catch shape drift

  • Checks: jonq check with inline assertions or named checks from jonq.yaml

  • Named queries: jonq run NAME from jonq.yaml

  • Interactive REPL: jonq -i data.json with tab completion and history

  • Follow mode: --follow to stream NDJSON line-by-line

  • Streaming mode: --stream for row-wise root-array queries

  • Watch mode: --watch to re-run on file change

  • Multiple inputs: local files, URLs, globs, stdin (auto-detected), NDJSON

  • Shell completions: --completions bash|zsh|fish

  • Explain mode: --explain to see query breakdown and jq filter

  • Fuzzy suggestions: typo correction for field names

  • Colorized output: syntax-highlighted JSON in terminal

Contents:

Indices and tables