Segment must be less than TotalSegments

TL;DR — 並列 Scan では、各ワーカーが Segment（そのスライスのインデックス）と TotalSegments（スライスの数）を設定します。DynamoDB は 0 ≤ Segment < TotalSegments を要求し、両方を一緒に渡す必要があります。TotalSegments 以上の Segment は拒否されます。各ワーカーに 0 から TotalSegments − 1 までの別個の Segment を割り当ててください。

意味

ValidationException: The Segment parameter is zero-based and must be less than parameter TotalSegments: Segment: 5 is not less than TotalSegments: 2

# on DynamoDB Local the same call reports the constraint generically instead:
ValidationException: 1 validation error detected: Value '5' at 'segment' failed to satisfy constraint: Member must have value less than or equal to 1

並列スキャンはテーブルを TotalSegments 個のスライスに分割します。各ワーカーは Segment で識別される1つのスライスをスキャンします。有効な Segment 値は 0 から TotalSegments − 1 です。TotalSegments 自体は 1 から 1,000,000 の間である必要があります。一方を他方なしで渡す、または範囲外の Segment を渡すと、DynamoDB は呼び出しを拒否します。これは HTTP 400 の ValidationException、クライアント側の問題で、パラメータが有効になるまでリトライ不可です。

発生する理由

off-by-one のセグメント割り当て — TotalSegments = 4 で、0..3 の代わりに 1..4 の Segment 値を使う。
Segment ≥ TotalSegments — スライス数に達するか超えるワーカーインデックス。
ペアの一方のみを渡す — TotalSegments なしで Segment を渡す（またはその逆）。並列スキャンには両方が必要です。
動的なワーカープールの不一致 — TotalSegments が実際に起動されたワーカー数と異なる値に設定され、一部のワーカーが範囲外のインデックスを得る。

修正方法

セグメントを 0 から TotalSegments − 1 に割り当てます — ワーカーごとに1つの別個の Segment。
すべての並列スキャンリクエストで 常に両方のパラメータを一緒に渡します。
TotalSegments をワーカー数に等しく保ち、1..1,000,000 の範囲内にします（TotalSegments が 1 なら単なる順次スキャンです）。
ワーカーの序数を Segment にマッピングするとき、ゼロベースのインデックス を使います。

例

const totalSegments = workers.length;
await Promise.all(
  workers.map((_, segment) =>
    doc.send(
      new ScanCommand({
        TableName: 'Orders',
        Segment: segment, // 0 .. totalSegments - 1
        TotalSegments: totalSegments
      })
    )
  )
);

DynoTable で

本番で Scan を並列化する前に、DynoTable で単一セグメントの Scan を実行し、テーブルとフィルターが期待どおりに振る舞うことを確かめましょう。⌘K でテーブルを開き、クエリパネルから Scan を実行して、返ってきたアイテムを確認します — ワーカー群を起動しなくても、各セグメントが触れるデータが分かります。

Scan をコードに移すときは、クエリビルダーでリクエストを試作しましょう — Scan のパラメータ一式に加えて Segment と TotalSegments も出力されます。プロファイルの切り替え（⌘P）と Settings → Profiles の Test Connection が、ワーカーを正しいアカウントに向け続けてくれます。AWS に接続するとインストールを参照してください。セグメントがゼロベースであることを忘れないでください。ワーカーが 4 つなら、有効な値は 0、1、2、3 であって 1〜4 ではありません。ワーカー数と TotalSegments は一致しているのに 1 つだけ失敗する、という場合の原因はたいていセグメント割り当ての 1 つずれです。

出典

Scan — Amazon DynamoDB API Reference (2026-07-13 時点で検証)
Scanning tables in DynamoDB (2026-07-13 時点で検証)

参考資料

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

Segment must be less than TotalSegments

意味

発生する理由

修正方法

例

DynoTable で

出典

関連するエラー

参考資料