MongoDB SQL Schema Builder CLI是用于Enterprise Advanced (EA) 自托管部署和Atlas专用集群（M10 及更高版本）上SQL接口的模式管理工具。您可以下载并针对集群运行CLI ，以生成或更新集合的模式。 SQL接口使用这些模式将SQL查询转换为MongoDB操作。
CLI 不会对数据进行采样。相反，它会分析它处理的每个集合中的每个文档，因此生成的模式可以精确反映集合中的准确数据。即使只在少量文档中出现的字段也包含在模式中。
模式重新生成始终由用户启动。 CLI不会自动或按安排刷新模式。每当根本的数据的形状发生变化时，您都应该重新生成模式，以便SQL接口对提供的模式信息进行操作。如果需要定期更新，可以通过设置 cron作业以按安排运行重新生成命令来自动执行此操作。
先决条件
在运行 MongoDB SQL 模式构建器 CLI 之前，请确保满足以下要求：
您的部署是MongoDB Enterprise集群（ Enterprise Advanced (EA) 自管理）或运行MongoDB 6.0 或更高版本 (Atlas )的专用集群（
M10及更高版本）。 CLI不支持MongoDB Community集群、免费集群、Flex 集群或M2和M5共享Atlas集群。MongoDB SQL Schema Builder CLI与您的操作系统和架构兼容：
Windows
x86_64。Linux
x86_64和arm64：带有 glibc 2.26 或更高版本的 OpenSSL 1.0、带有 glibc 2.28 或更高版本的 OpenSSL 1.1，或者附带 glibc 2.28 或更高版本的 OpenSSL 3.0。 MongoDB建议使用 OpenSSL 3.0 或更高版本以实现安全连接。
您可以使用连接字符串从运行CLI 的计算机连接到集群。
CLI 身份验证的数据库用户至少具有：
对于要处理的每个数据库，具有
read权限。此权限允许 CLI 列举和分析集合。在您处理的每个数据库中的
__sql_schemas集合上的find、insert和update权限，或数据库上的readWrite角色。CLI 会以更新或插入（upsert）的方式写入每个模式，因此即使是第一次运行，也需要update权限。在专用集群上，
__mdb_internal_sqlinterface数据库上的read权限。
您可以使用 --username 和 --password 标志提供凭证，也可以将其包含在连接字符串中。如果您未提供凭证，CLI 将尝试在没有身份验证的情况下连接并记录日志警告。
调用 CLI
您可以从命令行对集群运行 MongoDB SQL 模式构建器 CLI，以生成或更新模式。二进制文件命名为 mongodb-schema-manager。
获取连接字符串
CLI需要连接字符串(--uri) 才能连接到集群。您还可以提供配置文件(--file)，这样就不必在每次运行时重新输入参数。
以下示例分析 sales 数据库中的每个集合，并将追踪日志写入 logs 目录：
mongodb-schema-manager \ --uri "mongodb://<host>:<port>" \ --ns-include "sales.*" \ --logpath ./logs \ --verbosity info
运行完成后， CLI会打印为其创建或修改模式的数据库和命名空间。如果任何命名空间的多态性级别过高而无法进行有意义的使用，则该命名空间被视为不稳定。 CLI列出了这些命名空间。有关更多信息，请参阅不稳定模式。
模式的存储方式
CLI会将每个命名空间的一个模式文档写入其处理的每个数据库中的 __sql_schemas集合。
重要
将 __sql_schemas 集合视为 SQL 接口的保留命名空间。请勿手动修改。使用 CLI 来创建和更新其中包含的模式。
检查存储模式
要查看CLI生成的模式，请针对要检查的数据库中的 __sql_schemas集合运行聚合管道。每个文档报告以下元数据：
lastUpdated: 最近一次模式写入的日期和时间。
要列出数据库中每个模式的状态而不打印完整的模式主体，请在 mongosh 中运行以下管道：
db.getCollection("__sql_schemas").aggregate([ { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1 } }, { $sort: { namespace: 1 } } ])
要查看特定集合的完整模式，请匹配其名称：
db.getCollection("__sql_schemas").aggregate([ { $match: { _id: "<collection-name>" } }, { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1, schema: 1 } } ])
默认情况下，CLI 会隐式排除名称以两个下划线 (__) 开头的任何数据库或集合，包括 __sql_schemas 集合本身。要包含这些命名空间，必须使用 --ns-include 显式指定它们。示例，--ns-include "*.__*" 包含名称以 __ 开头的集合，但不包含名称以 __ 开头的数据库。
CLI 从视图管道和管道引用的源集合的模式中获取视图的模式。在正常情况下，CLI 不会对视图进行采样。为确保视图的衍生模式准确，请先为源集合生成最新的模式。
如果源集合不存在模式，或 CLI 无法从可用的源集合模式中获取模式，CLI 将回退到执行视图并对其输出文档进行采样。
CLI 标志参考
MongoDB SQL 模式构建者 CLI 接受以下标志。您必须提供 --uri 或 --file，以便 CLI 连接到您的集群。
-f, --file <CONFIG_FILE>- 配置文件的路径。命令行参数优先于配置文件中的值。
--uri <URI>- 集群的连接字符串。
-u, --username <USERNAME>- 用于身份验证的用户名。您还可以在连接字符串中指定用户名。
-p, --password <PASSWORD>- 用于身份验证的密码。您还可以在连接字符串中指定密码。
--ns-include <NS_INCLUDE>- 要包含的数据库和集合，格式为
<database_pattern>.<collection_pattern>。支持 Glob 语法，例如mydb.*。重复此标志以指定多个模式。如果忽略此标志，CLI 将包含所有数据库和集合。除非明确指定，否则以__开头的命名空间将被隐式排除。 --ns-exclude <NS_EXCLUDE>- 要排除的数据库和集合，其格式与
--ns-include相同。重复标志以指定多个模式。此标志优先于--ns-include。 --quiet- 启用静音模式以减少输出。默认：
false。 -o, --logpath <LOGPATH>- CLI 写入日志文件的目录。日志文件命名为
mongodb-schema-manager.log.{date}。如果您忽略此标志，CLI 将不写入日志文件。 -v, --verbosity <VERBOSITY>- 要在日志文件中捕获的日志级别。需要
--logpath。接受trace、debug、info、warn或error。默认：warn。 -a, --action <SCHEMA_ACTION>对模式执行的操作。默认：
merge。接受以下值：merge: 将新模式与现有模式合并。如果不存在模式，此操作将创建一个。此操作不会更新不稳定的模式。overwrite: 忽略并覆盖现有模式。如果不存在模式，此操作将创建一个。使用此操作更新不稳定模式。clear: 从现有模式文档中删除schema字段。如果不存在模式，此操作只捕获元数据。
--dry-run- 执行演练运行，不分析模式或向数据库写入数据。使用此标志来测试
--ns-include和--ns-exclude模式。默认值：false。 --resolver <RESOLVER>- 如果 DNS 解析失败或者较慢，则使用 DNS 解析器。接受
cloudflare、google或quad9。 -j, --jobs <JOBS>- 并发模式处理作业的最大数量。必须是大于
0的整数。默认：物理内核数的两倍。
不稳定模式
当集合的文档形状差异很大时（例如，使用字段名称作为映射键的集合），CLI 会将衍生模式标记为不稳定。不稳定模式在模式文档中将 unstable 设置为 true，并将捕获字段的数量限制为 additionalProperties 并设置为 true。不稳定模式可能无法完全表示命名空间中的数据。
当运行产生一个或多个不稳定模式时， CLI会打印受影响的命名空间：
The following namespaces have unstable schemas. They may not fully represent the data in the namespace. Unstable schemas are not updated by the schema-manager by default. To update them, use the 'overwrite' action.
默认 merge 操作不会更新不稳定模式。要更新不稳定模式，请使用 --action overwrite 运行 CLI。
何时重新生成模式
当根本的数据的形状发生变化时（例如添加字段、删除字段或更改现有字段的数据类型），请重新生成模式。CLI 不会自行检测数据形状变更，因此重新生成始终由用户发起。过时的模式可能会导致 SQL 接口将集合映射到错误的表和列。
了解详情
MongoDB模式经理概述 (PDF)： MongoDB SQL模式生成器的完整技术参考。