0
# Data Operations
1

2
Core CRUD operations and advanced data manipulation capabilities for working with DynamoDB items. This includes basic item operations, querying and scanning, batch operations, and streaming capabilities.
3

4
## Capabilities
5

6
### Put Item
7

8
Creates a new item or replaces an existing item in a table.
9

10
```java { .api }
11
/**
12
 * Creates a new item, or replaces an old item with a new item
13
 * @param request - The request containing table name, item data, and options
14
 * @return Response containing consumed capacity and item attributes
15
 */
16
PutItemResponse putItem(PutItemRequest request);
17

18
class PutItemRequest {
19
    static Builder builder();
20
    
21
    /** The name of the table to contain the item */
22
    String tableName();
23
    Builder tableName(String tableName);
24
    
25
    /** A map of attribute name/value pairs, one for each attribute */
26
    Map<String, AttributeValue> item();
27
    Builder item(Map<String, AttributeValue> item);
28
    
29
    /** Map of attribute names to expected attribute values */
30
    Map<String, ExpectedAttributeValue> expected();
31
    Builder expected(Map<String, ExpectedAttributeValue> expected);
32
    
33
    /** Determines the level of detail about consumed capacity returned */
34
    ReturnConsumedCapacity returnConsumedCapacity();
35
    Builder returnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);
36
    
37
    /** Determines whether item collection metrics are returned */
38
    ReturnItemCollectionMetrics returnItemCollectionMetrics();
39
    Builder returnItemCollectionMetrics(ReturnItemCollectionMetrics returnItemCollectionMetrics);
40
    
41
    /** Use ReturnValues if you want to get the item attributes as they appeared before they were updated */
42
    ReturnValue returnValues();
43
    Builder returnValues(ReturnValue returnValues);
44
    
45
    /** Condition expression that must evaluate to true for the operation to succeed */
46
    String conditionExpression();
47
    Builder conditionExpression(String conditionExpression);
48
    
49
    /** One or more substitution tokens for attribute names in an expression */
50
    Map<String, String> expressionAttributeNames();
51
    Builder expressionAttributeNames(Map<String, String> expressionAttributeNames);
52
    
53
    /** One or more values that can be substituted in an expression */
54
    Map<String, AttributeValue> expressionAttributeValues();
55
    Builder expressionAttributeValues(Map<String, AttributeValue> expressionAttributeValues);
56
}
57

58
class PutItemResponse {
59
    /** The item attributes as they appeared before they were updated */
60
    Map<String, AttributeValue> attributes();
61
    
62
    /** The capacity units consumed by the operation */
63
    ConsumedCapacity consumedCapacity();
64
    
65
    /** Information about item collection metrics */
66
    ItemCollectionMetrics itemCollectionMetrics();
67
}
68
```
69

70
**Usage Example:**
71

72
```java
73
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
74
import software.amazon.awssdk.services.dynamodb.model.*;
75
import java.util.Map;
76

77
DynamoDbClient client = DynamoDbClient.builder().build();
78

79
// Put a new item
80
Map<String, AttributeValue> item = Map.of(
81
    "userId", AttributeValue.builder().s("user123").build(),
82
    "name", AttributeValue.builder().s("John Doe").build(),
83
    "email", AttributeValue.builder().s("john@example.com").build(),
84
    "age", AttributeValue.builder().n("30").build()
85
);
86

87
PutItemResponse response = client.putItem(PutItemRequest.builder()
88
    .tableName("Users")
89
    .item(item)
90
    .conditionExpression("attribute_not_exists(userId)")  // Only if user doesn't exist
91
    .returnConsumedCapacity(ReturnConsumedCapacity.TOTAL)
92
    .build());
93

94
System.out.println("Consumed capacity: " + response.consumedCapacity().capacityUnits());
95
```
96

97
### Get Item
98

99
Retrieves a single item from a table by primary key.
100

