0
# Global Tables
1

2
Multi-region replication support for globally distributed applications. Global Tables provide fully managed, serverless, multi-region, and multi-active database replication for DynamoDB tables.
3

4
## Capabilities
5

6
### Create Global Table
7

8
Creates a global table from an existing DynamoDB table.
9

10
```java { .api }
11
/**
12
 * Creates a global table from an existing table
13
 * @param request - The request containing global table configuration
14
 * @return Response containing global table description
15
 */
16
CreateGlobalTableResponse createGlobalTable(CreateGlobalTableRequest request);
17

18
class CreateGlobalTableRequest {
19
    static Builder builder();
20
    
21
    /** The global table name */
22
    String globalTableName();
23
    Builder globalTableName(String globalTableName);
24
    
25
    /** The Regions where the global table needs to be created */
26
    List<Replica> replicationGroup();
27
    Builder replicationGroup(Collection<Replica> replicationGroup);
28
}
29

30
class Replica {
31
    static Builder builder();
32
    
33
    /** The Region of the replica to be added or deleted */
34
    String regionName();
35
    Builder regionName(String regionName);
36
}
37

38
class CreateGlobalTableResponse {
39
    /** Contains the details of the global table */
40
    GlobalTableDescription globalTableDescription();
41
}
42
```
43

44
### Describe Global Table
45

46
Retrieves information about a global table.
47

48
```java { .api }
49
/**
50
 * Returns information about the specified global table
51
 * @param request - The request containing global table name
52
 * @return Response containing global table description
53
 */
54
DescribeGlobalTableResponse describeGlobalTable(DescribeGlobalTableRequest request);
55

56
class DescribeGlobalTableRequest {
57
    static Builder builder();
58
    
59
    /** The name of the global table */
60
    String globalTableName();
61
    Builder globalTableName(String globalTableName);
62
}
63

64
class DescribeGlobalTableResponse {
65
    /** Contains the details of the global table */
66
    GlobalTableDescription globalTableDescription();
67
}
68

69
class GlobalTableDescription {
70
    /** The global table name */
71
    String globalTableName();
72
    
73
    /** The unique identifier of the global table */
74
    String globalTableArn();
75
    
76
    /** The creation time of the global table */
77
    Instant creationDateTime();
78
    
79
    /** The current state of the global table */
80
    GlobalTableStatus globalTableStatus();
81
    
82
    /** The Regions where the global table has replicas */
83
    List<ReplicaDescription> replicationGroup();
84
}
85
```
86

87
### Update Global Table
88

89
Adds or removes replicas in a global table.
90

91
```java { .api }
92
/**
93
 * Adds or removes replicas in the specified global table
94
 * @param request - The request containing replica updates
95
 * @return Response containing updated global table description
96
 */
97
UpdateGlobalTableResponse updateGlobalTable(UpdateGlobalTableRequest request);
98

99
class UpdateGlobalTableRequest {
100
    static Builder builder();
101
    
102
    /** The global table name */
103
    String globalTableName();
104
    Builder globalTableName(String globalTableName);
105
    
106
    /** A list of Regions that should be added or removed from the global table */
107
    List<ReplicaUpdate> replicaUpdates();
108
    Builder replicaUpdates(Collection<ReplicaUpdate> replicaUpdates);
109
}
110

111
class ReplicaUpdate {
112
    static Builder builder();
113
    
114
    /** The parameters required for creating a replica on a global table */
115
    CreateReplicaAction create();
116
    Builder create(CreateReplicaAction create);
117
    
118
    /** The name of the existing replica to be removed from the global table */
119
    DeleteReplicaAction delete();
120
    Builder delete(DeleteReplicaAction delete);
121
}
122
```
123

124
### List Global Tables
125

126
Lists all global tables for the current account.
127

