Segment must be less than TotalSegments

TL;DR — 在一次并行 Scan中，每个 worker 设置 Segment（它的切片索引）和 TotalSegments（有多少个切片）。DynamoDB 要求 0 ≤ Segment < TotalSegments，且两者必须一起提供。一个等于或高于 TotalSegments 的 Segment 会被拒绝。为每个 worker 分配一个从 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 个切片；每个 worker 扫描由 Segment 标识的一个切片。有效的 Segment 值是 0 到 TotalSegments − 1。TotalSegments 本身必须在 1 到 1,000,000 之间。如果你提供了其中一个而没有另一个，或者一个越界的 Segment，DynamoDB 会拒绝该调用。它是一个 HTTP 400 ValidationException，属于客户端错误，在参数有效之前不可重试。

为什么会发生

差一的段分配——当 TotalSegments = 4 时，使用 Segment 值 1..4 而不是 0..3。
Segment ≥ TotalSegments——一个达到或超过切片数量的 worker 索引。
只提供了这对中的一个——传入 Segment 而没有 TotalSegments（或反之）；并行扫描两者都需要。
一个动态 worker 池的不匹配——TotalSegments 设为一个与实际启动的 worker 数量不同的值，因此一些 worker 得到越界的索引。

如何修复

分配段 0 到 TotalSegments − 1——每个 worker 一个不同的 Segment。
在每个并行扫描请求上总是一起传入两个参数。
让 TotalSegments 等于 worker 数量且在 1..1,000,000 内（TotalSegments 为 1 就只是一次顺序扫描）。
使用从零开始的索引，在把一个 worker 的序号映射到它的 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 移至代码中时，在 Query Builder 中对请求进行原型设计 — 它会发出 Segment 和 TotalSegments 以及完整的 Scan 参数。设置→配置文件中的Profile切换（⌘P）和Test Connection使工作人员能够指向正确的帐户。参见连接 AWS和安装。请记住，段是从零开始的：对于四个工作人员，有效值为 0、1、2 和 3，而不是 1 到 4。当工作人员计数和 TotalSegments 匹配但一名工作人员仍然失败时，偏离一的段分配是最常见的原因。

来源

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 中

来源

相关错误

参考资料