DynamoDB: Query JSON (Guide w/ Code Examples)

A document path can filter a nested Map attribute after Query selects a partition. This example keeps items whose details.city is Lisbon; it does not search a JSON-encoded String.

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",
    FilterExpression: "#details.#city = :city",
    ExpressionAttributeNames: { "#pk": "pk", "#details": "details", "#city": "city" },
    ExpressionAttributeValues: { ":pk": "CUSTOMER#123", ":city": "Lisbon" },
    ExclusiveStartKey: lastKey,
  }));
  for (const item of page.Items ?? []) console.log(item);
  lastKey = page.LastEvaluatedKey;
} while (lastKey && Object.keys(lastKey).length > 0);

Store details as a DynamoDB Map, not JSON.stringify(details). For frequent lookups across partitions, copy the city to a top-level index key attribute.

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