DEV Community: DynoTable

Why we hand-wrote a PartiQL parser for DynamoDB

DynoTable — Sat, 15 Aug 2026 16:22:30 +0000

DynamoDB accepts a narrow slice of PartiQL and rejects everything else at request time. GROUP BY? ValidationException. A statement-level LIMIT? ValidationException. The * operator, CAST, a subquery? All of them parse fine in your head, travel over the wire, and die on the server. The only place that knowledge lived was the AWS documentation and the error messages, which meant every editor for DynamoDB — including ours, for a while — would happily let you compose a statement the engine was guaranteed to refuse.

We wanted the refusal to happen in the editor, on the keystroke, with a red squiggle on the exact clause and a one-click fix where a rewrite exists. That editor need turned into a hand-written lexer and CST parser for DynamoDB's PartiQL dialect, and this week we open-sourced it: dynamodb-partiql-parser, pure TypeScript, zero dependencies, MIT, with the CodeMirror wiring published separately as codemirror-lang-partiql. This post is why it's hand-written, what the first linter got wrong, and the two bugs that only showed up when someone pasted garbage.

Regex was fine, until it wasn't

The first PartiQL linter in DynoTable was about 650 lines of regex and token scanning, and it was genuinely useful: nineteen distinct checks, quick fixes for the common traps (IN (...) to [...], LIKE to contains(), IS NULL to attribute_not_exists()). It shipped, it caught real mistakes, users stopped filing "why does my query fail" tickets for the cases it covered.

But a regex linter knows patterns, not structure. It couldn't see that * in SELECT price * quantity is arithmetic DynamoDB rejects, because * also means "all columns" and telling those apart requires actually parsing. Its diagnostic ranges were approximations — close enough to point at a line, too coarse to drive a quick fix that splices text at exact offsets. And every new check made the pile more fragile, because each regex had to defend against every other regex's assumptions.

The fix for "the linter needs structure" is a parser. The question was which one.

Nobody had built one

For the Workbench's real-SQL side we had already been through this: an off-the-shelf SQL parser that lied to us, replaced by sql-parser-cst, which carries a source range on every node and preserves quoted-versus-unquoted identifiers. That experience set the bar for what the PartiQL side needed — a lossless concrete syntax tree, not a lossy AST.

But PartiQL is not SQL where it counts for a parser. DynamoDB's dialect writes IN lists with brackets (WHERE OrderID IN [100, 300, 234]), has bag literals (<<'a', 'b'>>), map literals with quoted keys ({'rating': 5}), a MISSING literal, document paths with list indexes (Devices.FireStick.DateWatched[0]), and RETURNING ALL OLD * — none of which a SQL grammar knows. In the other direction it lacks half of what a SQL grammar insists on. At the time, the parsers on npm were WebAssembly builds of AWS's Rust implementation for generic PartiQL, with no notion of what DynamoDB specifically rejects.

So we wrote one: a small lexer and a recursive-descent parser, modeled on the shape sql-parser-cst taught us to want. Every node carries its byte range. The whole thing has zero runtime dependencies — a property the CI now asserts, because it's what makes the parser embeddable anywhere, including the browser, including your project.

The grammar was the easy half. A linter's parser spends its whole life parsing broken code. Mid-keystroke, half a statement, a typo in the third clause. Stopping at the first error would make the editor useless, so the parser is error-tolerant: it records a diagnostic, resynchronizes, and keeps going, so the fourth clause still lints while the second is incomplete.

Swapping the engine without breaking the plane

By the time the parser was ready, the regex linter's four functions were load-bearing across the editor — including the one that decides whether a statement is safe to auto-execute. Silently changing that behavior shows up as "the editor won't run my query," which is the kind of bug users don't report so much as leave over.

So the swap was a strangler: the old linter was renamed, frozen, and kept in the tree. The new parser-driven linter re-exported the exact same four functions. And a parity corpus ran every fixture through both linters and pinned the outputs against each other — every diagnostic the regex version produced, the parser version had to produce too, before it was allowed to produce more. The old linter is still there today, frozen, as executable documentation of what the swap promised.

The bugs that only garbage finds

Two failures never appeared in any real query and both would have taken the editor down.

A CodeMirror linter runs synchronously on the document, on every change, with no error sink above it. One uncaught exception doesn't fail a lint — it white-screens the editor. And a recursive-descent parser has a natural uncaught exception built in: the call stack. Paste [[[[[[… a few thousand brackets deep, or a NOT NOT NOT … chain, and each nesting level is a stack frame; V8 eventually throws RangeError: Maximum call stack size exceeded straight through the linter.

The fixes are boring on purpose. Expression recursion has a hard depth ceiling — five hundred levels, far beyond anything a human writes, well under the stack budget — past which the parser emits a single diagnostic instead of throwing. And the constructs where pastes realistically chain, like A UNION B UNION C … thousands of arms long, were rewritten from recursion into flat lists: one parseSelect frame and an array of set-operations, instead of one frame per arm. The stress suite now pastes 100 KB of garbage and 30,000-deep operator chains at every build, and the public package wraps the whole pipeline in a lint() entry point that never throws, because the next editor to embed this will have the same no-error-sink problem we did.

A test suite you can audit against AWS's docs

The dialect rules — what DynamoDB accepts, what it rejects, which rewrite fixes what — all come from AWS's PartiQL reference. Documentation-derived behavior has a specific failure mode: the doc moves, the code doesn't, and nobody notices.

So the corpus is structured against it. Two hundred and eight fixtures, and every one opens with the URL of the AWS documentation page the rule comes from. A coverage table maps each documented rule to its fixture, and the suite fails if a rule loses its fixture. When AWS changes the dialect, the diff is a fixture diff with a citation on it.

