DynamoDB: Query KeyConditionExpression (Guide w/ Code Examples)

KeyConditionExpression selects one partition-key value and can optionally narrow its sort key. Names are aliased with # and values are bound with :; pagination retrieves all matching items.

Install @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb, use an ES module on a supported Node.js runtime, and configure an AWS Region and credentials. The examples use an existing Orders table with String keys pk and sk unless an index or timestamp key is described.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, QueryCommand } from "@aws-sdk/lib-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

let lastKey;
do {
  const page = await ddb.send(new QueryCommand({
    TableName: "Orders",
    KeyConditionExpression: "#pk = :pk",
    ExpressionAttributeNames: { "#pk": "pk" },
    ExpressionAttributeValues: { ":pk": "CUSTOMER#123" },
    ExclusiveStartKey: lastKey,
  }));
  for (const item of page.Items ?? []) console.log(item);
  lastKey = page.LastEvaluatedKey;
} while (lastKey && Object.keys(lastKey).length > 0);

Non-key attributes belong in FilterExpression. A filter cannot replace the required partition-key equality and does not reduce the capacity used by items already read.

Reference: AWS Query API. For related access patterns, see DynamoDB query examples.