DynamoDB Expression Attribute Names and Values
DynamoDB expressions are templates: you write placeholders, then supply the real
attribute names and values in two side maps. Coming from SQL, where
WHERE status = 'published' inlines both, this is the first thing that breaks.
What is the difference between #name and :value in DynamoDB?
#name is a placeholder for an attribute name, supplied through ExpressionAttributeNames; :value is a placeholder for an attribute value, supplied through ExpressionAttributeValues. Use #name to dodge reserved words and special characters, and :value for every literal, because DynamoDB never inlines values. A placeholder missing from its map fails loud; a value written as a mapped #name fails quietly.
- Values are never inline. Even a plain number gets a
:placeholder, typed in the value map. - Names need a placeholder only sometimes. A reserved word, a name that
doesn't start with an ASCII letter, or any character besides ASCII letters,
digits and
_(a dot, a space, a hyphen) forces one; aliasing every name is the safe habit. - A swap isn't always loud. A
#key in the value map is aValidationException, but a#publishedmapped as a name is a valid attribute reference that matches nothing.
Why the two maps exist
In SQL the query string carries everything: column names, literals, operators. DynamoDB deliberately separates the shape of the expression from its data.
Values go in their own map so DynamoDB can type each one (S, N, BOOL, …)
and so the parser never has to guess where a string ends. There is no quoting
or escaping to get wrong. See data types in DynamoDB for
the full type-tag list.
Names get the same treatment for a different reason: DynamoDB has a long list of reserved words, and any attribute matching one cannot appear as a bare name in an expression. The placeholder dodges the reservation entirely.
The reserved-word trap
Here is a CMS articles table (partition key BLOG#<blog>, sort key
ARTICLE#<slug>) whose attributes read naturally but happen to collide with
reserved words:
| Attribute | Reserved? | What it holds |
|---|---|---|
status | yes | draft / published |
name | yes | author display name |
size | yes | rendered byte length |
ttl | yes | archive expiry (epoch) |
slug | no | URL slug |
status, name, size, and ttl are all on AWS's reserved-words list, so this
filter fails on the first word:
FilterExpression status = :s
DynamoDB returns a ValidationException: "Attribute name is a reserved
keyword; reserved keyword: status". The fix is a name placeholder:
FilterExpression #status = :s
ExpressionAttributeNames { "#status": "status" }
ExpressionAttributeValues { ":s": { "S": "published" } }
slug is not reserved, so a query you tested against slug works, and you
assume the next one will too. Then status breaks it. The list runs to 573
words, so don't memorize it: placeholder every name and you never get bitten.
Map every value, always
Values are non-negotiable: there is no syntax for an inline literal. Even a plain number gets a placeholder. This update marks an article published, stamps its size, and sets a TTL 30 days out:
UpdateExpression: SET #status = :s, #size = :sz, #ttl = :exp
ExpressionAttributeNames: { "#status": "status", "#size": "size", "#ttl": "ttl" }
ExpressionAttributeValues: {
":s": { "S": "published" },
":sz": { "N": "20480" },
":exp": { "N": "1794096000" }
}
:exp is the publish time plus 30 days in epoch seconds
(Math.floor(Date.now() / 1000) + 30 * 86400); the value shown is
2026-11-08T00:00:00Z.
Once TTL is enabled on ttl and the time passes,
DynamoDB deletes the item, typically within a few days. To archive it, consume the TTL delete from
DynamoDB Streams and write the old image to S3.
:sz and :exp are sent as N strings, because DynamoDB's number type is
wire-encoded as a string.
Both maps belong to one request, so a value is shared only inside it: define :s once and use it in both the UpdateExpression and the
ConditionExpression of one UpdateItem (SET #status = :s guarded by
#status <> :s).
The Expression Builder generates the expression string and both maps together, with the type tags filled in, so the placeholders can't drift out of sync.
The one below queries the BLOG#eng articles and filters on status = published;
watch it alias every name in the ExpressionAttributeNames map, status included
as #filter0:
dynamodb-expression-builder is the open-source (MIT) library behind this tool.
Names for nested and awkward paths
The # placeholder does more than dodge reserved words. Document-path syntax uses
dots and brackets, so an attribute that literally contains a dot, say a metadata
key og.title, is unaddressable without a placeholder:
ProjectionExpression #og
ExpressionAttributeNames { "#og": "og.title" }
Without it, DynamoDB reads og.title as "the title field inside the og map",
a different thing entirely. Same story for names with spaces, hyphens or leading digits.
For nesting, you placeholder each segment: #meta.#author with both #meta and
#author defined.
Names vs values, side by side
#name | :value | |
|---|---|---|
| Substitutes | an attribute name | an attribute value |
| Map | ExpressionAttributeNames | ExpressionAttributeValues |
| Prefix | # | : |
| Needed for | reserved words, ., -, spaces | always (no inline literals) |
| Undefined, unused, or in the wrong map | ValidationException | ValidationException |
The quiet failure is the # that should have been a :. Map #published to
published in ExpressionAttributeNames and #status = #published is a valid
filter comparing two attributes: no error, and no match on an item without a
published attribute.
If a filter that should match returns nothing, check that every operand you
meant as a value starts with :.
Pitfalls and next steps
- Declaring a placeholder you don't use. DynamoDB rejects unused entries in either map, so a clause you drop can leave its value behind and fail the call. Build the maps from the expression, not ahead of it; the builder keeps them in lockstep.
- Assuming a name is safe because it worked once. Reserved-word collisions are per-attribute. Placeholder uniformly and stop guessing.
Every expression type uses these maps: see them at work in condition expressions, update expressions, key condition expressions and projection expressions.

Generate the expression plus both maps with the Expression Builder. In DynoTable, the visual filter builder writes the placeholders for you when it compiles your key conditions and filters.