128
```java { .api }
129
/**
130
 * Lists all global tables that have a replica in the specified Region
131
 * @param request - The request containing listing options
132
 * @return Response containing global table names
133
 */
134
ListGlobalTablesResponse listGlobalTables(ListGlobalTablesRequest request);
135

136
class ListGlobalTablesRequest {
137
    static Builder builder();
138
    
139
    /** The first global table name that this operation will evaluate */
140
    String exclusiveStartGlobalTableName();
141
    Builder exclusiveStartGlobalTableName(String exclusiveStartGlobalTableName);
142
    
143
    /** The maximum number of table names to return */
144
    Integer limit();
145
    Builder limit(Integer limit);
146
    
147
    /** Lists the global tables in a specific Region */
148
    String regionName();
149
    Builder regionName(String regionName);
150
}
151

152
class ListGlobalTablesResponse {
153
    /** List of global table names */
154
    List<GlobalTable> globalTables();
155
    
156
    /** The name of the last global table in the current page of results */
157
    String lastEvaluatedGlobalTableName();
158
}
159
```
160

161
**Usage Examples:**
162

163
```java
164
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
165
import software.amazon.awssdk.services.dynamodb.model.*;
166
import java.util.List;
167

168
DynamoDbClient client = DynamoDbClient.builder().build();
169

170
// Create global table with replicas in multiple regions
171
CreateGlobalTableResponse response = client.createGlobalTable(
172
    CreateGlobalTableRequest.builder()
173
        .globalTableName("Orders")
174
        .replicationGroup(List.of(
175
            Replica.builder().regionName("us-east-1").build(),
176
            Replica.builder().regionName("eu-west-1").build(),
177
            Replica.builder().regionName("ap-northeast-1").build()
178
        ))
179
        .build()
180
);
181

182
System.out.println("Global table created: " + response.globalTableDescription().globalTableName());
183

184
// Add new replica to existing global table
185
UpdateGlobalTableResponse updateResponse = client.updateGlobalTable(
186
    UpdateGlobalTableRequest.builder()
187
        .globalTableName("Orders")
188
        .replicaUpdates(List.of(
189
            ReplicaUpdate.builder()
190
                .create(CreateReplicaAction.builder()
191
                    .regionName("us-west-2")
192
                    .build())
193
                .build()
194
        ))
195
        .build()
196
);
197

198
// List all global tables
199
ListGlobalTablesResponse listResponse = client.listGlobalTables(
200
    ListGlobalTablesRequest.builder().build()
201
);
202

203
for (GlobalTable globalTable : listResponse.globalTables()) {
204
    System.out.println("Global table: " + globalTable.globalTableName());
205
}
206
```
207

208
## Global Table Settings
209

210
### Describe Global Table Settings
211

212
Retrieves detailed Region-specific settings for a global table, including billing mode, capacity settings, and auto-scaling configuration for each replica.
213

214
```java { .api }
215
/**
216
 * Describes Region-specific settings for a global table
217
 * @param request - The request containing global table name
218
 * @return Response containing detailed global table settings for all replicas
219
 */
220
DescribeGlobalTableSettingsResponse describeGlobalTableSettings(DescribeGlobalTableSettingsRequest request);
221

222
class DescribeGlobalTableSettingsRequest {
223
    static Builder builder();
224
    
225
    /** The name of the global table to describe */
226
    String globalTableName();
227
    Builder globalTableName(String globalTableName);
228
}
229

230
class DescribeGlobalTableSettingsResponse {
231
    /** The name of the global table */
232
    String globalTableName();
233
    
234
    /** The Region-specific settings for each replica of the global table */
235
    List<ReplicaSettingsDescription> replicaSettings();
236
}
237

238
class ReplicaSettingsDescription {
239
    /** The Region name of the replica */
240
    String regionName();
241
    
242
    /** The current state of the replica (CREATING, UPDATING, DELETING, ACTIVE) */
243
    ReplicaStatus replicaStatus();
244
    
245
    /** The read/write capacity mode of the replica */
246
    BillingModeSummary replicaBillingModeSummary();
247
    
248
    /** The maximum number of strongly consistent reads consumed per second */
249
    Long replicaProvisionedReadCapacityUnits();
250
    
251
    /** Auto scaling settings for replica's read capacity units */
252
    AutoScalingSettingsDescription replicaProvisionedReadCapacityAutoScalingSettings();
253
    
254
    /** The maximum number of writes consumed per second */
255
    Long replicaProvisionedWriteCapacityUnits();
256
    
257
    /** Auto scaling settings for replica's write capacity units */
258
    AutoScalingSettingsDescription replicaProvisionedWriteCapacityAutoScalingSettings();
259
    
260
    /** Global secondary index settings for this replica */
261
    List<ReplicaGlobalSecondaryIndexSettingsDescription> replicaGlobalSecondaryIndexSettings();
262
    
263
    /** Table class for this replica */
264
    TableClass replicaTableClass();
265
}
266
```
267

