Creating an Amazon CloudSearch Domain

To search your data with Amazon CloudSearch, the first thing you need to do is create a search domain. If you have multiple collections of data that you want to make searchable, you can create multiple search domains. Before you can send search requests to a new domain, you must also configure access policies, configure index fields, and upload the data you want to search.

When you create a search domain, you must give it a unique name. Domain names must start with a letter or number and be at least 3 and no more than 28 characters long. The allowed characters are: a-z, 0-9, and hyphen (-). Upper case letters, underscores (_), and other special characters are not allowed in domain names.

By default, all new domains are created using the 2013-01-01 API version. If you have previously created search domains with the 2011-02-01 API version, you can opt to use the old API for your new domain. However, we recommend using the 2013-01-01 API for all new use cases. All domains will need to migrate to the 2013-01-01 API when the 2011-02-01 API is retired.

You can choose the AWS region where you want to create your search domain. Typically, you should choose the region closest to your operations. For example, if you reside in Europe, create your search domain in the Europe (Ireland) region (eu-west-1). For a current list of supported regions and endpoints, see Regions and Endpoints. For more information about choosing a region, see Regions and Endpoints for Amazon CloudSearch.

Note

Amazon CloudSearch domains in different regions are entirely independent. For example, if you create a search domain called my-domain in us-east-1, and another domain called my-domain in eu-west-1, they are completely independent and do not share any data.

Each search domain has unique endpoints through which you upload data for indexing and submit search requests. A domain's document and search endpoints remain the same for the life of the domain. For example, the endpoints for a domain called imdb-movies might be:

doc-imdb-movies-nypdffbzrfkoudsurkxvgwbpi4.us-east-1.cloudsearch.amazonaws.com
search-imdb-movies-nypdffbzrfkoudsurkxvgwbpi4.us-east-1.cloudsearch.amazonaws.com

Important

By default, access to a new domain's document and search endpoints is blocked for all IP addresses. You must configure access policies for the domain to be able to submit search requests to the domain's search endpoint and upload data from the command line or through the domain's document endpoint. You can upload documents and search the domain through the Amazon CloudSearch console without configuring access policies.

You can create a search domain from the Amazon CloudSearch console, using the aws cloudsearch create-domain command, or using one of the AWS SDKs.

Creating a Domain Using the Amazon CloudSearch Console

The Amazon CloudSearch console enables you to easily create new search domains and provides a variety of options for configuring indexing options.

To create a domain

1. Sign in to the AWS Management Console and open the Amazon CloudSearch console at https://console.aws.amazon.com/cloudsearch/home.

2. Choose Create domain.

3. Enter a name for your new domain. Domain names must start with a letter or number and be at least 3 and no more than 28 characters long. Domain names can contain the following characters: a-z (lower case), 0-9, and - (hyphen). Upper case letters, underscores (_), and other special characters are not allowed in domain names.

   Optionally, you can set the Desired instance type and Desired replication count to prescale your domain. For more information, see Configuring Scaling Options in Amazon CloudSearch.

4. Choose Next.

5. In the configuring options, select Manual configuration and choose Next.

6. Configure the index fields for the domain. For instructions, see configure indexing options.

7. Choose Next.

8. Configure the domain access policy. For instructions, see configure access policies.

   Note

   Until you configure access policies, you will only be able to upload documents and submit search queries through the console. By default, the document and search endpoints are configured to block all IP addresses.

9. Choose Next.

10. Review the domain configuration and choose Create.

The domain's document and search service endpoints are displayed on the domain dashboard when the domain becomes active. At that point, you can upload documents for indexing and start searching your data.

Creating a Domain Using the AWS CLI

You use the aws cloudsearch create-domain command to create search domains. For information about installing and setting up the AWS CLI, see the AWS Command Line Interface User Guide.

To create a domain

• Run the aws cloudsearch create-domain command and specify the name of the domain you want to create with the --domain-name option. For example, to create a domain called movies:

  aws cloudsearch create-domain --domain-name movies
  {
    "DomainStatus": {
        "DomainId": "965407640801/movies", 
        "Created": true, 
        "Deleted": false, 
        "SearchInstanceCount": 0, 
        "DomainName": "movies", 
        "SearchService": {}, 
        "RequiresIndexDocuments": false, 
        "Processing": false, 
        "DocService": {}, 
        "ARN": "arn:aws:cloudsearch:us-east-1:965407640801:domain/movies", 
        "SearchPartitionCount": 0
    }
  }

The aws cloudsearch create-domain command returns immediately. It takes about ten minutes to create endpoints for a new domain. You can use the aws cloudsearch describe-domains command to view a summary of the domain's status and configuration. For more information, see Getting Information About an Amazon CloudSearch Domain.

Important

Once a domain's endpoints are active, they remain the same for the life of the domain. You should cache the endpoints—there's no need to query for the endpoint before submitting a document or search service request and doing so is likely to result in your requests being throttled.

Creating an Amazon CloudSearch Domain Using the AWS SDKs

The AWS SDKs (except the Android and iOS SDKs) support all of the Amazon CloudSearch actions defined in the Amazon CloudSearch Configuration API, including CreateDomain. For more information about installing and using the AWS SDKs, see AWS Software Development Kits.