Spring Data DynamoDB

Add the module dependency:

The module builds on the AWS SDK v2 DynamoDbClient. If you are not already managing the SDK version through a BOM, import it:

AbstractDynamoDbConfiguration configures this module’s mapping, template, and repository infrastructure around a DynamoDbClient bean supplied by the application.

The minimum viable entity is a class-level @Table plus a partition key.

A DynamoDB base table has exactly one partition key and at most one sort key. The verifier enforces this at bootstrap: an entity with no @PartitionKey, or with two @SortKey properties, fails fast when the application context starts rather than on first query. An entity that declares both @Table and @SecondaryIndex is likewise rejected — a class is either a base-table entity or a read-only index view, never both.

@PartitionKey is meta-annotated with @Id, so Spring Data’s isIdProperty() resolves the base-table partition key as the entity’s id.

By default an attribute takes the Java property’s name. Use @Column when they differ:

@Column composes with the key annotations: on a key property the key annotation’s own value() wins if set, otherwise @Column applies, otherwise the property name is used. All three of these map to the attribute pk:

Annotate a numeric property with Spring Data’s @Version:

save() then writes with a condition expression: attribute_not_exists(version) for a new item, or version = <previous> for an update. A concurrent modification surfaces as OptimisticLockingFailureException.

Note that DynamoDB’s BatchWriteItem cannot carry condition expressions, so the template’s saveAll() rejects entities with a @Version property entirely — an InvalidDataAccessApiUsageException is thrown. Use save() per item where the guard matters.

@Embedded flattens an embedded object’s columns into the owning item rather than nesting them under an attribute. That is what makes single-table design work: one physical table holds several item kinds, and each row populates only the field whose shape it actually is.

Given rows whose sk is TOURNAMENT#winter2026, PLAYER#p1, MATCH#m1, RESULT#m1, a single findByPk("TOURNAMENT#winter2026") returns four ArenaItem`s — each with exactly one non-null payload field, selected by matching its `startsWith prefix against the row’s sort-key value.

Selection rules:

The nested map is built by walking the type’s declared fields reflectively, so @Column names are not applied inside it — attributes are named after the Java fields. static, transient, and synthetic fields are skipped. Reading requires a no-arg constructor (visibility does not matter).

The flag applies to single-valued properties only. Collection-typed properties are already stored as native DynamoDB types (see section 8), so @Embedded has no effect on them either way.

Prefix routing cannot separate hierarchical sort keys where one kind’s prefix is a prefix of another’s. With ORDER#9876 for an order and ORDER#9876#LINE#abc for its lines, startsWith = "ORDER#" matches both, so an order-line row populates the order field as well. Use regex to draw that boundary:

Ambiguity is never checked, whichever marker you use: if two members can match the same sort key, both are populated. Keep the routes mutually exclusive.

