jq select with contains: Why It Matches Too Much, and What to Use
You want every object in an array whose tags include "go", so you write
.[] | select(.tags | contains(["go"])). It returns the repos tagged "go", and
also the ones tagged "golang". Then a record with "tags": null shows up, jq
stops with an error, and every record after it is silently skipped.
I ran every command below on three jq builds: the two official releases listed in
the box above (checksums matched each release’s sha256sum.txt) and the jq that
ships in /usr/bin on macOS. All output is copied from the terminal, and a script
re-runs each command on all three builds and compares the output. They agreed
everywhere except two small spots, listed at the end.
Short answer (tested 2026-10-11): contains is a substring test, even inside
arrays and objects. For “this array has exactly this element”, use any:
$ jq -c '.[] | select(any(.tags[]?; . == "go")) | .name' repos.json
"api-server"
| You want | Use | Not |
|---|---|---|
| Field equals a value | select(.lang == "Go") | |
| String field contains a substring | select(.lang | contains("go")) (case-sensitive) | |
| Same, ignoring case | select(.lang | test("go"; "i")) | |
| Array field has an exact element | select(any(.tags[]?; . == "go")) | contains(["go"]), which also matches "golang" |
| Array field has any of several values | select(any(.tags[]?; IN("go", "react"))) | select(.tags[] == "go"), which can print a record twice |
| Array of objects has one object matching two conditions | select(any(.items[]; .sku == "A1" and .qty >= 3)) | contains([{sku: "A1", qty: 3}]) |
Field might be null or missing | .tags[]? or (.tags // []) | .tags | contains(...), which errors and stops |
| Keep the result as an array | map(select(...)) | .[] | select(...), which prints separate values |
The test file
All examples use this repos.json. Note that cli-tools is tagged "golang",
not "go", that legacy-cron has "tags": null, and that docs-site has no
tags key at all:
[
{"name": "api-server", "lang": "Go", "tags": ["go", "http"], "owner": {"team": "platform"}, "stars": 120},
{"name": "cli-tools", "lang": "golang", "tags": ["golang", "cli"], "owner": {"team": "devex"}, "stars": 45},
{"name": "web-app", "lang": "TypeScript", "tags": ["frontend", "react"], "owner": {"team": "web"}, "stars": 300},
{"name": "legacy-cron", "lang": "Python", "tags": null, "owner": {"team": "platform"}, "stars": 3},
{"name": "docs-site", "lang": "Markdown", "owner": {"team": "devex"}, "stars": 12}
]
select basics: a stream, or an array with map
select(f) passes its input through if f is true and drops it otherwise. The
manual: it “produces its input unchanged if f returns true for that input, and
produces no output otherwise.” With .[] in front, you get one value per match:
$ jq -c '.[] | select(.lang == "Go") | .name' repos.json
"api-server"
Wrap it in map() if you need an array back, for example to write it to a file or
pipe it into length:
$ jq -c 'map(select(.stars >= 45)) | map({name, stars})' repos.json
[{"name":"api-server","stars":120},{"name":"cli-tools","stars":45},{"name":"web-app","stars":300}]
Combine conditions with and, or and not:
$ jq -c '.[] | select(.stars > 40 and (.tags // [] | length) > 0) | .name' repos.json
"api-server"
"cli-tools"
"web-app"
contains on a string field: substring, case-sensitive
On a string, contains is a plain substring test, and it is case-sensitive.
"Go" is not matched by "go":
$ jq -c '.[] | select(.lang | contains("go")) | .name' repos.json
"cli-tools"
To ignore case, use test with the "i" flag (it takes a regex), or lowercase
the field first:
$ jq -c '.[] | select(.lang | test("^go"; "i")) | .name' repos.json
"api-server"
"cli-tools"
$ jq -c '.[] | select(.lang | ascii_downcase == "go") | .name' repos.json
"api-server"
The first one matches anything that starts with “go” in any case, so it also
catches "golang". The second is an exact, case-insensitive comparison.
One more thing about substring tests: every string contains the empty string. If the search term comes from a variable and the variable is empty, every record matches:
$ jq -c --arg q "" '.[] | select(.name | contains($q)) | .name' repos.json
"api-server"
"cli-tools"
"web-app"
"legacy-cron"
"docs-site"
contains on an array field: still a substring test
This is the one that catches people. The manual defines it like this: “An array B
is contained in an array A if all elements in B are contained in any element in
A.” And for strings, contained means substring. So ["golang"] contains
["go"]:
$ jq -c '.[] | select(.tags // [] | contains(["go"])) | .name' repos.json
"api-server"
"cli-tools"
cli-tools has no "go" tag, only "golang". The same rule makes
contains(["go", "cli"]) look like an “has both tags” check when it isn’t:
$ jq -c '.[] | select(.tags // [] | contains(["go","cli"])) | .name' repos.json
"cli-tools"
No repo is tagged both "go" and "cli". cli-tools passed because "golang"
contains "go".
Exact element match: any, or index
any(generator; condition) is true if the condition holds for at least one output
of the generator. Here the generator is each tag, and the condition is an exact
comparison:
$ jq -c '.[] | select(any(.tags[]?; . == "go")) | .name' repos.json
"api-server"
The ? after .tags[] matters, see the next section.
index also works. On an array with a non-array argument, it looks for an element
equal to the argument and returns its position, or null:
$ jq -c '.[] | select(.tags | index("go")) | .name' repos.json
"api-server"
This works even though "go" is at position 0. In jq only false and null
count as false; the manual says “anything else is a “true value"", including 0.
(If you’re used to JavaScript, that’s the opposite of what you’d expect, and here
it helps.)
Side by side, on a single value:
$ jq -n -c '"golang" | contains("go"), (["golang"] | contains(["go"])), (["golang"] | index("go")), ("golang" | index("go"))'
true
true
null
0
“Has all of these tags”
There is no built-in for “contains all of these, exactly”. Loop over the wanted
values with all and check each with index:
$ jq -c '.[] | select((.tags // []) as $t | ["go","cli"] | all(. as $w | $t | index($w))) | .name' repos.json
That printed nothing, which is correct: no repo has both. Swap all for any to
get “has at least one of these”:
$ jq -c '.[] | select((.tags // []) as $t | ["go","cli"] | any(. as $w | $t | index($w))) | .name' repos.json
"api-server"
"cli-tools"
cli-tools matched on "cli" this time, not on "golang".
“Has any of these tags”: any with IN
IN(s) is true if the input equals any value in s. Combined with any:
$ jq -c '.[] | select(any(.tags[]?; IN("go","react"))) | .name' repos.json
"api-server"
"web-app"
If the list comes from the command line, pass it as JSON and expand it with []:
$ jq -c --argjson want '["go","react"]' '.[] | select(any(.tags[]?; IN($want[]))) | .name' repos.json
"api-server"
"web-app"
Don’t drop the any. select(.tags[]? | IN(...)) runs select once per tag, so a
record with two matching tags is printed twice:
$ jq -c '.[] | select(.tags[]? | IN("go","http")) | .name' repos.json
"api-server"
"api-server"
A null or missing field stops the whole run
legacy-cron has "tags": null, and docs-site has no tags, which jq also reads
as null. contains refuses to compare null with an array:
$ jq -c '.[] | select(.tags | contains(["go"])) | .name' repos.json
"api-server"
"cli-tools"
jq: error (at repos.json:7): null (null) and array (["go"]) cannot have their containment checked
The exit code was 5 on all three builds. The two names printed are from before the
error; docs-site was never checked. That’s because the whole file is one JSON
value, and .[] is a single run over it: after an error, jq moves on to the next
input value, and there isn’t one. So where the null sits decides how much you lose. With
the null record first (nullfirst.json: legacy-cron with "tags": null, then
api-server with ["go", "http"], then docs-site without tags), nothing is
printed at all:
$ jq -c '.[] | select(.tags | contains(["go"])) | .name' nullfirst.json
jq: error (at nullfirst.json:5): null (null) and array (["go"]) cannot have their containment checked
Iterating a null with [] fails the same way, so any(.tags[]; ...) without the ?
is no safer:
$ jq -c '.[] | select(any(.tags[]; . == "go")) | .name' nullfirst.json
jq: error (at nullfirst.json:5): Cannot iterate over null (null)
If your data is one object per line (NDJSON) instead of one big array, each line is its own input, so jq does carry on after the bad record. But look at the exit code: it was 0 on all three builds, with the error printed in between.
$ jq -c 'select(.tags | contains(["go"])) | .name' repos.ndjson
jq: error (at repos.ndjson:1): null (null) and array (["go"]) cannot have their containment checked
"api-server"
(repos.ndjson is two lines: legacy-cron with "tags": null, then api-server
with ["go", "http"].) A script that only checks $? won’t notice that a record
was skipped.
Three fixes, all tested on the same three-record file:
$ jq -c '.[] | select(any(.tags[]?; . == "go")) | .name' nullfirst.json
"api-server"
$ jq -c '.[] | select(.tags // [] | contains(["go"])) | .name' nullfirst.json
"api-server"
$ jq -c '.[] | select(.tags | index("go")) | .name' nullfirst.json
"api-server"
[]?iterates nothing when the value can’t be iterated.// []replacesnull(andfalse) with an empty array beforecontainssees it.indexonnulljust returnsnull, no error. That’s handy, but it also means a typo in the field name fails silently.
You can also put ? after contains(...). It works here, but ? is shorthand
for try, so it hides every error inside it, including ones you’d want to see.
Watch out with not
Negating a filter that errors is worse, because the result looks plausible:
$ jq -c '.[] | select(.tags | contains(["go"]) | not) | .name' repos.json
"web-app"
jq: error (at repos.json:7): null (null) and array (["go"]) cannot have their containment checked
legacy-cron and docs-site don’t have the "go" tag either, but they were
never checked. With the // [] guard, all three show up (and note cli-tools is
still missing, because of the substring rule):
$ jq -c '.[] | select(.tags // [] | contains(["go"]) | not) | .name' repos.json
"web-app"
"legacy-cron"
"docs-site"
Arrays of objects
The same substring rule applies when the array holds objects. orders.json:
[
{"id": 1, "items": [{"sku": "A1", "qty": 2}, {"sku": "B7", "qty": 1}]},
{"id": 2, "items": [{"sku": "A10", "qty": 5}]},
{"id": 3, "items": [{"sku": "C3", "qty": 1}, {"sku": "A1", "qty": 4}]},
{"id": 4, "items": []}
]
contains matches "A10" when you ask for "A1"
$ jq -c '.[] | select(.items | contains([{sku: "A1"}])) | .id' orders.json
1
2
3
Order 2 only has A10. For objects, the manual says B is contained in A “if all
of the values in B are contained in the value in A with the same key”, and the
values are strings, so substring again. Use any with ==:
$ jq -c '.[] | select(any(.items[]; .sku == "A1")) | .id' orders.json
1
3
Two conditions must be on the same object
This one doesn’t even need a substring to go wrong. Which orders have a line with
SKU A1 and quantity 1? None of them do. contains says two:
$ jq -c '.[] | select(.items | contains([{sku: "A1"}, {qty: 1}])) | .id' orders.json
1
3
Each object in the argument only needs to match some element, not the same one.
Order 1 has A1 on one line and a quantity of 1 on another (B7). Put both
conditions inside one any so they’re checked against the same item:
$ jq -c '.[] | select(any(.items[]; .sku == "A1" and .qty == 1)) | .id' orders.json
$ jq -c '.[] | select(any(.items[]; .sku == "A1" and .qty >= 3)) | .id' orders.json
3
The first printed nothing, which is the right answer.
Duplicates from select(.items[]...)
select(.items[].sku == "A1") is a common shortcut. It gives the right answer on
orders.json only because no order has two A1 lines. With two:
$ jq -n -c '[{"id":5,"items":[{"sku":"A1"},{"sku":"A1"}]}] | .[] | select(.items[].sku == "A1") | .id'
5
5
$ jq -n -c '[{"id":5,"items":[{"sku":"A1"},{"sku":"A1"}]}] | .[] | select(any(.items[]; .sku == "A1")) | .id'
5
any returns a single true or false per record, so each record comes out
once.
Filter the inner array, keep the outer objects
If you want every order but only its matching lines, filter items in place:
$ jq -c '.[] | .items |= map(select(.sku == "A1"))' orders.json
{"id":1,"items":[{"sku":"A1","qty":2}]}
{"id":2,"items":[]}
{"id":3,"items":[{"sku":"A1","qty":4}]}
{"id":4,"items":[]}
What differed between versions
macOS /usr/bin/jq (1.6-apple) | 1.7.1 | 1.8.2 | |
|---|---|---|---|
Every select, contains, any, all, IN, test command above | same output | same output | same output |
Error messages for the null cases above | same | same | same |
"héllo wörld" | index("w") | 7 | 7 | 6 |
On 1.8.2:
$ jq -n -c '"héllo wörld" | index("w")'
6
1.7.1 and the macOS build print 7 for the same command: they count bytes, and
é is two bytes in UTF-8. The change is in the 1.8 release notes: “Use code point index for
indices/1, index/1 and rindex/1”, marked as a breaking change. It only
affects strings with non-ASCII characters, and it doesn’t change any select on
this page, because select only cares whether index returned null.
Which one to use
- Exact element in an array:
select(any(.tags[]?; . == "go")). It’s exact, it survivesnulland missing fields, and it prints each record once. - One of several values:
select(any(.tags[]?; IN("go", "react"))). - Several conditions on one nested object: one
any(.items[]; A and B). - Substring in a string field:
containsis fine. Usetest(...; "i")to ignore case, and check that the search term isn’t empty. - Avoid
containson arrays and objects unless substring matching is what you want, and never call it on a field that can benullwithout// []in front.
The manual sections quoted above are in the official jq manual: https://jqlang.org/manual/
Related: converting JSON to CSV, where a select usually comes
right before @csv, and editing a JSON file in place,
which covers what happens when a select matches nothing and you write the result
back.