101
```java { .api }
102
/**
103
 * Returns a set of attributes for the item with the given primary key
104
 * @param request - The request containing table name, key, and projection options
105
 * @return Response containing the item attributes
106
 */
107
GetItemResponse getItem(GetItemRequest request);
108

109
class GetItemRequest {
110
    static Builder builder();
111
    
112
    /** The name of the table containing the requested item */
113
    String tableName();
114
    Builder tableName(String tableName);
115
    
116
    /** A map of attribute names to AttributeValue objects, representing the primary key */
117
    Map<String, AttributeValue> key();
118
    Builder key(Map<String, AttributeValue> key);
119
    
120
    /** List of attributes to retrieve */
121
    List<String> attributesToGet();
122
    Builder attributesToGet(Collection<String> attributesToGet);
123
    
124
    /** Determines the read consistency model */
125
    Boolean consistentRead();
126
    Builder consistentRead(Boolean consistentRead);
127
    
128
    /** Determines the level of detail about consumed capacity returned */
129
    ReturnConsumedCapacity returnConsumedCapacity();
130
    Builder returnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);
131
    
132
    /** A string that identifies one or more attributes to retrieve from the table */
133
    String projectionExpression();
134
    Builder projectionExpression(String projectionExpression);
135
    
136
    /** One or more substitution tokens for attribute names in an expression */
137
    Map<String, String> expressionAttributeNames();
138
    Builder expressionAttributeNames(Map<String, String> expressionAttributeNames);
139
}
140

141
class GetItemResponse {
142
    /** A map of attribute names to AttributeValue objects */
143
    Map<String, AttributeValue> item();
144
    
145
    /** The capacity units consumed by the operation */
146
    ConsumedCapacity consumedCapacity();
147
}
148
```
149

150
**Usage Example:**
151

152
```java
153
// Get a specific item
154
GetItemResponse response = client.getItem(GetItemRequest.builder()
155
    .tableName("Users")
156
    .key(Map.of("userId", AttributeValue.builder().s("user123").build()))
157
    .projectionExpression("userId, #n, email")  // Only get specific attributes
158
    .expressionAttributeNames(Map.of("#n", "name"))  // 'name' is a reserved word
159
    .consistentRead(true)  // Strong consistency
160
    .build());
161

162
if (response.hasItem()) {
163
    Map<String, AttributeValue> item = response.item();
164
    String name = item.get("name").s();
165
    String email = item.get("email").s();
166
    System.out.println("User: " + name + " (" + email + ")");
167
} else {
168
    System.out.println("User not found");
169
}
170
```
171

172
### Update Item
173

174
Edits an existing item's attributes or adds a new item if it doesn't exist.
175

176
```java { .api }
177
/**
178
 * Edits an existing item's attributes, or adds a new item to the table if it does not already exist
179
 * @param request - The request containing table name, key, and update expression
180
 * @return Response containing updated attributes and consumed capacity
181
 */
182
UpdateItemResponse updateItem(UpdateItemRequest request);
183

184
class UpdateItemRequest {
185
    static Builder builder();
186
    
187
    /** The name of the table containing the item to update */
188
    String tableName();
189
    Builder tableName(String tableName);
190
    
191
    /** The primary key of the item to be updated */
192
    Map<String, AttributeValue> key();
193
    Builder key(Map<String, AttributeValue> key);
194
    
195
    /** Map of attribute updates */
196
    Map<String, AttributeValueUpdate> attributeUpdates();
197
    Builder attributeUpdates(Map<String, AttributeValueUpdate> attributeUpdates);
198
    
199
    /** Map of attribute names to expected attribute values */
200
    Map<String, ExpectedAttributeValue> expected();
201
    Builder expected(Map<String, ExpectedAttributeValue> expected);
202
    
203
    /** Use ReturnValues if you want to get the item attributes as they appear before or after they are updated */
204
    ReturnValue returnValues();
205
    Builder returnValues(ReturnValue returnValues);
206
    
207
    /** Determines the level of detail about consumed capacity returned */
208
    ReturnConsumedCapacity returnConsumedCapacity();
209
    Builder returnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);
210
    
211
    /** Determines whether item collection metrics are returned */
212
    ReturnItemCollectionMetrics returnItemCollectionMetrics();
213
    Builder returnItemCollectionMetrics(ReturnItemCollectionMetrics returnItemCollectionMetrics);
214
    
215
    /** An expression that defines one or more attributes to be updated */
216
    String updateExpression();
217
    Builder updateExpression(String updateExpression);
218
    
219
    /** A condition that must be satisfied for the update to succeed */
220
    String conditionExpression();
221
    Builder conditionExpression(String conditionExpression);
222
    
223
    /** One or more substitution tokens for attribute names in an expression */
224
    Map<String, String> expressionAttributeNames();
225
    Builder expressionAttributeNames(Map<String, String> expressionAttributeNames);
226
    
227
    /** One or more values that can be substituted in an expression */
228
    Map<String, AttributeValue> expressionAttributeValues();
229
    Builder expressionAttributeValues(Map<String, AttributeValue> expressionAttributeValues);
230
}
231

232
class UpdateItemResponse {
233
    /** A map of attribute names to AttributeValue objects representing the item as it appears before or after it was updated */
234
    Map<String, AttributeValue> attributes();
235
    
236
    /** The capacity units consumed by the operation */
237
    ConsumedCapacity consumedCapacity();
238
    
239
    /** Information about item collection metrics */
240
    ItemCollectionMetrics itemCollectionMetrics();
241
}
242
```
243

