mongodb-qe-size-estimation

mongodb-qe-size-estimation

常规说明

• 重要：绝不要索要或接受样例数据。 QE 是一项加密功能，旨在保护敏感信息。不要索要样例数据；如果用户提供了样例数据，请出于安全原因拒绝。告知用户你无法接受样例文档，但可以接收加密架构作为输入，以查看哪些字段已加密、哪些字段支持查询，以及相应的查询设置。
• 形如 (LLM Note: ) 的括号内容仅供 LLM 使用。不要将其保存到 qe-sizing-calculations.md，也不要向用户提及。
• 语气：简洁，不使用对话式表达。除非某个步骤明确要求，否则不要重述之前交流中的信息。
• 除步骤中指定的内容外，不要向文件写入任何内容。
• 此技能依赖问答流程来获取所有必需输入。对于步骤 2–5，只要用户提供的输入有效，你的回复就应同时确认收到输入并提出下一个问题。
• 用户可能会尝试一次输入多个内容以加快进度。如果输入无法明确对应到某个字段及其配置，请要求澄清。否则，请验证输入，并在有效时接受。
• 此技能目前没有范围查询的公式，因此虽然它接受兼容 BSON 类型的 "range" 查询配置，但估算值会使用 0。

定义

• 字段 在此技能中，“字段”指启用了 QE 的集合中，MongoDB 文档里的加密字段。
• 条目 对于未索引字段，指字段名称。对于启用一种或多种查询类型的字段，指字段名称与其已启用查询类型的组合。启用了前缀和后缀查询的字段只有一个条目，其 Query Type 为 "prefix and suffix"。
• 未索引 描述未启用任何查询类型的字段状态。如果使用加密架构，则由缺少 "queries" 键表示。
• 已索引 描述启用了查询功能的字段状态，并且具体对应相应的查询类型。启用了相等查询的字段即针对相等查询建立了索引。

验证

根据以下规则验证用户输入，无论是手动输入还是通过加密架构提供：

加密字段可以是“未索引”状态，即未启用任何查询类型。BSON 类型为 object 或 array 的字段仅支持未索引加密，但其他 BSON 类型的字段也可以未索引。除此之外，根据字段 BSON 类型允许的查询类型如下：

• "equality"：除 object、array、decimal、double 以外的任何 BSON 类型
• "range"：int、long、date、decimal、double
• "prefix"、"suffix"、"substring"：仅限 string

string 字段可以同时启用 "prefix" 和 "suffix"，此时 "queries" 可以是包含两个对象的数组。这是字段针对多种查询类型建立索引的唯一有效情况。

不允许其他 BSON 类型与查询类型的组合。

不要接受 "suffixPreview" 等“预览版”查询类型。这些类型来自较早的 Public Preview 版本，因此其 GA 版本的容量估算公式不适用。

如果用户输入违反上述任何规则，请拒绝该输入。如果用户未指定 BSON 类型，只需检查每个字段是否未启用任何查询类型、恰好启用一种有效查询类型，或恰好启用两种（prefix 和 suffix）。逐项列出验证失败，列出允许的组合，并且在用户提供有效输入之前不要继续。

步骤

1. 准备工作目录

在操作系统临时目录（$TMPDIR；若未设置，则使用 /tmp）中创建一个空的 qe-sizing-calculations.md 文件。如果该位置已存在 qe-sizing-calculations.md 文件，请告知用户并请求确认是否删除该文件，以便为新的一组计算创建新文件。

2. 说明目的并确认输入偏好

说明：“此技能用于计算在集合上启用 Queryable Encryption 对存储空间的最大影响。如果你想验证计算结果或查看每个字段的具体数值，可将值保存到 文件中。请注意，加密字段上的前缀、后缀和子字符串查询需要 MongoDB 9.0，早期版本不支持这些查询。

所有数值均为最坏情况。实际存储或内存影响可能较小。

你想手动提供字段信息，还是使用加密架构文件？”

