0
# AWS SDK for Java v2 - DynamoDB
1

2
The AWS SDK for Java v2 DynamoDB client provides comprehensive access to Amazon DynamoDB, a fully managed NoSQL database service. This library offers both synchronous and asynchronous APIs for all DynamoDB operations including CRUD operations, batch processing, transactions, PartiQL queries, table management, and advanced features like Global Tables and Streams.
3

4
## Package Information
5

6
- **Package Name**: dynamodb
7
- **Package Type**: maven
8
- **Group ID**: software.amazon.awssdk
9
- **Artifact ID**: dynamodb
10
- **Language**: Java
11
- **Installation**: Add to your Maven `pom.xml`:
12

13
```xml
14
<dependency>
15
    <groupId>software.amazon.awssdk</groupId>
16
    <artifactId>dynamodb</artifactId>
17
    <version>2.33.4</version>
18
</dependency>
19
```
20

21
## Core Imports
22

23
```java
24
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
25
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;
26
import software.amazon.awssdk.services.dynamodb.model.*;
27
```
28

29
## Basic Usage
30

31
```java
32
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
33
import software.amazon.awssdk.services.dynamodb.model.*;
34
import software.amazon.awssdk.regions.Region;
35
import java.util.Map;
36

37
// Create a synchronous DynamoDB client
38
DynamoDbClient client = DynamoDbClient.builder()
39
    .region(Region.US_EAST_1)
40
    .build();
41

42
// Put an item into a table
43
Map<String, AttributeValue> item = Map.of(
44
    "PK", AttributeValue.builder().s("user#123").build(),
45
    "name", AttributeValue.builder().s("John Doe").build(),
46
    "email", AttributeValue.builder().s("john@example.com").build()
47
);
48

49
PutItemResponse response = client.putItem(PutItemRequest.builder()
50
    .tableName("Users")
51
    .item(item)
52
    .build());
53

54
// Get an item from a table
55
GetItemResponse getResponse = client.getItem(GetItemRequest.builder()
56
    .tableName("Users")
57
    .key(Map.of("PK", AttributeValue.builder().s("user#123").build()))
58
    .build());
59

60
Map<String, AttributeValue> retrievedItem = getResponse.item();
61
```
62

63
## Architecture
64

65
The DynamoDB client is built around several key components:
66

67
- **Client Interfaces**: `DynamoDbClient` (sync) and `DynamoDbAsyncClient` (async) provide the main entry points
68
- **Request/Response Models**: Strongly-typed request and response objects for all operations
69
- **Exception Hierarchy**: Service-specific exceptions extending `DynamoDbException`
70
- **Utility Components**: Retry policies, paginators, and waiters for enhanced functionality
71
- **Builder Pattern**: Fluent builders for all request objects and client configuration
72

73
## Capabilities
74

75
### Data Operations
76

77
Core CRUD operations and advanced data manipulation capabilities for working with DynamoDB items.
78

79
```java { .api }
80
// Basic item operations
81
PutItemResponse putItem(PutItemRequest request);
82
GetItemResponse getItem(GetItemRequest request);
83
UpdateItemResponse updateItem(UpdateItemRequest request);
84
DeleteItemResponse deleteItem(DeleteItemRequest request);
85

86
// Query and scan operations
87
QueryResponse query(QueryRequest request);
88
ScanResponse scan(ScanRequest request);
89

90
// Batch operations
91
BatchGetItemResponse batchGetItem(BatchGetItemRequest request);
92
BatchWriteItemResponse batchWriteItem(BatchWriteItemRequest request);
93
```
94

95
[Data Operations](./data-operations.md)
96

97
### Transactions
98

99
ACID transaction support for complex multi-item operations with strong consistency guarantees.
100

101
```java { .api }
102
// Transaction operations
103
TransactWriteItemsResponse transactWriteItems(TransactWriteItemsRequest request);
104
TransactGetItemsResponse transactGetItems(TransactGetItemsRequest request);
105

106
// PartiQL transaction support
107
ExecuteTransactionResponse executeTransaction(ExecuteTransactionRequest request);
108
```
109

110
[Transactions](./transactions.md)
111

112
### PartiQL
113

114
SQL-compatible query language support for DynamoDB with batch execution capabilities.
115

116
```java { .api }
117
// PartiQL operations
118
ExecuteStatementResponse executeStatement(ExecuteStatementRequest request);
119
BatchExecuteStatementResponse batchExecuteStatement(BatchExecuteStatementRequest request);
120
ExecuteTransactionResponse executeTransaction(ExecuteTransactionRequest request);
121
```
122

