How queries work in Resource Explorer Query 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`