0
# Import and Export
1
2
Bulk data import from S3 and export to S3 capabilities for large-scale data operations. These features enable efficient data migration, backup to external storage, and integration with data processing pipelines.
3
4
## Capabilities
5
6
### Import Table
7
8
Creates a new DynamoDB table by importing data from Amazon S3.
9
10
```java { .api }
11
/**
12
* Imports table data from an S3 bucket
13
* @param request - The request containing import configuration
14
* @return Response containing import description
15
*/
16
ImportTableResponse importTable(ImportTableRequest request);
17
18
class ImportTableRequest {
19
static Builder builder();
20
21
/** Providing a ClientToken makes the call idempotent */
22
String clientToken();
23
Builder clientToken(String clientToken);
24
25
/** The S3 bucket that provides the source for the import */
26
S3BucketSource s3BucketSource();
27
Builder s3BucketSource(S3BucketSource s3BucketSource);
28
29
/** The format of the source data */
30
InputFormat inputFormat();
31
Builder inputFormat(InputFormat inputFormat);
32
33
/** Additional properties that specify how the input is formatted */
34
InputFormatOptions inputFormatOptions();
35
Builder inputFormatOptions(InputFormatOptions inputFormatOptions);
36
37
/** Represents the properties of the table created for the import operation */
38
TableCreationParameters tableCreationParameters();
39
Builder tableCreationParameters(TableCreationParameters tableCreationParameters);
40
}
41
42
class S3BucketSource {
43
static Builder builder();
44
45
/** The S3 bucket that is being imported from */
46
String s3Bucket();
47
Builder s3Bucket(String s3Bucket);
48
49
/** The key prefix shared by all S3 Objects that are being imported */
50
String s3KeyPrefix();
51
Builder s3KeyPrefix(String s3KeyPrefix);
52
53
/** The account number of the S3 bucket that is being imported from */
54
String s3BucketOwner();
55
Builder s3BucketOwner(String s3BucketOwner);
56
}
57
58
class TableCreationParameters {
59
static Builder builder();
60
61
/** The name of the table created as part of the import operation */
62
String tableName();
63
Builder tableName(String tableName);
64
65
/** The attributes of the table created as part of the import operation */
66
List<AttributeDefinition> attributeDefinitions();
67
Builder attributeDefinitions(Collection<AttributeDefinition> attributeDefinitions);
68
69
/** The primary key and optionally the secondary indexes of the table created as part of the import operation */
70
List<KeySchemaElement> keySchema();
71
Builder keySchema(Collection<KeySchemaElement> keySchema);
72
73
/** The billing mode for the table created as part of the import operation */
74
BillingMode billingMode();
75
Builder billingMode(BillingMode billingMode);
76
77
/** Represents the provisioned throughput settings for a specified table or index */
78
ProvisionedThroughput provisionedThroughput();
79
Builder provisionedThroughput(ProvisionedThroughput provisionedThroughput);
80
81
/** The global secondary indexes (if any) on the table created as part of the import operation */
82
List<GlobalSecondaryIndex> globalSecondaryIndexes();
83
Builder globalSecondaryIndexes(Collection<GlobalSecondaryIndex> globalSecondaryIndexes);
84
85
/** Represents the settings used to enable server-side encryption */
86
SSESpecification sseSpecification();
87
Builder sseSpecification(SSESpecification sseSpecification);
88
}
89
90
class ImportTableResponse {
91
/** Represents the properties of the table created for the import operation */
92
ImportTableDescription importTableDescription();
93
}
94
95
class ImportTableDescription {
96
/** The Amazon Resource Number (ARN) corresponding to the import request */
97
String importArn();
98
99
/** The status of the import */
100
ImportStatus importStatus();
101
102
/** The table name of the table created as part of the import operation */
103
String tableName();
104
105
/** The Amazon Resource Number (ARN) of the table being imported into */
106
String tableArn();
107
108
/** The parameters for the new table that is being imported into */
109
TableCreationParameters tableCreationParameters();
110
111
/** The S3 bucket that provides the source for the import */
112
S3BucketSource s3BucketSource();
113
114
/** The format of the source data */
115
InputFormat inputFormat();
116
117
/** The time when this import task began */
118
Instant startTime();
119
120
/** The time at which the creation of this import task completed */
121
Instant endTime();
122
123
/** The number of items successfully imported into the new table */
124
Long importedItemCount();
125
126
/** The number of errors that occurred during the import */
127
Long errorCount();
128
129
/** The client token that was provided for the import task */
130
String clientToken();
131
}
132
```
133
134
**Usage Example:**
135
136
```java
137
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
138
import software.amazon.awssdk.services.dynamodb.model.*;
139
import java.util.List;
140
141
DynamoDbClient client = DynamoDbClient.builder().build();
142
143
// Import data from S3 to create a new table
144
ImportTableResponse response = client.importTable(ImportTableRequest.builder()
145
.clientToken("import-products-" + System.currentTimeMillis())
146
.s3BucketSource(S3BucketSource.builder()
147
.s3Bucket("my-data-bucket")
148
.s3KeyPrefix("dynamodb-exports/products/")
149
.build())
150
.inputFormat(InputFormat.DYNAMODB_JSON)
151
.tableCreationParameters(TableCreationParameters.builder()
152
.tableName("Products-Imported")
153
.attributeDefinitions(List.of(
154
AttributeDefinition.builder()
155
.attributeName("productId")
156
.attributeType(ScalarAttributeType.S)
157
.build()
158
))
159
.keySchema(List.of(
160
KeySchemaElement.builder()
161
.attributeName("productId")
162
.keyType(KeyType.HASH)
163
.build()
164
))
165
.billingMode(BillingMode.PAY_PER_REQUEST)
166
.sseSpecification(SSESpecification.builder()
167
.enabled(true)
168
.sseType(SSEType.KMS)
169
.build())
170
.build())
171
.build());
172
173
ImportTableDescription importDesc = response.importTableDescription();
174
System.out.println("Import started: " + importDesc.importArn());
175
System.out.println("Status: " + importDesc.importStatus());
176
System.out.println("Target table: " + importDesc.tableName());
177
```
178
179
### Describe Import
180
181
Retrieves information about a table import operation.
182
183
```java { .api }
184
/**
185
* Describes an import task
186
* @param request - The request containing import ARN
187
* @return Response containing import description
188
*/
189
DescribeImportResponse describeImport(DescribeImportRequest request);
190
191
class DescribeImportRequest {
192
static Builder builder();
193
194
/** The Amazon Resource Name (ARN) associated with the table import */
195
String importArn();
196
Builder importArn(String importArn);
197
}
198
199
class DescribeImportResponse {
200
/** Represents the properties of the table created for the import operation */
201
ImportTableDescription importTableDescription();
202
}
203
```
204
205
### List Imports
206
207
Lists all import tasks for the current account.
208
209
```java { .api }
210
/**
211
* Lists completed imports within the past 90 days
212
* @param request - The request containing filtering options
213
* @return Response containing list of imports
214
*/
215
ListImportsResponse listImports(ListImportsRequest request);
216
217
class ListImportsRequest {
218
static Builder builder();
219
220
/** An optional string that, if supplied, must be the name of a table */
221
String tableArn();
222
Builder tableArn(String tableArn);
223
224
/** The number of ImportSummary objects returned in a single page */
225
Integer pageSize();
226
Builder pageSize(Integer pageSize);
227
228
/** An optional string that, if supplied, must be the name of a table */
229
String nextToken();
230
Builder nextToken(String nextToken);
231
}
232
233
class ListImportsResponse {
234
/** A list of ImportSummary objects */
235
List<ImportSummary> importSummaryList();
236
237
/** If this value is returned, there are additional results to be displayed */
238
String nextToken();
239
}
240
241
class ImportSummary {
242
/** The Amazon Resource Number (ARN) corresponding to the import request */
243
String importArn();
244
245
/** The status of the import operation */
246
ImportStatus importStatus();
247
248
/** The table name of the table created as part of the import operation */
249
String tableName();
250
251
/** The Amazon Resource Number (ARN) of the table being imported into */
252
String tableArn();
253
254
/** The S3 bucket that provides the source for the import */
255
S3BucketSource s3BucketSource();
256
257
/** The format of the source data */
258
InputFormat inputFormat();
259
260
/** The time when this import task began */
261
Instant startTime();
262
263
/** The time at which the creation of this import task completed */
264
Instant endTime();
265
}
266
```
267
268
**Usage Example:**
269
270
```java
271
// List all imports
272
ListImportsResponse response = client.listImports(ListImportsRequest.builder()
273
.pageSize(20)
274
.build());
275
276
System.out.println("Found " + response.importSummaryList().size() + " imports:");
277
278
for (ImportSummary importSummary : response.importSummaryList()) {
279
System.out.println(" Import: " + importSummary.importArn());
280
System.out.println(" Status: " + importSummary.importStatus());
281
System.out.println(" Table: " + importSummary.tableName());
282
System.out.println(" Started: " + importSummary.startTime());
283
System.out.println(" S3 Source: s3://" + importSummary.s3BucketSource().s3Bucket() +
284
"/" + importSummary.s3BucketSource().s3KeyPrefix());
285
System.out.println();
286
}
287
288
// Check specific import status
289
DescribeImportResponse describeResponse = client.describeImport(DescribeImportRequest.builder()
290
.importArn("arn:aws:dynamodb:us-east-1:123456789012:table/Products-Imported/import/01234567890123-abcdefab")
291
.build());
292
293
ImportTableDescription importDetails = describeResponse.importTableDescription();
294
System.out.println("Import status: " + importDetails.importStatus());
295
System.out.println("Items imported: " + importDetails.importedItemCount());
296
System.out.println("Errors: " + importDetails.errorCount());
297
```
298
299
### Export Table to Point in Time
300
301
Exports table data to Amazon S3 from a specific point in time.
302
303
```java { .api }
304
/**
305
* Exports table data to an Amazon S3 bucket
306
* @param request - The request containing export configuration
307
* @return Response containing export description
308
*/
309
ExportTableToPointInTimeResponse exportTableToPointInTime(ExportTableToPointInTimeRequest request);
310
311
class ExportTableToPointInTimeRequest {
312
static Builder builder();
313
314
/** The Amazon Resource Name (ARN) associated with the table to export */
315
String tableArn();
316
Builder tableArn(String tableArn);
317
318
/** Time in the past from which to export table data */
319
Instant exportTime();
320
Builder exportTime(Instant exportTime);
321
322
/** Providing a ClientToken makes the call idempotent */
323
String clientToken();
324
Builder clientToken(String clientToken);
325
326
/** The name of the Amazon S3 bucket to export the snapshot to */
327
String s3Bucket();
328
Builder s3Bucket(String s3Bucket);
329
330
/** The Amazon S3 bucket prefix to use as the file name and path of the exported snapshot */
331
String s3Prefix();
332
Builder s3Prefix(String s3Prefix);
333
334
/** Type of encryption used on the backup */
335
S3SseAlgorithm s3SseAlgorithm();
336
Builder s3SseAlgorithm(S3SseAlgorithm s3SseAlgorithm);
337
338
/** The ID of the AWS KMS managed key used to encrypt the S3 bucket where export data is stored */
339
String s3SseKmsKeyId();
340
Builder s3SseKmsKeyId(String s3SseKmsKeyId);
341
342
/** The format for the exported data */
343
ExportFormat exportFormat();
344
Builder exportFormat(ExportFormat exportFormat);
345
346
/** Option to export the table across multiple S3 files */
347
ExportType exportType();
348
Builder exportType(ExportType exportType);
349
350
/** The maximum number of items to export */
351
Long maxItems();
352
Builder maxItems(Long maxItems);
353
}
354
355
class ExportTableToPointInTimeResponse {
356
/** Contains a description of the table export */
357
ExportDescription exportDescription();
358
}
359
360
class ExportDescription {
361
/** The Amazon Resource Name (ARN) of the table export */
362
String exportArn();
363
364
/** Export can be in one of the following states: IN_PROGRESS, COMPLETED, or FAILED */
365
ExportStatus exportStatus();
366
367
/** The time at which the export task began */
368
Instant startTime();
369
370
/** The time at which the export task completed */
371
Instant endTime();
372
373
/** The name of the manifest file for the export task */
374
String exportManifest();
375
376
/** The Amazon Resource Name (ARN) of the table that was exported */
377
String tableArn();
378
379
/** Unique ID of the table that was exported */
380
String tableId();
381
382
/** Point in time from which table data was exported */
383
Instant exportTime();
384
385
/** The client token that was provided for the export task */
386
String clientToken();
387
388
/** The name of the Amazon S3 bucket containing the export */
389
String s3Bucket();
390
391
/** The Amazon S3 bucket prefix used as the file name and path of the exported snapshot */
392
String s3Prefix();
393
394
/** Type of encryption used on the backup */
395
S3SseAlgorithm s3SseAlgorithm();
396
397
/** The ID of the AWS KMS managed key used to encrypt the S3 bucket where export data was stored */
398
String s3SseKmsKeyId();
399
400
/** Status code for the result of the failed export */
401
String failureCode();
402
403
/** Export failure reason description */
404
String failureMessage();
405
406
/** The format of the exported data */
407
ExportFormat exportFormat();
408
409
/** The billable size of the table export */
410
Long billedSizeBytes();
411
412
/** The number of items exported */
413
Long itemCount();
414
415
/** The type of export that was performed */
416
ExportType exportType();
417
}
418
```
419
420
**Usage Example:**
421
422
```java
423
import java.time.Instant;
424
import java.time.temporal.ChronoUnit;
425
426
// Export table data to S3
427
Instant exportTime = Instant.now().minus(1, ChronoUnit.HOURS);
428
429
ExportTableToPointInTimeResponse response = client.exportTableToPointInTime(
430
ExportTableToPointInTimeRequest.builder()
431
.tableArn("arn:aws:dynamodb:us-east-1:123456789012:table/Orders")
432
.exportTime(exportTime)
433
.s3Bucket("my-export-bucket")
434
.s3Prefix("exports/orders/2025-09-07/")
435
.exportFormat(ExportFormat.DYNAMODB_JSON)
436
.exportType(ExportType.FULL_EXPORT)
437
.s3SseAlgorithm(S3SseAlgorithm.AES256)
438
.clientToken("export-orders-" + System.currentTimeMillis())
439
.build()
440
);
441
442
ExportDescription exportDesc = response.exportDescription();
443
System.out.println("Export started: " + exportDesc.exportArn());
444
System.out.println("Status: " + exportDesc.exportStatus());
445
System.out.println("S3 Location: s3://" + exportDesc.s3Bucket() + "/" + exportDesc.s3Prefix());
446
```
447
448
### Describe Export
449
450
Retrieves information about a table export operation.
451
452
```java { .api }
453
/**
454
* Describes an existing export of a table
455
* @param request - The request containing export ARN
456
* @return Response containing export description
457
*/
458
DescribeExportResponse describeExport(DescribeExportRequest request);
459
460
class DescribeExportRequest {
461
static Builder builder();
462
463
/** The Amazon Resource Name (ARN) associated with the export */
464
String exportArn();
465
Builder exportArn(String exportArn);
466
}
467
468
class DescribeExportResponse {
469
/** Represents the properties of the export */
470
ExportDescription exportDescription();
471
}
472
```
473
474
### List Exports
475
476
Lists all export tasks for the current account.
477
478
```java { .api }
479
/**
480
* Lists completed exports within the past 90 days
481
* @param request - The request containing filtering options
482
* @return Response containing list of exports
483
*/
484
ListExportsResponse listExports(ListExportsRequest request);
485
486
class ListExportsRequest {
487
static Builder builder();
488
489
/** The Amazon Resource Name (ARN) associated with the exported table */
490
String tableArn();
491
Builder tableArn(String tableArn);
492
493
/** Maximum number of exports to return */
494
Integer maxResults();
495
Builder maxResults(Integer maxResults);
496
497
/** An optional string that, if supplied, must be the name of a table */
498
String nextToken();
499
Builder nextToken(String nextToken);
500
}
501
502
class ListExportsResponse {
503
/** A list of ExportSummary objects */
504
List<ExportSummary> exportSummaries();
505
506
/** If this value is returned, there are additional results to be displayed */
507
String nextToken();
508
}
509
510
class ExportSummary {
511
/** The Amazon Resource Name (ARN) of the export */
512
String exportArn();
513
514
/** Export can be in one of the following states: IN_PROGRESS, COMPLETED, or FAILED */
515
ExportStatus exportStatus();
516
517
/** The time at which the export task began */
518
Instant startTime();
519
520
/** The time at which the export task completed */
521
Instant endTime();
522
523
/** The type of export that was performed */
524
ExportType exportType();
525
}
526
```
527
528
**Usage Example:**
529
530
```java
531
// List all exports for a specific table
532
ListExportsResponse response = client.listExports(ListExportsRequest.builder()
533
.tableArn("arn:aws:dynamodb:us-east-1:123456789012:table/Orders")
534
.maxResults(50)
535
.build());
536
537
System.out.println("Found " + response.exportSummaries().size() + " exports:");
538
539
for (ExportSummary exportSummary : response.exportSummaries()) {
540
System.out.println(" Export: " + exportSummary.exportArn());
541
System.out.println(" Status: " + exportSummary.exportStatus());
542
System.out.println(" Type: " + exportSummary.exportType());
543
System.out.println(" Started: " + exportSummary.startTime());
544
if (exportSummary.endTime() != null) {
545
System.out.println(" Completed: " + exportSummary.endTime());
546
}
547
System.out.println();
548
}
549
```
550
551
## Data Formats
552
553
### Supported Import Formats
554
555
```java { .api }
556
enum InputFormat {
557
DYNAMODB_JSON("DYNAMODB_JSON"),
558
ION("ION"),
559
CSV("CSV");
560
}
561
562
enum InputFormatOptions {
563
// CSV-specific options
564
CSV_DELIMITER(","),
565
CSV_HEADER_LIST("header1,header2,header3");
566
}
567
```
568
569
### Supported Export Formats
570
571
```java { .api }
572
enum ExportFormat {
573
DYNAMODB_JSON("DYNAMODB_JSON"),
574
ION("ION");
575
}
576
577
enum ExportType {
578
FULL_EXPORT("FULL_EXPORT"),
579
INCREMENTAL_EXPORT("INCREMENTAL_EXPORT");
580
}
581
```
582
583
### S3 Security Options
584
585
```java { .api }
586
enum S3SseAlgorithm {
587
AES256("AES256"),
588
KMS("KMS");
589
}
590
```
591
592
## Import/Export Best Practices
593
594
### Data Validation
595
596
Always validate imported data and monitor export progress:
597
598
```java
599
// Monitor import progress
600
public void monitorImportProgress(String importArn) {
601
ImportStatus status = ImportStatus.IN_PROGRESS;
602
603
while (status == ImportStatus.IN_PROGRESS) {
604
try {
605
Thread.sleep(30000); // Wait 30 seconds
606
607
DescribeImportResponse response = client.describeImport(
608
DescribeImportRequest.builder().importArn(importArn).build()
609
);
610
611
ImportTableDescription desc = response.importTableDescription();
612
status = desc.importStatus();
613
614
System.out.println("Import status: " + status);
615
if (desc.importedItemCount() != null) {
616
System.out.println("Items imported: " + desc.importedItemCount());
617
}
618
if (desc.errorCount() != null && desc.errorCount() > 0) {
619
System.out.println("Errors: " + desc.errorCount());
620
}
621
622
} catch (InterruptedException e) {
623
Thread.currentThread().interrupt();
624
break;
625
}
626
}
627
628
System.out.println("Final import status: " + status);
629
}
630
```
631
632
### Cost Optimization
633
634
1. **Export Compression**: Use efficient export formats
635
2. **S3 Storage Classes**: Use appropriate S3 storage classes for exports
636
3. **Selective Exports**: Export only necessary data ranges
637
4. **Batch Operations**: Group related import/export operations
638
639
```java
640
// Optimize export with specific time range and format
641
ExportTableToPointInTimeRequest optimizedExport = ExportTableToPointInTimeRequest.builder()
642
.tableArn(tableArn)
643
.exportTime(specificPointInTime)
644
.s3Bucket("my-backup-bucket")
645
.s3Prefix("efficient-exports/")
646
.exportFormat(ExportFormat.ION) // More compact format
647
.exportType(ExportType.INCREMENTAL_EXPORT) // Only changes
648
.s3SseAlgorithm(S3SseAlgorithm.AES256) // Cost-effective encryption
649
.build();
650
```
651
652
### Security Considerations
653
654
1. **Encryption**: Always use encryption for sensitive data
655
2. **Access Control**: Implement proper IAM policies for S3 buckets
656
3. **Network Security**: Use VPC endpoints when possible
657
4. **Data Classification**: Tag exports appropriately
658
659
```java
660
// Secure export configuration
661
.s3SseAlgorithm(S3SseAlgorithm.KMS)
662
.s3SseKmsKeyId("arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012")
663
.clientToken("secure-export-" + UUID.randomUUID())
664
```
665
666
### Error Handling
667
668
```java
669
try {
670
ImportTableResponse response = client.importTable(request);
671
// Monitor import progress
672
monitorImportProgress(response.importTableDescription().importArn());
673
674
} catch (ResourceNotFoundException e) {
675
System.err.println("S3 resource not found: " + e.getMessage());
676
} catch (ValidationException e) {
677
System.err.println("Invalid import configuration: " + e.getMessage());
678
} catch (LimitExceededException e) {
679
System.err.println("Import limits exceeded: " + e.getMessage());
680
} catch (DynamoDbException e) {
681
System.err.println("DynamoDB error: " + e.getMessage());
682
}
683
```