Type Alias QueryOptions

QueryOptions:
    | { consistentRead?: never; filter?: FilterParams; indexName: string }
    | {
        consistentRead?: boolean;
        filter?: FilterParams;
        indexName?: undefined;
    }

Specifies additional options for querying items, including optional consistent read, index name and filter conditions.

A filter is applied by DynamoDB after the read, so it narrows the result set rather than the work: it saves bandwidth, not capacity. To narrow what is read, put the condition in the key condition instead — a sort key accepts a range for exactly this reason.

Filter keys are the attributes of the queried entity and of its declared relationships, and support dot-path notation for nested @ObjectAttribute fields. Each key accepts an equality, an "IN" array, a comparison, a $between range, a $beginsWith prefix or a $contains check — whichever of those the form the table stores the attribute in can carry. Conditions join with AND; $or takes an array of blocks.

Example

// Everything created in January, by one entity type
await Customer.query("123", {
  filter: {
    type: "Order",
    createdAt: { $gte: new Date("2026-01-01"), $lt: new Date("2026-02-01") }
  }
});

// An OR block, with a range in one arm
await Customer.query("123", {
  filter: {
    $or: [{ total: { $between: [50, 100] } }, { name: { $beginsWith: "Scale" } }]
  }
});

Type Alias QueryOptions

Example

Settings