MongoDB SQL模式构建器CLI

用例

当您在 EA 自托管部署中运行SQL接口并且需要为集合生成或更新模式时，请使用MongoDB SQL Schema Builder CLI 。 CLI是此部署类型支持的模式管理路径。

CLI不会对您的数据示例。相反，它会分析其处理的每个集合中的每个文档，因此生成的模式精确地反映了集合中的确切数据。即使只出现在一小部分文档中的字段也会包含在该模式中。

模式重新生成始终由用户启动。 CLI不会自动或按安排刷新模式。每当根本的数据的形状发生变化时，您都应该重新生成模式，以便SQL接口对提供的模式信息进行操作。

先决条件

在运行MongoDB SQL模式生成器CLI之前，请确保满足以下要求：

• 您的部署是MongoDB Enterprise集群。 CLI不支持MongoDB Community集群。

• 您可以使用连接字符串(--uri) 或配置文件(--file) 从运行CLI的计算机连接到集群。

• CLI验证的数据库用户至少具有：

  • 要进程的每个数据库的 read权限。此权限允许CLI枚举和分析您的集合。

  • 您进程的每个数据库中 __sql_schemas集合的 find、insert 和 update 特权，或者数据库上的 readWrite角色。 CLI会使用更新或更新或插入（upsert）写入每个模式，因此即使在首次运行也需要 update权限。

您可以提供带有 --username 和 --password 标志的凭证，或将其包含在连接字符串中。如果您不提供凭证， CLI将尝试在不进行身份验证的情况下进行连接，并记录警告。

调用CLI

您可以命令行针对集群运行MongoDB SQL Schema Builder CLI ，以生成或更新模式。该二进制文件名为 mongodb-schema-manager。

以下示例分析 sales数据库中的每个集合，并将跟踪日志写入 logs目录：

mongodb-schema-manager \
   --uri "mongodb://<host>:<port>" \
   --ns-include "sales.*" \
   --logpath ./logs \
   --verbosity info

运行完成后， CLI会打印为其创建或修改模式的数据库和命名空间。如果任何命名空间的多态性级别过高而无法进行有意义的使用，则该命名空间被视为不稳定。 CLI列出了这些命名空间。有关更多信息，请参阅不稳定模式。

如何存储模式

CLI会将每个命名空间的一个模式文档写入其处理的每个数据库中的 __sql_schemas集合。

db.__sql_schemas.aggregate([
   { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1 } },
   { $sort: { namespace: 1 } }
])

db.__sql_schemas.aggregate([
   { $match: { _id: "<collection-name>" } },
   { $project: { _id: 0, namespace: "$_id", type: 1, lastUpdated: 1, unstable: 1, schema: 1 } }
])

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>。支持 Global 语法，例如 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 SQL接口
• 使用SQL接口进行查询
• MongoDB SQL接口概述

• MongoDB模式经理概述 (PDF)： MongoDB SQL模式生成器的完整技术参考。