jq contains

Daniel Parker

3 min read

·

24-02-2025

1

0

Share

The command-line JSON processor jq is a powerful tool for parsing and manipulating JSON data. One of its most useful features is the contains operator, allowing you to efficiently check if a JSON object or array contains a specific value. This article will delve into the intricacies of jq contains, showcasing its versatility and providing practical examples. We'll explore how to effectively utilize contains for various JSON structures and scenarios.

Understanding jq contains

The contains operator in jq is designed to check for the presence of a value within a JSON array or object. It returns true if the value is found, and false otherwise. The key difference between contains and other searching mechanisms is its simplicity and directness. It performs a straightforward check for exact value matches.

Important Note: contains performs a shallow comparison. It only checks for equality at the top level of an array or object. Nested structures within the array elements are not recursively examined.

Basic Usage: Checking for Values in Arrays

Let's start with the most straightforward use case: searching for a value within a JSON array.

Consider this JSON data:

[ "apple", "banana", "cherry", "date" ]

To check if this array contains "banana", we'd use the following jq command:

jq '. | contains("banana")' <<< '["apple", "banana", "cherry", "date"]'

This will output:

true

Similarly, searching for "grape" would yield:

jq '. | contains("grape")' <<< '["apple", "banana", "cherry", "date"]'

Output:

false

Searching within Objects

While primarily designed for arrays, contains can also be applied to objects, but its behavior is nuanced. It only checks for the existence of a key-value pair at the top level of the object, not within nested objects or arrays.

Let's use this example:

{
  "fruit": "apple",
  "color": "red",
  "size": "medium"
}

To verify the presence of the key-value pair "fruit": "apple": (Note: This doesn't check if the value "apple" exists independently, only the complete key-value pair). You would not use contains directly for this. Instead, you might use has to check for the existence of the key "fruit" and then access the value to compare:

jq '.fruit == "apple"' <<< '{"fruit": "apple", "color": "red", "size": "medium"}'

This would return true. Directly using contains on the object itself to find the value "apple" won't work as intended.

Advanced Usage: Combining with Other jq Filters

The true power of contains comes when combined with other jq filters. This allows for more complex searches and data manipulation.

For example, let's say we have an array of objects, and we want to find if any object contains a specific value in a particular field:

[
  {"name": "Alice", "age": 30},
  {"name": "Bob", "age": 25},
  {"name": "Charlie", "age": 35}
]

To see if any object has an age of 30:

jq '.[] | .age == 30' <<< '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}, {"name": "Charlie", "age": 35}]'

This returns true because one object matches. We are not using contains here because we're comparing a value within a specific key. Note that the output will include the true and also potentially other false values from the loop, if you need a single true/false answer, use any:

jq '.[] | .age == 30 | any' <<< '[{"name": "Alice", "age": 30}, {"name": "Bob", "age": 25}, {"name": "Charlie", "age": 35}]'

This would return true.

Handling Different Data Types

Remember that contains performs strict type checking. "1" and 1 are considered different values. Ensure that the data type of the value you're searching for matches the data type in the JSON.

Conclusion: jq contains in Your Workflow

The contains operator in jq offers a straightforward and efficient way to check for the existence of specific values within JSON arrays. While not suitable for deep searches within nested structures, its combination with other jq functions unlocks its full potential for complex JSON data processing. Remember to always keep data types in mind for accurate results. Mastering jq contains significantly enhances your ability to effectively filter and manipulate JSON data using the command line.