That discipline paid for itself the week we open-sourced. The linter's IN-list warning cited two caps: 50 values on a partition key column, 100 on a non-key column. Re-verifying every number before publication, we could confirm the 100 in AWS's current documentation — and could not find the 50 anywhere in an operative doc. It survives all over blog posts and old forum answers, but the primary source has moved on. The linter had it right by accident (it only warns past 100, since without your schema it can't tell which case applies), and the comment now says exactly which half of the claim is documented and which is folklore.

What transfers if you're building one

A hand-written recursive-descent parser for a small dialect is days of work, not months, and you own every error message. The scary version of "write a parser" assumes a big grammar.
Build a CST, not an AST. Byte ranges on every node are what turn diagnostics into quick fixes; a lossy tree can't splice text.
If the parser feeds a linter, error tolerance is the feature. Recover and continue; a parser that stops at the first error lints nothing after it.
Swap engines behind a frozen interface with a parity corpus pinning old against new. The old implementation is the spec you already agreed to.
Anywhere input can nest, someone will paste something that nests absurdly. Depth-cap the recursion and flatten the chains; test with garbage, not just queries.
Cite your sources in the tests. A fixture that names the doc page it encodes is a test that can be audited when the doc changes — and it will change.

The parser is on GitHub and npm (npm install dynamodb-partiql-parser), with the editor integration in codemirror-lang-partiql. If you want the dialect itself rather than the parser, PartiQL vs SQL covers what DynamoDB's subset can and can't do and PartiQL examples is the practical walkthrough; the editor all of this was built for is in DynoTable, and you can try it free.

DynamoDB Sparse Indexes

DynoTable — Fri, 14 Aug 2026 12:32:18 +0000

A sparse index is a secondary index that holds only the items carrying its
key attribute — so a small, hot subset of a huge table becomes its own
pre-filtered, ready-to-query collection.

You have millions of rows but the query you run all day touches a tiny slice: the
open support tickets, the unpaid invoices, the accounts flagged for review.

Filtering that slice still scans the whole table and bills you for every read. A
sparse index makes the index itself small instead.

What is a sparse index in DynamoDB?

A sparse index is a secondary index that holds only the items carrying its key attribute. Because DynamoDB skips any item missing that key, you invent a key only the wanted items write — open tickets, unpaid invoices — and the index becomes that exact subset. Queries then read just it, no filter, no wasted read capacity.

A secondary index only indexes items that have its key. Omit the key on an item and it never enters the index — no placeholder, no null row.
So you invent a key only the wanted items carry. Write it on the items you query, remove it on the rest. The index becomes exactly that subset.
The query reads only the subset, no filter. Its size tracks the small hot set, not the table total.
REMOVE is the lever, not blanking. An empty string isn't a valid index key — DynamoDB rejects the whole write with a ValidationException — so you must delete the attribute.

The problem: filtering doesn't save reads

Coming from SQL, you assume a WHERE clause narrows the work. DynamoDB's
FilterExpression does not. It runs after items are read, not before.

Per the
AWS Developer Guide,
"a Query consumes the same amount of read capacity, regardless of whether a filter
expression is present" — you pay for every item examined, then throw the
non-matches away.

So if 50 of your 5 million tickets are open, a filtered Query/Scan reads
through millions to hand you those 50.

That is the footgun behind every "why is my scan so expensive" thread;
query vs. scan has the full cost picture.

A sparse index sidesteps it by making the index itself small.

How sparseness works

A secondary index only indexes items that actually have the index's key
attributes.

The
AWS docs on sparse indexes
spell this out: DynamoDB writes an item to a secondary index only when that item
carries the index's key attributes, so an index over a rarely-set attribute stays
naturally small.

Miss the GSI's partition key (or sort key) on an item and DynamoDB just doesn't
write it to the index. No placeholder, no null row — the item is absent.

That "absence by default" is the whole trick. Don't index a status attribute
that every item carries. Invent an attribute that only the items you want to
query carry at all.

The index then becomes a clean list of exactly those items, and a Query against
it reads only them — no filter, no wasted capacity.

Picture the base table feeding the index, where only items carrying the key cross over:

Only the keyed (open) items replicate to the index; closed items never enter it.

This is the same key-shaping mindset as
single-table design: keys are tools you build for a
specific access pattern, not faithful mirrors of your data.

A worked example: "open tickets only"

Take a support-ticket table. The base table is keyed for fetching a ticket by id
and listing a customer's tickets:

PK	SK	attributes
TICKET#a91f	DETAIL	subject, body, priority, openState
CUSTOMER#88	TICKET#a91f	subject, priority, openState

Over the table's lifetime, most tickets end up closed. But the dashboard query
your agents hit all day is "show me every open ticket, oldest first" — a few
hundred rows hiding inside millions.

Define a GSI with partition key openBucket and sort key
openedAt, and only write openBucket on open tickets. Set it when the
ticket is created; REMOVE it when the ticket resolves.

PK	SK	openBucket	openedAt
TICKET#a91f	DETAIL	OPEN	2026-06-23T09:14:00Z	← open: in the index
TICKET#b02c	DETAIL	OPEN	2026-06-22T16:40:00Z	← open: in the index
TICKET#77de	DETAIL	(absent)	2026-05-30T11:02:00Z	← closed: NOT in the index

Tickets a91f and b02c carry openBucket, so they live in the GSI. Ticket
77de was resolved and had openBucket removed, so it silently dropped out. The
dashboard is now one cheap query:

Example	Notes
`Query IndexName = "open-tickets-index"`
`KeyConditionExpression: openBucket = "OPEN"`
`ScanIndexForward: true # oldest first`

This reads only open tickets. As tickets close, the index shrinks on its own — its
size tracks the open population, never the total.

One static partition value ("OPEN") is fine here precisely because the set stays
small. A huge open set would need a sharded partition key, but the "small subset"
index is exactly where one value is the right call.

The transition that makes it work is a single update expression — removing the
attribute when the ticket resolves.

Prototype that REMOVE clause and the typed key condition for the read side in the
DynamoDB Expression Builder, instead of
hand-assembling ExpressionAttributeNames and :val placeholders yourself.

Do it in DynoTable

The hard part of a sparse index is seeing which items made it
into the index versus which silently fell out.

DynoTable lets you switch a table view to a secondary index and see exactly the
populated subset. So you can confirm a resolved ticket really left
open-tickets-index instead of lingering with a stale key.

Pitfalls and next steps

A few things to watch:

Remove the key, don't blank it. An empty string isn't a valid index key — writing openBucket = "" fails with a ValidationException, so the item is never indexed with it. To drop an item from the index you must REMOVE the attribute.
The index is eventually consistent. GSIs update asynchronously, so a just-resolved ticket may briefly still appear — GSI reads support eventual consistency only. Don't trust it for "is this ticket open right now".
Mind projected attributes. A Query on the index returns only the attributes projected into it. If the dashboard needs subject and priority, project them — or pay an extra GetItem for the full base item.
Both GSIs and LSIs can be sparse — the lever is the same: omit the index's sort key on items you don't want indexed. A GSI is usually the better fit, though: you can add it after table creation and give it its own key schema and capacity. GSI vs. LSI breaks down the trade-off.

Sparse indexes are one of the oldest ideas in the model. The original
2007 Amazon Dynamo paper
built the store around serving known, high-volume access patterns cheaply.

A sparse index is exactly that: shape the keys so the common query reads nothing it
doesn't need.

To build and inspect one for real, download DynoTable, point it at
your table, and flip the data view to your sparse GSI — watch the subset update as
items gain and lose the index key.

DynamoDB Sort Key Strategies: 3 Patterns and When to Use Each

DynoTable — Fri, 14 Aug 2026 12:31:47 +0000

A DynamoDB primary key is one or two attributes: a partition key alone, or a
partition key plus a sort key. The partition key decides which physical
partition holds an item.

The sort key decides the order of items inside that partition — and that
ordering is what makes Query powerful.

Pick the wrong sort key and you can still write data, but you lose range reads,
ordering, and several access patterns from one collection.

Coming from SQL you'd reach for an ORDER BY or a secondary index after the
fact. In DynamoDB you bake the order into the key up front, or you don't get it.

How do DynamoDB sort keys work?

A DynamoDB sort key orders items within a partition, so Query can do range reads — >=, between, begins_with — instead of fetching one item at a time. String sort keys order by UTF-8 bytes (Numbers order numerically), so design a string key (an ISO-8601 timestamp, a zero-padded number) so byte-order equals the order you want to read.

The sort key is your in-partition index. It orders the item collection on disk, so Query can do range reads (>=, between, begins_with) instead of a single GetItem.
String sort keys order by UTF-8 bytes (Numbers order numerically). Design a string key so byte-order equals the order you want to read — an ISO-8601 timestamp, a zero-padded number, never a raw UUID or 6/23/2026.
One well-shaped sort key serves many access patterns. A composite key (EVT#<timestamp>) is a prefix and a range at once — no GSI needed.
Direction is free. ScanIndexForward = false reads newest-first at the same cost; don't store reversed timestamps to fake it.

Why the sort key is the lever

Without a sort key, every item in a partition is addressable only by its full
primary key — a GetItem at best. Add a sort key and DynamoDB stores items
sorted by it within the partition, which unlocks Query.

That means range conditions (>=, between), prefix matching (begins_with),
and a ScanIndexForward flag to read ascending or descending.

Per the AWS DynamoDB Developer Guide, all items sharing a partition key form an
item collection, ordered on disk by the sort key.

So the sort key isn't just a second identifier. It's the index you query against
inside a partition.

That ordering is byte-order on the encoded sort key: strings compare by UTF-8
bytes, numbers compare numerically. This one fact drives almost every strategy
below.

If you want range queries to mean something, byte-order has to match the order you
want to read.

Strategy 1: make the sort key sortable

The most common mistake is a sort key that isn't meaningfully ordered. A random
UUID gives you uniqueness but no useful range query — "give me the last 20"
becomes impossible because byte-order is arbitrary.

Instead, encode the value you sort and filter on into the sort key, in a
representation whose byte-order equals its logical order. For timestamps that
means a lexicographically-sortable format: an ISO-8601 string or a zero-padded
epoch.

ISO-8601 was designed so string comparison equals chronological comparison —
exactly what a range query needs. Avoid formats like 6/23/2026; they sort wrong
the moment the month rolls over.

If you sort on numbers (a version counter, a score), use DynamoDB's native
Number type rather than a string, so 42 sorts after 9 instead of before
it.

If a number must live inside a composite string sort key, zero-pad it to a fixed
width.

Strategy 2: composite sort keys for hierarchy

A sort key can encode a hierarchy by concatenating segments with a delimiter,
most commonly #. One begins_with condition then selects a whole sub-tree:

SK
EVENT#2026-06#01#login
EVENT#2026-06#03#export
EVENT#2026-07#02#login

begins_with(SK, "EVENT#2026-06#") returns just June's events; the broader
begins_with(SK, "EVENT#") returns all of them.

Segment ordering is a design decision. Coarse-to-fine (year → month → day) keeps
related items contiguous, so a range read stays one cheap query instead of a
scatter across the partition.

Strategy 3: control direction with ScanIndexForward

DynamoDB stores items in ascending sort-key order and reads them that way by
default. To read newest-first — the natural order for an activity feed — set
ScanIndexForward = false on the Query.

This is a read-time flag, not a schema decision: the same collection serves both
directions at the same cost. Don't invert your timestamps (storing a "reverse
epoch") just to get descending reads.

One item collection, stored once in ascending order, read either way:

Same items, same partition, same cost — only the read direction differs.

Worked example: an actor-scoped audit log

Suppose you record timestamped events produced by actors — users, services, API
keys — in a SaaS product, and you have two reads:

The activity stream for one actor, newest event first.
One actor's events within a time window (e.g. "everything between the two deploys"), for an investigation.

Both reads are scoped to a single actor, so the actor is the partition key and the
event time is the sort key. Use generic key names so the same table can hold other
entities later:

PK	SK	attributes
ACTOR#u_8814	EVT#2026-06-23T09:12:04Z	action=login, ip, ua
ACTOR#u_8814	EVT#2026-06-23T14:05:11Z	action=export, target
ACTOR#u_8814	EVT#2026-06-24T08:40:55Z	action=login, ip, ua
ACTOR#svc_billing	EVT#2026-06-23T00:00:00Z	action=invoice.run

The EVT# prefix plus an ISO-8601 timestamp gives a sortable sort key. Read 1 is
Query PK = "ACTOR#u_8814" with ScanIndexForward = false for newest-first. Read
2 narrows the same partition with a between condition on the sort key:

Example	Notes
`Query`
`PK = "ACTOR#u_8814"`
`AND SK BETWEEN "EVT#2026-06-23T00:00:00Z"`
`AND "EVT#2026-06-23T23:59:59Z"`

One collection, two access patterns, no GSI — because the sort key is both a prefix
(EVT#) and a range (the timestamp). The descending read and the window read are
the same items in the same order; only the parameters differ.

Building that key condition by hand, it's easy to fumble the between bounds or
the reserved-word escaping on attribute names.

The DynamoDB Expression Builder
generates the KeyConditionExpression, the ExpressionAttributeNames, and the
ExpressionAttributeValues for a begins_with or between sort-key condition.

Copy it straight into your SDK call instead of debugging escaping at runtime.

Do it in DynoTable

Designing a sort key is iterative: write a few representative items, run the range
query, and check the rows come back in the order you expect. Doing that against a
live table in a GUI beats round-tripping through code.

Flip the sort direction, tighten the between bounds, and watch the returned
collection change without writing a line of code — the fastest way to confirm a
sort-key design before you commit it.

Pitfalls and next steps

Sort keys must be unique within a partition. If two events can share a timestamp, append a disambiguator (a sequence number or short id) to the sort key so the composite stays unique.
A hot partition can't be sorted around. If one actor produces far more events than the rest, the sort key won't save you — you need a partition-key design that spreads the load. See single-table design.
A second sort order needs a second index. The base table's sort key gives one ordering. To order the same items differently (by event type, say), add a GSI with a different sort key — weighing the local vs global secondary index trade-offs.
Don't reach for Scan to "sort later". Sorting client-side after a Scan reads the whole table and throws ordering away; that's the Scan footgun. Push the order into the sort key instead.

Once the key condition is right, try DynoTable to model the
collection, run the ascending and descending queries side by side, and verify your
sort-key strategy against real data before it ships.

PartiQL for DynamoDB by Example

DynoTable — Fri, 14 Aug 2026 12:31:46 +0000

PartiQL is a SQL-compatible query language for DynamoDB. It's friendlier than the
raw API for ad-hoc work — but it runs on the same engine, so the same key rules
(and the same costs) apply underneath the familiar syntax.

How do you write PartiQL queries for DynamoDB?

PartiQL gives DynamoDB four SQL-shaped statements — SELECT, INSERT, UPDATE,
and DELETE — run through ExecuteStatement. Each one compiles to a native
operation underneath, so filtering on the partition key stays a
Query while omitting it becomes a full-table Scan. Writes still target one item
by its primary key; there's no relational JOIN, GROUP BY, or aggregate.

Every statement runs through the same ExecuteStatement API (or its batch/transaction
variants). Table and index names must be double-quoted when they contain special
characters; attribute names in expressions follow the same quoting rules as the
low-level API. The PartiQL docs in DynoTable mirror these
examples with schema-aware autocomplete and a searchable history of past runs.

SELECT

SELECT * FROM "AppData"
WHERE "PK" = 'CUSTOMER#42' AND begins_with("SK", 'ORDER#')

Filter on the partition key and this is a Query. Omit the partition key and
PartiQL silently runs a full-table Scan — same footgun,
just hidden behind SELECT *.

`WHERE` clause shape	Compiled operation	Typical cost driver
`PK = ?` (exact partition)	`Query`	Items in that partition (plus filter waste)
`PK = ? AND begins_with(SK, ?)`	`Query`	Sort-key range within one partition
`GSI1PK = ?` via `FROM "Table"."GSI1"`	`Query` on index	Items in the index partition
No partition-key equality on table or index	`Scan`	Every item in the target, before filters

Put numbers on the Scan path: a table with 500,000 items averaging 1 KB each meters
~125,000 read request units on on-demand billing for a full SELECT * (500,000 KB
÷ 4 KB per unit, eventually consistent at 0.5 RCU each). Add WHERE status = 'OPEN'
and the bill is identical — filtering happens after the read is metered. The keyed
SELECT in the example above touches only the CUSTOMER#42 partition; if that
collection holds 40 orders at 1 KB each, the same eventually-consistent read costs
5 units (40 KB total), not 125,000.

ExecuteStatement paginates like the native API: a non-empty NextToken means
more rows remain. Loop until the token is absent (pagination guide).

INSERT

INSERT INTO "AppData" VALUE {'PK': 'CUSTOMER#42', 'SK': 'PROFILE', 'plan': 'pro'}

UPDATE

UPDATE "AppData" SET "plan" = 'enterprise'
WHERE "PK" = 'CUSTOMER#42' AND "SK" = 'PROFILE'

DELETE

DELETE FROM "AppData"
WHERE "PK" = 'CUSTOMER#42' AND "SK" = 'ORDER#2026-001'

Querying an index

Use the index name in the FROM clause:

SELECT * FROM "AppData"."GSI1" WHERE "GSI1PK" = 'STATUS#OPEN'

WHERE also supports IN, contains() and begins_with():

SELECT * FROM "AppData"
WHERE "PK" = 'CUSTOMER#42' AND "SK" IN ['ORDER#1', 'ORDER#2']

Parameterized statements

Use ? placeholders instead of inlining values — it sidesteps quoting/injection
issues and lets the SDK marshal types for you:

SELECT * FROM "AppData" WHERE "PK" = ? AND begins_with("SK", ?)

Pass Parameters: [{ S: 'CUSTOMER#42' }, { S: 'ORDER#' }] to ExecuteStatement.

Prefer parameters in application code and reserve string interpolation for ad-hoc
console sessions. The SDK marshals types (N for numbers, BOOL for booleans)
so you avoid the classic "42" string where DynamoDB expected a number attribute.
Reserved attribute names still need aliases in PartiQL exactly as in
FilterExpression — run your names through the
reserved-words checker before baking them
into a stored statement.

Batch and transactions

BatchExecuteStatement — up to 25 statements in one round trip. Faster, but no cross-item atomicity (each succeeds or fails on its own).
ExecuteTransaction — up to 100 statements, all-or-nothing. Use it when several writes must commit together.

Batch and transaction ceilings are fixed service limits, not tuning knobs. A cart
checkout that touches 30 line items still needs chunking: two BatchExecuteStatement
calls (25 + 5) or one transaction if you need atomicity across all 30 (and each
statement still targets a single item by full primary key).

PartiQL vs Workbench SQL

PartiQL executes on DynamoDB — one keyed access pattern per statement. DynoTable's
SQL Workbench executes in the client over rows
you've already pulled, which unlocks JOIN, GROUP BY, and aggregates PartiQL
deliberately omits. The split is operational, not cosmetic:

Need	Reach for
Single-partition read/write by primary key	PartiQL `SELECT` / DML
Cross-partition filter you modeled a GSI for	PartiQL against the index
Ad-hoc join across two entity types	Workbench SQL over bounded queries
Monthly revenue roll-up by SKU	Workbench `GROUP BY`
Production hot-path microservice	Native `Query` / `GetItem` APIs

Workbench still respects DynamoDB's access rules: you fetch partitions with keyed
reads (or bounded Scans you accept consciously), then SQL shapes the result set
locally. See PartiQL vs SQL for the full comparison.

The PartiQL footgun

PartiQL looks like SQL but runs on the DynamoDB engine, so SQL habits backfire:

A single UPDATE/DELETE must target one item by its full primary key — there's no UPDATE … WHERE status = 'x' mass update (loop with a batch instead).
No JOIN, no GROUP BY, no aggregates (COUNT/SUM/AVG). See PartiQL vs SQL.
Omitting the partition key turns any SELECT into a full-table Scan — bounded only by your bill.

When you genuinely need a JOIN, a GROUP BY, or an aggregate, DynoTable's SQL
Workbench runs them client-side over the rows you've pulled — the SQL PartiQL
can't speak, inside DynamoDB's access-pattern rules.

PartiQL doesn't change the underlying data types — values
still go over the wire as DynamoDB-JSON, which you can inspect with the
converter.

For UPDATE and DELETE statements, the WHERE clause must resolve to exactly one
item. Partial-key WHERE clauses that match many rows fail at compile time or runtime
rather than mass-updating — loop with a keyed Query, then issue per-item DML inside
BatchExecuteStatement or a transaction when you need atomicity.

Complex KeyConditionExpression shapes (nested begins_with, mixed AND/OR) are
easier to prototype in the
DynamoDB Expression Builder and translate into
PartiQL's WHERE syntax once the condition is correct.

Try DynoTable to run PartiQL statements with schema-aware autocomplete
and browse the results in a sortable table view — then pivot the same dataset into
Workbench when you need a join or aggregate the engine cannot push down.

DynamoDB Pagination: LastEvaluatedKey Explained (w/ Examples)

DynoTable — Wed, 12 Aug 2026 09:37:56 +0000

DynamoDB never returns "all" results in one call. A Query or Scan returns at
most 1 MB of data, then hands you a LastEvaluatedKey to resume from. Getting
pagination right means looping on that key — not on a counter.

How does pagination work in DynamoDB?

A Query or Scan returns at most 1 MB per call, then hands back a LastEvaluatedKey. To page, you pass that key as the next call's ExclusiveStartKey and loop until DynamoDB returns no key. There are no page numbers, no total count, and Limit caps items evaluated — not items returned.

let key;
do {
  const out = await client.send(new QueryCommand({...params, ExclusiveStartKey: key}));
  process(out.Items);
  key = out.LastEvaluatedKey;
} while (key);

When LastEvaluatedKey is undefined, you've reached the end. Pass it back as
ExclusiveStartKey to fetch the next slice.

Each page is bounded by two independent ceilings: the Limit you set (if
any) and a hard 1 MB response cap. A partition with chunky items can fill a
page on three rows even when Limit is 100 — DynamoDB stops when either bound
is hit and still returns a LastEvaluatedKey if more data remains. Plan UI copy
around "load more" rather than "showing 25 of N", because N is unknown until
you've walked every page.

The control flow is a single loop that exits only on an absent key:

Every pass either resumes from the returned key or stops — there is no counter.

Limit is not a page size

Limit caps how many items DynamoDB evaluates, not how many it returns after
a FilterExpression. A Limit: 25 query behind a filter can return 3 items and
still hand you a LastEvaluatedKey — you must keep paging until the key is empty,
even when a page looks short. A non-empty LastEvaluatedKey never promises
more matching items either; only an absent key proves you've reached the end.

What you might expect	What DynamoDB actually does
`Limit: 25` → 25 rows in the page	Evaluates up to 25 items; filters may shrink the returned set
Short page → end of data	Short page + non-empty key → keep paging
Empty page → done	Empty page + non-empty key → more data exists beyond the filter
`Limit` controls bill per request	Bill follows items read, including filtered-out rows

A concrete read: partition USER#42 holds 200 order items averaging 2 KB each.
Query with Limit: 50 and FilterExpression: status = 'OPEN' might evaluate
50 items (~100 KB metered), match 4, and return a key — you page again. Without
the filter, the same Limit: 50 evaluates 50 items and bills ~25 read capacity
units on-demand (50 × 2 KB → 100 KB, rounded up per 4 KB block at 0.5 RCU each
for eventually-consistent reads). Pass ReturnConsumedCapacity: TOTAL on every
call to see the metered units per page instead of guessing.

Let the SDK paginate

Both SDKs wrap the loop above so you can iterate pages directly:

// AWS SDK for JavaScript v3
import {paginateQuery} from '@aws-sdk/lib-dynamodb';
for await (const page of paginateQuery({client}, params)) {
  process(page.Items);
}

# boto3
paginator = client.get_paginator('query')
for page in paginator.paginate(**params):
    process(page['Items'])

No page numbers

DynamoDB has no total count and no random page access — you can't jump to
"page 7" or page backwards without replaying the cursors. Design UIs around
infinite scroll / "load more", not numbered pages. (A Select: 'COUNT' query
still reads — and bills for — every matched item to count them.)

Stateless cursors for APIs

LastEvaluatedKey is just the key attributes of the last item. Base64-encode it
and hand it to clients as an opaque nextToken; decode it back into
ExclusiveStartKey on the next request. No server-side cursor state.

That token is DynamoDB-JSON — eyeball or hand-craft one with the
DynamoDB-JSON converter. And if you're paging to
work around a Scan, that's usually a signal to add an
index instead.

Treat the token as opaque and immutable. Clients must send back exactly what
you issued; decoding, mutating a sort-key component, and re-encoding breaks the
resume point and can skip or duplicate rows. Version the envelope ({"v":1,"lek":…})
so you can rotate encoding without breaking in-flight sessions. For Scan pages,
the key includes the segment id when you use parallel segments — a token from
segment 2 must resume segment 2, not segment 0.

PartiQL's ExecuteStatement uses the same resume model under a different name:
NextToken on the response becomes NextToken on the next request. The mental
model — loop until the token is absent — is identical to Query/Scan.

Pick a pagination strategy

Approach	Best for	Trade-off
Manual `do/while` on the key	Full control, custom backoff, mixed ops	Easy to forget error handling or capacity caps
SDK paginator (`paginateQuery`)	Batch jobs, exports, CLI tools	Less control over per-page side effects
Base64 `nextToken` in your API	Mobile/web "load more"	Must validate and never expose raw table keys
DynoTable result grid	Exploratory reads, verifying key order	Client-side; not a server pagination pattern

Whichever path you choose, never infer progress from page index. Page 14 of a
Scan over a growing table is not "14 × Limit items in" — items added or deleted
between calls can shift boundaries. Idempotent downstream writes (natural keys,
conditional puts) keep replays safe when a client retries the same token after a
timeout.

Capacity adds up across pages

Pagination does not discount reads. Ten pages that each touch 1 MB of item data
meter roughly ten times the single-page cost. Background jobs that walk an entire
table via Query on a GSI should multiply "cost per page" by "pages until key
absent" before scheduling — the
pricing calculator accepts that per-page
unit count directly.

Large responses also hit wire limits before capacity limits: if a single item
approaches 400 KB, you may get one item per page regardless of Limit. The
item size calculator shows when an item
crosses the 4 KB read rounding boundary (one RCU per 4 KB for strongly-consistent
reads, half that eventually consistent).

Build and inspect the loop

To skip writing the loop at all, the
query builder composes the full Query/Scan
request and emits a runnable SDK v3, CLI, or boto3 program — pagination loop
included. Set your partition key, optional sort condition, projection, and filter;
the emitted program wraps paginateQuery or an equivalent manual loop with
ExclusiveStartKey wiring already in place.

For the underlying API fields and consistency options, see
Querying in DynoTable — the same pagination rules apply
whether you call the SDK, PartiQL, or the desktop app's PartiQL tab.

Try DynoTable to page through query results visually, with the cursor
tracked for you and ReturnConsumedCapacity surfaced per request so you can see
each page's read units without wrapping every call yourself.

How to Run DynamoDB Local with Docker — Complete Guide

DynoTable — Wed, 12 Aug 2026 09:37:20 +0000

DynamoDB Local is AWS's downloadable emulation of DynamoDB in a single process —
same API, no AWS account, no network, no per-request bill. Use it for local
development and integration tests, then point the same code at the cloud in
production. It ignores provisioned throughput and never throttles, so it can't
stand in for load or limit testing.

How do I run DynamoDB Local with Docker?

Run docker run -p 8000:8000 amazon/dynamodb-local to start the official image,
which exposes the DynamoDB engine on http://localhost:8000. Point your AWS SDK
or CLI at that endpoint with any dummy credentials, then create tables and run
requests exactly as you would against the cloud. Add -sharedDb and a mounted
-dbPath volume to keep data across restarts.

Start the container

docker run -p 8000:8000 amazon/dynamodb-local

That exposes the engine on http://localhost:8000.

docker-compose

Most projects pin it in docker-compose.yml so the whole team gets the same
endpoint:

services:
  dynamodb:
    image: amazon/dynamodb-local
    user: root
    command: '-jar DynamoDBLocal.jar -sharedDb -dbPath /data'
    ports:
      - '8000:8000'
    volumes:
      - dynamodb-data:/data
volumes:
  dynamodb-data:

The image runs as the non-root dynamodblocal user, which can't open a
database file inside the root-owned named volume — without user: root you hit
SQLiteException [14] unable to open database file and every call hangs.

Persistence

By default DynamoDB Local is in-memory — every table vanishes when the
container stops. Two flags make it durable:

-sharedDb keeps all clients on one shared database file (without it, each set of credentials/region gets its own isolated DB — a common "where did my table go?" surprise).
-dbPath /data + a mounted volume writes that file to disk, so data survives docker compose down.

Point the SDK at it

Only the endpoint changes — credentials can be any dummy values:

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';

const client = new DynamoDBClient({
  endpoint: 'http://localhost:8000',
  region: 'local',
  credentials: {accessKeyId: 'x', secretAccessKey: 'x'}
});

Create a table

aws dynamodb create-table \
  --endpoint-url http://localhost:8000 \
  --table-name AppData \
  --attribute-definitions AttributeName=PK,AttributeType=S AttributeName=SK,AttributeType=S \
  --key-schema AttributeName=PK,KeyType=HASH AttributeName=SK,KeyType=RANGE \
  --billing-mode PAY_PER_REQUEST

A single-table PK/SK schema like this is a good
default. When you load fixtures, convert plain JSON to the wire format with the
DynamoDB-JSON converter.

Verify the container is up and the table landed:

aws dynamodb list-tables --endpoint-url http://localhost:8000

Browse it with a GUI

CLI calls get tedious fast. The usual options are the open-source dynamodb-admin
web UI or a desktop client. DynoTable connects straight to
localhost:8000 (or any LocalStack endpoint — see
connecting to DynamoDB Local & LocalStack)
and lets you browse, query with the SQL Workbench, and edit local tables with the
same UI you use for cloud tables — no aws CLI round-trips.

What Local does not emulate

Treat Local as an API compatibility layer, not a capacity simulator. It ignores
provisioned throughput, never returns
ProvisionedThroughputExceededException,
and does not model on-demand burst behavior. A load test against Local tells you
nothing about partition limits or adaptive capacity in AWS.

Other gaps show up in integration tests if you do not plan for them:

Behavior	DynamoDB Local	AWS DynamoDB
Billing / RCU / WCU	None	Metered per request
Throttling	Never	Yes, at table/index limits
TTL deletion timing	Best-effort, not SLA-bound	Background sweeps on AWS schedule
DynamoDB Streams delivery	Simplified	Full stream semantics + Lambda wiring
Transactions across tables	Supported in recent builds	Full ACID with documented limits
Global Tables / PITR	Not available	Production features

If your test asserts throttling, TTL expiry within seconds, or stream fan-out,
run at least one suite against a disposable cloud table or LocalStack with the
features you need enabled.

A practical local workflow

Most teams wire Local into three layers:

Unit tests — spin the container in CI, create tables in beforeAll, tear down in afterAll. Keep fixtures small; marshal plain JSON through the DynamoDB JSON converter when tests paste attribute maps by hand.
Integration tests — exercise the same SDK client factory your app uses, swapping only endpoint and credentials. Assert on item shape and conditional writes, not on consumed capacity (Local does not return meaningful ConsumedCapacity for budgeting).
Manual exploration — connect DynoTable with a Local profile, stage edits, and run PartiQL or key-condition queries before you deploy schema changes.

When you outgrow a single process — multiple services, S3 triggers, or IAM-style
routing — graduate to LocalStack or a
dev account. Local stays the fastest loop for "does my access pattern compile?"

Seed data without hand-marshalling

Loading ten fixture items from a JSON file is faster when you do not tag every
value yourself. Paste the array into the
DynamoDB JSON converter, copy the marshalled
output, and batch-write with BatchWriteItem against --endpoint-url http://localhost:8000. For update-heavy fixtures, assemble the
UpdateExpression in the
DynamoDB expression builder and paste the
generated attribute maps into your test harness.

DynoTable's item editor performs the same marshalling on commit — useful when a
test failure leaves you staring at raw {"S":...} blobs in the CLI.

When to leave Local

Ship to a real table when you need any of the following measured on AWS itself:

Capacity planning — a 1 KB item queried 1,000 times per second consumes roughly 250 eventually-consistent RCU per second on on-demand billing; Local reports zero. Model that with the pricing calculator using sizes from the item-size calculator.
Index propagation lag — GSI reads are eventually consistent in production; Local returns index rows quickly enough that stale-read bugs hide until deploy.
Cross-account IAM — resource-scoped roles and condition keys only exist in the cloud.

Keep Local for fast feedback on schema and expression syntax; validate cost and
consistency assumptions against a staging table before production traffic.

Pitfalls worth scripting around

Forgotten -sharedDb — each unique credential pair gets an isolated database; CI and your laptop look like different universes.
Root-owned volume without user: root — the SQLite backend fails silently until you add the compose override from the section above.
Assuming Streams parity — stream-enabled Lambdas need a cloud or LocalStack target; Local alone will not exercise fan-out.
Empty-string keys — allowed on non-key attributes since 2020, still rejected on keys; validate fixtures the same way you would in AWS.

Download DynoTable, add a profile pointed at http://localhost:8000,
and browse the tables you just created — the same grid, filter builder, and SQL
Workbench you use in production, with zero AWS spend on the loop.

DynamoDB GSI vs LSI

DynoTable — Wed, 12 Aug 2026 09:37:09 +0000

Both a Global Secondary Index (GSI) and a Local Secondary Index (LSI) let you
Query by an attribute that isn't your table's key. They are not
interchangeable — the differences decide which one a pattern needs.

What is the difference between a GSI and an LSI in DynamoDB?

A Global Secondary Index can use any top-level scalar attribute (String, Number, or Binary) as its partition key, gets its own capacity, and can be added anytime — but only serves eventually consistent reads. A Local Secondary Index keeps the table's same partition key with a different sort key, supports strongly consistent reads and shares the table's capacity, but must be created with the table.

The differences that matter

	GSI	LSI
Partition key	Any scalar (S/N/B)	Same as the table
Sort key	Any scalar (S/N/B)	Any scalar (S/N/B)
When created	Anytime	Table-creation only
Consistency	Eventual only	Strong available
Capacity	Its own	Shares the table's
Write propagation	Async (eventual)	Synchronous (atomic)
Max per table	20 (default, raisable)	5 (hard)
10 GB partition cap	No	Yes (per PK)

A rule of thumb

Need a different partition key (e.g. look up orders by status instead of customer)? You need a GSI — an LSI can't repartition.
Need a second sort order within the same partition — an LSI keeps the table's exact partition key and only swaps in a different sort key — decided up front, with strongly-consistent reads? An LSI fits.

The choice collapses to one question — which key are you changing:

Different partition key forces a GSI; a different sort key on the same partition is the only case an LSI fits.

In practice most teams reach for GSIs almost exclusively: they're addable later,
independently scaled, and not subject to the 10 GB per-partition limit. Overload a
single GSI's keys to serve several patterns — see
single-table design.

If you're adding a GSI to kill a Scan, remember it has
its own read/write capacity. Size that extra cost with the
pricing calculator, and
try DynoTable to inspect an index's projected attributes before you
commit to it.

Worked example: open tickets by priority

Say you run a support desk. Tickets live under PK = TEAM#7 with
SK = TICKET#8842. Two access patterns compete:

Fetch one ticket by id — GetItem on the base table key.
List open tickets for the team, highest priority first — needs a different sort order than creation time.

Pattern 2 cannot be a base-table Query on SK alone because the sort key is the
ticket id, not status. Your options:

Approach	Keys	Consistency on list	When it fits
GSI with `GSI1PK = TEAM#7`, `GSI1SK = STATUS#open#P#1#TICKET#8842`	New partition + sort	Eventual	Status changes often; add index after launch
LSI with same `PK`, `LSI1SK = STATUS#open#P#1#...`	Same partition, new sort	Strong	Index planned at table creation; status reads must be fresh
Filter on base `Query`	Base keys only	Strong	Tiny partitions only — filters bill the whole partition

For a busy queue where agents refresh every few seconds, eventual consistency on
a GSI is usually acceptable. For a financial ledger line that must reflect a
status change before the API returns, serve the read from the base table or an
LSI.

Write amplification in numbers

Every base-table write propagates to each secondary index that projects the
changed attributes. A ticket update that touches status and priority on a table
with two GSIs and one LSI can fan out to four index writes plus the base write.

On on-demand billing in us-east-1, a 1 KB item write costs one WCU per
destination. Updating one attribute on that item across one GSI adds roughly one
more WCU to the request total — the
pricing calculator accepts item size and
request rate if you want a monthly line item before you add indexes.

LSIs share the table's throughput pool. A hot LSI sort key on a overloaded
partition can throttle base-table writes even when the base partition key spread
looks healthy — GSIs isolate that risk at the cost of separate capacity.

The 10 GB LSI partition ceiling

An LSI lives inside the same physical partition as its base-table partition key.
AWS documents a 10 GB per partition limit for item collections that include
LSI data. A tenant with millions of tickets under one TEAM#7 partition can hit
that ceiling while the GSI-free base table still looks fine on paper.

GSIs repartition on their own keys, so no single customer partition carries the
entire LSI payload. That repartitioning is why most production schemas default
to GSIs even when an LSI could technically serve the read.

Choosing at design time

Question	Lean GSI	Lean LSI
Need a different partition key?	Yes	No — LSI cannot
Must reads be strongly consistent?	No — GSI is eventual	Yes
Index added after table exists?	Yes	No — table creation only
Partition may grow past ~10 GB of related items?	Yes — GSI spreads	Risky on LSI
Want isolated write scaling?	Yes	No — shares table WCU

When you overload several access patterns onto one GSI, sketch the key templates
first in the single-table design tool —
it surfaces which reads share an index and flags unsupported patterns before you
pay for a backfill.

Inspect indexes before you commit

In DynoTable, open the table's index picker and run the same filter against the
base table and each GSI side by side. You see projected attributes immediately —
attributes missing from the GSI result are not in the projection — and you can
confirm whether an eventual GSI read is fresh enough for your UI.

Build the KeyConditionExpression for a candidate GSI in the
DynamoDB expression builder, then emit a
full paginated program with the
query builder to paste into a staging test.

Singleton Items in DynamoDB

DynoTable — Wed, 12 Aug 2026 09:11:23 +0000

A singleton item is a single row with a fixed, hardcoded key that holds
state for your whole application — not one record per user or per order, but
one record, period. Feature flags, a config blob, a global kill-switch:
the kind of thing a relational app would keep in a one-row settings table.

Coming from SQL, you'd reach for a config table with id = 1 and a SELECT * FROM config. In DynamoDB you do the same thing with a hardcoded partition
key — and because you always know that key, you read it with a GetItem, not
a Query or a Scan.

What is a singleton item in DynamoDB?

A singleton item is a single DynamoDB row stored under a fixed, hardcoded key that holds global state for your whole application — feature flags, a config blob, a system-wide version — rather than one record per user or order. Because you always know the key, you read it with a GetItem and update it with update plus condition expressions.

A singleton is one item with a constant key. You hardcode the PK/SK in your code (e.g. CONFIG#GLOBAL) instead of templating in a user or order id.
Read it with GetItem, never Scan. You always know the full key, so a point read has a flat, predictable cost (at most 1 RCU for a small item) — no filter, no table walk.
It's a hot key by definition. Every request can touch the same partition, so cache it and keep the item small; don't make it a write bottleneck.
Mutate it safely with update + condition expressions, not read-modify-write in your app — that's where the lost-update race lives.

Recognize the pattern

You have global state when the data isn't scoped to any one entity. A few tells:

A flag that's the same for everyone (signup_enabled = false).
A blob of tunables your app reads on boot (rate limits, default quotas).
A counter or version number for the whole system, not per-row.

Anything scoped to a user, tenant, or order is not a singleton — that's an
ordinary item keyed by that entity's id. The singleton is the leftover global
slice that has nowhere else to live.

Give it a constant key

The whole pattern hinges on one decision. The key is a literal, not a template.
For a global feature-flags item in an overloaded single table, pick a fixed
prefix and a fixed value:

PK	SK	attributes
SETTINGS#APP	FLAGS#V1	signup_enabled, maintenance_mode, ai_search_enabled

PK = "SETTINGS#APP" and SK = "FLAGS#V1" are baked into the code. There's no
user id, no tenant id — the application asks for exactly this item every time.
That predictability is the point: a known key is a GetItem, and a GetItem
is the cheapest, most consistent read DynamoDB offers.

The V1 suffix is deliberate. If the flag schema changes shape later, you write
a FLAGS#V2 item and flip readers over, instead of mutating the live one in
place. Versioning the singleton key buys you a clean migration seam.

Read it with GetItem

Because the key is fully known, you never Query and you never Scan for a
singleton. A Scan reads the whole table and filters client-side — the classic
Scan footgun — and it's absurd overkill for fetching
one row you can address directly.

A GetItem against SETTINGS#APP / FLAGS#V1 returns the flags in a single
strongly- or eventually-consistent read. On on-demand in us-east-1, AWS bills a
GetItem of an item ≤ 4 KB as 0.5 RCU eventually-consistent or 1 RCU
strongly-consistent
(AWS read/write capacity docs).
Keep the singleton small and that cost stays flat forever — bloating the config
blob into a second 4 KB block doubles the billed read.

On the read path, when the app boots or a request lands, you GetItem the fixed
key, you cache the result. The flow:

The fixed key turns a global lookup into one point read with a built-in default path.

Note the no branch: a missing singleton should never crash you. Default to the
safe value (feature off, maintenance on) so a first-deploy gap or a bad
key fails closed, not open.

Update it without a race

The trap is updating a singleton with read-modify-write in your app: you
GetItem the flags, flip one in memory, then PutItem the whole thing back.
Two concurrent writers both read the old item and the second Put clobbers the
first's change. Lost update.

Two DynamoDB features kill the race without app-side locking:

Update expressions mutate one attribute server-side, leaving the rest untouched. No need to re-Put the whole item.
Condition expressions make the write succeed only if the item still looks the way you expect, so a stale write is rejected with ConditionalCheckFailedException (AWS condition expression docs).

To flip one flag, target just that attribute with a SET and guard it with a
version bump so concurrent writers can't trample each other:

Example	Notes
`# UpdateItem`
`Key PK=SETTINGS#APP SK=FLAGS#V1`
`UpdateExpression SET signup_enabled = :on, schema_version = :next`
`ConditionExpression schema_version = :current`

If two writers race, the second one's schema_version = :current check fails
and it retries against the fresh value. You can scaffold the names, values, and
this exact expression shape in the
DynamoDB Expression Builder before wiring
it into code. For a deeper look at the operators, see the
update-expression idioms guide.

Mind the hot key

A singleton is, by construction, a hot key — every part of your app may read
the same partition. That's fine for reads if you cache, but it's the one real
risk of the pattern.

Cache aggressively. Read the flags once per process (or per N seconds), not on every request. The singleton's value is the cheapest thing to memoize.
Don't make it a write hot spot. A flag toggled by an admin a few times a day is nothing. A singleton you increment on every request is a partition-throughput bottleneck — that's a counter problem, not a singleton.
Keep it small. Read cost scales with item size in 4 KB blocks. A bloated config blob makes every boot more expensive than it needs to be.

If you genuinely need a high-write global counter, the singleton is the wrong
shape — shard it across N items and sum on read. That's a different pattern.

Singleton vs per-entity item

The line is simply what the data is scoped to.

	Singleton item	Per-entity item
Key	Hardcoded constant (`SETTINGS#APP`)	Templated with an id (`USER#42`)
How many	Exactly one	One per user / order / tenant
Typical read	`GetItem` on the known key	`GetItem` or `Query` by entity
Scope	Whole application	A single entity
Use for	Global flags, config, system version	Profiles, orders, anything per-id

If you find yourself wanting two singletons of the same kind, you don't have a
singleton — you have a per-entity item and the entity is the thing you forgot to
key by (per-tenant config, say).

Pitfalls and next steps

Don't Scan for it. You know the key; address it directly.
Don't read-modify-write it. Use update + condition expressions.
Don't let it go missing silently. Default to the safe value on a cache miss.
Don't overload it with high-frequency writes. That's a sharded-counter job.

The singleton lives comfortably inside a
single-table design — it's just one more item
collection with a fixed key alongside your entity rows.

Try DynoTable to browse your table, find the singleton row by its
fixed key, and edit flags by hand while you build the write path.

DynamoDB Single-Table Design: The Complete Guide

DynoTable — Wed, 12 Aug 2026 09:10:51 +0000

Coming from SQL, the instinct is one table per entity: customers, orders,
order_items. In DynamoDB that instinct is usually wrong. A single table that
stores every entity, distinguished by overloaded key prefixes, lets you fetch
a parent and its children in one Query — no joins, no N+1.

What is single-table design in DynamoDB?

Single-table design stores every entity — customers, orders, order items — in one
DynamoDB table, distinguished by overloaded partition key and
sort key prefixes. Because the keys are designed around your access patterns
rather than your entities, a parent and all its children live in one
item collection and come back in a single Query — no joins,
no N+1 reads.

The idea

Pick generic key names (PK, SK) and encode the entity type in the value:

PK	SK	attributes
CUSTOMER#42	PROFILE	name, email, plan
CUSTOMER#42	ORDER#2026-001	total, status
CUSTOMER#42	ORDER#2026-002	total, status

Now one Query PK = "CUSTOMER#42" returns the profile and every order in a
single billed read. SK begins_with "ORDER#" narrows it to just the orders.

Visually, the overloaded items stack under one partition key as a single item collection:

One read of the partition hands back the customer and every order together.

Start from access patterns, not nouns

Single-table design begins with a numbered list of reads and writes your application
actually performs — "show customer profile", "list open orders for customer",
"lookup order by id globally" — not with an ER diagram of entity boxes. Each pattern
must compile to a Query or GetItem on the base table or on an overloaded GSI.
If a pattern needs a Scan, the keys are wrong; fix the model before shipping.

Write the list down explicitly. A three-pattern app might look like:

Fetch customer + all orders for one customer id (high volume).
List all open orders across customers, sorted by date (moderate volume).
Fetch one order by its public order id (high volume).

Pattern 1 is a base-table Query on PK = CUSTOMER#<id>. Pattern 2 lands on
GSI1PK = STATUS#OPEN with GSI1SK as the date. Pattern 3 might use
PK = ORDER#<id>, SK = METADATA as a separate item collection from pattern 1's
CUSTOMER#<id> / ORDER#<id> rows — duplicate the order summary twice if both
access paths are hot, or accept a second Query when one path is rare.

The free Single-Table Design tool accepts
that pattern list and emits a PK/SK/GSI layout with example items, CreateTable JSON,
and per-pattern cost hints so you can compare alternatives before committing.

Overloaded GSIs

The same trick works on indexes. Put a generic GSI1PK/GSI1SK on items, and a
single GSI serves multiple access patterns depending on what each item writes
into those attributes:

PK	SK	GSI1PK	GSI1SK
ORDER#001	METADATA	STATUS#OPEN	2026-01-04
ORDER#002	METADATA	STATUS#OPEN	2026-01-05

Now Query GSI1 WHERE GSI1PK = "STATUS#OPEN" lists open orders by date — a
pattern the base table can't answer. A different entity can reuse GSI1 with its
own meaning (e.g. CATEGORY#books). One index, many queries.

Many-to-many: the adjacency list

For relationships (a user in many teams, a team with many users), write the edge
twice with the ids swapped: PK=USER#1, SK=TEAM#9 and PK=TEAM#9, SK=USER#1.
Querying either side lists the other — the DynamoDB stand-in for a join table.

Read cost: one Query vs many GetItems

The billing win is real when children live under the parent's partition key. Suppose
a customer profile (1 KB) and twelve order summaries (1 KB each) share
PK = CUSTOMER#42. One eventually-consistent Query on that partition reads
13 KB total → 2 read request units (13 KB rounds up to four 4 KB blocks at 0.5
RCU each). Fetching the same thirteen items with thirteen GetItem calls meters
the same per-item rounding individually → 7 units (thirteen × 0.5 RCU minimum
one block per item). Same data, more than triple the read units — before network
round trips.

Access style	Round trips	Read units (13 × 1 KB items, EC)
`Query PK = CUSTOMER#42`	1	2
13 × `GetItem` by full primary key	13	7
`Scan` + filter on customer id	1+ pages	whole table

Numbers shift with item size — profile blobs at 6 KB each cross two 4 KB blocks
per item — which is why the
item-size calculator sits next to the design
tool. Writes obey a 1 KB rounding boundary (one WCU per kilobyte, doubled inside
transactions); fat order rows cost more to denormalize onto the parent partition.

Entity typing and sparse indexes

Most teams add a string type or entity attribute (CUSTOMER, ORDER, LINE)
so application code can branch when a Query returns mixed sort-key prefixes.
GSIs can be sparse: only items that populate GSI1PK/GSI1SK appear on the
index, so a customer profile row with those attributes empty does not consume index
storage or show up in unrelated queries.

When two entity types share an index, document what each prefix means (STATUS#,
CATEGORY#, EMAIL#) in the same place you document the base-table prefixes.
Future you should not have to reverse-engineer meaning from CloudWatch graphs alone.

When not to single-table

It isn't free. One overloaded table is harder to reason about, harder to evolve,
and analytics-hostile. If your access patterns are genuinely unknown or change
constantly, or the data is mostly analytical, separate tables (or a different
store) can be the saner call. Single-table wins when the patterns are known and
high-volume.

Signal	Lean separate tables	Lean single-table
Access patterns documented and stable		✓
Many unrelated domains with no shared reads	✓
Team new to DynamoDB, needs obvious table names	✓
Parent + children fetched together constantly		✓
Heavy ad-hoc analytics across arbitrary joins	✓ (or warehouse)
Hot multi-entity dashboard on one partition key		✓

Regulatory or organizational boundaries (different data owners, distinct backup
policies) can also justify multiple tables even when a single-table model fits
access patterns technically.

Cost of the wrong shape

Modelling as separate tables forces a Scan or client-side join to reassemble a
customer, and that is the Scan footgun. Model the access
patterns first, then design keys to make each one a Query. (For the ad-hoc
cross-entity question you never modeled for, DynoTable's SQL
Workbench runs the JOIN client-side — exploration
doesn't have to wait for a re-model.)

Evolving a live single-table layout usually means adding GSIs or new item
types, not renaming PK/SK semantics in place. Treat prefix contracts like API
versions: add ORDER#v2# rather than repurpose ORDER# mid-flight. Migrations
that rewrite every item's keys belong in a controlled backfill with dual-write
periods, not in a Friday-afternoon script.

Sketch the design itself with the free
Single-Table Design tool — it turns your
access-pattern list into a PK/SK/GSI plan with example items and cost hints.
Estimate what these items cost per read with the
item-size & capacity calculator, and
compose the resulting Query programs in the
query builder when you're ready to ship SDK code.
Read composite primary keys if partition +
sort key mechanics still feel fuzzy — single-table design is mostly disciplined
composite-key usage with shared attribute names.

Try DynoTable to browse a single-table schema and see the overloaded
collections side by side — partition inspector view lines up sort-key order with
the access patterns you sketched.

Why a DynamoDB Scan Is Slow and Expensive

DynoTable — Wed, 12 Aug 2026 09:10:49 +0000

A Scan reads every item in the table and only filters afterward. It is
the operation you reach for out of SQL muscle memory, and the one that quietly
runs up your bill while making your latency worse than the RDS box you left.

Why is my DynamoDB Scan slow and expensive?

A Scan reads every item in the table before the FilterExpression runs, so
you pay to read the whole table no matter how few rows come back, and it gets
slower as the table grows. The fix is almost always a keyed Query — model the
access pattern around a key so DynamoDB touches one partition instead of
everything.

A Scan reads the whole table, every time. Size, not your result count, decides what you pay and how long it takes.
The FilterExpression is a lie about cost. It runs after the read is metered, so returning 12 items can bill for reading 12 million.
A Scan gets slower as you grow. A keyed Query stays flat — it touches one partition no matter how big the table gets.
The fix is almost always modeling, not tuning. If you Scan to answer a routine question, you are missing a key.

What a Scan actually does

Coming from SQL, SELECT * FROM events WHERE type = 'checkout' feels free —
the engine has an index, or it doesn't, but either way you get rows back. In
DynamoDB there is no query planner deciding that for you.

A Scan walks the entire table sequentially, 1 MB at a time, and hands each
page to your FilterExpression. Whatever the filter rejects is still read,
still metered, and still on your bill. (AWS: Scanning tables)

That is the trap. The filter looks like a WHERE clause, but it changes the
result set, never the cost. A Scan consumes the same read capacity whether or
not a filter is present. (AWS: Scanning tables)

Count the read units

DynamoDB meters reads in read capacity units (RCUs). One RCU buys a single
strongly consistent read of an item up to 4 KB; eventually consistent reads
cost half that. Bigger items round up to the next 4 KB. (AWS: Read/write
capacity mode)

Take an analytics table, ProductEvents. Each row is one tracked event:

PK  = "TENANT#acme"
SK  = "TS#2026-06-23T14:08:55Z#evt_9f3a"
attrs: eventType, sessionId, userId, payloadBytes

Say it holds 2,000,000 events, each ~1 KB, all under one busy tenant. You
want today's checkouts. The reflexive move:

Example	Notes
`Scan ProductEvents`
`FilterExpression: eventType = "checkout"`

That filter might return 40 rows. But the Scan read all 2,000,000 items
first. At ~1 KB each (1 RCU per 4 KB, eventually consistent ≈ 0.5 RCU per 4 KB),
you metered roughly 250,000 RCUs — and paged through ~2 GB of data — to
hand back 40 items.

Now model the access pattern as a key and Query it instead:

Example	Notes
`Query ProductEvents`
`PK = "TENANT#acme"`
`AND SK begins_with "TS#2026-06-23"`

This reads only the matched slice of one partition. If those 40 checkout rows
plus the day's other events come to ~2 MB, you pay for ~2 MB of reads, not
2 GB. Same answer, a tiny fraction of the cost — and the latency stays flat
as the table grows.

Scan vs Query, metered

	Scan + filter	Keyed Query
Reads	Every item in the table	One partition, narrowed by SK
Billed capacity	Whole table, before the filter	Only the items in your slice
Our example	~250,000 RCUs (~2 GB)	a few hundred RCUs (~2 MB)
Latency	Grows with table size	Flat as the table grows
Result count	Decides nothing about cost	Matches what you pay for

On a Scan, your result count and your bill are
unrelated. On a Query, they track each other.

Decide before you Scan

Most accidental Scans come from one question: can I name the partition I
need? If yes, it is a Query. If no, the fix is a key, not a bigger filter.

Here is the decision in flow form.

The path almost always ends at Query; you only fall through to Scan when no
key — present or addable — fits the access pattern.

If the pattern is real and recurring but the base table can't key it, that is
the signal to add a Global Secondary Index so the question
becomes a Query. Modeling your keys around your access patterns up front is
the whole game — see single-table design.

Write the keyed query, not a filter

When you do need a condition beyond the key, build it deliberately rather than
dumping everything into a FilterExpression. The
DynamoDB Expression Builder generates the
KeyConditionExpression and attribute placeholders for you, so the partition
and sort key do the narrowing — before DynamoDB meters the read, not after.

Example	Notes
`KeyConditionExpression: PK = :tenant AND begins_with(SK, :day)`

When a Scan is actually fine

A Scan is the wrong default for routine queries. It's the right tool when
you genuinely mean "read everything":

One-off exports or backfills run by hand.
Tiny config / lookup tables where the whole table is a few KB.
Background jobs that page the full table on purpose. Split those across workers with Segment / TotalSegments — a parallel scan — instead of one long sequential crawl. (AWS: Scanning tables)

And note PartiQL doesn't save you: SELECT * FROM ProductEvents WHERE eventType = 'checkout' with no key predicate compiles straight to a Scan.
It's the same footgun in SQL clothing. (See Query vs Scan
for the full breakdown.)

When you truly need cross-item analytics — a GROUP BY, a JOIN, an aggregate
DynamoDB can't express — DynoTable's SQL Workbench runs them client-side over a
bounded result set, instead of hammering the table with a full Scan.

Next steps

Estimate what either pattern costs with the
pricing calculator, read
Query vs Scan for the API-level contrast, and
download DynoTable to run these against your own tables and watch
how many items each approach actually reads.

DynamoDB ReturnValues: Get the Old or New Item

DynoTable — Tue, 11 Aug 2026 09:45:44 +0000

By default a DynamoDB write returns nothing but success. But you often need the data
around the write — the value before you changed it, or the fresh value after. The
naive fix is a second GetItem, which is an extra round trip and a race: someone
else can write in between. DynamoDB avoids both with the ReturnValues parameter,
which hands back the old or new item atomically as part of the write itself.

What does ReturnValues do in DynamoDB?

ReturnValues tells a DynamoDB write to hand back the item as part of the same call, so you skip a second GetItem and the race it creates. PutItem and DeleteItem accept NONE or ALL_OLD; UpdateItem accepts all five (NONE, ALL_OLD, UPDATED_OLD, ALL_NEW, UPDATED_NEW), returning old or new values atomically.

ReturnValues returns the item as part of the write — no second read, no race.
NONE (default) — return nothing.
ALL_OLD — the entire item as it was before the write.
UPDATED_OLD — only the attributes the update changed, before values.
ALL_NEW — the entire item after the write.
UPDATED_NEW — only the changed attributes, after values.
PutItem/DeleteItem accept only NONE or ALL_OLD; UpdateItem accepts all five.

The problem: you need the value you just overwrote

Say you run a support desk and an agent changes a ticket's status from open to
pending. Your audit log needs to record what the status was before the change.
Without ReturnValues you'd:

GetItem to read the current status,
UpdateItem to set the new one.

Between steps 1 and 2 another agent could change the status — now your audit log records
a stale "before" value. Worse, it's two calls for one logical operation. ReturnValues
collapses it into a single atomic UpdateItem that returns the old status as it
actually was at write time.

The five options, and when to use each

UpdateItem supports the full set; the choice is what slice of the item and which
side of the write you need:

`ReturnValues`	Returns	Use when
`NONE`	nothing	you don't need the item back (default)
`ALL_OLD`	whole item, pre-write	auditing / "what did I just replace?"
`UPDATED_OLD`	changed attrs, pre-write	you only care about the fields you touched
`ALL_NEW`	whole item, post-write	you need the fresh full item to return to a caller
`UPDATED_NEW`	changed attrs, post-write	reading back a counter/value you just incremented

UPDATED_NEW is the everyday hero: increment a counter with an
update expression and read the new total back in
the same call, no race. For the support-ticket audit, ALL_OLD (or UPDATED_OLD if
you only log the status field) captures the pre-change state atomically.

Note the asymmetry: PutItem and DeleteItem only support NONE and ALL_OLD —
there's no "new" value to return for a delete, and a put's new value is just what you
sent. Only UpdateItem, which mutates in place, offers all five.
AWS documents
the exact matrix.

Writing the update in DynoTable

Assemble the UpdateItem and its update expression visually with the
DynamoDB expression builder — it emits the
SET/ADD clause plus the attribute-name and value maps. In the app, DynoTable
shows the resulting item after a staged write is committed, so you see the new state
directly.

Pitfalls + next steps

Don't GetItem-then-write to read around a change — it's a round trip and a race; use ReturnValues.
UPDATED_* returns only touched attributes — if you need the whole item, use ALL_*.
PutItem/DeleteItem can't return new values — only NONE/ALL_OLD.
ReturnValues is not a substitute for a condition — to guard a write, add a condition expression; to read back its effect, use ReturnValues. They compose.
Related: update expressions, atomic counters.

Want to make edits and see the before/after without scripting two calls?
Download DynoTable and edit your items directly.

Atomic counter with `UPDATED_NEW`

Inventory systems increment a version or stock field on every write. The
pattern is one UpdateItem with ADD stock :inc and ReturnValues: UPDATED_NEW:

UpdateItem  PK=SKU#8842
  UpdateExpression: ADD stock :one
  ExpressionAttributeValues: {":one": {"N": "1"}}
  ReturnValues: UPDATED_NEW
→ Attributes.stock.N == "41"   (was 40)

You receive only the changed attribute map, not the full item — ideal when the
item is large but the caller needs the new counter. For audit trails that must
capture every field before change, switch to ALL_OLD.

The write still bills as an UpdateItem on the item's size; ReturnValues does
not add a separate read charge — DynamoDB already loaded the item to apply the
update.

Capacity note

Returning attributes does not double the WCU cost of the write itself. You pay
for the write based on the item size before and after the update per AWS
rules, independent of how many attributes appear in the response payload.

If you were tempted to GetItem then UpdateItem to log the old value, you
paid for a read plus a write. ReturnValues: ALL_OLD on the update removes the
read entirely — on a 2 KB item at 500 updates per second that saves roughly
250 eventually-consistent RCU per second.

Compose with condition expressions

ReturnValues and
condition expressions compose on the
same call. Example: increment retryCount only while below a cap, and return the
new count:

ConditionExpression: retryCount < :max
UpdateExpression: ADD retryCount :one
ReturnValues: UPDATED_NEW

If the condition fails, DynamoDB returns ConditionalCheckFailedException and
no attribute payload — distinct from a successful update with an empty
UPDATED_NEW when nothing changed.

Use the expression builder to generate the
UpdateExpression, condition, and marshalled value maps together.

Decision guide

You need…	Setting	Works on
Nothing back	`NONE`	Put, Update, Delete
Full item before overwrite/delete	`ALL_OLD`	Put, Update, Delete
Only changed fields, before	`UPDATED_OLD`	Update
Full item after patch	`ALL_NEW`	Update
Only changed fields, after	`UPDATED_NEW`	Update

Deletes and puts

DeleteItem with ReturnValues: ALL_OLD is how you implement "pop and return"
semantics on a queue item — the deleted row comes back in Attributes. There is
no ALL_NEW on delete because the item no longer exists.

PutItem with ALL_OLD returns the previous item when you overwrite an existing
key — useful for swap workflows. When the key did not exist, the response omits
Attributes.

Verify in DynoTable

Stage an attribute change in the item editor: the review pane shows old and new
values side by side before commit — the same information UPDATED_OLD and
UPDATED_NEW would return, without writing a script. After commit, copy the row
as JSON for test fixtures via the grid's export actions.

How DynamoDB Request Routing Works

DynoTable — Tue, 11 Aug 2026 09:45:11 +0000

Every read or write you send hits a fleet of stateless request routers first.
A router hashes your partition key, maps the hash to the storage node that owns
that key's data, and forwards the request there. That one hop is why a key lookup
costs the same whether the table holds a thousand items or a billion.

How does DynamoDB request routing work?

DynamoDB routes every request through a stateless request router fleet that hashes your partition key, maps the hash to the single storage node owning that partition, and forwards the read or write there. Routing is a pure function of the key's hash, so one lookup costs the same whether the table holds a thousand items or a billion.

The request router is the front door. It's a stateless fleet that takes your request, hashes the partition key, and routes it to the storage node holding that partition — no scanning, no full-table knowledge needed.
The partition key decides everything. Routing is a pure function of the partition key's hash — the same key always routes to the partition that owns it, so GetItem is O(1), not O(table size).
One primary, two secondaries. A write lands on the partition's primary node, which acknowledges once a quorum (two of the three replicas) has persisted it.
Bad keys defeat the design. A low-cardinality or "hot" partition key funnels traffic to one node — the routing is fine, your key is the problem.

Start with the problem routing solves

Coming from SQL, you picture a query planner: it reads statistics, picks an index,
maybe scans. The cost scales with how much data it touches. That model doesn't fit
a key-value store that has to answer in single-digit milliseconds at any size.

DynamoDB's answer is to make a single-item lookup a direct address, not a
search. The partition key is the input to a hash function that computes where the
data physically lives — not a column you filter on. No statistics, no planner.

That's the trade you accept when you move off relational thinking: you give up
ad-hoc query flexibility and get constant-time addressing in return.

Meet the request router

When a request arrives, it doesn't go straight to storage. It hits a request
router — a stateless, horizontally scaled fleet that fronts the whole service.
(The USENIX ATC '22 DynamoDB paper describes this request-router fleet.)

The router does three things and holds no data of its own:

Authenticates and authorizes the request against IAM.
Hashes the partition key to find the partition that owns it.
Forwards the request to the storage node for that partition.

Because routers are stateless, the service adds more of them under load. None of
them is a bottleneck and none is a single point of failure — the same property the
2007 Amazon Dynamo paper
built the original system around.

Follow one read through the router

Take a telemetry table for a drone fleet. Items are keyed by DroneId (partition
key) and ReadingTs (sort key), with attributes like BatteryPct and AltitudeM.

You ask for one drone's readings from June 23:

Example	Notes
`PK = "DRONE#A19F"`
`SK begins_with "2026-06-23"`

The diagram below traces the request top to bottom — read it as one downward flow.

The router hashes DRONE#A19F, maps it to the partition that owns that key, and
forwards the read to that partition's primary storage node, which returns the item.

The hash points at one partition out of however many the table
has. The router never looks at other partitions, so adding drones — and partitions
— doesn't slow this lookup down.

Know what a partition actually is

A partition is a unit of storage and throughput. Each one is capped (roughly
10 GB and a fixed slice of read/write capacity), and DynamoDB splits a partition
when it outgrows either limit. Every item with a given partition key starts on one
partition; split-for-heat can later carve that collection by sort-key range (unless
an LSI or a monotonic sort key pins it), which is what still makes a Query over
one partition key cheap.

Each partition is replicated to three storage nodes spread across Availability
Zones: one primary and two secondaries.

Node role	Handles	Consistency it can serve
Primary	All writes; strongly-consistent reads	Strong (sees its own latest write)
Secondary	Eventually-consistent reads; failover	Eventual (may lag the primary)

A write goes to the primary, which acknowledges the write once a quorum (two of the
three replicas) has persisted it. A strongly consistent read is routed to the primary
so it reflects the latest write. An eventually consistent read may be served
by a secondary that hasn't caught up yet — half the cost, possibly stale.

Name the footgun: a hot partition key

Routing is only as good as your partition key. The hash spreads keys evenly, so if
your keys have high cardinality and even traffic, load spreads across all
nodes. Break either property and you get a hot partition.

Say you key that telemetry by Region instead of DroneId. Now every drone in
us-east-1 shares one partition key — so their reads and writes hash to the same
keyspace slot and pile onto one item collection. The router is doing its job
perfectly; you've just funneled the whole fleet at a single partition's capacity.

Warning

A hot key is a modeling bug, not a routing bug. The fix is a higher-cardinality
partition key (or a write-sharding suffix), not more capacity.

You can't watch the router pick a node, but you can design keys that route well.
When you build a key condition in the
Expression Builder, the partition key you put
on the left of PK = … is the exact value the router will hash — keeping that
value high-cardinality is what keeps reads on separate nodes.

How this ties back to your access patterns

Request routing is the mechanism that makes the single-table design
rules non-negotiable: you model around the partition key because the partition key
is the address. It's also why a Query beats a Scan —
a Query hits one partition through the router, while a Scan walks every
partition in sequence.

Secondary indexes get their own partitions and their own routing: a
GSI is routed by its own partition key, independent of the
base table's, which is why a GSI can be hot even when the table isn't.

Next steps

Design keys that route to many nodes, not one. Sketch the PK = … condition in the
Expression Builder to see exactly which value
gets hashed, then download DynoTable to run those queries against your
own tables and see exactly what each key condition returns.

DEV Community: DynoTable

Why we hand-wrote a PartiQL parser for DynamoDB

Regex was fine, until it wasn't

Nobody had built one

Swapping the engine without breaking the plane

The bugs that only garbage finds

A test suite you can audit against AWS's docs

What transfers if you're building one

DynamoDB Sparse Indexes

What is a sparse index in DynamoDB?

The problem: filtering doesn't save reads

How sparseness works

A worked example: "open tickets only"

Do it in DynoTable

Pitfalls and next steps

DynamoDB Sort Key Strategies: 3 Patterns and When to Use Each

How do DynamoDB sort keys work?

Why the sort key is the lever

Strategy 1: make the sort key sortable

Strategy 2: composite sort keys for hierarchy

Strategy 3: control direction with ScanIndexForward

Worked example: an actor-scoped audit log

Do it in DynoTable

Pitfalls and next steps

PartiQL for DynamoDB by Example

How do you write PartiQL queries for DynamoDB?

SELECT

INSERT

UPDATE

DELETE

Querying an index

Parameterized statements

Batch and transactions

PartiQL vs Workbench SQL

The PartiQL footgun

DynamoDB Pagination: LastEvaluatedKey Explained (w/ Examples)

How does pagination work in DynamoDB?

Limit is not a page size

Let the SDK paginate

No page numbers

Stateless cursors for APIs

Pick a pagination strategy

Capacity adds up across pages

Build and inspect the loop

How to Run DynamoDB Local with Docker — Complete Guide

How do I run DynamoDB Local with Docker?

Start the container

docker-compose

Persistence

Point the SDK at it

Create a table

Browse it with a GUI

What Local does not emulate

A practical local workflow

Seed data without hand-marshalling

When to leave Local

Pitfalls worth scripting around

DynamoDB GSI vs LSI

What is the difference between a GSI and an LSI in DynamoDB?

The differences that matter

A rule of thumb

Worked example: open tickets by priority

Write amplification in numbers

The 10 GB LSI partition ceiling

Choosing at design time

Inspect indexes before you commit

Related reading

Singleton Items in DynamoDB

What is a singleton item in DynamoDB?

Recognize the pattern

Give it a constant key

Read it with GetItem

Update it without a race

Mind the hot key

Singleton vs per-entity item

Pitfalls and next steps

DynamoDB Single-Table Design: The Complete Guide

What is single-table design in DynamoDB?

The idea

Start from access patterns, not nouns

Atomic counter with `UPDATED_NEW`