Toolarity

jq select with contains: Why It Matches Too Much, and What to Use

Guide jq Published November 12, 2026

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 wantUseNot
Field equals a valueselect(.lang == "Go")
String field contains a substringselect(.lang | contains("go")) (case-sensitive)
Same, ignoring caseselect(.lang | test("go"; "i"))
Array field has an exact elementselect(any(.tags[]?; . == "go"))contains(["go"]), which also matches "golang"
Array field has any of several valuesselect(any(.tags[]?; IN("go", "react")))select(.tags[] == "go"), which can print a record twice
Array of objects has one object matching two conditionsselect(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 arraymap(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.
  • // [] replaces null (and false) with an empty array before contains sees it.
  • index on null just returns null, 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.11.8.2
Every select, contains, any, all, IN, test command abovesame outputsame outputsame output
Error messages for the null cases abovesamesamesame
"héllo wörld" | index("w")776

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 survives null and 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: contains is fine. Use test(...; "i") to ignore case, and check that the search term isn’t empty.
  • Avoid contains on arrays and objects unless substring matching is what you want, and never call it on a field that can be null without // [] 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.