Using Amazon Resource Explorer to search for resources - 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.

Using Amazon Resource Explorer to search for resources

The primary purpose of enabling Amazon Resource Explorer in your Amazon Web Services account is to allow your users to search for resources in the account. Use the Amazon Web Services Management Console or the Amazon Command Line Interface (Amazon 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 Managing Resource Explorer views to provide access to search.

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

  • A search can return only the first 1,000 results.

    This requirement includes a search with an empty query string that matches all resources. To see resources beyond the 1,000 returned by an empty query string, you must use queries to restrict matching results to those you want to see and limit the number of matches to less than 1,000.

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

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

  3. Choose Search to submit your query.

    Resource Explorer displays all of the results that match both the Filter defined in the view and the Query that you provide. 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.

  4. 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 service.

Amazon 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-west-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-cn:resource-explorer-2:us-west-2:123456789012:view/My-Resources-View/1a2b3c4d-5d6e-7f8a-9b0c-abcd11111111