268
**Usage Example:**
269

270
```java
271
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
272
import software.amazon.awssdk.services.dynamodb.model.*;
273

274
DynamoDbClient client = DynamoDbClient.builder().build();
275

276
// Describe global table settings
277
DescribeGlobalTableSettingsResponse response = client.describeGlobalTableSettings(
278
    DescribeGlobalTableSettingsRequest.builder()
279
        .globalTableName("my-global-table")
280
        .build()
281
);
282

283
System.out.println("Global Table: " + response.globalTableName());
284

285
// Examine settings for each replica
286
response.replicaSettings().forEach(replica -> {
287
    System.out.println("Region: " + replica.regionName());
288
    System.out.println("Status: " + replica.replicaStatus());
289
    
290
    if (replica.replicaBillingModeSummary() != null) {
291
        System.out.println("Billing Mode: " + replica.replicaBillingModeSummary().billingMode());
292
    }
293
    
294
    if (replica.replicaProvisionedReadCapacityUnits() != null) {
295
        System.out.println("Read Capacity: " + replica.replicaProvisionedReadCapacityUnits());
296
    }
297
    
298
    if (replica.replicaProvisionedWriteCapacityUnits() != null) {
299
        System.out.println("Write Capacity: " + replica.replicaProvisionedWriteCapacityUnits());
300
    }
301
    
302
    System.out.println("---");
303
});
304
```
305

306
### Update Global Table Settings
307

308
Updates settings for a global table and all its replicas, including billing mode, capacity settings, auto-scaling configuration, and replica-specific settings.
309

310
```java { .api }
311
/**
312
 * Updates settings for a global table and its replicas
313
 * @param request - The request containing global table settings updates
314
 * @return Response containing updated global table settings
315
 */
316
UpdateGlobalTableSettingsResponse updateGlobalTableSettings(UpdateGlobalTableSettingsRequest request);
317

318
class UpdateGlobalTableSettingsRequest {
319
    static Builder builder();
320
    
321
    /** The name of the global table to update */
322
    String globalTableName();
323
    Builder globalTableName(String globalTableName);
324
    
325
    /** The billing mode of the global table (PROVISIONED or PAY_PER_REQUEST) */
326
    BillingMode globalTableBillingMode();
327
    Builder globalTableBillingMode(BillingMode globalTableBillingMode);
328
    
329
    /** The maximum number of writes consumed per second before DynamoDB returns a ThrottlingException */
330
    Long globalTableProvisionedWriteCapacityUnits();
331
    Builder globalTableProvisionedWriteCapacityUnits(Long globalTableProvisionedWriteCapacityUnits);
332
    
333
    /** Auto scaling settings for managing provisioned write capacity for the global table */
334
    AutoScalingSettingsUpdate globalTableProvisionedWriteCapacityAutoScalingSettingsUpdate();
335
    Builder globalTableProvisionedWriteCapacityAutoScalingSettingsUpdate(AutoScalingSettingsUpdate globalTableProvisionedWriteCapacityAutoScalingSettingsUpdate);
336
    
337
    /** Settings for global secondary indexes that will be modified */
338
    List<GlobalTableGlobalSecondaryIndexSettingsUpdate> globalTableGlobalSecondaryIndexSettingsUpdate();
339
    Builder globalTableGlobalSecondaryIndexSettingsUpdate(Collection<GlobalTableGlobalSecondaryIndexSettingsUpdate> globalTableGlobalSecondaryIndexSettingsUpdate);
340
    
341
    /** Settings for each replica region that will be modified */
342
    List<ReplicaSettingsUpdate> replicaSettingsUpdate();
343
    Builder replicaSettingsUpdate(Collection<ReplicaSettingsUpdate> replicaSettingsUpdate);
344
}
345

346
class UpdateGlobalTableSettingsResponse {
347
    /** The name of the global table */
348
    String globalTableName();
349
    
350
    /** The updated Region-specific settings for each replica */
351
    List<ReplicaSettingsDescription> replicaSettings();
352
}
353
```
354