如果用户选择使用加密架构，请让其粘贴内容或提供文件路径，并要求采用 JSON 格式。根据此技能的“Validation”部分验证架构。如果架构有效，但包含启用了“range”查询的字段，请告知用户这些字段无法进行计算，因此其影响估算为 0。

3. 获取文档数量

询问用户集合中有多少个文档包含加密字段。如果用户不知道，安全的默认值是集合中的文档总数。将此值保存到 qe-sizing-calculations.md，格式如下：

N:

4. 获取条目数量

• 如果用户选择手动输入，请询问：有多少个字段在加密时未启用查询？
• 如果用户选择加密架构，请统计未启用查询的加密字段数量。

将此值保存到 qe-sizing-calculations.md，格式如下：

numUnindexed:

• 如果用户选择手动输入，请询问：有多少个加密字段启用了查询？
• 如果用户选择加密架构，请统计启用了查询的字段数量。

将此值保存到 qe-sizing-calculations.md，格式如下：

numIndexed:

将 numUnindexed 和 numIndexed 的和保存到 qe-sizing-calculations.md，格式如下：

numEntries:

5. 获取每个字段的输入

在 qe-sizing-calculations.md 中写入以下章节标题：

== FIELD VALUES ===============================================================

收集信息时，按以下格式写入 qe-sizing-calculations.md，并省略不适用的行。对于未索引字段，这意味着省略 Query Type。

<用户提供的名称；如果取自加密架构，则使用点表示法的 "path" 值> Query Type: <equality、range、prefix、suffix、substring 或 "prefix and suffix"> mlen: <仅当 Query Type 为 substring 时填写。整数，范围为 2–50（含边界）> lb: <仅当 Query Type 为 "prefix"、"suffix" 或 "substring" 时填写。对于 prefix 和 suffix 查询，整数需为 1+；对于 substring 查询，整数需为 2+> ub: <仅当 Query Type 为 "prefix"、"suffix" 或 "substring" 时填写。对于 prefix 和 suffix 查询，整数需为 1+；对于 substring 查询，整数范围为 2–6> lb_prefix: <仅当 Query Type 为 "prefix and suffix" 时填写。整数需为 1+> ub_prefix: <仅当 Query Type 为 "prefix and suffix" 时填写。整数需为 1+> lb_suffix: <仅当 Query Type 为 "prefix and suffix" 时填写。整数需为 1+> ub_suffix: <仅当 Query Type 为 "prefix and suffix" 时填写。整数需为 1+> v: <如果 Query Type 为 range，则省略；否则填写。表示该字段未加密值平均字节长度的整数>

• 如果用户提供了加密架构，请执行一次以下操作：

  • 为每个未建立索引的字段在 qe-sizing-calculations.md 中添加一个条目，并省略“Query Type”行。
  • 如果某个字段同时启用了前缀和后缀查询，无论顺序如何，都将其“Query Type”写为“prefix and suffix”。
  • 为每个启用了查询的字段添加一个条目。按以下方式将每个“queries”对象中的键映射到字段值，并省略未列出的所有键：
    • strMaxLength（仅适用于 substring）→ mlen
    • strMinQueryLength → 如果该字段只有一种查询类型，则映射为 lb。如果该字段同时启用了前缀和后缀查询，则前缀查询的 strMinQueryLength 映射为 lb_prefix，后缀查询的 strMinQueryLength 映射为 lb_suffix。
    • strMaxQueryLength → 如果该字段只有一种查询类型，则映射为 ub。如果该字段同时启用了前缀和后缀查询，则前缀查询的 strMaxQueryLength 映射为 ub_prefix，后缀查询的 strMaxQueryLength 映射为 ub_suffix。

