Creating, listing, and deleting Amazon OpenSearch Serverless collections

A collection in Amazon OpenSearch Serverless is a logical grouping of one or more indexes that represent an analytics workload. OpenSearch Service automatically manages and tunes the collection, requiring minimal manual input.

Permissions required

OpenSearch Serverless uses the following AWS Identity and Access Management (IAM) permissions for creating and managing collections. You can specify IAM conditions to restrict users to specific collections.

The following sample identity-based access policy provides the minimum permissions necessary for a user to manage a single collection named Logs:

[
   {
      "Sid":"Allows managing logs collections",
      "Effect":"Allow",
      "Action":[
         "aoss:CreateCollection",
         "aoss:ListCollections",
         "aoss:BatchGetCollection",
         "aoss:UpdateCollection",
         "aoss:DeleteCollection",
         "aoss:CreateAccessPolicy",
         "aoss:CreateSecurityPolicy"
      ],
      "Resource":"*",
      "Condition":{
         "StringEquals":{
            "aoss:collection":"Logs"
         }
      }
   }
]

aoss:CreateAccessPolicy and aoss:CreateSecurityPolicy are included because encryption, network, and data access policies are required in order for a collection to function properly. For more information, see Identity and Access Management for Amazon OpenSearch Serverless.

Creating collections

You can use the console or the AWS CLI to create a serverless collection. These steps cover how to create a search or time series collection. To create a vector search collection, see Working with vector search collections.

Create a collection (console)

The collection status changes to Creating as OpenSearch Serverless creates the collection.

Create a collection (CLI)

Before you create a collection using the AWS CLI, you must have an encryption policy with a resource pattern that matches the intended name of the collection. For example, if you plan to name your collection logs-application, you might create an encryption policy like this:

aws opensearchserverless create-security-policy \
  --name logs-policy \
  --type encryption --policy "{\"Rules\":[{\"ResourceType\":\"collection\",\"Resource\":[\"collection\/logs-application\"]}],\"AWSOwnedKey\":true}"

If you plan to use the policy for additional collections, you can make the rule more broad, such as collection/logs* or collection/*.

You also need to configure network settings for the collection in the form of a network policy. Using the previous logs-application example, you might create the following network policy:

aws opensearchserverless create-security-policy \
  --name logs-policy \
  --type network --policy "[{\"Description\":\"Public access for logs collection\",\"Rules\":[{\"ResourceType\":\"dashboard\",\"Resource\":[\"collection\/logs-application\"]},{\"ResourceType\":\"collection\",\"Resource\":[\"collection\/logs-application\"]}],\"AllowFromPublic\":true}]"

To create a collection, send a CreateCollection request:

aws opensearchserverless create-collection --name "logs-application" --type SEARCH --description "A collection for storing log data"

For type, specify either SEARCH or TIMESERIES. For more information, see Choosing a collection type.

Sample response

{
    "createCollectionDetail": {
        "id": "07tjusf2h91cunochc",
        "name": "books",
        "description":"A collection for storing log data",
        "status": "CREATING",
        "type": "SEARCH",
        "kmsKeyArn": "auto",
        "arn": "arn:aws:aoss:us-east-1:123456789012:collection/07tjusf2h91cunochc",
        "createdDate": 1665952577473
    }
}

If you don't specify a collection type in the request, it defaults to TIMESERIES. If your collection is encrypted with an AWS owned key, the kmsKeyArn is auto rather than an ARN.

Accessing OpenSearch Dashboards

After you create a collection with the AWS Management Console, you can navigate to the collection's OpenSearch Dashboards URL. You can find the Dashboards URL by choosing Collections in the left navigation pane and selecting the collection to open its details page. The URL takes the format https://dashboards.us-east-1.aoss.amazonaws.com/_login/?collectionId=07tjusf2h91cunochc. Once you navigate to the URL, you'll automatically log into Dashboards.

If you already have the OpenSearch Dashboards URL available but aren't on the AWS Management Console, calling the Dashboards URL from the browser will redirect to the console. Once you enter your AWS credentials, you'll automatically log in to Dashboards. For information about accessing collections for SAML, see Accessing OpenSearch Dashboards with SAML.

The OpenSearch Dashboards console timeout is one hour and isn't configurable.

Viewing collections

You can view the existing collections in your AWS account on the Collections tab of the Amazon OpenSearch Service console.

To list collections along with their IDs, send a ListCollections request.

aws opensearchserverless list-collections

Sample response

{
   "collectionSummaries":[
      {
         "arn":"arn:aws:aoss:us-east-1:123456789012:collection/07tjusf2h91cunochc",
         "id":"07tjusf2h91cunochc",
         "name":"my-collection",
         "status":"CREATING"
      }
   ]
}

To limit the search results, use collection filters. This request filters the response to collections in the ACTIVE state:

aws opensearchserverless list-collections --collection-filters '{ "status": "ACTIVE" }'

To get more detailed information about one or more collections, including the OpenSearch endpoint and the OpenSearch Dashboards endpoint, send a BatchGetCollection request:

aws opensearchserverless batch-get-collection --ids ["07tjusf2h91cunochc", "1iu5usc4rame"]

Sample response

{
   "collectionDetails":[
      {
         "id": "07tjusf2h91cunochc",
         "name": "my-collection",
         "status": "ACTIVE",
         "type": "SEARCH",
         "description": "",
         "arn": "arn:aws:aoss:us-east-1:123456789012:collection/07tjusf2h91cunochc",
         "kmsKeyArn": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
         "createdDate": 1667446262828,
         "lastModifiedDate": 1667446300769,
         "collectionEndpoint": "https://07tjusf2h91cunochc.us-east-1.aoss.amazonaws.com",
         "dashboardEndpoint": "https://07tjusf2h91cunochc.us-east-1.aoss.amazonaws.com/_dashboards"
      },
      {
         "id": "178ukvtg3i82dvopdid",
         "name": "another-collection",
         "status": "ACTIVE",
         "type": "TIMESERIES",
         "description": "",
         "arn": "arn:aws:aoss:us-east-1:123456789012:collection/178ukvtg3i82dvopdid",
         "kmsKeyArn": "arn:aws:kms:us-east-1:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab",
         "createdDate": 1667446262828,
         "lastModifiedDate": 1667446300769,
         "collectionEndpoint": "https://178ukvtg3i82dvopdid.us-east-1.aoss.amazonaws.com",
         "dashboardEndpoint": "https://178ukvtg3i82dvopdid.us-east-1.aoss.amazonaws.com/_dashboards"
      }
   ],
   "collectionErrorDetails":[]
}

Deleting collections

Deleting a collection deletes all data and indexes in the collection. You can't recover collections after you delete them.

To delete a collection using the AWS CLI, send a DeleteCollection request:

aws opensearchserverless delete-collection --id 07tjusf2h91cunochc

Sample response

{
   "deleteCollectionDetail":{
      "id":"07tjusf2h91cunochc",
      "name":"my-collection",
      "status":"DELETING"
   }
}