355
**Usage Example:**
356

357
```java
358
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
359
import software.amazon.awssdk.services.dynamodb.model.*;
360
import java.util.Arrays;
361

362
DynamoDbClient client = DynamoDbClient.builder().build();
363

364
// Update global table to pay-per-request billing
365
UpdateGlobalTableSettingsResponse response = client.updateGlobalTableSettings(
366
    UpdateGlobalTableSettingsRequest.builder()
367
        .globalTableName("my-global-table")
368
        .globalTableBillingMode(BillingMode.PAY_PER_REQUEST)
369
        .build()
370
);
371

372
// Update specific replica settings
373
UpdateGlobalTableSettingsResponse replicaResponse = client.updateGlobalTableSettings(
374
    UpdateGlobalTableSettingsRequest.builder()
375
        .globalTableName("my-global-table")
376
        .replicaSettingsUpdate(
377
            ReplicaSettingsUpdate.builder()
378
                .regionName("us-west-2")
379
                .replicaProvisionedReadCapacityUnits(1000L)
380
                .replicaProvisionedWriteCapacityUnits(1000L)
381
                .build()
382
        )
383
        .build()
384
);
385

386
// Update with auto-scaling settings
387
UpdateGlobalTableSettingsResponse autoScalingResponse = client.updateGlobalTableSettings(
388
    UpdateGlobalTableSettingsRequest.builder()
389
        .globalTableName("my-global-table")
390
        .globalTableProvisionedWriteCapacityAutoScalingSettingsUpdate(
391
            AutoScalingSettingsUpdate.builder()
392
                .minimumUnits(5L)
393
                .maximumUnits(1000L)
394
                .autoScalingDisabled(false)
395
                .targetTrackingScalingPolicyConfiguration(
396
                    TargetTrackingScalingPolicyConfiguration.builder()
397
                        .targetValue(70.0)
398
                        .build()
399
                )
400
                .build()
401
        )
402
        .build()
403
);
404

405
System.out.println("Updated Global Table: " + response.globalTableName());
406
response.replicaSettings().forEach(replica -> {
407
    System.out.println("Replica " + replica.regionName() + " status: " + replica.replicaStatus());
408
});
409
```
410

411
## Import and Export
412

413
### Import Table
414

415
Creates a new table by importing data from S3.
416

