UpdateGlobalTable - Amazon DynamoDB

UpdateGlobalTable

Adds or removes replicas in the specified global table. The global table must already exist to be able to use this operation. Any replica to be added must be empty, have the same name as the global table, have the same key schema, have DynamoDB Streams enabled, and have the same provisioned and maximum write capacity units.

Important

This operation only applies to Version 2017.11.29 (Legacy) of global tables. We recommend using Version 2019.11.21 (Current) when creating new global tables, as it provides greater flexibility, higher efficiency and consumes less write capacity than 2017.11.29 (Legacy). To determine which version you are using, see Determining the version. To update existing global tables from version 2017.11.29 (Legacy) to version 2019.11.21 (Current), see Updating global tables.

Note

This operation only applies to Version 2017.11.29 of global tables. If you are using global tables Version 2019.11.21 you can use UpdateTable instead.

Although you can use UpdateGlobalTable to add replicas and remove replicas in a single request, for simplicity we recommend that you issue separate requests for adding or removing replicas.

If global secondary indexes are specified, then the following conditions must also be met:

  • The global secondary indexes must have the same name.

  • The global secondary indexes must have the same hash key and sort key (if present).

  • The global secondary indexes must have the same provisioned and maximum write capacity units.

Request Syntax

{ "GlobalTableName": "string", "ReplicaUpdates": [ { "Create": { "RegionName": "string" }, "Delete": { "RegionName": "string" } } ] }

Request Parameters

The request accepts the following data in JSON format.

Note

In the following list, the required parameters are described first.

GlobalTableName

The global table name.

Type: String

Length Constraints: Minimum length of 3. Maximum length of 255.

Pattern: [a-zA-Z0-9_.-]+

Required: Yes

ReplicaUpdates

A list of Regions that should be added or removed from the global table.

Type: Array of ReplicaUpdate objects

Required: Yes

Response Syntax

{ "GlobalTableDescription": { "CreationDateTime": number, "GlobalTableArn": "string", "GlobalTableName": "string", "GlobalTableStatus": "string", "ReplicationGroup": [ { "GlobalSecondaryIndexes": [ { "IndexName": "string", "ProvisionedThroughputOverride": { "ReadCapacityUnits": number } } ], "KMSMasterKeyId": "string", "ProvisionedThroughputOverride": { "ReadCapacityUnits": number }, "RegionName": "string", "ReplicaInaccessibleDateTime": number, "ReplicaStatus": "string", "ReplicaStatusDescription": "string", "ReplicaStatusPercentProgress": "string", "ReplicaTableClassSummary": { "LastUpdateDateTime": number, "TableClass": "string" } } ] } }

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

GlobalTableDescription

Contains the details of the global table.

Type: GlobalTableDescription object

Errors

For information about the errors that are common to all actions, see Common Errors.

GlobalTableNotFoundException

The specified global table does not exist.

HTTP Status Code: 400

InternalServerError

An error occurred on the server side.

HTTP Status Code: 500

ReplicaAlreadyExistsException

The specified replica is already part of the global table.

HTTP Status Code: 400

ReplicaNotFoundException

The specified replica is no longer part of the global table.

HTTP Status Code: 400

TableNotFoundException

A source table with the name TableName does not currently exist within the subscriber's account or the subscriber is operating in the wrong AWS Region.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: