Overview

This series teaches jq through heavily annotated, self-contained shell examples. Each example focuses on a single concept and includes inline annotations explaining what each command does, why that approach is idiomatic, and what output or state results.

Series Structure

The examples are organized into three levels based on complexity:

• Beginner — Identity filter, field access, array indexing, pipes, basic types, object and array construction, iteration, optional operators, and command-line flags
• Intermediate — map, select, reduce, group_by, sort_by, unique_by, conditionals, string functions, path expressions, and type conversions
• Advanced — User-defined functions, recursion, path manipulation, format strings, streaming parser, SQL-style joins, environment variables, and real-world API data processing

Structure of Each Example

Every example follows a consistent five-part format:

1. Brief Explanation — what the filter does and why it matters (2-3 sentences)
2. Mermaid Diagram — visual representation of data flow or filter composition (when appropriate)
3. Heavily Annotated Code — shell commands with # => comments describing each filter stage and its output
4. Key Takeaway — the core insight to retain from the example (1-2 sentences)
5. Why It Matters — production relevance and real-world impact (50-100 words)

How to Use This Series

Each page presents annotated shell invocations using echo '...' | jq '...' so every example runs on any machine with jq installed. Read the annotations alongside the code to understand both the mechanics and the intent. The examples build on each other within each level, so reading sequentially gives the fullest understanding of how jq filters compose into real-world pipelines.

Examples by Level

Beginner (Examples 1–28)

• Example 1: Identity Filter
• Example 2: Field Access with .foo
• Example 3: Nested Field Access with .foo.bar
• Example 4: Array Index with .[N]
• Example 5: Array Slice with .[M:N]
• Example 6: Pipe Operator |
• Example 7: Comma Operator for Multiple Outputs
• Example 8: Object Construction with {}
• Example 9: Array Construction with []
• Example 10: String Interpolation with \(expr)
• Example 11: The type Function
• Example 12: Null Handling
• Example 13: length Function
• Example 14: keys and values
• Example 15: keys_unsorted
• Example 16: has Function
• Example 17: in Operator
• Example 18: empty Filter
• Example 19: .[] Array Iteration
• Example 20: .[] Object Iteration
• Example 21: Optional Field Access with .foo?
• Example 22: .[]? Optional Iteration
• Example 23: Raw Output with -r
• Example 24: Compact Output with -c
• Example 25: Null Input with -n
• Example 26: Slurp Mode with -s
• Example 27: Raw Input with -R
• Example 28: Multiple Input Files

Intermediate (Examples 29–56)

• Example 29: map Function
• Example 30: select Function
• Example 31: map_values Function
• Example 32: select with Object Filtering
• Example 33: select with Multiple Conditions
• Example 34: sort_by Function
• Example 35: group_by Function
• Example 36: unique_by Function
• Example 37: reverse and flatten
• Example 38: add Function
• Example 39: any and all
• Example 40: reduce Expression
• Example 41: reduce for Building Objects
• Example 42: limit and first/last
• Example 43: range Function
• Example 44: if-then-else Expression
• Example 45: Alternative Operator //
• Example 46: try-catch for Error Handling
• Example 47: split and join
• Example 48: test and match for Regex
• Example 49: capture for Named Groups
• Example 50: String Trimming and Case Functions
• Example 51: startswith and endswith
• Example 52: tostring and tonumber
• Example 53: to_entries and from_entries
• Example 54: with_entries Shorthand
• Example 55: contains and inside
• Example 56: min_by and max_by

Advanced (Examples 57–85)

• Example 57: Defining Functions with def
• Example 58: Functions with Filter Arguments
• Example 59: Recursive Functions
• Example 60: recurse Built-in
• Example 61: path Expression
• Example 62: getpath, setpath, and delpaths
• Example 63: leaf_paths
• Example 64: Update Operator |=
• Example 65: Alternative Update //=
• Example 66: del Function
• Example 67: indices, index, rindex
• Example 68: @base64 and @base64d
• Example 69: @csv and @tsv
• Example 70: @html and @uri
• Example 71: @json and @text
• Example 72: $ENV and env
• Example 73: Variable Binding with as
• Example 74: Pattern Matching with as
• Example 75: SQL-Style Cross Join
• Example 76: INDEX Function
• Example 77: inputs for Multiple Documents
• Example 78: debug for Inspection
• Example 79: builtins Function
• Example 80: Streaming Parser with tostream and fromstream
• Example 81: GitHub API Response Processing
• Example 82: npm Registry Response Processing
• Example 83: Log File JSON Processing
• Example 84: Configuration File Transformation
• Example 85: Complex Multi-Source Data Pipeline