Amazon Rekognition
Developer Guide

Example 1: Managing Collections

This section provides working examples of creating, listing, and deleting collections. Examples using both the AWS CLI and the AWS SDK for Java are provided.

For information about managing collections and related API operations, see Storage-Based API Operations: Storing Faces and Searching Face Matches.

Creating, Listing, and Deleting Collections: Using the AWS CLI

The following are example AWS CLI commands that you can use to create and delete collections. An example AWS CLI command that lists collections is also provided.

  • Create a face collection – The following create-collection AWS CLI command creates a face collection (examplecollection) in the us-east-1 region.


    The command specifies the adminuser profile that you set up in Step 2: Set Up the AWS Command Line Interface (AWS CLI). The AWS CLI command uses the credentials associated with the adminuser profile to sign and authenticate the request. If you don't provide this profile, the default profile is assumed.

    aws rekognition create-collection \ --collection-id "examplecollection" \ --region us-east-1 \ --profile adminuser

    Amazon Rekognition creates the collection in the specified region, and returns the Amazon Resource Name (ARN) of the newly created collection. An example response is shown following:

    { "CollectionArn": "aws:rekognition:us-east-1:acct-id:collection/examplecollection", "StatusCode": 200 }

  • List Collections – The following list-collections AWS CLI command returns a list of collections in the us-east-1 region.

    aws rekognition list-collections \ --region us-east-1 \ --profile adminuser

    The following is an example response:

    { "CollectionIds": [ "examplecollection1", "examplecollection2", "examplecollection3" ] }
  • Delete a face collection – The following delete-collection AWS CLI command deletes a face collection.

    aws rekognition delete-collection \ --collection-id "examplecollection" \ --region us-east-1 \ --profile adminuser

Creating, Listing, and Deleting Face Collections: Using the AWS SDK for Java

The following Java example code uses the AWS SDK for Java to create and delete two collections. The code example also lists the available collections.

import java.util.List; import com.amazonaws.AmazonClientException; import com.amazonaws.auth.AWSCredentials; import com.amazonaws.auth.AWSStaticCredentialsProvider; import com.amazonaws.auth.profile.ProfileCredentialsProvider; import com.amazonaws.regions.Regions; import; import; import; import; import; import; import; import; public class CollectionExample { public static void main(String[] args) throws Exception { AWSCredentials credentials; try { credentials = new ProfileCredentialsProvider("AdminUser").getCredentials(); } catch (Exception e) { throw new AmazonClientException( "Cannot load the credentials from the credential profiles file. " + "Please make sure that your credentials file is at the correct " + "location (/Users/userid/.aws/credentials), and is in valid format.", e); } AmazonRekognition amazonRekognition = AmazonRekognitionClientBuilder .standard() .withRegion(Regions.US_WEST_2) .withCredentials(new AWSStaticCredentialsProvider(credentials)) .build(); // 1. CreateCollection 1 String collectionId = "exampleCollection"; String collectionId2 = "exampleCollection2"; System.out.println("Creating collections: " + collectionId + " & " + collectionId2); CreateCollectionResult createCollectionResult = callCreateCollection( collectionId, amazonRekognition); System.out.println("CollectionArn : " + createCollectionResult.getCollectionArn()); System.out.println("Status code : " + createCollectionResult.getStatusCode().toString()); //CreateCollection 2 createCollectionResult = callCreateCollection(collectionId2, amazonRekognition); System.out.println("CollectionArn : " + createCollectionResult.getCollectionArn()); System.out.println("Status code : " + createCollectionResult.getStatusCode().toString()); // 3. Page through collections with ListCollections System.out.println("Listing collections"); int limit = 1; ListCollectionsResult listCollectionsResult = null; String paginationToken = null; do { if (listCollectionsResult != null) { paginationToken = listCollectionsResult.getNextToken(); } listCollectionsResult = callListCollections(paginationToken, limit, amazonRekognition); List < String > collectionIds = listCollectionsResult.getCollectionIds(); for (String resultId: collectionIds) { System.out.println(resultId); } } while (listCollectionsResult != null && listCollectionsResult.getNextToken() != null); // 4. Clean up collections with DeleteCollection System.out.println("Deleting collections"); DeleteCollectionResult deleteCollectionResult = callDeleteCollection( collectionId, amazonRekognition); System.out.println(collectionId + ": " + deleteCollectionResult.getStatusCode() .toString()); DeleteCollectionResult deleteCollectionResult2 = callDeleteCollection( collectionId2, amazonRekognition); System.out.println(collectionId2 + ": " + deleteCollectionResult2.getStatusCode() .toString()); } private static CreateCollectionResult callCreateCollection(String collectionId, AmazonRekognition amazonRekognition) { CreateCollectionRequest request = new CreateCollectionRequest() .withCollectionId(collectionId); return amazonRekognition.createCollection(request); } private static DeleteCollectionResult callDeleteCollection(String collectionId, AmazonRekognition amazonRekognition) { DeleteCollectionRequest request = new DeleteCollectionRequest() .withCollectionId(collectionId); return amazonRekognition.deleteCollection(request); } private static ListCollectionsResult callListCollections(String paginationToken, int limit, AmazonRekognition amazonRekognition) { ListCollectionsRequest listCollectionsRequest = new ListCollectionsRequest() .withMaxResults(limit) .withNextToken(paginationToken); return amazonRekognition.listCollections(listCollectionsRequest); } }