Search query syntax reference for Resource Explorer - AWS Resource Explorer
How queries work in Resource ExplorerQuery string syntax

Search query syntax reference for Resource Explorer

AWS Resource Explorer helps you to find individual AWS resources in your AWS accounts. To help you find the exact resources you're looking for, Resource Explorer accepts search query strings that support the syntax described in this topic. For example queries that demonstrate how to use the features described here, see Example Resource Explorer search queries.

Note

At this time, tags attached to AWS Identity and Access Management (IAM) resources, such as roles or users, are not indexed.

How queries work in Resource Explorer

Search queries always use a view. If you don't explicitly specify one, Resource Explorer uses the view designated as the default for the AWS Region that you're working in.

Views determine which resources are available for you to query. You can create different views that each return a different set of resources.

For example, you could create a view that includes only those resources that are tagged with the key Environment and the value Production. Then, you could choose to grant access for that view to only those users who have a business reason to view those resources. A separate view that includes the Alpha or Beta environment resources could be accessed by different users who need to view those resources. For information about controlling who gets access to which views, see Granting access to Resource Explorer views for search.

Query string syntax

This section provides information about basic aspects of query syntax, filters, and filter operators.

Search query string

A QueryString is a set of free-form text keywords that Resource Explorer implicitly joins using OR operator logic. You seperate each keyword from the others by using a space, as shown in the following example:

ec2 billing test gamma

Resource Explorer evaluates this list of keywords to mean:

ec2 OR billing OR test OR gamma

The search results for this example are based on the following behavior:

  • Resource Explorer sorts results by relevance and gives higher preference to resources that match a greater number of the search terms. Resources that match more of the terms are pushed higher in the search results.

  • Resources that do not match one or more of the terms aren't excluded from the results, but Resource Explorer considers them of lower relevance. Resources that don't match the terms are pushed further down in the search results.

If you specify an empty string for the QueryString parameter, your query returns the first 1,000 resources that are available through the view used for the operation. The maximum number of resources that can be returned by any query is 1,000.

Note

AWS reserves the right to update the matching logic and relevance algorithms for evaluating free-form text keywords so that we can provide customers with the most relevant results. Therefore, results returned for the same queries using free-form text keywords might change over time. Where you require more deterministic results, we recommend that you use filters. Filter matching logic does not change over time.

Filters

You can limit the results of your query more strictly by including filters.

If you use more than one filter in the search query, Resource Explorer joins the filters using the AND operator. If a filter contains multiple values, Resource Explorer uses the OR operator between each value.

For example, consider the following query that consists of two free-form keywords and two specified filters:

test instance service:EC2 region:us-west-2

Resource Explorer evaluates the query as follows:

( test OR instance ) AND service:EC2 AND region:us-west-2

The query string test instance follows the logical OR syntax of a keyword query string while the specified service: and region: filters follow the implicit AND syntax. This example query's results include any resources that are associated with Amazon EC2, and are in the US West (Oregon) AWS Region, and have at least one of the keywords attached in some way.

Note

Because of the implicit AND operator, you can successfully use only one filter for an attribute that can have only one value associated with the resource. For example, a resource can be part of only one AWS Region. Therefore, the following query returns no results.

region:us-east-1 region:us-west-1

This limitation does not apply to the filters for attributes that can have multiple values at the same time, such as tag:, tag.key:, and tag.value:.

Specifying multiple filter values

Resource Explorer allows you to specify multiple values for each filter, which Resource Explorer joins with the OR operator. You can use this operator to scope down results to multiple resource types, accounts, tags, and more with a simple syntax. When specifying multiple values in the same filter, separate each value with a comma.

For example, consider the following query that consists of two filters, where one filter includes multiple possible values separated by a comma:

service:EC2 region:us-west-2,us-east-1

Given the comma-separated syntax of the region: filter, Resource Explorer evaluates the query as follows:

(service:EC2) AND (region:us-west-2 OR region:us-east-1)

Resource Explorer applies the OR operator to the comma-separated region: filter values.

This example query's results include any resources that are associated with Amazon EC2 and are in the US West (Oregon) or US East (N. Virginia) AWS Region.

Note

You can escape or quote the commas used to specify the OR operator like other special characters. For example, tag.key:comma\,literal or tag.key:"comma,literal".

The following table lists the available filter names that you can use in a Resource Explorer search query.

Filter name Description and example

accountid:

The AWS account that owns the resource. Resource Explorer includes in the results only the resources that are owned by the specified account.

accountid:123456789012

application:

This filter enables you to search for resources with an awsApplication tag key and a resource group value. You can search by application name or the application resource group ARN.

application:MyApplicationName

application:arn:aws:resource-groups:us-east-1:123456789012:group/MyApplicationName/123456789abced

arn:aws:resource-groups:us-east-1:123456789012:group/MyApplicationName/123456789abced

Note

To use this filter, your view must have access to tagging data.

id:

The identifier of an individual resource, expressed as an Amazon resource name (ARN).

id:arn:aws:license-manager:us-east-1:123456789012:license-configuration:lic-ecbd5574fd92cb0d312baea26EXAMPLE

region:

The AWS Region where the resource is located. Resource Explorer includes in the results only the resources that reside in the specified AWS Region.

region:us-east-1

Note

Typing only the Region code (without a filter, such as us-east-1) doesn't return the same results as region:us-east-1. This outcome is because, as a free-form text keyword that isn't a filter, the Region code is broken down into its individual pieces. For example, us-east-1 is searched as us, east, and 1. This breakdown into components doesn't occur when you use the region: prefix.

region:global

A special case for the region: filter that you can use to find resources that are not associated with an individual AWS Region but are considered to be global in scope.

region:global

