Using AWS Resource Explorer to search for resources - AWS Resource Explorer
Search query templates

Using AWS Resource Explorer to search for resources

The primary purpose of enabling AWS Resource Explorer in your AWS account is to allow your users to search for resources in the account, and to use the Resource Explorer console to quickly act on those resources. You can use the AWS Management Console or the AWS Command Line Interface (AWS CLI) to search for resources using Resource Explorer.

The following are some of the main characteristics of Resource Explorer search.

  • Every search must use a view.

    The view is what Resource Explorer uses to determine who has permissions to see which resources. To use a view in a Resource Explorer search operation, the user must have an Allow on the resource-explorer-2:Search operation for the specified view. This permission comes from an identity-based permission policy attached to the principal making the request.

    The view can include a filter that limits which resources can be included in the results. By creating different views that use filters and by granting different principals access to different views, you can configure an environment where each group of users can view only the resources relevant to them.

    For more information about views, see Configuring an Resource Explorer view to provide access to resource searches.

  • Resource Explorer uses asynchronous background processes to maintain its indexes.

    It can take Resource Explorer some time for its indexing processes to discover newly created or modified resources and add them to the local index. It can take additional time for Resource Explorer to replicate changes in the local indexes to the aggregator index.

    The same applies to resources that you delete. It can take some time after you delete a resource for that deletion to be discovered by the indexing process and that resource's information to be removed from the local index. Additional time is needed for Resource Explorer to replicate that deletion from the local index to the account's aggregator index.

    Additions, modifications, and deletions to your resources can take up to a maximum of 36 hours for Resource Explorer to show those changes in search results in all Regions where you've activated Resource Explorer.

  • A search in Resource Explorer occurs within an AWS Region.

    Each Region where you turn on Resource Explorer contains an index of only the resources stored in that Region. Views are also associated with Regions, and can return only the resources found in that Region's index. The one exception to this is the aggregator index, that receives a replicated copy of all of the local indexes to support searching across all Regions in the account.

  • Cross-Region search requires an aggregator index for the account.

    To let users search for resources across all AWS Regions, the administrator must designate one Region to contain the aggregator index for the account. A copy of every local index is automatically replicated to the aggregator index.

    Because of this, only views in the aggregator index Region can return results that include resources from all AWS Regions in the account.

  • A query consists of any number of free-form text keywords and filters.

    Free-form keywords are combined in the query using logical OR operators. Filters that use Resource Explorer defined filter names are combined in the query using logical AND operators. Consider the following example query.

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

    This is evaluated by Resource Explorer as follows.

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

    This query requires that matching resources must be Amazon EC2 resources in the US West (Oregon) Region, and have at least one of the keywords (test, instance) attached in some way, such as in the name, description, or tags.

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

  • A search can return only the first 1,000 results if you include free-form text.

    If your query includes free-form text, Resource Explorer uses the Search API operation, but if your query does not include free-form text, Resource Explorer uses the ListResources operation. Search operations are limited to 1,000 results that are sorted by relevancy, while the ListResources operation has no upper limit and are not sorted by relevancy. To view query resources beyond 1,000 results when using free-form text (the Search operation), you must use additional filters to restrict matching results to those you want to see.

  • There is a per-account quota on the number of search operations that you can perform.

    Quotas limit how many queries you can make per second, and how many queries you can make each month. For specific quota numbers, see Quotas for Resource Explorer. Quota usage depends on if Resource Explorer performs resource queries using the Search or ListResources operations on your behalf based on the logic described in the previous list item.

AWS Management Console
To search for resources using Resource Explorer

  1. On the Resource search page, start by choosing the view that you want to use. You can choose from among only those views that you have permissions to access.

  2. (Optional) Choose a Query template.

    1. For templates that require a specified resource type or application, choose a value.

    2. Choose Apply.

  3. (Optional) For Query, enter the search terms and filters that identify the resources you want to see. For information about all of the available syntax options, see Search query syntax reference for Resource Explorer.

  4. Resource Explorer displays all of the results that match both the Filter defined in the view and the Query that you provide. If your query includes free-form text, the results are sorted by relevance, with those resources that match more of your query terms appearing higher in the list and resources that match fewer terms appearing further down the list.

  5. You can view details about the selected resource from within Resource Explorer by selecting the checkbox in the table.

    Alternatively, you can choose the identifier of a resource to navigate to that resource type's native console, where you can interact with the resource in all of the ways supported by that AWS service.

After submitting your search query, Resource Explorer displays a results table. You can use the

AWS CLI
To search for resources using Resource Explorer

Run the following command to search for resources using the specified view. That view must exist in the Region in which you run the operation. The following example searches for Amazon EC2 instances that are tagged env=production in the US East (Ohio) (us-east-2). For information about all of the available syntax options for the query-string parameter, see Search query syntax reference for Resource Explorer.

$ aws resource-explorer-2 search \
    --region us-east-1 \
    --query-string "resourcetype:AWS::EC2::Instance tag:env=production"
    --view-arn arn:aws:resource-explorer-2:us-east-2:123456789012:view/My-Resources-View/1a2b3c4d-5d6e-7f8a-9b0c-abcd11111111

Search query templates

The Resource Explorer console provides search query templates, which are predefined query configurations for common queries. Query templates allow you to quickly perform a search and better understand how to customize your own queries. For some templates, you must specify the desired resource type or application in the template filter. After selecting a query template, you can add additional query strings and filters.

You can choose from the following query templates:

  • Tagged resources — This template returns resources with user or system tags, including tagged resource types that are not supported by Resource Explorer.

  • All untagged resources — This template returns resources with no user or system tags.

  • All non-taggable resources — This template returns resources that do not support tagging.

  • All untagged resources of [type] — This template returns resources with no user tags of the specified type.

  • Resources not in [application] — This template returns resources that do not belong in the specified application.

  • All resources in [application] — This template returns resources that belong to the specified application.

  • Amazon EC2 resources that are not instances in [application] — This template returns Amazon EC2 resources that are not the ec2:instance resource type and that belong in the specified application.