jq map() : Transform Every Array Element
jq map(f) runs f on every element of an array and collects the results into a new array.
map() reshapes an API array in place, which is handy when a later step or a GitHub Actions matrix needs a trimmed-down JSON array.
What it does
map(f) is shorthand for [.[] | f]: it iterates the input array, applies f to each element, and wraps the outputs back into an array. map(select(c)) filters an array while keeping it an array.
Common usage
# pull one field from each element into a new array
jq 'map(.name)' tags.json
# filter and keep an array (matrix-friendly)
jq 'map(select(.draft == false))' pulls.json
# build small objects for a matrix
jq -c 'map({name: .name, sha: .commit.sha})' tags.jsonFunctions
| Form | What it does |
|---|---|
| map(.field) | Array of one field from each element |
| map(select(c)) | Filter elements but stay an array |
| map({k: .v}) | Reshape each element into a new object |
| map_values(f) | Apply f to each value of an object |
In CI
map() keeps the result an array, which is exactly what a GitHub Actions matrix include list wants. Add -c so the array stays on one line when you write it to $GITHUB_OUTPUT.
Common errors in CI
"jq: error: Cannot iterate over null (null)" from map() means the input was null, not an array (a missing key upstream). "jq: error (at <stdin>:0): Cannot index string with \"name\"" means an element was a string, so .name inside map() had nothing to index.