123
[PartiQL](./partiql.md)
124

125
### Table Management
126

127
Complete table lifecycle management including creation, modification, and deletion.
128

129
```java { .api }
130
// Table operations
131
CreateTableResponse createTable(CreateTableRequest request);
132
DescribeTableResponse describeTable(DescribeTableRequest request);
133
UpdateTableResponse updateTable(UpdateTableRequest request);
134
DeleteTableResponse deleteTable(DeleteTableRequest request);
135
ListTablesResponse listTables(ListTablesRequest request);
136
```
137

138
[Table Management](./table-management.md)
139

140
### Backup and Restore
141

142
Comprehensive backup and restore capabilities including on-demand backups and point-in-time recovery.
143

144
```java { .api }
145
// Backup operations
146
CreateBackupResponse createBackup(CreateBackupRequest request);
147
DescribeBackupResponse describeBackup(DescribeBackupRequest request);
148
DeleteBackupResponse deleteBackup(DeleteBackupRequest request);
149
ListBackupsResponse listBackups(ListBackupsRequest request);
150

151
// Restore operations
152
RestoreTableFromBackupResponse restoreTableFromBackup(RestoreTableFromBackupRequest request);
153
RestoreTableToPointInTimeResponse restoreTableToPointInTime(RestoreTableToPointInTimeRequest request);
154
```
155

156
[Backup and Restore](./backup-restore.md)
157

158
### Global Tables
159

160
Multi-region replication support for globally distributed applications.
161

162
```java { .api }
163
// Global table operations
164
CreateGlobalTableResponse createGlobalTable(CreateGlobalTableRequest request);
165
DescribeGlobalTableResponse describeGlobalTable(DescribeGlobalTableRequest request);
166
UpdateGlobalTableResponse updateGlobalTable(UpdateGlobalTableRequest request);
167
ListGlobalTablesResponse listGlobalTables(ListGlobalTablesRequest request);
168
```
169

170
[Global Tables](./global-tables.md)
171

172
### Import and Export
173

174
Bulk data import from S3 and export to S3 capabilities for large-scale data operations.
175

176
```java { .api }
177
// Import operations
178
ImportTableResponse importTable(ImportTableRequest request);
179
DescribeImportResponse describeImport(DescribeImportRequest request);
180
ListImportsResponse listImports(ListImportsRequest request);
181

182
// Export operations
183
ExportTableToPointInTimeResponse exportTableToPointInTime(ExportTableToPointInTimeRequest request);
184
DescribeExportResponse describeExport(DescribeExportRequest request);
185
ListExportsResponse listExports(ListExportsRequest request);
186
```
187

188
[Import and Export](./import-export.md)
189

190
## Client Configuration
191

192
### Synchronous Client
193

194
```java { .api }
195
interface DynamoDbClient extends AwsClient {
196
    static DynamoDbClientBuilder builder();
197
    String serviceName();
198
    // All 57 DynamoDB operations...
199
}
200

201
interface DynamoDbClientBuilder {
202
    DynamoDbClientBuilder region(Region region);
203
    DynamoDbClientBuilder credentialsProvider(AwsCredentialsProvider credentialsProvider);
204
    DynamoDbClientBuilder endpointOverride(URI endpointOverride);
205
    DynamoDbClientBuilder httpClient(SdkHttpClient httpClient);
206
    DynamoDbClient build();
207
}
208
```
209

210
### Asynchronous Client
211

212
```java { .api }
213
interface DynamoDbAsyncClient extends AwsClient {
214
    static DynamoDbAsyncClientBuilder builder();
215
    String serviceName();
216
    // All 57 DynamoDB operations returning CompletableFuture<T>...
217
}
218

219
interface DynamoDbAsyncClientBuilder {
220
    DynamoDbAsyncClientBuilder region(Region region);
221
    DynamoDbAsyncClientBuilder credentialsProvider(AwsCredentialsProvider credentialsProvider);
222
    DynamoDbAsyncClientBuilder endpointOverride(URI endpointOverride);
223
    DynamoDbAsyncClientBuilder httpClient(SdkAsyncHttpClient httpClient);
224
    DynamoDbAsyncClient build();
225
}
226
```
227

228
## Core Data Types
229

230
### AttributeValue
231

232
Represents a DynamoDB attribute value with support for all DynamoDB data types.
233