244
**Usage Example:**
245

246
```java
247
// Update user attributes
248
UpdateItemResponse response = client.updateItem(UpdateItemRequest.builder()
249
    .tableName("Users")
250
    .key(Map.of("userId", AttributeValue.builder().s("user123").build()))
251
    .updateExpression("SET email = :e, age = age + :inc, lastLogin = :now")
252
    .conditionExpression("attribute_exists(userId)")  // Only if user exists
253
    .expressionAttributeValues(Map.of(
254
        ":e", AttributeValue.builder().s("newemail@example.com").build(),
255
        ":inc", AttributeValue.builder().n("1").build(),
256
        ":now", AttributeValue.builder().s("2025-09-07T17:00:00Z").build()
257
    ))
258
    .returnValues(ReturnValue.ALL_NEW)  // Return item after update
259
    .build());
260

261
Map<String, AttributeValue> updatedItem = response.attributes();
262
```
263

264
### Delete Item
265

266
Deletes a single item from a table by primary key.
267

268
```java { .api }
269
/**
270
 * Deletes a single item in a table by primary key
271
 * @param request - The request containing table name, key, and conditions
272
 * @return Response containing old attributes and consumed capacity
273
 */
274
DeleteItemResponse deleteItem(DeleteItemRequest request);
275

276
class DeleteItemRequest {
277
    static Builder builder();
278
    
279
    /** The name of the table from which to delete the item */
280
    String tableName();
281
    Builder tableName(String tableName);
282
    
283
    /** A map of attribute names to AttributeValue objects, representing the primary key */
284
    Map<String, AttributeValue> key();
285
    Builder key(Map<String, AttributeValue> key);
286
    
287
    /** Map of attribute names to expected attribute values */
288
    Map<String, ExpectedAttributeValue> expected();
289
    Builder expected(Map<String, ExpectedAttributeValue> expected);
290
    
291
    /** Use ReturnValues if you want to get the item attributes as they appeared before they were deleted */
292
    ReturnValue returnValues();
293
    Builder returnValues(ReturnValue returnValues);
294
    
295
    /** Determines the level of detail about consumed capacity returned */
296
    ReturnConsumedCapacity returnConsumedCapacity();
297
    Builder returnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);
298
    
299
    /** Determines whether item collection metrics are returned */
300
    ReturnItemCollectionMetrics returnItemCollectionMetrics();
301
    Builder returnItemCollectionMetrics(ReturnItemCollectionMetrics returnItemCollectionMetrics);
302
    
303
    /** A condition that must be satisfied for the delete to succeed */
304
    String conditionExpression();
305
    Builder conditionExpression(String conditionExpression);
306
    
307
    /** One or more substitution tokens for attribute names in an expression */
308
    Map<String, String> expressionAttributeNames();
309
    Builder expressionAttributeNames(Map<String, String> expressionAttributeNames);
310
    
311
    /** One or more values that can be substituted in an expression */
312
    Map<String, AttributeValue> expressionAttributeValues();
313
    Builder expressionAttributeValues(Map<String, AttributeValue> expressionAttributeValues);
314
}
315

316
class DeleteItemResponse {
317
    /** A map of attribute names to AttributeValue objects, representing the item as it appeared before it was deleted */
318
    Map<String, AttributeValue> attributes();
319
    
320
    /** The capacity units consumed by the operation */
321
    ConsumedCapacity consumedCapacity();
322
    
323
    /** Information about item collection metrics */
324
    ItemCollectionMetrics itemCollectionMetrics();
325
}
326
```
327

