Query Contains Examples with AWS CLI

avatar

Borislav Hadzhiev

Fri Sep 17 20213 min read

banner

Photo by Jamie Fenn

Table of Contents #

  1. Query Contains Examples with AWS CLI
  2. Query NOT Contains Example with AWS CLI

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.

In order 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
aws s3api list-buckets --query 'Buckets[?contains(Name, `amplify`) == `true`]'

contains query basic

Note that the string we've passed to the --query parameter is enclosed in single quotes.

The second argument we've passed to the contains function is enclosed in backticks and the boolean operator at the end is also enclosed in backticks.

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

It 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 are listing all the S3 buckets, and checking whether the 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 Nameproperty 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
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
aws s3api list-buckets --query 'Buckets[?contains(Name, `amplify`) == `true`].{name:Name, createdAt: CreationDate}'

In the command above we've filtered the results to only buckets whose Name property contains the string amplify and we're returning an array of objects, where we've 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
aws s3api list-buckets --query 'Buckets[?contains(Name, `dev`) == `false`]'

not contains query

In the command above, the contains function will get 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 will return true.

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

Further Reading #

Join my newsletter

I'll send you 1 email a week with links to all of the articles I've written that week

Buy Me A Coffee