234
```java { .api }
235
class AttributeValue {
236
    static Builder builder();
237
    
238
    // String value
239
    String s();
240
    Builder s(String s);
241
    boolean hasS();
242
    
243
    // Number value  
244
    String n();
245
    Builder n(String n);
246
    boolean hasN();
247
    
248
    // Binary value
249
    SdkBytes b();
250
    Builder b(SdkBytes b);
251
    boolean hasB();
252
    
253
    // String set
254
    List<String> ss();
255
    Builder ss(Collection<String> ss);
256
    boolean hasSs();
257
    
258
    // Number set
259
    List<String> ns();
260
    Builder ns(Collection<String> ns);
261
    boolean hasNs();
262
    
263
    // Binary set
264
    List<SdkBytes> bs();
265
    Builder bs(Collection<SdkBytes> bs);
266
    boolean hasBs();
267
    
268
    // Map
269
    Map<String, AttributeValue> m();
270
    Builder m(Map<String, AttributeValue> m);
271
    boolean hasM();
272
    
273
    // List
274
    List<AttributeValue> l();
275
    Builder l(Collection<AttributeValue> l);
276
    boolean hasL();
277
    
278
    // Null
279
    Boolean nul();
280
    Builder nul(Boolean nul);
281
    boolean hasNul();
282
    
283
    // Boolean
284
    Boolean bool();
285
    Builder bool(Boolean bool);
286
    boolean hasBool();
287
}
288
```
289

290
## Exception Handling
291

292
### Base Exception
293

294
```java { .api }
295
class DynamoDbException extends AwsServiceException {
296
    String getMessage();
297
    String getErrorCode();
298
    int statusCode();
299
    String requestId();
300
}
301
```
302

303
### Common Exceptions
304

305
```java { .api }
306
class ResourceNotFoundException extends DynamoDbException;
307
class ConditionalCheckFailedException extends DynamoDbException;
308
class ProvisionedThroughputExceededException extends DynamoDbException;
309
class ValidationException extends DynamoDbException;
310
class ThrottlingException extends DynamoDbException;
311
class InternalServerErrorException extends DynamoDbException;
312
class TransactionCanceledException extends DynamoDbException;
313
class TransactionConflictException extends DynamoDbException;
314
class ItemCollectionSizeLimitExceededException extends DynamoDbException;
315
class RequestLimitExceededException extends DynamoDbException;
316
```
317

318
## Utility Classes
319

320
### Retry Policy
321

322
```java { .api }
323
class DynamoDbRetryPolicy {
324
    static RetryStrategy resolveRetryStrategy(SdkClientConfiguration config);
325
    static RetryPolicy resolveRetryPolicy(SdkClientConfiguration config);  // Deprecated
326
}
327
```
328

329
### Waiters
330

331
```java { .api }
332
interface DynamoDbWaiter extends SdkAutoCloseable {
333
    static DynamoDbWaiter builder();
334
    
335
    WaiterResponse<DescribeTableResponse> waitUntilTableExists(DescribeTableRequest request);
336
    WaiterResponse<DescribeTableResponse> waitUntilTableNotExists(DescribeTableRequest request);
337
}
338
```
339

340
## Constants and Enums
341

342
### Table Status
343

344
```java { .api }
345
enum TableStatus {
346
    CREATING("CREATING"),
347
    UPDATING("UPDATING"),
348
    DELETING("DELETING"),
349
    ACTIVE("ACTIVE"),
350
    INACCESSIBLE_ENCRYPTION_CREDENTIALS("INACCESSIBLE_ENCRYPTION_CREDENTIALS"),
351
    ARCHIVING("ARCHIVING"),
352
    ARCHIVED("ARCHIVED");
353
}
354
```
355

356
### Comparison Operators
357

358
```java { .api }
359
enum ComparisonOperator {
360
    EQ("EQ"),
361
    NE("NE"),
362
    IN("IN"),
363
    LE("LE"),
364
    LT("LT"),
365
    GE("GE"),
366
    GT("GT"),
367
    BETWEEN("BETWEEN"),
368
    NOT_NULL("NOT_NULL"),
369
    NULL("NULL"),
370
    CONTAINS("CONTAINS"),
371
    NOT_CONTAINS("NOT_CONTAINS"),
372
    BEGINS_WITH("BEGINS_WITH");
373
}
374
```
375

376
### Stream View Types
377

378
```java { .api }
379
enum StreamViewType {
380
    KEYS_ONLY("KEYS_ONLY"),
381
    NEW_IMAGE("NEW_IMAGE"),
382
    OLD_IMAGE("OLD_IMAGE"),
383
    NEW_AND_OLD_IMAGES("NEW_AND_OLD_IMAGES");
384
}
385
```