Search query syntax reference for Resource Explorer - Amazon Resource Explorer
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China.

Search query syntax reference for Resource Explorer

Amazon Resource Explorer helps you to find individual Amazon resources in your Amazon Web Services 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.

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 Amazon Web Services 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.

Basics

At its most basic, a QueryString is a set of free-form text keywords that are implicitly joined by a logical OR operator. Separate 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

Resource Explorer sorts results by relevance, giving higher preference to resources that match a greater number of the search terms. Resources that don't match one or more of the terms aren't excluded from the results. However, Resource Explorer considers them of lower relevance and pushes them 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

Amazon 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. Unlike text keywords, filters are evaluated in the query with the AND operator. For example, consider the following query that consists of two free-form keywords and two filters:

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

This query is evaluated as follows:

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

Filters are always evaluated using AND logical operators. If a resource doesn't match the filter, that resource is not included in the results. The example query's results include any resources that are associated with Amazon EC2 and are in the US West (Oregon) Amazon Web Services Region and have at least one of the keywords attached in some way.

Note

Because of the implicit AND, 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 Amazon Web Services 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:.

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

Filter name Description and example

id:

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

id:arn:aws-cn:license-manager:cn-north-1:123456789012:license-configuration:lic-ecbd5574fd92cb0d312baea26EXAMPLE

accountid:

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

accountid:123456789012

region:

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

region:cn-north-1

Note

Typing only the Region code (without a filter, such as cn-north-1) doesn't return the same results as region:cn-north-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, 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 Amazon Web Services 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.

service:

The Amazon Web 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

resourcetype:

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

resourcetype:ec2:instance

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

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.

Note

Resources with Amazon 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

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

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.

"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".

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 Amazon Web Services 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.

-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 Amazon 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:)