417
```java { .api }
418
/**
419
 * Imports table data from an S3 bucket
420
 * @param request - The request containing import configuration
421
 * @return Response containing import description
422
 */
423
ImportTableResponse importTable(ImportTableRequest request);
424

425
class ImportTableRequest {
426
    static Builder builder();
427
    
428
    /** Providing a ClientToken makes the call idempotent */
429
    String clientToken();
430
    Builder clientToken(String clientToken);
431
    
432
    /** The S3 bucket that provides the source for the import */
433
    S3BucketSource s3BucketSource();
434
    Builder s3BucketSource(S3BucketSource s3BucketSource);
435
    
436
    /** The format of the source data */
437
    InputFormat inputFormat();
438
    Builder inputFormat(InputFormat inputFormat);
439
    
440
    /** Additional properties that specify how the input is formatted */
441
    InputFormatOptions inputFormatOptions();
442
    Builder inputFormatOptions(InputFormatOptions inputFormatOptions);
443
    
444
    /** Represents the properties of the table created for the import operation */
445
    TableCreationParameters tableCreationParameters();  
446
    Builder tableCreationParameters(TableCreationParameters tableCreationParameters);
447
}
448

449
class ImportTableResponse {
450
    /** Represents the properties of the table created for the import operation */
451
    ImportTableDescription importTableDescription();
452
}
453
```
454

455
### Export Table to Point in Time
456

457
Exports table data to S3 from a specific point in time.
458

459
```java { .api }
460
/**
461
 * Exports table data to an Amazon S3 bucket
462
 * @param request - The request containing export configuration
463
 * @return Response containing export description
464
 */
465
ExportTableToPointInTimeResponse exportTableToPointInTime(ExportTableToPointInTimeRequest request);
466

467
class ExportTableToPointInTimeRequest {
468
    static Builder builder();
469
    
470
    /** The Amazon Resource Name (ARN) associated with the table to export */
471
    String tableArn();
472
    Builder tableArn(String tableArn);
473
    
474
    /** Time in the past from which to export table data */
475
    Instant exportTime();
476
    Builder exportTime(Instant exportTime);
477
    
478
    /** Providing a ClientToken makes the call idempotent */
479
    String clientToken();
480
    Builder clientToken(String clientToken);
481
    
482
    /** The name of the Amazon S3 bucket to export the snapshot to */
483
    String s3Bucket();
484
    Builder s3Bucket(String s3Bucket);
485
    
486
    /** The Amazon S3 bucket prefix to use as the file name and path of the exported snapshot */
487
    String s3Prefix();
488
    Builder s3Prefix(String s3Prefix);
489
    
490
    /** Type of encryption used on the backup */
491
    S3SseAlgorithm s3SseAlgorithm();
492
    Builder s3SseAlgorithm(S3SseAlgorithm s3SseAlgorithm);
493
    
494
    /** The ID of the AWS KMS managed key used to encrypt the S3 bucket where export data is stored */
495
    String s3SseKmsKeyId();
496
    Builder s3SseKmsKeyId(String s3SseKmsKeyId);
497
    
498
    /** The format for the exported data */
499
    ExportFormat exportFormat();
500
    Builder exportFormat(ExportFormat exportFormat);
501
}
502

503
class ExportTableToPointInTimeResponse {
504
    /** Contains a description of the table export */
505
    ExportDescription exportDescription();
506
}
507
```
508

509
**Usage Examples:**
510

511
```java
512
import java.time.Instant;
513
import java.time.temporal.ChronoUnit;
514

515
// Export table data to S3
516
Instant exportTime = Instant.now().minus(1, ChronoUnit.HOURS);
517

518
ExportTableToPointInTimeResponse exportResponse = client.exportTableToPointInTime(
519
    ExportTableToPointInTimeRequest.builder()
520
        .tableArn("arn:aws:dynamodb:us-east-1:123456789012:table/Orders")
521
        .exportTime(exportTime)
522
        .s3Bucket("my-export-bucket")
523
        .s3Prefix("exports/orders/2025-09-07/")
524
        .exportFormat(ExportFormat.DYNAMODB_JSON)
525
        .s3SseAlgorithm(S3SseAlgorithm.AES256)
526
        .clientToken("export-orders-" + System.currentTimeMillis())
527
        .build()
528
);
529

530
System.out.println("Export started: " + exportResponse.exportDescription().exportArn());
531
```