accesspatterns.dev for agents and crawlers

Foundations

What an item is, and how the key addresses it.

• Items, not rows - Two items in one table can have completely different attributes.
• The key is the address - GetItem needs the whole primary key: partition and sort.

Reads and cost

The three ways to read, and what each one charges you.

• One query, a whole collection - Items that share a partition key are read together in one Query.
• The sort key is a query language - Conditions on the sort key narrow a Query before it reads, for free.
• A filter is not an index - A FilterExpression runs after the read: you pay for everything scanned.
• Read the latest first - A sorted timestamp makes 'the most recent' a direction, not a sort in your code.
• Read a page, keep the bookmark - Limit caps a page; LastEvaluatedKey is the bookmark you feed back to resume.

Writing data

Putting, changing, and guarding items.

• PutItem replaces - PutItem writes a whole item and overwrites any item with the same key.
• UpdateItem edits in place - UpdateItem changes named attributes and can increment a counter atomically.
• Claim it, or fail - A ConditionExpression lets a write happen only if the data still allows it.
• No silent clobbers - A version check lets an update land only if nobody changed the item since you read it.

Modelling relationships

One-to-many, secondary indexes, and sparse indexes.

• Model a one-to-many with one partition - A parent and its children share a partition key, so one Query fetches them together.
• One key, every level - A path in the sort key lets one begins_with read any level of a hierarchy.
• A different key for a different question - A secondary index re-keys your items so you can Query them on a new axis.
• Traverse a relationship both ways - An index that swaps the partition and sort keys reads the same edges from the other side.
• Absence as a filter - An item appears in an index only if it has the index's key, so leaving the key off filters it out.
• Keep the total where you read it - A denormalised count on the parent turns an aggregate into a single GetItem.

Single-table design

One table, one index, many access patterns.

• One index, many questions - Different entity types share generic index keys, so one index serves several access patterns.
• An index holds only what you project - Projection decides which attributes an index carries, trading storage against an extra read.
• One table, an application's worth of questions - Generic keys and one overloaded index answer five access patterns with no join and no scan.