Query Contains Examples with AWS CLI

# Table of Contents

# Query Contains Examples with AWS CLI

The --query parameter in AWS CLI enables us to do client-side filtering on the JSON output the CLI returns.

To return only values that contain a certain string, use the contains function with the --query parameter.

Let's look at an example that returns only S3 buckets that contain amplify in their name.

shell

Copied!
aws s3api list-buckets --query 'Buckets[?contains(Name, `amplify`) == `true`]'

contains query basic

Note that the string we passed to the --query parameter is enclosed in single quotes.
The second argument we passed to the contains function is enclosed in backticks.
The boolean operator at the end is also enclosed in backticks.

The --query parameter uses JMESPath. We used the contains function.

The function applies the contains filter on the client side after the AWS CLI has made the API call to retrieve the buckets, but before the output is returned to the caller.

In the command above, we listed all S3 buckets and checked whether each bucket's Name property contains the string amplify.

The contains function returns true or false, so we are checking if the function returned true. If it did, then the value of the bucket's Name property contains the string amplify and should be included in the output.

If we only wanted to return a list of the bucket names that contain amplify, we can append .Name to the expression.

shell

Copied!
aws s3api list-buckets --query 'Buckets[?contains(Name, `amplify`) == `true`].Name'

contains return names

Similarly, if we want to format the output in an array of objects but only pick certain properties, or rename the properties of the object, we can chain an object to the JMESPath expression.

shell

Copied!
aws s3api list-buckets --query 'Buckets[?contains(Name, `amplify`) == `true`].{name:Name, createdAt: CreationDate}'

We filtered the results to only buckets whose Name property contains the string amplify.
We then returned an array of objects where we renamed the Name property to name and the CreationDate property to createdAt.

contains chain object

The contains function works differently on strings and lists. If the first argument to contains is a string, then the function checks if the second argument is contained in that string. For instance, contains(`hello`, `hell`) returns true.

However, when the first argument is a list, the function checks for equality between the elements in the list and the second argument passed to the contains function. For example, with a first argument of ["hello", "world"], the invocation of contains(@, `hell`) returns false

# Query NOT Contains Example with AWS CLI

To filter the output of an AWS CLI command based on a string not being contained in the results, check that the contains function returns false.

The following example lists all of my S3 Buckets where the bucket's name doesn't contain the string dev.

shell

Copied!
aws s3api list-buckets --query 'Buckets[?contains(Name, `dev`) == `false`]'

not contains query

The contains function was invoked on all of the bucket objects in the output list.

For each bucket object, e.g. - {"Name": "my-bucket", "CreationDate": "2020-06-..."}, the contains function is called with the value of the bucket's Name property and the string dev.

If the value of the bucket's Name property contains the string dev, the contains function returns true.

Since we are specifically filtering for buckets with names that don't contain the string dev, we specified that the result of the function invocation should evaluate to false.

# Additional Resources

You can learn more about the related topics by checking out the following tutorials:

I wrote a book in which I share everything I know about how to become a better, more efficient programmer.

You can use the search field on my Home Page to filter through all of my articles.

Query Contains Examples with AWS CLI

# Table of Contents