DynamoDB Projection Expressions
A projection expression is the SELECT col1, col2 of DynamoDB: a
comma-separated list of attribute 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 RCU 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 GSI instead.
- It is not an access control. The caller picks the projection, and a read
without one returns every attribute. IAM conditions on
dynamodb:Attributesanddynamodb:Selectenforce what a role may read. - Use
#nameplaceholders 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 GSI 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
Querythat 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:
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).
ProjectionExpression | Covering GSI | |
|---|---|---|
| Cuts payload | Yes | Yes |
| Cuts read cost | No | Yes, read at the index's size |
| Extra storage | None | A second copy of the projected fields |
| Extra write cost | None | Writes propagate to the index |
| Best for | Trimming responses; small wins | Hot 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
nameorstatusin 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:
LastEvaluatedKeycomes 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.

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.
- AWS DynamoDB Developer Guide, Using projection expressions in DynamoDB: read capacity is based on item size before any
ProjectionExpressionis applied. https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ProjectionExpressions.html ↩ - AWS DynamoDB Developer Guide, Reserved Words in DynamoDB. https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ReservedWords.html ↩
- AWS DynamoDB Developer Guide, Attribute Projections (
KEYS_ONLY/INCLUDE/ALL). https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html ↩