Idiomatic single-table sort keys are hierarchical strings (MATCH#2026-01-18#m1). @SortKeyTemplate composes one from several properties on write and decomposes it back on read, so your Java model keeps typed fields while the wire format stays a single overloaded string.

No sk property is required. Saving writes sk = "MATCH#2026-01-18#m1" directly to the DynamoDB item, and reading decomposes that value back onto matchDate and matchId. Point reads, existence checks, and key-based deletes accept the composed sk value. Entity-based updates and deletes compose the key from the placeholder properties. A DynamoDB primary key cannot be changed by UpdateItem; templates targeting secondary-index columns are recomposed as update values.

The placeholder properties are persisted as ordinary attributes by default. They are redundant for mapping but remain queryable in filter expressions and usable as secondary-index keys. Annotate a placeholder @Derived to keep it out of the item:

That trades independent queryability for item size. When a derived method binds every partition-key attribute plus a leading subset of the default base-table template placeholders, the repository composes a sort-key equality or begins_with condition without needing the placeholder attributes to be stored. Other predicates on an @Derived property are translated normally, but a filter cannot match an attribute that is absent from the item. Leave @Derived off when the property must remain independently queryable.

@Derived is rejected at bootstrap on a property that is not a placeholder of some @SortKeyTemplate on the same entity, on a key property, and on a primitive type — in each case the value could not be recovered on read.

column targets an attribute other than sk — typically an overloaded GSI attribute. It controls write/read mapping only; it does not make a base-entity repository query that GSI. Model the GSI with a typed @SecondaryIndex view when repository queries must use it:

The annotation is repeatable, so one entity may compose several columns as long as each targets a distinct column:

Two templates targeting the same column, or a template on a column that also has a declared @SortKey, are rejected at bootstrap.

Limitation. Decomposition anchors on the literal segments and takes whatever falls between them, so it is unambiguous only if a placeholder value never contains the next literal. True for ids, enums and dates; not guaranteed for free text. Template shapes are intentionally not restricted; if placeholders are adjacent or repeated, decomposition follows the parser’s normal left-to-right behavior and the application owns the resulting semantics.

@ItemCollectionView provides a simpler way to model Single Table Design for read queries. It is designed specifically for read-only aggregation: instead of returning one object for every item and requiring callers to inspect which fields are populated, the annotation groups related entities from the same partition into one typed item-collection view.

@ItemCollectionMember identifies which projection row type should be mapped to each field. Routing is based on the entity’s sort key and can use startsWith, endsWith, or regex:

The classes referenced by @ItemCollectionMember are projection row types and do not need @Table. The enclosing @ItemCollectionView supplies the physical table and index metadata. Normal property mapping annotations such as @Column and @Embedded remain available when needed:

When the view is queried, the module reads the matching rows and maps each row to the appropriate @ItemCollectionMember field based on its sort-key pattern. This allows a query to return a single grouped representation instead of requiring application code to iterate over every result and check which field is populated.

For example, given the following rows:

the rows can be grouped into a single item-collection view:

Unlike @Embedded, @ItemCollectionView is read-only and intended for grouping query results. It does not embed or flatten the child entities into one DynamoDB item, and it does not change how the child entities are persisted. A child type may also be an independently writable @Table entity, but item-collection materialization does not require it.

The routing rules follow the same matching semantics as @Embedded:

As with @Embedded, use regex when hierarchical sort keys would otherwise cause overlapping prefix matches. For example, startsWith = "ORDER#" would match both ORDER#9876 and ORDER#9876#LINE#1, while regex = "ORDER#[^#]+" matches only the order row.

Unlike @Embedded (whose pattern is compiled and validated at bootstrap), an @ItemCollectionMember regex is compiled on the first item-collection query, so an invalid pattern surfaces then rather than at application startup.

An item-collection view may also be a Java record. Members are resolved from the sort-key pattern and supplied through the record’s canonical constructor, so no setters or default constructor are required:

The row projection types (OrderData, OrderLineData) may likewise be records. A member with no matching row is supplied as null to the constructor.

@ItemCollectionView is useful when the primary goal is to query a single-table design and group its heterogeneous rows into a convenient read model, while keeping the underlying @Table entities independent and suitable for normal persistence.

An item-collection view is read through an ItemCollectionRepository<A> (see section 4.8), or through the template’s queryItemCollection(…​) when you need a hand-written key condition:

queryItemCollection executes one DynamoDB Query request and folds only that response page. DynamoDbPageRequest controls the evaluated-item limit and optional starting cursor, while EntityQueryResult.getLastEvaluatedKey() exposes the continuation cursor. The caller decides whether to submit that cursor in another request. For repository-level keyset iteration, query the row projection as Window<T> and advance with its ScrollPosition; the framework never drains the remaining pages implicitly.

tableName is optional: when every registered @Table entity resolves to the same physical table, the view picks it up automatically, and @SecondaryIndex("GSI1") is enough. Set it explicitly only in a multi-table application.

A view’s @PartitionKey/@SortKey are the index’s keys, and every read the module issues for a view automatically sets IndexName and the resolved TableName — callers never pass an index name.

Views support the same @Embedded prefix routing the base table uses, so one query can reconstruct heterogeneous rows from an overloaded index:

One findByCollectionKey("PT#winter2026#p1") returns the player row and all of that player’s match rows, each reconstructed as the right shape.

Both local (LSI) and global (GSI) secondary indexes are modelled with the same @SecondaryIndex annotation — the index type is determined by the underlying DynamoDB index, not by a different Java annotation. The difference is in how many key attributes each supports: an LSI is single-attribute (it reuses the base partition key plus one alternate sort key), while a GSI supports up to four partition attributes and four sort attributes (a GA feature as of November 2025, see the AWS blog post Multi-key support for Global Secondary Index in Amazon DynamoDB). A multi-attribute GSI uses real domain attributes instead of hand-concatenated synthetic keys. Express them with order:

Order the sort attributes from most general to most specific to maximise query flexibility. order values must be contiguous and start at 0; gaps and duplicates are rejected at bootstrap.

On a multi-attribute GSI, DynamoDB requires equality (=) on every partition attribute, allows optional equality conditions on the sort attributes from left to right (you may supply a prefix but not skip one), and permits a range condition (<, >, BETWEEN, begins_with) only on the last supplied sort attribute.

Note the naming difference between the two idiomatic styles, both valid:

An LSI is declared with the same @SecondaryIndex annotation as a GSI. It shares the base table’s partition key and adds one alternate sort key. It is single-attribute only (multi-attribute keys are GSI-only) and must exist at table-creation time.

A DynamoDB index cannot be written, and it has no GetItem — only Query and Scan. The module enforces both:

Writes go through the base @Table entity that the index projects. findAll() and count() on a view are supported and scan the view’s own index rather than the base table.

DynamoDbRepository<T, ID> extends ListCrudRepository, so findAll() and findAllById(…​) return List rather than Iterable, matching the other Spring Data store modules. It adds update(entity) on top of the standard CRUD surface.

Note that the repository’s inherited saveAll(…​) calls save() per entity (individual PutItem calls with full @Version support). To use BatchWriteItem instead, inject DynamoDbOperations and call its saveAll() method directly — that path batches at 25 but cannot enforce optimistic-locking conditions.

existsById(id) issues a projection-only GetItem that returns only the partition-key attribute and never triggers entity conversion or lifecycle events.

When the base table has both a partition key and a sort key, the repository’s id type is DynamoDbCompositeId, and you pass one to any id-based method (findById, existsById, deleteById):

DynamoDbCompositeId.of(partitionKey, sortKey) carries both key values. Declare the repository as DynamoDbRepository<ArenaItem, DynamoDbCompositeId> when the table has a composite key; this also applies when @SortKeyTemplate owns the physical base-table sk and the entity has no @SortKey property. In that case, pass the fully composed sk as the composite ID’s sort-key value. Use a scalar id type (for example DynamoDbRepository<ArenaItem, String>) when the table’s key is the partition key alone. The implementation dispatches on the id’s runtime type, so both id shapes work through the same repository contract.

A view is backed by a read-only fragment:

SecondaryIndexRepository<T> extends only Spring Data’s plain Repository marker, so save, delete and findById are absent — calling one is a compile error, not a runtime surprise. Everything a view can do still works: derived queries, @Query, pagination, count, exists.

Derived method names are translated into a DynamoDB Query against the entity’s key schema. The rules DynamoDB itself enforces, which the module validates up front rather than letting a malformed request reach the service:

Inequality predicates on a declared @SortKey are emitted as sort-key conditions, not filter expressions: …AndCreatedAtGreaterThanEqual, …AndCreatedAtBetween and …AndCreatedAtStartingWith all become part of the KeyConditionExpression. An inequality on a partition-key attribute cannot be a key condition, so such a method degrades to a Scan and requires @AllowScan. For the default base-table @SortKeyTemplate, equality on a leading placeholder subset becomes begins_with(sk, composedPrefix), while equality on every placeholder becomes sk = composedValue. Explicit column templates are not auto-selected as indexes; query those attributes through a typed @SecondaryIndex view.

If no index can serve a derived method as a Query, it would have to become a full-table Scan. Rather than doing that silently, the module rejects the method at bootstrap:

The failure happens when the application context starts, not on first invocation — a scan-shaped method can never reach production unnoticed.

Spring Data’s derived limiting keywords are honoured. findFirstBy… and findTopBy… apply a Limit of 1 to the underlying Query, and findTop<N>By… applies a limit of N:

A single-entity limiting method (findFirstBy… returning Match) returns the first result and does not throw when several rows match — the limit truncates the result set at the source.

A derived OrderBy may reference only the selected index’s sort key. Ascending order maps to DynamoDB’s ScanIndexForward=true; descending order maps to ScanIndexForward=false. Ordering by a non-sort-key attribute is rejected when the repository method is bootstrapped rather than being emulated with an in-memory sort.

DynamoDB pages by an opaque LastEvaluatedKey, not a numeric offset, so Window<T> is the supported paginated return type. Both Page<T> and Slice<T> are rejected at bootstrap:

Only a keyset ScrollPosition is accepted (ScrollPosition.keyset(), .forward(…​), .backward(…​)); an offset position raises InvalidDataAccessApiUsageException.

DynamoDB returns a single resume cursor per page (LastEvaluatedKey), which points after the last item, so a position is only available for the final element: call positionAt(window.size() - 1), as above. Any other index raises IllegalStateException rather than returning the page-end cursor, which would silently skip the rows in between. Use window.hasPosition(index) if you want to probe without catching.

An @ItemCollectionView (section 2.6) is read through an ItemCollectionRepository<V>, the read-only counterpart to SecondaryIndexRepository:

It contributes a fixed set of partition-oriented finders — there are no derived query methods, since an item-collection view always folds one partition (or one index collection) into a single object:

The Optional-returning finders issue one Query request and fold that response page onto the view’s @ItemCollectionMember fields; they do not follow LastEvaluatedKey implicitly. findByPartitionKeyAndSortKey narrows to a single item, …StartingWith to a begins_with prefix, and …Between to a sort-key range. For a collection that can exceed one DynamoDB page, query its row projection as Window<T>, or call DynamoDbOperations.queryItemCollection(…​) repeatedly with the returned cursor. existsByPartitionKey uses Select=COUNT with a per-request limit of one and stops at the first matching item; if a filter removes an evaluated item, it follows the cursor until a match is counted or DynamoDB reports no next page.

For a key condition the fixed finders cannot express, add a @Query method whose expression is passed straight through to queryItemCollection:

Derived query methods and @Update methods are both rejected at bootstrap on an ItemCollectionRepository — only the fixed finders and read-only @Query methods are allowed, because an item-collection view is read-only and @ItemCollectionView never changes how the underlying @Table entities are written. When the view is index-backed (@ItemCollectionView(indexName = "GSI2", …)), the same finders run against that index, and partitionKey/sortKey name the index’s key attributes.

Parameters bind by name: the :from placeholder in the expression resolves to the argument annotated @Param("from") — declare the @Param name without the leading colon. @ExpressionName maps a #alias to a real attribute name, which also sidesteps DynamoDB’s reserved words (region, year, status, …). @ExpressionValue supplies a value inline, evaluated as a SpEL expression (a quoted literal such as 'ACTIVE' is the common case).

keyConditionExpression is an escape hatch: it bypasses the module’s key-condition validation entirely, so indexName must always be set explicitly when you use it (the escape hatch does not auto-select an index), and correctness is yours. ItemCollectionRepository @Query methods are exempt from this requirement.

A base-table DynamoDbRepository rejects @Query(indexName=…​); use a derived method for base-table key queries. For an explicit key condition on a typed SecondaryIndexRepository, the caller is responsible for naming the same physical index represented by its @SecondaryIndex view. Filter-only queries on a typed view do not need indexName: they scan the index declared by the view and still require @AllowScan or allowScan = true.

Other attributes: consistentRead, limit, and allowScan (the @Query-side equivalent of @AllowScan). Declared filter-only queries and normal named queries without scan opt-in are rejected when the repository is created, matching the fail-fast behavior of derived scan queries.

For non-PartiQL read queries, a long/Long return type executes a DynamoDB count and a boolean/Boolean return type executes an existence check. Other supported return types materialize entities normally.

@Update owns updateExpression, conditionExpression, names, and values; do not combine it with @Query, which is read-only. Create new items with repository save/insert or the corresponding DynamoDbOperations methods.

A @Update method is always an UpdateItem against one item — never a Query or Scan. The partition and sort key are resolved from the method’s @Param-annotated arguments. For an entity whose base sort key is owned by @SortKeyTemplate, the sort-key argument is the fully composed physical value (for example MATCH#2026-01-18#m1), not the individual placeholder values. There are no derived deleteByX/updateByX methods: an update operation is always explicit.

Values bind positionally. Supported return types are List<T>, Optional<T> and a single T; Window pagination over PartiQL is not implemented yet. PartiQL is not supported for ItemCollectionRepository methods because those methods must fold paged query rows into a view; such a declaration is rejected at repository bootstrap.

Set namedQueriesLocation on @EnableDynamoDbRepositories to a classpath properties resource. Each property key is the domain class’s simple name plus the repository method name:

The expression has repository-specific semantics:

Named parameters bind exactly as they do for inline @Query expressions. An optional method-level @Query annotation can supply metadata while the properties file supplies the expression text: names, values, limit and consistentRead are retained. indexName is also retained for an item-collection query. A typed secondary-index repository always scans the index declared by its @SecondaryIndex view, while a base-table repository rejects method-level indexName. Explicit aliases support nonconventional mappings such as #partition -> pk; otherwise a conventional placeholder such as #pk resolves to pk.

Named queries are read-only; combining one with @Update is rejected during repository bootstrap. Resolution follows queryLookupStrategy exactly:

saveAll() accepts entities of mixed types: items are grouped by their resolved table name and dispatched as one or more BatchWriteItem requests (chunked at 25). Unprocessed items are retried with exponential backoff. @Version entities are rejected because BatchWriteItem cannot carry condition expressions.

DynamoDbCompositeId (section 4.2) is a repository-level convenience — the template exposes the two keys directly instead.

The builder validates the section 4.4 rules at build time and aliases every attribute name through ExpressionAttributeNames, so reserved words never need special handling. It also rejects null key values, duplicate partition-key assignments, and filter placeholders that collide with the auto-generated key placeholders. Available conditions: sortEq, sortLt, sortLe, sortGt, sortGe, sortBetween, sortBeginsWith, plus filterExpression, scanIndexForward, consistentRead, exclusiveStartKey and limit.

Callbacks return the entity that continues through the operation, so they may replace or modify it. update() and delete() do not invoke update/delete callbacks; those operations publish events only.

All events extend DynamoDbMappingEvent<T>, whose source is the entity (or entity class for an expression-based update) and whose tableName is the resolved physical table. There is no DynamoDbBeforeConvertEvent; before-convert behavior is callback-only.

For save() and insert():

For saveAll(), steps 1–3 run for every entity first. The chunked BatchWriteItem requests then complete, including retries for unprocessed items, before steps 5–6 run for every entity. Hooks are emitted per entity, not once for the batch.

An entity-based update() publishes BeforeUpdate, executes UpdateItem, then publishes AfterUpdate. An expression-based update follows the same event order and then converts the returned ALL_NEW attributes, invoking AfterConvert and publishing AfterConvertEvent. A delete publishes BeforeDelete, executes DeleteItem, then publishes AfterDelete.

Standard entity reads (findById, query, scan, PartiQL, and index-query paths) perform item-to-Java conversion, invoke DynamoDbAfterConvertCallback, and then publish DynamoDbAfterConvertEvent for each converted entity. Item-collection folding uses its dedicated converter path and does not emit per-row after-convert hooks.