Intermediate5 min read

DynamoDB Expression Attribute Names and Values

DynamoDB expressions are templates: you write placeholders, then supply the real 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 a ValidationException, but a #published mapped 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:

AttributeReserved?What it holds
statusyesdraft / published
nameyesauthor display name
sizeyesrendered byte length
ttlyesarchive expiry (epoch)
slugnoURL 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 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:

Build your request
Generated code
new QueryCommand({
  "TableName": "Articles",
  "KeyConditionExpression": "#hashKey = :hashKeyValue",
  "FilterExpression": "#filter0 = :filterValue0",
  "ExpressionAttributeNames": {
    "#hashKey": "PK",
    "#filter0": "status"
  },
  "ExpressionAttributeValues": {
    ":hashKeyValue": {
      "S": "BLOG#eng"
    },
    ":filterValue0": {
      "S": "published"
    }
  }
})

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
Substitutesan attribute namean attribute value
MapExpressionAttributeNamesExpressionAttributeValues
Prefix#:
Needed forreserved words, ., -, spacesalways (no inline literals)
Undefined, unused, or in the wrong mapValidationExceptionValidationException

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.

DynoTable's filter builder on the articles table: a status = published filter on the BLOG#eng partition.
DynoTable's filter builder on the articles table: a status = published filter on the BLOG#eng partition.

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.

By Dmitriy · Updated