Usage¶
Basic Usage¶
jonq provides a command-line interface for querying JSON files using a SQL-like syntax.
The basic syntax is:
jonq <path/to/json_file> "<query>"
Query Syntax¶
The query syntax follows a simplified SQL format:
select <fields> [if <condition>] [group by <fields>] [sort <field> [asc|desc] [limit]]
Where:
<fields>
- Comma-separated list of fields to select or aggregationsif <condition>
- Optional filtering conditiongroup by <fields>
- Optional grouping by one or more fieldssort <field>
- Optional field to sort byasc|desc
- Optional sort direction (default: asc)limit
- Optional integer to limit the number of results
Field Selection¶
To select all fields:
jonq data.json "select *"
To select specific fields:
jonq data.json "select name, age"
Nested fields can be accessed using dot notation:
jonq data.json "select name, profile.age, profile.address.city"
Array elements can be accessed using square brackets:
jonq data.json "select name, orders[0].item"
You can use quotes for fields with spaces or special characters:
jonq data.json "select 'first name', address.'street address'"
Filtering¶
Filter results using the if
keyword:
jonq data.json "select name, age if age > 30"
Combine conditions with and
and or
:
jonq data.json "select name, age if age > 25 and city = 'New York'"
jonq data.json "select name, age if age > 30 or city = 'Los Angeles'"
Use parentheses for complex expressions:
jonq data.json "select name, age if (age > 30 and city = 'Chicago') or (age < 25 and city = 'New York')"
Sorting and Limiting¶
Sort results by a field:
jonq data.json "select name, age sort age"
Sort in descending order:
jonq data.json "select name, age sort age desc"
Limit the number of results:
jonq data.json "select name, age sort age desc 5"
Aggregation Functions¶
jonq supports several aggregation functions:
sum()
- Calculate the sum of valuesavg()
- Calculate the average of valuescount()
- Count the number of itemsmax()
- Find the maximum valuemin()
- Find the minimum value
Examples:
jonq data.json "select sum(age) as total_age"
jonq data.json "select avg(age) as average_age"
jonq data.json "select count(*) as user_count"
jonq data.json "select max(orders.price) as highest_price"
jonq data.json "select min(orders.price) as lowest_price"
You can use aliases with the as
keyword:
jonq data.json "select count(*) as total_users"
Grouping¶
Group data and perform aggregations per group:
jonq data.json "select city, count(*) as user_count group by city"
jonq data.json "select city, avg(age) as avg_age group by city"