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.

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

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. 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) AWS 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 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:.

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