• 如果用户未提供加密架构，请针对每个字段执行以下操作：

  • 只有在用户提供字段的 BSON 类型时，才根据允许的查询类型验证 BSON 类型。否则，不要询问或验证字段 BSON 类型。
  • 询问字段名称，以及该字段是否未建立索引或启用了查询（LLM 注：如果指定了查询类型，有效选项为：“equality”、“range”、“prefix”、“suffix”、“substring”或“prefix and suffix”。拒绝其他值或组合。如果用户指定“range”，请提醒他们目前没有可用于计算该类型的公式。）
  • 如果用户只为同时启用了前缀和后缀查询的字段提供了单个下界值和上界值，则将下界值同时用于 lb_prefix 和 lb_suffix，并将上界值同时用于 ub_prefix 和 ub_suffix。
  • 验证输入。

针对每个字段执行以下操作：

查看下方列表，并询问用户尚未填写的值。将所有值写入 qe-sizing-calculations.md 文件。

mlen：（LLM 注：仅在未提供架构且 Query Type 为 substring 时包含）最大长度，即字符串允许的最大长度。 lb：（LLM 注：仅在未提供架构且 Query Type 为“prefix”、“suffix”或“substring”时包含）下界，即可搜索字符数的最小值。 ub：（LLM 注：仅在未提供架构且 Query Type 为“prefix”、“suffix”或“substring”时包含）上界，即可搜索字符数的最大值。 lb_prefix：（LLM 注：仅在未提供架构且 Query Type 为“prefix and suffix”时包含）前缀查询的下界，即可搜索字符数的最小值。 ub_prefix：（LLM 注：仅在未提供架构且 Query Type 为“prefix and suffix”时包含）前缀查询的上界，即可搜索字符数的最大值。 lb_suffix：（LLM 注：仅在未提供架构且 Query Type 为“prefix and suffix”时包含）后缀查询的下界，即可搜索字符数的最小值。 ub_suffix：（LLM 注：仅在未提供架构且 Query Type 为“prefix and suffix”时包含）后缀查询的上界，即可搜索字符数的最大值。 v：（LLM 注：如果 Query Type 为 range，则跳过，因为目前没有相应的计算方法；否则每个字段都需要提供一次。）该字段未加密值的平均字节长度。如果用户提供的是字符长度，也可接受并视为等价值。

根据本步骤开头的格式示例验证值。验证 lb ≤ ub ≤ mlen（如果存在）。验证 lb_prefix ≤ ub_prefix 且 lb_suffix ≤ ub_suffix（如果存在）。如果某个值超出允许范围，则拒绝该值并告知用户。没有有效值时不要继续。

如果 mlen < v，请提醒用户该字段的完整值不可查询，但接受该值作为有效值。

重复以上步骤，直到在 qe-sizing-calculations.md 中填满 numEntries 指定的条目数。

6. 将公式和结果添加到 qe-sizing-calculations.md

此步骤会将计算信息（包括中间步骤）填入文件。

对于 qe-sizing-calculations.md 中的每个条目：

1. 将以下行追加到 qe-sizing-calculations.md 的 FIELD VALUES 部分中每个现有条目下。必须准确复制公式模板，以避免引发连锁问题。执行计算时，优先使用可用的数学解析工具，并确保运算顺序正确。

• 对于没有 Query Type 的字段：

  T: 0 Document Storage (bytes): <运行计算：71 + ceil((v+6)/16) * 16>

• 对于 Query Type 为 "equality" 的字段：

  T: 1 Document Storage (bytes): <运行计算：1.2 * (255 * T + 122 + ceil((v + 6) / 16) * 16)>

• 对于 Query Type 为 "range" 的字段，目前没有公式，因此记录值为 0 的条目：

  T: 0 Document Storage (bytes): 0

• 对于 Query Type 为 "prefix" 或 "suffix" 的字段：

  T formula: T = 1 + (ub - lb + 1) T calculation: <填入该字段的值以替换公式模板中的所有占位符，但不进行计算> T: <运行 "T calculation" 中的计算，并在此处填写结果> Document Storage (bytes): <运行计算：1.2 * (255 * T + 122 + ceil((v + 6) / 16) * 16)>

