Beginner6 min read

DynamoDB Projection Expressions

A projection expression is the SELECT col1, col2 of DynamoDB: a comma-separated list of names that tells GetItem, Query, or Scan to return only those attributes instead of the whole item.

Do DynamoDB projection expressions reduce read cost?

No. A ProjectionExpression trims the response payload, not the read capacity you're billed. DynamoDB reads the full item, meters the on the item's full size, then drops the attributes you didn't name on the way out. To cut read cost, use a covering instead.

  • It is not an access control. The caller picks the projection, and a read without one returns every attribute. IAM conditions on dynamodb:Attributes and dynamodb:Select enforce what a role may read.
  • Use #name placeholders for anything that might be reserved. Plain attribute names in the expression collide with DynamoDB's ~570 reserved words and fail the request.
  • For read savings, use a covering index instead. A that projects only the attributes you need is read at its own (smaller) size.

What it actually saves

Coming from SQL, you'd assume SELECT a, b scans less than SELECT *. In DynamoDB that intuition is wrong.

A read's capacity is computed from the item's full size, rounded up to 4 KB per item for GetItem or on the summed size for a Query or Scan, before the projection is applied (check a size with the item-size calculator). AWS is explicit: a ProjectionExpression does not change the read capacity a request consumes.1

So a projection saves you two things, both downstream of the read:

  • Bytes over the wire. A 6 KB item returned as two small attributes is a tiny response. On a Query that returns hundreds of items, that adds up fast.
  • Client-side work. Less to deserialize, less to hold in memory, less to leak into a log or an API response by accident.

What it does not save is the RCU. A projection never lowers the bill, because the read is metered before the projection runs. If you added one and the number didn't move, that is the documented behavior.

Project a public user profile

Say you run a user directory. Each profile is one item, keyed so you can fetch a person by handle:

PK = "PROFILE#ada"      (partition key)
SK = "PROFILE#ada"      (sort key, single-item collection)

The item is fat. It carries the public face of the account plus a pile of private and operational attributes:

{
  "PK": "PROFILE#ada",
  "SK": "PROFILE#ada",
  "displayName": "Ada L.",
  "avatarUrl": "https://cdn.example.com/u/ada.png",
  "bio": "Builds things.",
  "emailAddress": "ada@example.com",
  "passwordResetToken": "…",
  "billingCustomerId": "cus_…",
  "lastLoginIp": "…",
  "internalRiskScore": 0.02
}

A public profile card needs three fields. Fetching the whole item means emailAddress, lastLoginIp, and internalRiskScore travel to a context that should never see them. Name only the public subset:

GetItem  PK = "PROFILE#ada"  SK = "PROFILE#ada"
ProjectionExpression: displayName, avatarUrl, bio

The response carries three attributes. The private ones are never serialized into it, so this code path can't leak them into a log or a downstream API.

That protects your code, not the table. Any caller allowed to GetItem can drop the projection and read everything.

To enforce the boundary, use an IAM policy: dynamodb:Attributes lists the attributes a role may request, and dynamodb:Select set to SPECIFIC_ATTRIBUTES forces every read to name them.

That holds for GetItem too, though it takes no Select parameter: AWS applies the key to every operation that returns item attributes, and a read that names none counts as ALL_ATTRIBUTES. On a read-only role, write the condition as StringEquals, as AWS's read-only variant does, not StringEqualsIfExists.

Without the Select condition, a read with no projection still returns the whole item. (AWS: fine-grained access control)

The DynamoDB Expression Builder emits the ProjectionExpression, its ExpressionAttributeNames map, and the SDK call. The preset below is the profile-card GetItem above; add or remove fields to watch the ProjectionExpression change:

Build your request
Generated code
new GetItemCommand({
  "TableName": "Profiles",
  "Key": {
    "PK": {
      "S": "PROFILE#ada"
    },
    "SK": {
      "S": "PROFILE#ada"
    }
  },
  "ProjectionExpression": "#proj0, #proj1, #proj2",
  "ExpressionAttributeNames": {
    "#proj0": "displayName",
    "#proj1": "avatarUrl",
    "#proj2": "bio"
  }
})

dynamodb-expression-builder is the open-source (MIT) library behind this tool.

Escape reserved words with # placeholders

A projection naming a reserved word such as status is rejected,2 so alias it with an expression attribute name. Nested paths take a placeholder per segment, and a list element takes an index:

ProjectionExpression       displayName, #s, #addr.#city, tags[0]
ExpressionAttributeNames   { "#s": "status", "#addr": "address", "#city": "city" }

Expression names and values covers the mechanics, and the reserved-words checker flags the collisions in a list of names and emits the alias map.

When a covering index beats a projection

To cut read cost, not just payload, use a Global Secondary Index that projects only the attributes you read. A Query against it is metered at the index entry's smaller size.3

For the profile card, that is a GSI keyed on the same PK with Projection: { ProjectionType: "INCLUDE", NonKeyAttributes: ["displayName", "avatarUrl", "bio"] }.

Two catches. GetItem can't read a GSI, so the lookup becomes a Query on the index. And GSI reads are eventually consistent only, so a just-saved profile can read stale for a moment (when a GSI read can be stale).

ProjectionExpressionCovering GSI
Cuts payloadYesYes
Cuts read costNoYes, read at the index's size
Extra storageNoneA second copy of the projected fields
Extra write costNoneWrites propagate to the index
Best forTrimming responses; small winsHot reads of a few fields from big items

The index costs you storage and write capacity to save read capacity: worth it for a frequent read of a thin slice from a heavy item, not for a one-off GetItem.

Index projections weighs KEYS_ONLY, INCLUDE and ALL. Without an index, split the fat item into a small public item and a private item, and read only the one you need.

Pitfalls and next steps

  • Don't expect a smaller bill. A projection alone never changes RCU. If the number didn't move, that's the documented behavior, not a bug.
  • Placeholder reserved words. A bare name or status in the expression fails the request, so #-map it.
  • Include the key attributes if you'll re-fetch or update the item. Paging doesn't need them: LastEvaluatedKey comes back whatever you project.
  • Reach for a covering index only when a hot pattern reads a few fields from large items; weigh the write and storage cost first.
A PartiQL SELECT of the three public profile fields in DynoTable.
A PartiQL SELECT of the three public profile fields in DynoTable.

The projection trims what a key condition already read. Build the ProjectionExpression and its attribute-name map in the Expression Builder. In DynoTable, run the same column list as a PartiQL SELECT displayName, avatarUrl, bio.


  1. AWS DynamoDB Developer Guide, Using projection expressions in DynamoDB: read capacity is based on item size before any ProjectionExpression is applied. https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html ↩
  2. AWS DynamoDB Developer Guide, Reserved Words in DynamoDB. https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html ↩
  3. AWS DynamoDB Developer Guide, Attribute Projections (KEYS_ONLY / INCLUDE / ALL). https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html ↩

By Dmitriy · Updated