328
### Query Operations
329

330
Finds items based on primary key values and optional sort key conditions.
331

332
```java { .api }
333
/**
334
 * Finds items based on primary key values
335
 * @param request - The request containing table name, key conditions, and filters
336
 * @return Response containing matching items and pagination info
337
 */
338
QueryResponse query(QueryRequest request);
339

340
class QueryRequest {
341
    static Builder builder();
342
    
343
    /** The name of the table containing the requested items */
344
    String tableName();
345
    Builder tableName(String tableName);
346
    
347
    /** The name of an index to query */
348
    String indexName();
349
    Builder indexName(String indexName);
350
    
351
    /** The attributes to be returned in the result */
352
    Select select();
353
    Builder select(Select select);
354
    
355
    /** List of attributes to retrieve */
356
    List<String> attributesToGet();
357
    Builder attributesToGet(Collection<String> attributesToGet);
358
    
359
    /** The maximum number of items to evaluate */
360
    Integer limit();
361
    Builder limit(Integer limit);
362
    
363
    /** Determines the read consistency model */
364
    Boolean consistentRead();
365
    Builder consistentRead(Boolean consistentRead);
366
    
367
    /** The condition that specifies the key values for items to be retrieved */
368
    Map<String, Condition> keyConditions();
369
    Builder keyConditions(Map<String, Condition> keyConditions);
370
    
371
    /** A condition that must be satisfied to include an item in the result set */
372
    String filterExpression();
373
    Builder filterExpression(String filterExpression);
374
    
375
    /** A condition that defines the key values for items to be retrieved */
376
    String keyConditionExpression();
377
    Builder keyConditionExpression(String keyConditionExpression);
378
    
379
    /** A string that identifies one or more attributes to retrieve from the table */
380
    String projectionExpression();
381
    Builder projectionExpression(String projectionExpression);
382
    
383
    /** One or more substitution tokens for attribute names in expressions */
384
    Map<String, String> expressionAttributeNames();
385
    Builder expressionAttributeNames(Map<String, String> expressionAttributeNames);
386
    
387
    /** One or more values that can be substituted in expressions */
388
    Map<String, AttributeValue> expressionAttributeValues();
389
    Builder expressionAttributeValues(Map<String, AttributeValue> expressionAttributeValues);
390
    
391
    /** Specifies the order for index traversal */
392
    Boolean scanIndexForward();
393
    Builder scanIndexForward(Boolean scanIndexForward);
394
    
395
    /** The primary key of the first item that this operation will evaluate */
396
    Map<String, AttributeValue> exclusiveStartKey();
397
    Builder exclusiveStartKey(Map<String, AttributeValue> exclusiveStartKey);
398
    
399
    /** Determines the level of detail about consumed capacity returned */
400
    ReturnConsumedCapacity returnConsumedCapacity();
401
    Builder returnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);
402
}
403

404
class QueryResponse {
405
    /** An array of item attributes that match the query criteria */
406
    List<Map<String, AttributeValue>> items();
407
    
408
    /** The number of items in the response */
409
    Integer count();
410
    
411
    /** The number of items evaluated, before applying filters */
412
    Integer scannedCount();
413
    
414
    /** The primary key of the item where the operation stopped */
415
    Map<String, AttributeValue> lastEvaluatedKey();
416
    
417
    /** The capacity units consumed by the operation */
418
    ConsumedCapacity consumedCapacity();
419
}
420
```
421

