jq select() : Filter JSON by a Condition

jq select(f) passes its input through unchanged when f is true and drops it otherwise.

select() is how you filter a stream of JSON objects from an API down to the ones a workflow step actually cares about.

What it does

select(condition) evaluates the condition against the current input. If it is true the input is emitted; if it is false or null the input is dropped. Combined with .[] it filters an array element by element.

Common usage

Terminal

# only open PRs, just their numbers
gh api repos/cli/cli/pulls --jq '.[] | select(.state == "open") | .number'
# items where a numeric field passes a threshold
jq '.[] | select(.size > 1000)' files.json
# match a string field
jq '.[] | select(.name | startswith("v2"))' tags.json

Operators

Form	What it does
select(.x == "y")	Keep inputs where field x equals y
select(.n > 10)	Keep inputs where numeric n exceeds 10
select(.a and .b)	Keep inputs where both are truthy
select(.x \| test("re"))	Keep inputs whose x matches a regex

Common errors in CI

"jq: error: null (null) and number (5) cannot be compared" means the field is missing on some elements, so a comparison hit null; guard with select(.n != null and .n > 5). "jq: error: syntax error, unexpected ==" usually means you wrote = instead of == for equality.

Related guides

jq .[] : Iterate Over a JSON Array or ObjectThe jq .[] operator streams each element of an array or each value of an object. Reference for iterating gh a… jq map() : Transform Every Array Elementjq map(f) applies a filter to each element of an array and returns a new array. Reference for reshaping gh ap… jq has() : Test Whether a Key Existsjq has("key") returns true when an object contains a key or an array has an index. Reference for guarding opt… jq test() : Match a String Against a Regexjq test(re) returns true when a string matches a regex. Reference for filtering gh api items by pattern in CI…