Note

Typing only the keyword global doesn't return the same results as region:global because the literal word "global" is not attached to global resources. Typing global as a keyword returns only those resources that have that literal string associated with the resource.

resourcetype:

The resource type in service:type notation. Resource Explorer includes in the results only the resources of the specified type.

resourcetype:ec2:instance

resourcetype.supports:

This filter enables you to search for resources that support tags. tags is the only supported value. Resource Explorer includes in the results only the resources that are taggable.

resourcetype.supports:tags

service:

The AWS service that is associated with the type of the resource. Resource Explorer includes in the results only the resources that are created and managed by the specified service.

service:ec2

tag:

A tag key/value pair expressed as <key>=<value>. Resource Explorer includes in the results only the resources that have a tag with both a matching key and the specified value.

tag:environment=production

To use this filter, your view must have an IncludeProperty with the Name parameter specified as tags. This configuration displays the tag property and value in resource search results.

tag:all

A special case of the tag: filter that enables you to search for resources that have one or more user-created tags attached, even if the resource type is not supported in Resource Explorer.

To use this filter, your view must have an IncludeProperty with the Name parameter specified as tags. This configuration displays the tag property and value in resource search results.

Note

Resources with AWS service-created tags still appear in results for this filter.

tag:none

A special case of the tag: filter that enables you to search for any resources that don't have any user-created tags attached.

To use this filter, your view must have an IncludeProperty with the Name parameter specified as tags. This configuration displays the tag property and value in resource search results.

Note

Resources with AWS service-created tags still appear in results for this filter.

tag.key:

A tag key. Resource Explorer includes in the results only the resources that have a tag with a matching key, regardless of value.

tag.key:environment

To use this filter, your view must have an IncludeProperty with the Name parameter specified as tags. This configuration displays the tag property and value in resource search results.

tag.value:

A tag value. Resource Explorer includes in the results only the resources that have a tag with a matching value, regardless of the key name.

tag.value:production

To use this filter, your view must have an IncludeProperty with the Name parameter specified as tags. This configuration displays the tag property and value in resource search results.

Filter operators

You can modify your keywords and filters by including one of the operators shown in the following table as part of the string.

Operator Description and example

"multiple word phrase"

or

"hyphenated-phrase"

Surround a multi-word phrase that should be treated as a single keyword with double quotation marks characters (" "). Resource Explorer includes only those resources that match the entire phrase, with all words together, and in the specified order.

If you don't use the double quotation marks, Resource Explorer breaks up the phrase into its components by spaces or hyphens, and includes resources that match the individual components, even if they're not together or in a different order. Quotations should be around everything after the operator.

"This matches only resources with the whole sentence."

This matches resources with any of the words.

"us-east-1" – matches only resources that associated with that exact Region.

us-east-1 – matches any resource that contain "us" or "east" or "1".

-tag:"environment=production"

keyword*

Prefix wildcard matching. You can place a wildcard character (an asterisk *) at only the end of the string. Resource Explorer includes in the results only the resources with values that start with the prefix text before the *. The following example matches all AWS Regions that begin with us-east.

region:us-east*

Important

Unified search automatically inserts a wildcard character (*) operator at the end of the first keyword in the string. This means that unified search results include resources that match any string that starts with the specified keyword.

The search performed by the Query text box on the Resource search page in the Resource Explorer console does not automatically append a wildcard character. You can insert a * manually after any term in the search string.

value,value

OR operator. You can place a comma (,) between multiple values in a filter. The following example causes Resource Explorer to return search results that match any of the values in the region: filter.

service:EC2 region:us-west-2,us-east-1

-keyword

NOT operator. You can place a hyphen (-) at the beginning of its keyword or filter to invert the search results. Resource Explorer excludes from the results any resources that match the keyword or filter that follows this operator. The following example causes all resources associated with the Amazon EC2 service to be excluded from the results.

-service:ec2

Important

If you use the AWS CLI search command and your --query-string parameter value has the - operator as the first character, you must separate the parameter name from its value with an equal sign character (=) instead of the usual space character. If you use the space character, the CLI misinterprets the string. For example, the following query fails.

aws resource-explorer-2 search --query-string "-tag:none region:us-east-1"

The following corrected query string, with an = replacing the space, works as expected.

aws resource-explorer-2 search --query-string="-tag:none region:us-east-1"

If you change the order of the filters in the query string so that the - isn't the first character in the parameter value, you can use the standard space character. The following query string works.

aws resource-explorer-2 search --query-string "region:us-east-1 -tag:none"
\<special character>

You can escape special characters that must be included exactly as shown rather than interpreted. If your text includes one of the special characters ( * " - : = \), you must precede that character with a backslash (\) to ensure that the character is taken literally. The following example shows how to use a free-form text keyword that includes the hyphen (-) character ("my-key-word").

Also, to prevent Resource Explorer from breaking up the expression at the hyphens into three separate keywords, you can surround the entire phrase in double quotation marks.

"my\-key\-word"

To insert a literal backslash, insert two backslash characters in a row. The first backslash is interpreted as the escape and the second backslash is the literal character to insert.

"some_text\\some_more_text"
Note

If the view includes the tags attached to the resources, then the Search operation doesn't throw validation errors for search strings, because a filter that's not valid could also be interpreted as a free-form text search. For example, even though cat:blue looks like a filter, Resource Explorer can't parse it as one because cat: isn't one of the valid, defined filters. Instead Resource Explorer interprets the whole string as a free-form search string to allow it to match things like a tag key name or a piece of an ARN.

The operation does throw a validation error if either of the following is true:

  • The view doesn't include information about tags

  • The search query explicitly uses a tag filter (tag.key:, tag.value:, or tag:)