422
**Usage Example:**
423

424
```java
425
// Query items by partition key and sort key range
426
QueryResponse response = client.query(QueryRequest.builder()
427
    .tableName("Orders")
428
    .keyConditionExpression("customerId = :cid AND orderDate BETWEEN :start AND :end")
429
    .expressionAttributeValues(Map.of(
430
        ":cid", AttributeValue.builder().s("customer123").build(),
431
        ":start", AttributeValue.builder().s("2025-01-01").build(),
432
        ":end", AttributeValue.builder().s("2025-12-31").build()
433
    ))
434
    .projectionExpression("orderId, orderDate, totalAmount")
435
    .limit(20)  // Limit results
436
    .scanIndexForward(false)  // Descending order
437
    .build());
438

439
System.out.println("Found " + response.count() + " orders");
440
for (Map<String, AttributeValue> item : response.items()) {
441
    String orderId = item.get("orderId").s();
442
    String orderDate = item.get("orderDate").s();
443
    System.out.println("Order: " + orderId + " on " + orderDate);
444
}
445

446
// Handle pagination
447
if (response.hasLastEvaluatedKey()) {
448
    // Use lastEvaluatedKey as exclusiveStartKey in next query
449
    Map<String, AttributeValue> startKey = response.lastEvaluatedKey();
450
}
451
```
452

453
### Scan Operations
454

455
Reads every item in a table or secondary index.
456

457
```java { .api }
458
/**
459
 * Returns one or more items and item attributes by accessing every item in a table or a secondary index
460
 * @param request - The request containing table name, filters, and scan options
461
 * @return Response containing all matching items and pagination info
462
 */
463
ScanResponse scan(ScanRequest request);
464

465
class ScanRequest {
466
    static Builder builder();
467
    
468
    /** The name of the table containing the requested items */
469
    String tableName();
470
    Builder tableName(String tableName);
471
    
472
    /** The name of a secondary index to scan */
473
    String indexName();
474
    Builder indexName(String indexName);
475
    
476
    /** List of attributes to retrieve */
477
    List<String> attributesToGet();
478
    Builder attributesToGet(Collection<String> attributesToGet);
479
    
480
    /** The maximum number of items to evaluate */
481
    Integer limit();
482
    Builder limit(Integer limit);
483
    
484
    /** The attributes to be returned in the result */
485
    Select select();
486
    Builder select(Select select);
487
    
488
    /** A map of attribute names to values, used for filtering */
489
    Map<String, Condition> scanFilter();
490
    Builder scanFilter(Map<String, Condition> scanFilter);
491
    
492
    /** A string that contains conditions that DynamoDB applies after the Scan operation */
493
    String filterExpression();
494
    Builder filterExpression(String filterExpression);
495
    
496
    /** A string that identifies one or more attributes to retrieve from the table */
497
    String projectionExpression();
498
    Builder projectionExpression(String projectionExpression);
499
    
500
    /** One or more substitution tokens for attribute names in expressions */
501
    Map<String, String> expressionAttributeNames();
502
    Builder expressionAttributeNames(Map<String, String> expressionAttributeNames);
503
    
504
    /** One or more values that can be substituted in expressions */
505
    Map<String, AttributeValue> expressionAttributeValues();
506
    Builder expressionAttributeValues(Map<String, AttributeValue> expressionAttributeValues);
507
    
508
    /** The primary key of the first item that this operation will evaluate */
509
    Map<String, AttributeValue> exclusiveStartKey();
510
    Builder exclusiveStartKey(Map<String, AttributeValue> exclusiveStartKey);
511
    
512
    /** Determines the level of detail about consumed capacity returned */
513
    ReturnConsumedCapacity returnConsumedCapacity();
514
    Builder returnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);
515
    
516
    /** For a parallel Scan request, TotalSegments specifies the total number of segments */
517
    Integer totalSegments();
518
    Builder totalSegments(Integer totalSegments);
519
    
520
    /** For a parallel Scan request, Segment identifies an individual segment to be scanned */
521
    Integer segment();
522
    Builder segment(Integer segment);
523
    
524
    /** Determines the read consistency model */
525
    Boolean consistentRead();
526
    Builder consistentRead(Boolean consistentRead);
527
}
528

529
class ScanResponse {
530
    /** An array of item attributes that match the scan criteria */
531
    List<Map<String, AttributeValue>> items();
532
    
533
    /** The number of items in the response */
534
    Integer count();
535
    
536
    /** The number of items evaluated, before applying filters */
537
    Integer scannedCount();
538
    
539
    /** The primary key of the item where the operation stopped */
540
    Map<String, AttributeValue> lastEvaluatedKey();
541
    
542
    /** The capacity units consumed by the operation */
543
    ConsumedCapacity consumedCapacity();
544
}
545
```
546