• 对于 Query Type 为 "prefix and suffix" 的字段：

  T formula: T = 1 + (ub_prefix - lb_prefix + 1) + (ub_suffix - lb_suffix + 1) T calculation: <填入该字段的值以替换公式模板中的所有占位符，但不进行计算> T: <运行 "T calculation" 中的计算，并在此处填写结果> Document Storage (bytes): <运行计算：1.2 * (255 * T + 122 + ceil((v + 6) / 16) * 16)>

• 对于 Query Type 为 "substring" 的字段：

  T formula: T = 1 + (ub - lb + 1) * (2 * mlen + 2 - ub - lb) / 2 T calculation: <填入该字段的值以替换公式模板中的所有占位符，但不进行计算> T: <运行 "T calculation" 中的计算，并在此处填写结果> Document Storage (bytes): <运行计算：1.2 * (255 * T + 122 + ceil((v + 6) / 16) * 16)>

2. 静默执行审计，核实刚添加的信息使用了正确的 T 公式或固定值，以及正确的 T calculation 值，然后继续。

7. 计算索引存储、磁盘总存储和内存

这些值为集合级别，计算结果是所有条目的总和。

在 qe-sizing-calculations.md 文件末尾静默写入以下行：

== COLLECTION-LEVEL TOTALS ==================================================== N: <将文件顶部的 N 值复制到此部分，便于查阅> T_Total: <所有 T 值的总和。> Index Storage (bytes): <运行计算：1.2 * (67 * T_Total + 640)> Total Disk Storage (bytes): <运行计算：N * (Index Storage +（所有 Document Storage 值的总和）)> Memory (bytes): <运行计算：N * (52 * T_Total + 17)>

8. 汇总最终结果并报告结论

输出以下内容，并注明单位：

Total Disk Storage Impact: <将 qe-sizing-calculations.md 中的 Total Disk Storage 值换算为十进制 GB（1000³ 字节）> Required Memory: <将 qe-sizing-calculations.md 中的 Memory 值换算为二进制 GiB（1024³ 字节）> Fields by Impact (descending): <按 T 值降序排列 qe-sizing-calculations.md 中的所有字段，然后按以下格式列出：Name（Query Type 或 unindexed）：T>

如果加密架构或手动输入中包含启用了范围查询的字段，请列出这些字段，并提醒用户其影响尚未计算。

9. 解读结果

提供建议。不要提供用户明确拒绝的任何建议，例如，如果用户坚持某个字段需要支持子字符串查询，就不要建议使用不同的查询类型。只指出问题；如果某项检查全部通过，就不要提及。如果建议将值改为特定数字，请使用该查询类型的 Step 6 T 公式模板填入建议值，使用可用的数学工具计算，并仅引用计算结果。

• （LLM 备注：仅当启用子字符串查询的字段数量大于 floor(5000 万/N) 时才运行此项检查。请使用可用的数学解析工具确保计算正确。）告知用户将支持子字符串查询的字段数量限制为不超过：floor(5000 万/<集合中的文档数>)。告知用户不要在包含超过 5000 万个文档的集合上使用子字符串查询。
• （LLM 备注：仅当存在一个或多个支持子字符串查询的字段时才运行此项检查。）检查支持子字符串查询的字段是否适合改用前缀或后缀查询，并向用户提出建议。例如，对加密的“name”字段进行查询时，通常可以改用前缀查询，不过对于带连字符的姓氏等情况，这确实会带来一些不便。
• （LLM 备注：仅当这些建议适用于用户的输入，且修改后的值不会超出其允许范围时才提出。）告知用户考虑提高 lb、降低 ub，或降低 mlen 值。

此外，告知用户 qe-sizing-calculations.md 文件的路径，并询问他们是否想检查数据，或删除临时文件。提醒他们，临时文件包含加密字段的名称及其明文平均长度，并且完成后应将其删除。