effect-dynamodb 1.24.0 → 1.26.0

package/dist/Query.js

@@ -12,8 +12,29 @@ import * as Projection from "@effect-dynamodb/schema/Projection.js";
 import { Effect, Function, Option, Pipeable, Stream } from "effect";
 import { DynamoClient } from "./DynamoClient.js";
 import { compileExpr, ExprTag, emptyPartProblem, isEmptyExpr } from "./internal/Expr.js";
+import { batchGetRaw } from "./internal/Hydrate.js";
+import { packedExprRefusal, packedProjectionRefusal, } from "./internal/Packed.js";
 import { compilePath } from "./internal/PathBuilder.js";
+import { diagnoseFailure, explainDiagnosis, withCause } from "./internal/WriteDiagnosis.js";
 import { fromAttributeMap, toAttributeValue } from "./Marshaller.js";
+/**
+ * @internal The raw-row hook a projection of `paths` runs: the query's
+ * {@link QueryState.rawRow}, unless it declares the attributes it rewrites
+ * ({@link QueryRawRow.attributes}) and the projection names none of them.
+ */
+const projectedRawRow = (hook, paths) => {
+    if (hook?.attributes === undefined)
+        return hook;
+    const rewrites = new Set(hook.attributes);
+    return paths.some((path) => rewrites.has(String(path[0]))) ? hook : undefined;
+};
+/** @internal The raw-row hook the projection of `state` runs, if any. */
+const activeRawRow = (state) => projectedRawRow(state.rawRow, [
+    ...(state.projection ?? []).map((attribute) => [attribute]),
+    ...(state.projectionPaths ?? []),
+]);
+/** @internal The attributes the active raw-row hook of `state` reads (see {@link QueryRawRow.reads}). */
+const rawRowReads = (state) => activeRawRow(state)?.reads ?? [];
 /** @internal Dedupe + drop absent entries from a caller-supplied key field list. */
 const normalizeKeyFields = (fields) => {
     if (!fields)
@@ -43,9 +64,13 @@ class QueryImpl {
 // Constructor (internal — used by Entity and Collection)
 // ---------------------------------------------------------------------------
 export const make = (config) => new QueryImpl({
+    rawRow: config.rawRow,
+    packed: config.packed ?? [],
     liveRows: config.liveRows,
     prepare: config.prepare,
     keepRow: undefined,
+    hydration: config.hydration,
+    keyConditionDiagnosis: config.keyConditionDiagnosis,
     tableName: config.tableName,
     indexName: config.indexName,
     pkField: config.pkField,
@@ -60,7 +85,6 @@ export const make = (config) => new QueryImpl({
     maxPagesValue: undefined,
     scanForward: true,
     consistentRead: false,
-    globalIndex: config.globalIndex ?? false,
     ignoreOwnershipFlag: false,
     exclusiveStartKey: undefined,
     isScan: false,
@@ -76,9 +100,13 @@ export const make = (config) => new QueryImpl({
  * No key condition — only filter expressions and entity type filter.
  */
 export const makeScan = (config) => new QueryImpl({
+    rawRow: config.rawRow,
+    packed: config.packed ?? [],
     liveRows: config.liveRows,
     prepare: config.prepare,
     keepRow: undefined,
+    hydration: undefined,
+    keyConditionDiagnosis: undefined,
     tableName: config.tableName,
     indexName: config.indexName,
     pkField: "",
@@ -93,7 +121,6 @@ export const makeScan = (config) => new QueryImpl({
     maxPagesValue: undefined,
     scanForward: true,
     consistentRead: false,
-    globalIndex: config.globalIndex ?? false,
     ignoreOwnershipFlag: false,
     exclusiveStartKey: undefined,
     isScan: true,
@@ -160,9 +187,10 @@ export const reverse = (self) => new QueryImpl({
     scanForward: false,
 });
 /**
- * Enable consistent reads for this query (or scan). Refused with a
- * `ValidationError` when it runs on a global secondary index, which DynamoDB
- * reads only eventually consistently.
+ * Enable consistent reads for this query (or scan). Sent as asked: DynamoDB
+ * rejects it on a global secondary index, which it reads only eventually
+ * consistently, and the query fails with a `ValidationError`
+ * (`operation: "query.consistentRead"`) naming the index (#144).
  */
 export const consistentRead = Function.dual((args) => isQuery(args[0]), (self) => new QueryImpl({
     ...self._state,
@@ -196,20 +224,35 @@ export const startFrom = Function.dual(2, (self, cursor) => cursor === ""
         ...self._state,
         exclusiveStartKey: decodeCursor(cursor),
     }));
+/** @internal The decoder of a projected (raw) row: the raw-row hook, or the identity. */
+const rawRowDecoder = (hook) => hook ?? ((raw) => Effect.succeed(raw));
+/** @internal Throw `[EDD-9076]` for a projection inside a packed attribute. */
+const refusePackedProjection = (state, paths) => {
+    const refused = packedProjectionRefusal(paths, state.packed);
+    if (refused !== undefined)
+        throw new Error(refused);
+};
 /**
  * Select specific attributes to return (ProjectionExpression).
  * Reduces read capacity and network transfer. When projection is active,
  * items are returned as raw `Record<string, unknown>` instead of decoded
  * schema instances, since projected items may be partial.
+ *
+ * An attribute stored packed (`DynamoModel.Packed` — an EventStore stream's
+ * `data`, for one) comes back as its parsed JSON, whatever its stored form
+ * (a native map, a JSON string, or compressed bytes), and may only be
+ * selected whole: a path inside it throws `[EDD-9076]`.
  */
 export const select = Function.dual(2, (self, attributes) => {
     if (self._state.predicates.length > 0) {
         throw new Error(rejectPredicateWithProjection("select() after filterBy()"));
     }
+    const paths = attributes.map((attribute) => [attribute]);
+    refusePackedProjection(self._state, paths);
     return new QueryImpl({
         ...self._state,
         projection: attributes,
-        decoder: (raw) => Effect.succeed(raw),
+        decoder: rawRowDecoder(projectedRawRow(self._state.rawRow, paths)),
     });
 });
 /**
@@ -222,11 +265,13 @@ export const selectProjected = (self, storedPaths, decode) => {
     if (self._state.predicates.length > 0) {
         throw new Error(rejectPredicateWithProjection("select() after filterBy()"));
     }
+    refusePackedProjection(self._state, storedPaths);
+    const rawRow = rawRowDecoder(projectedRawRow(self._state.rawRow, storedPaths));
     return new QueryImpl({
         ...self._state,
         projection: undefined,
         projectionPaths: storedPaths,
-        decoder: (raw) => Effect.succeed(decode(raw)),
+        decoder: (raw) => Effect.map(rawRow(raw), (row) => decode(row)),
     });
 };
 /**
@@ -250,6 +295,12 @@ export const selectRenamed = (self, paths, resolveDbName) => {
 /**
  * Add an Expr-based filter expression to the query.
  * Multiple filterExpr calls are ANDed together.
+ *
+ * On a query whose items store an attribute packed (`DynamoModel.Packed` — an
+ * EventStore stream with `storedAs.data`, for one), a filter that addresses a
+ * path inside it, or applies anything but `attribute_exists` /
+ * `attribute_not_exists` to it, throws `[EDD-9076]`: DynamoDB sees one opaque
+ * value. Use {@link filterBy}, which runs on the decoded item.
  */
 export const filterExpr = Function.dual(2, (self, expr) => {
     // A filter that asserts nothing (`.filter({})`, `and()`) is no filter: it is
@@ -259,6 +310,9 @@ export const filterExpr = Function.dual(2, (self, expr) => {
     // (`emptyPartProblem`).
     if (isEmptyExpr(expr))
         return self;
+    const refused = packedExprRefusal(expr, self._state.packed, "filter");
+    if (refused !== undefined)
+        throw new Error(refused);
     return new QueryImpl({
         ...self._state,
         exprFilters: [...self._state.exprFilters, expr],
@@ -333,10 +387,11 @@ export const selectPaths = Function.dual(2, (self, paths) => {
     if (self._state.predicates.length > 0) {
         throw new Error(rejectPredicateWithProjection("select() after filterBy()"));
     }
+    refusePackedProjection(self._state, paths);
     return new QueryImpl({
         ...self._state,
         projectionPaths: paths,
-        decoder: (raw) => Effect.succeed(raw),
+        decoder: rawRowDecoder(projectedRawRow(self._state.rawRow, paths)),
     });
 });
 // ---------------------------------------------------------------------------
@@ -468,9 +523,100 @@ const buildDynamoCommand = (state, tableName, overrides, extraProjectionFields =
         ConsistentRead: input.ConsistentRead,
         Limit: computeRequestLimit(state, state.limitValue),
         ScanIndexForward: state.isScan ? undefined : state.scanForward,
+        // An LSI that does not project the items: DynamoDB fetches them from the
+        // table. Not with a ProjectionExpression, which DynamoDB rejects beside
+        // `Select: ALL_ATTRIBUTES` (and which fetches the named attributes itself).
+        ...(state.hydration?._tag === "Fetch" && input.ProjectionExpression === undefined
+            ? { Select: "ALL_ATTRIBUTES" }
+            : {}),
         ...overrides,
     };
 };
+/**
+ * @internal The state the index request is built from. A `BatchGet`-hydrated
+ * query sends its projection on the `BatchGetItem`, not on the index query
+ * (whose rows only carry keys).
+ */
+const indexQueryState = (state) => state.hydration?._tag === "BatchGet"
+    ? { ...state, projection: undefined, projectionPaths: undefined }
+    : state;
+/**
+ * @internal Replace index rows with the table items they refer to, for a
+ * `BatchGet`-hydrated query (see {@link QueryHydration}); any other query's
+ * rows are returned as they are. The result is in `rows` order, `undefined`
+ * for an item that no longer exists (it is dropped like an excluded row).
+ */
+const hydrateRows = (client, tableName, state, rows) => {
+    const hydration = state.hydration;
+    if (hydration?._tag !== "BatchGet" || rows.length === 0)
+        return Effect.succeed(rows);
+    return Effect.gen(function* () {
+        const [pkName, skName] = hydration.tableKey;
+        const requests = [];
+        for (const row of rows) {
+            const pk = row[pkName];
+            const sk = row[skName];
+            if (pk === undefined || sk === undefined) {
+                // Table keys are always projected into a secondary index.
+                return yield* Effect.die(new Error(`Query hydration: an index row of "${state.indexName}" lacks the table key ` +
+                    `attribute "${pk === undefined ? pkName : skName}".`));
+            }
+            requests.push({ tableName, key: { [pkName]: pk, [skName]: sk } });
+        }
+        const ownership = !state.ignoreOwnershipFlag && state.entityTypes.length > 0;
+        // A `select` moves here: the projection, plus what matching (the table
+        // key) and the ownership check read — stripped again unless selected.
+        const names = {};
+        const projected = new Set([
+            ...(state.projection ?? []),
+            ...(state.projectionPaths ?? []).map((segments) => String(segments[0])),
+        ]);
+        const borrowed = projected.size === 0
+            ? []
+            : [
+                ...new Set([
+                    pkName,
+                    skName,
+                    ...(ownership ? ["__edd_e__"] : []),
+                    ...rawRowReads(state),
+                ]),
+            ].filter((field) => !projected.has(field));
+        // What the raw-row hook reads survives until it has run (see `examinePage`).
+        const keptForRawRow = new Set(rawRowReads(state));
+        const expression = buildProjection(state, names, borrowed);
+        const fetched = yield* batchGetRaw(client, requests, {
+            projection: expression === undefined ? undefined : { expression, names },
+            rereadMissing: true,
+        });
+        const hydrated = [];
+        for (const item of fetched) {
+            if (item === undefined) {
+                hydrated.push(undefined);
+                continue;
+            }
+            if (ownership) {
+                const owner = item.__edd_e__?.S;
+                if (owner === undefined || !state.entityTypes.includes(owner)) {
+                    // The index row passed the same `__edd_e__` filter: a defect.
+                    return yield* Effect.die(new Error(`Query hydration: an item fetched through index "${state.indexName}" has ` +
+                        `__edd_e__ ${JSON.stringify(owner)}, not ` +
+                        `${state.entityTypes.map((t) => JSON.stringify(t)).join(" or ")}, although ` +
+                        "its index row passed the same filter."));
+                }
+            }
+            if (borrowed.length === 0) {
+                hydrated.push(item);
+                continue;
+            }
+            const stripped = { ...item };
+            for (const field of borrowed)
+                if (!keptForRawRow.has(field))
+                    delete stripped[field];
+            hydrated.push(stripped);
+        }
+        return hydrated;
+    });
+};
 // ---------------------------------------------------------------------------
 // Internal: limit / pageSize execution helpers
 // ---------------------------------------------------------------------------
@@ -546,15 +692,7 @@ const refuseEmptyFilterParts = (state) => {
  */
 const prepared = (state, tableName) => {
     // A consistent read of a GSI — which DynamoDB only reads eventually
-    // consistently — is refused before anything is sent (#133).
-    if (state.consistentRead && state.globalIndex) {
-        return Effect.fail(new ValidationError({
-            entityType: state.entityTypes.join(", ") || "unknown",
-            operation: "query.consistentRead",
-            cause: `consistentRead: index "${state.indexName}" is a global secondary index, which ` +
-                "DynamoDB reads only eventually consistently. Nothing was sent.",
-        }));
-    }
+    // consistently — is DynamoDB's to reject: diagnosed by `send` (#144).
     // A filter with an empty part where none may be is refused before
     // anything is sent (#133).
     const filterRefusal = refuseEmptyFilterParts(state);
@@ -576,6 +714,38 @@ const prepared = (state, tableName) => {
             };
         });
 };
+/**
+ * @internal Send one request of a terminal. DynamoDB's rejection of what the
+ * library does not pre-check (#144) is diagnosed against the request sent, on
+ * failure only: a consistent read of a GSI, the key condition's rules (an
+ * empty key value, a reversed `BETWEEN`) and an `isIn()` with no values in the
+ * filter, named as {@link KeyConditionDiagnosis} says. Anything else passes
+ * through.
+ */
+const send = (client, state, cmd) => {
+    const request = state.isScan ? client.scan(cmd) : client.query(cmd);
+    return request.pipe(diagnoseFailure({
+        sent: () => ({ _tag: "Read", scan: state.isScan, input: cmd }),
+        only: ["ConsistentReadOnGsi", "EmptyKeyBound", "BetweenReversed", "EmptyIn"],
+        rewrite: (diagnosis, original) => {
+            const entityType = state.entityTypes.join(", ") || "unknown";
+            const naming = state.keyConditionDiagnosis ?? {
+                operation: "query",
+                label: `query of ${entityType}`,
+            };
+            const [operation, label] = diagnosis._tag === "ConsistentReadOnGsi"
+                ? ["query.consistentRead", "query"]
+                : diagnosis._tag === "EmptyIn"
+                    ? ["query.filter", naming.label]
+                    : [naming.operation, naming.label];
+            return new ValidationError({
+                entityType,
+                operation,
+                cause: withCause(explainDiagnosis(diagnosis, label), original),
+            });
+        },
+    }));
+};
 /** @internal Does the decoded item pass every client-side predicate? */
 const accepts = (state, item) => {
     for (const predicate of state.predicates) {
@@ -627,8 +797,74 @@ forCursor) => {
         borrowed.add(state.skField);
     for (const attr of state.liveRows?.reads ?? [])
         borrowed.add(attr);
+    // …and a raw-row hook reads what it dispatches on (a collection's `__edd_e__`).
+    for (const attr of rawRowReads(state))
+        borrowed.add(attr);
     return [...borrowed].filter((field) => !projected.has(field));
 };
+/**
+ * @internal Examine one response's rows in order, as `execute` and `paginate`
+ * both do: drop excluded rows, hydrate (see {@link QueryHydration}), decode,
+ * apply the client predicates, and stop once `budget` items are accepted.
+ *
+ * Without a client predicate every row is accepted, so only the rows the
+ * budget can still take are hydrated and decoded; a row dropped after
+ * hydration (its item gone) widens the window by one. With a predicate,
+ * acceptance is only known after decode, so the whole response is examined
+ * (#122). `stoppedAt` is the index of the row that filled the budget, or -1.
+ */
+const examinePage = (client, tableName, state, returned, budget, borrowedFields) => Effect.gen(function* () {
+    const hasPredicate = state.predicates.length > 0 || dropsRows(state);
+    // Borrowed attributes the raw-row hook reads are stripped after it ran:
+    // borrowed into the request's projection, or — on a `BatchGet`-hydrated
+    // query — into the hydrating fetch's (see `hydrateRows`).
+    const hookReads = new Set(rawRowReads(state));
+    const strippedAfterHook = new Set(borrowedFields.filter((field) => hookReads.has(field)));
+    if (state.hydration?._tag === "BatchGet") {
+        const projected = new Set([
+            ...(state.projection ?? []),
+            ...(state.projectionPaths ?? []).map((segments) => String(segments[0])),
+        ]);
+        if (projected.size > 0) {
+            for (const field of hookReads)
+                if (!projected.has(field))
+                    strippedAfterHook.add(field);
+        }
+    }
+    const items = [];
+    let next = 0;
+    while (next < returned.length) {
+        const end = budget === undefined || hasPredicate
+            ? returned.length
+            : Math.min(returned.length, next + (budget - items.length));
+        const positions = [];
+        for (let i = next; i < end; i++) {
+            if (!isExcludedRow(state, returned[i]))
+                positions.push(i);
+        }
+        const sources = yield* hydrateRows(client, tableName, state, positions.map((i) => returned[i]));
+        for (let k = 0; k < positions.length; k++) {
+            const source = sources[k];
+            if (source === undefined)
+                continue;
+            const raw = fromAttributeMap(source);
+            for (const field of borrowedFields)
+                if (!hookReads.has(field))
+                    delete raw[field];
+            const item = yield* state.decoder(raw);
+            for (const field of strippedAfterHook)
+                delete raw[field];
+            if (hasPredicate && !accepts(state, item))
+                continue;
+            items.push(item);
+            if (budget !== undefined && items.length >= budget) {
+                return { items, stoppedAt: positions[k] };
+            }
+        }
+        next = end;
+    }
+    return { items, stoppedAt: -1 };
+});
 // ---------------------------------------------------------------------------
 // Terminals
 // ---------------------------------------------------------------------------
@@ -666,14 +902,14 @@ export const execute = (self) => Effect.gen(function* () {
         ? yield* self._state.resolveTableName
         : self._state.tableName;
     const state = yield* prepared(self._state, tableName);
+    const indexState = indexQueryState(state);
     const limitValue = state.limitValue;
     if (limitValue !== undefined && limitValue <= 0) {
         return { items: [], cursor: null };
     }
     // Key attributes borrowed into an active projection so an over-reading
     // request can still rebuild a cursor. Stripped again before decoding.
-    const borrowedFields = cursorProjectionFields(state, true);
-    const hasPredicate = state.predicates.length > 0 || dropsRows(state);
+    const borrowedFields = cursorProjectionFields(indexState, true);
     const items = [];
     let startKey = state.exclusiveStartKey;
     let pageCount = 0;
@@ -681,34 +917,14 @@ export const execute = (self) => Effect.gen(function* () {
     while (true) {
         pageCount++;
         const remaining = limitValue === undefined ? undefined : limitValue - items.length;
-        const cmd = buildDynamoCommand(state, tableName, { ExclusiveStartKey: startKey, Limit: computeRequestLimit(state, remaining, pageCount) }, borrowedFields);
-        const result = state.isScan ? yield* client.scan(cmd) : yield* client.query(cmd);
+        const cmd = buildDynamoCommand(indexState, tableName, { ExclusiveStartKey: startKey, Limit: computeRequestLimit(state, remaining, pageCount) }, borrowedFields);
+        const result = yield* send(client, state, cmd);
         const returned = (result.Items ?? []);
         const lastEvaluatedKey = result.LastEvaluatedKey;
-        // Without a client predicate every returned row is accepted, so the take
-        // window is known before decoding and the budget can bound it directly.
-        // With one, acceptance is only known AFTER decode, so every returned row
-        // is examined and the loop stops once the budget fills (#122).
-        const take = remaining === undefined || hasPredicate
-            ? returned.length
-            : Math.min(remaining, returned.length);
-        /** Index of the last row examined when the limit was reached, else -1. */
-        let stoppedAt = -1;
-        for (let i = 0; i < take; i++) {
-            if (isExcludedRow(state, returned[i]))
-                continue;
-            const raw = fromAttributeMap(returned[i]);
-            for (const field of borrowedFields)
-                delete raw[field];
-            const item = yield* state.decoder(raw);
-            if (hasPredicate && !accepts(state, item))
-                continue;
-            items.push(item);
-            if (limitValue !== undefined && items.length >= limitValue) {
-                stoppedAt = i;
-                break;
-            }
-        }
+        // Index of the last row examined when the limit was reached, else -1.
+        const page = yield* examinePage(client, tableName, state, returned, remaining, borrowedFields);
+        items.push(...page.items);
+        const stoppedAt = page.stoppedAt;
         // Stopped inside the page: the surplus was discarded, so the cursor has
         // to be rebuilt from the last item handed back rather than from
         // LastEvaluatedKey. `stoppedAt` is the last row ACCEPTED, which is what
@@ -759,30 +975,15 @@ const pageStream = (client, tableName, state) => {
     }, (pageState) => Effect.gen(function* () {
         const pageCount = pageState.pageCount + 1;
         const remaining = limitValue === undefined ? undefined : limitValue - pageState.emitted;
-        const borrowedFields = cursorProjectionFields(state, false);
-        const cmd = buildDynamoCommand(state, tableName, {
+        const indexState = indexQueryState(state);
+        const borrowedFields = cursorProjectionFields(indexState, false);
+        const cmd = buildDynamoCommand(indexState, tableName, {
             ExclusiveStartKey: pageState.key,
             Limit: computeRequestLimit(state, remaining, pageCount),
         }, borrowedFields);
-        const result = state.isScan ? yield* client.scan(cmd) : yield* client.query(cmd);
+        const result = yield* send(client, state, cmd);
         const returned = (result.Items ?? []);
-        // See `execute` — a client predicate rejects rows after decode, so
-        // the budget cannot bound the examine window, only the accepted one.
-        const hasPredicate = state.predicates.length > 0 || dropsRows(state);
-        const take = remaining === undefined || hasPredicate
-            ? returned.length
-            : Math.min(remaining, returned.length);
-        const examined = yield* Effect.forEach(returned
-            .slice(0, take)
-            .filter((item) => !isExcludedRow(state, item))
-            .map((item) => {
-            const raw = fromAttributeMap(item);
-            for (const field of borrowedFields)
-                delete raw[field];
-            return raw;
-        }), (raw) => state.decoder(raw));
-        const kept = hasPredicate ? examined.filter((item) => accepts(state, item)) : examined;
-        const decoded = remaining === undefined ? kept : kept.slice(0, remaining);
+        const { items: decoded } = yield* examinePage(client, tableName, state, returned, remaining, borrowedFields);
         const emitted = pageState.emitted + decoded.length;
         const hasMorePages = result.LastEvaluatedKey != null;
         const maxPagesReached = state.maxPagesValue != null && pageCount >= state.maxPagesValue;
@@ -811,7 +1012,9 @@ export const count = (self) => Effect.gen(function* () {
     const tableName = self._state.resolveTableName
         ? yield* self._state.resolveTableName
         : self._state.tableName;
-    const state = yield* prepared(self._state, tableName);
+    // A hydrated query counts index rows: nothing is fetched (and a `select`
+    // projection, which hydration would send on the fetch, is not sent).
+    const state = indexQueryState(yield* prepared(self._state, tableName));
     const limitValue = state.limitValue;
     if (limitValue !== undefined && limitValue <= 0)
         return 0;
@@ -846,7 +1049,7 @@ export const count = (self) => Effect.gen(function* () {
                 ExclusiveStartKey: start,
                 Limit: computeRequestLimit(state, remaining, pages),
             });
-            const result = state.isScan ? yield* client.scan(cmd) : yield* client.query(cmd);
+            const result = yield* send(client, state, cmd);
             const rows = (result.Items ?? []);
             counted += rows.filter((row) => !isExcludedRow(state, row)).length;
             start = result.LastEvaluatedKey;
@@ -868,7 +1071,7 @@ export const count = (self) => Effect.gen(function* () {
             Select: "COUNT",
             Limit: computeRequestLimit(state, remaining),
         });
-        const result = state.isScan ? yield* client.scan(cmd) : yield* client.query(cmd);
+        const result = yield* send(client, state, cmd);
         total += result.Count ?? 0;
         exclusiveStartKey = result.LastEvaluatedKey;
         if (limitValue !== undefined && total >= limitValue)
@@ -882,8 +1085,7 @@ export const count = (self) => Effect.gen(function* () {
  * Return the built DynamoDB command input without executing.
  * Useful for debugging, logging, or passing to DynamoClient directly.
  * Fails with a `ValidationError` for a filter the query would refuse to send
- * (an empty part under `or` / `not`, an `or()` with no parts, an `isIn` with
- * no values).
+ * (an empty part under `or` / `not`, an `or()` with no parts).
  */
 export const asParams = (self) => Effect.gen(function* () {
     const state = self._state;
@@ -891,7 +1093,9 @@ export const asParams = (self) => Effect.gen(function* () {
     if (refusal !== undefined)
         return yield* refusal;
     const tableName = state.resolveTableName ? yield* state.resolveTableName : state.tableName;
-    return buildDynamoCommand(state, tableName);
+    // A `BatchGet`-hydrated query shows its index query; the `BatchGetItem`
+    // that follows each page is not part of these parameters.
+    return buildDynamoCommand(indexQueryState(state), tableName);
 });
 // ---------------------------------------------------------------------------
 // Type guard