547
### Batch Operations
548

549
Perform multiple read or write operations in a single request for improved efficiency.
550

551
```java { .api }
552
/**
553
 * Returns the attributes of one or more items from one or more tables
554
 * @param request - The request containing multiple table keys to retrieve
555
 * @return Response containing retrieved items and unprocessed keys
556
 */
557
BatchGetItemResponse batchGetItem(BatchGetItemRequest request);
558

559
class BatchGetItemRequest {
560
    static Builder builder();
561
    
562
    /** A map of one or more table names and key sets to retrieve */
563
    Map<String, KeysAndAttributes> requestItems();
564
    Builder requestItems(Map<String, KeysAndAttributes> requestItems);
565
    
566
    /** Determines the level of detail about consumed capacity returned */
567
    ReturnConsumedCapacity returnConsumedCapacity();
568
    Builder returnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);
569
}
570

571
class KeysAndAttributes {
572
    static Builder builder();
573
    
574
    /** The primary keys of the items to retrieve */
575
    List<Map<String, AttributeValue>> keys();
576
    Builder keys(Collection<Map<String, AttributeValue>> keys);
577
    
578
    /** List of attributes to retrieve */
579
    List<String> attributesToGet();
580
    Builder attributesToGet(Collection<String> attributesToGet);
581
    
582
    /** Determines the read consistency model */
583
    Boolean consistentRead();
584
    Builder consistentRead(Boolean consistentRead);
585
    
586
    /** A string that identifies one or more attributes to retrieve */
587
    String projectionExpression();
588
    Builder projectionExpression(String projectionExpression);
589
    
590
    /** One or more substitution tokens for attribute names */
591
    Map<String, String> expressionAttributeNames();
592
    Builder expressionAttributeNames(Map<String, String> expressionAttributeNames);
593
}
594

595
class BatchGetItemResponse {
596
    /** A map of table name to list of items */
597
    Map<String, List<Map<String, AttributeValue>>> responses();
598
    
599
    /** A map of tables and their respective keys that were not processed */
600
    Map<String, KeysAndAttributes> unprocessedKeys();
601
    
602
    /** The read capacity units consumed by the operation */
603
    List<ConsumedCapacity> consumedCapacity();
604
}
605

606
/**
607
 * Puts or deletes multiple items in one or more tables
608
 * @param request - The request containing multiple write operations
609
 * @return Response containing unprocessed items and consumed capacity
610
 */
611
BatchWriteItemResponse batchWriteItem(BatchWriteItemRequest request);
612

613
class BatchWriteItemRequest {
614
    static Builder builder();
615
    
616
    /** A map of one or more table names and write requests */
617
    Map<String, List<WriteRequest>> requestItems();
618
    Builder requestItems(Map<String, List<WriteRequest>> requestItems);
619
    
620
    /** Determines the level of detail about consumed capacity returned */
621
    ReturnConsumedCapacity returnConsumedCapacity();
622
    Builder returnConsumedCapacity(ReturnConsumedCapacity returnConsumedCapacity);
623
    
624
    /** Determines whether item collection metrics are returned */
625
    ReturnItemCollectionMetrics returnItemCollectionMetrics();
626
    Builder returnItemCollectionMetrics(ReturnItemCollectionMetrics returnItemCollectionMetrics);
627
}
628

629
class WriteRequest {
630
    static Builder builder();
631
    
632
    /** A request to perform a PutItem operation */
633
    PutRequest putRequest();
634
    Builder putRequest(PutRequest putRequest);
635
    
636
    /** A request to perform a DeleteItem operation */
637
    DeleteRequest deleteRequest();
638
    Builder deleteRequest(DeleteRequest deleteRequest);
639
}
640

641
class BatchWriteItemResponse {
642
    /** A map of tables and their respective unprocessed write requests */
643
    Map<String, List<WriteRequest>> unprocessedItems();
644
    
645
    /** The write capacity units consumed by the operation */
646
    Map<String, List<ItemCollectionMetrics>> itemCollectionMetrics();
647
    
648
    /** The capacity units consumed by the operation */
649
    List<ConsumedCapacity> consumedCapacity();
650
}
651
```
652

