Add jq cheatsheet

tools/jq.sh

@@ -0,0 +1,69 @@
+##############################################################################
+# JQ — BASICS
+##############################################################################
+
+jq '.' data.json                                # Pretty-print JSON (identity filter)
+jq '.name' data.json                            # Get one field
+jq -r '.name' data.json                         # Raw output: no quotes around strings (for shell pipelines)
+jq -c '.users[]' data.json                      # Compact output: one JSON value per line
+echo '{"a":1}' | jq '.'                         # jq reads stdin too — this is how it composes with curl
+
+
+##############################################################################
+# JQ — NESTED DATA & ARRAYS
+##############################################################################
+
+jq '.owner.email' data.json                     # Nested field access
+jq '.users[0]' data.json                        # First array element ([-1] = last)
+jq '.users[]' data.json                         # Iterate: emit every element
+jq '.users[].name' data.json                    # One field from every element
+jq '.users | length' data.json                  # Count elements (works on arrays, objects, strings)
+
+
+##############################################################################
+# JQ — FILTERING WITH select
+##############################################################################
+
+jq '.users[] | select(.age > 18)' data.json                 # Keep elements matching a condition
+jq '.users[] | select(.city == "Seattle")' data.json        # String equality
+jq '.users[] | select(.age > 18 and .active)' data.json     # Combine conditions (and / or / not)
+jq '.users[] | select(.name | test("^A"))' data.json        # Regex test on a string field
+
+
+##############################################################################
+# JQ — RESHAPING WITH map & OBJECT CONSTRUCTION
+##############################################################################
+
+jq 'map(.name)' data.json                       # Array of just the names (input: a top-level array)
+jq '.users | map({name, city})' data.json       # Reshape: new objects with only these fields ({name} = shorthand for {name: .name})
+jq '.users[] | {n: .name, senior: (.age >= 65)}' data.json  # Build computed objects field by field
+jq '[.users[] | select(.active)]' data.json      # Collect filter results back into an array
+
+
+##############################################################################
+# JQ — STRINGS, NUMBERS, AGGREGATION
+##############################################################################
+
+jq '.price | tostring' data.json                # Number -> string (tonumber goes the other way)
+jq '.tags | join(", ")' data.json               # Array of strings -> one string (split(",") reverses it)
+jq '.users | sort_by(.age)' data.json           # Sort an array of objects by a field
+jq '.users | map(.city) | unique' data.json     # Distinct values (unique sorts too)
+jq '.users | group_by(.city) | map({city: .[0].city, count: length})' data.json  # Group + count per group
+jq '[.users[].age] | add' data.json             # Sum an array of numbers (add also concatenates strings/arrays)
+jq '.users | max_by(.age)' data.json            # Element with the max field (min_by for the min)
+
+
+##############################################################################
+# JQ — KEYS & REAL-WORLD PIPELINES
+##############################################################################
+
+jq 'keys' data.json                             # List an object's keys (sorted)
+jq 'has("email")' data.json                     # Does the key exist? (use .users[0] | has("email") for elements)
+jq 'del(.password)' data.json                   # Remove a field (e.g. before sharing output)
+curl -s https://api.github.com/users/octocat | jq '{login, followers}'  # Shape a live API response in one line
+jq -r '.[] | select(.level == "error") | .msg' app.log.json  # Extract error messages from JSON logs
+jq --arg v "2.4.1" '.version = $v' data.json   # Pass a shell value safely with --arg (never string-interpolate JSON by hand)
+jq -s '.' part1.json part2.json                 # --slurp: merge multiple JSON files into one array
+
+# Manual: https://jqlang.github.io/jq/manual/
+# Trilingual (EN/ES/PT) extended version: https://github.com/Ezra-Zhao/jq-cheatsheet