653
**Usage Example:**
654

655
```java
656
// Batch get multiple items from different tables
657
Map<String, KeysAndAttributes> requestItems = Map.of(
658
    "Users", KeysAndAttributes.builder()
659
        .keys(List.of(
660
            Map.of("userId", AttributeValue.builder().s("user1").build()),
661
            Map.of("userId", AttributeValue.builder().s("user2").build())
662
        ))
663
        .projectionExpression("userId, name, email")
664
        .build(),
665
    "Orders", KeysAndAttributes.builder()
666
        .keys(List.of(
667
            Map.of("orderId", AttributeValue.builder().s("order1").build())
668
        ))
669
        .build()
670
);
671

672
BatchGetItemResponse response = client.batchGetItem(BatchGetItemRequest.builder()
673
    .requestItems(requestItems)
674
    .returnConsumedCapacity(ReturnConsumedCapacity.TOTAL)
675
    .build());
676

677
// Process responses
678
Map<String, List<Map<String, AttributeValue>>> responses = response.responses();
679
List<Map<String, AttributeValue>> users = responses.get("Users");
680
List<Map<String, AttributeValue>> orders = responses.get("Orders");
681

682
// Handle unprocessed keys (retry if needed)
683
if (response.hasUnprocessedKeys()) {
684
    Map<String, KeysAndAttributes> unprocessed = response.unprocessedKeys();
685
    // Retry with exponential backoff
686
}
687
```
688

689
## Additional Type Definitions
690

691
### Condition and Filter Types
692

693
```java { .api }
694
class Condition {
695
    static Builder builder();
696
    
697
    /** A list of one or more values to evaluate against the supplied attribute */
698
    List<AttributeValue> attributeValueList();
699
    Builder attributeValueList(Collection<AttributeValue> attributeValueList);
700
    
701
    /** A comparator for evaluating attributes */
702
    ComparisonOperator comparisonOperator();
703
    Builder comparisonOperator(ComparisonOperator comparisonOperator);
704
}
705

706
class ExpectedAttributeValue {
707
    static Builder builder();
708
    
709
    /** Represents the data for the expected attribute */
710
    AttributeValue value();
711
    Builder value(AttributeValue value);
712
    
713
    /** Causes DynamoDB to evaluate the value before attempting a conditional operation */
714
    Boolean exists();
715
    Builder exists(Boolean exists);
716
    
717
    /** A comparator for evaluating attributes in the AttributeValueList */
718
    ComparisonOperator comparisonOperator();
719
    Builder comparisonOperator(ComparisonOperator comparisonOperator);
720
    
721
    /** One or more values to evaluate against the supplied attribute */
722
    List<AttributeValue> attributeValueList();
723
    Builder attributeValueList(Collection<AttributeValue> attributeValueList);
724
}
725
```
726

727
### Batch Operation Types
728

729
```java { .api }
730
class PutRequest {
731
    static Builder builder();
732
    
733
    /** A map of attribute name/value pairs, one for each attribute */
734
    Map<String, AttributeValue> item();
735
    Builder item(Map<String, AttributeValue> item);
736
}
737

738
class DeleteRequest {
739
    static Builder builder();
740
    
741
    /** A map of attribute names to AttributeValue objects, representing the primary key */
742
    Map<String, AttributeValue> key();
743
    Builder key(Map<String, AttributeValue> key);
744
}
745
```
746

747
### Capacity and Metrics Types
748

749
```java { .api }
750
class ConsumedCapacity {
751
    static Builder builder();
752
    
753
    /** The name of the table that was affected by the operation */
754
    String tableName();
755
    Builder tableName(String tableName);
756
    
757
    /** The total number of capacity units consumed by the operation */
758
    Double capacityUnits();
759
    Builder capacityUnits(Double capacityUnits);
760
    
761
    /** The total number of read capacity units consumed by the operation */
762
    Double readCapacityUnits();
763
    Builder readCapacityUnits(Double readCapacityUnits);
764
    
765
    /** The total number of write capacity units consumed by the operation */
766
    Double writeCapacityUnits(); 
767
    Builder writeCapacityUnits(Double writeCapacityUnits);
768
    
769
    /** The amount of throughput consumed on the table */
770
    Capacity table();
771
    Builder table(Capacity table);
772
    
773
    /** The amount of throughput consumed on each local secondary index */
774
    Map<String, Capacity> localSecondaryIndexes();
775
    Builder localSecondaryIndexes(Map<String, Capacity> localSecondaryIndexes);
776
    
777
    /** The amount of throughput consumed on each global secondary index */
778
    Map<String, Capacity> globalSecondaryIndexes();
779
    Builder globalSecondaryIndexes(Map<String, Capacity> globalSecondaryIndexes);
780
}
781

782
class Capacity {
783
    static Builder builder();
784
    
785
    /** The total number of read capacity units consumed on a table or an index */
786
    Double readCapacityUnits();
787
    Builder readCapacityUnits(Double readCapacityUnits);
788
    
789
    /** The total number of write capacity units consumed on a table or an index */
790
    Double writeCapacityUnits();
791
    Builder writeCapacityUnits(Double writeCapacityUnits);
792
    
793
    /** The total number of capacity units consumed on a table or an index */
794
    Double capacityUnits();
795
    Builder capacityUnits(Double capacityUnits);
796
}
797

798
class ItemCollectionMetrics {
799
    static Builder builder();
800
    
801
    /** The partition key value of the item collection */
802
    Map<String, AttributeValue> itemCollectionKey();
803
    Builder itemCollectionKey(Map<String, AttributeValue> itemCollectionKey);
804
    
805
    /** An estimate of item collection size, in gigabytes */
806
    List<Double> sizeEstimateRangeGB();
807
    Builder sizeEstimateRangeGB(Collection<Double> sizeEstimateRangeGB);
808
}
809
```
810

811
### Enum Definitions
812

813
```java { .api }
814
enum ReturnValue {
815
    NONE("NONE"),
816
    ALL_OLD("ALL_OLD"),
817
    UPDATED_OLD("UPDATED_OLD"),
818
    ALL_NEW("ALL_NEW"),
819
    UPDATED_NEW("UPDATED_NEW");
820
}
821

822
enum ReturnConsumedCapacity {
823
    INDEXES("INDEXES"),
824
    TOTAL("TOTAL"),
825
    NONE("NONE");
826
}
827

828
enum ReturnItemCollectionMetrics {
829
    SIZE("SIZE"),
830
    NONE("NONE");
831
}
832

833
enum Select {
834
    ALL_ATTRIBUTES("ALL_ATTRIBUTES"),
835
    ALL_PROJECTED_ATTRIBUTES("ALL_PROJECTED_ATTRIBUTES"),
836
    SPECIFIC_ATTRIBUTES("SPECIFIC_ATTRIBUTES"),
837
    COUNT("COUNT");
838
}
839

840
enum ConditionalOperator {
841
    AND("AND"),
842
    OR("OR");
843
}
844
```