从 BI Connector 迁移到 SQL 接口

本指南涵盖了从MongoDB Connector for BI和Atlas BI Connector迁移到较新的SQL接口的过程。

重要

MongoDB Connector for BI 和 Atlas BI Connector 在 2026 年 9 月达到了生命周期结束 (EOL)。

SQL接口

与 BI Connector 类似，SQL Interface 使您能够使用各种基于 SQL 的工具（例如 Tableau 和 Power BI）分析 MongoDB 部署中的数据。

与 BI Connector 相比，SQL Interface 具有以下优势：

您可以直接连接到 Atlas 专用集群，无需联合数据库实例。这是大多数 Atlas 连接的推荐路径。
通过 Atlas 联合数据库实例，您可以读取 Atlas 集群以外的数据源中的数据。当单个查询必须跨越多个数据源时，请使用此路径。
模式是单独持久化的，可以在不中断 SQL 查询功能的情况下进行更新。
您可以将自定义MongoDB连接器用于Tableau和 Power BI。

要比较这两种 Atlas 连接路径，请参阅 MongoDB SQL 界面概述。

SQL 界面限制

SQL 接口提供只读访问权限。
MongoSQL 是唯一支持的方言。MongoSQL 兼容 SQL-92。不支持其他 SQL 方言。
如果您通过联合数据库实例进行连接，则所有 Atlas Data Federation 限制也应用。它们不适用于直接连接到专用集群。

准备过渡到 SQL 接口

在从 BI Connector 转换到 SQL Interface 之前，请确认您的部署满足迁移目标的前提条件。MongoDB 还建议您生成一份过渡就绪报告，以帮助规划您的过渡。

先决条件

先决条件取决于您迁移到的位置。要比较 Atlas 目标，请参阅 MongoDB SQL 界面概述。

Atlas 专用集群：要连接的MongoDB 数据库用户。要启用 SQL 接口，您还需要一个具有 Project Cluster Manager 或 Project Replica Set Manager 角色的 Atlas user。
Atlas 联合数据库实例：一个包含可查询数据和用于连接的 MongoDB 数据库用户的联合数据库实例。
自管理 Enterprise Advanced (EA) 部署：具有所需数据库权限的 MongoDB 数据库用户。不需要 Atlas 项目角色。

生成过渡就绪报告

MongoDB 提供了一个 MongoSQL 迁移就绪工具，帮助您规划从 BI Connector 到 SQL Interface 的迁移。该工具会根据您过去使用 BI Connector 的情况生成报告，提供实时模式分析和建议，并突出显示需要更改语法才能使用 MongoSQL 正常运行的查询。

要生成报告，您必须至少向该工具提供以下详细信息之一：

您的 BI Connector 日志，用于查询分析。
您的集群URI ，用于模式分析。

您可以分析查询和/或模式。

下载 MongoSQL 就绪报告工具。

选择下面适合您操作系统的标签页并下载可执行文件。

下载MongoDB MongoSQL 就绪报告工具。

向就绪报告工具授予执行权限。

如果该文件还没有执行权限，请授予该权限。

 chmod +x <executable-filename>

 chmod +x <executable-filename>

 chmod +x <executable-filename>

（可选）下载并解压您的 BI Connector 日志。

提供 BI Connector 日志后，Readiness Report Tool 即可报告以下信息：

历史查询数据，例如数量和频率。
在 MongoSQL 中会失败的查询语法。
具有关系数据库未知数据类型的集合字段。

对于本地部署的 BI Connector，日志位于您配置 mongosqld 日志路径的位置。

要下载您的 Atlas BI Connector 日志，请执行以下操作：

在 Atlas 用户界面中，转到具有要分析的 BI 连接的 Atlas 集群。
从集群的选项（），选择Download Logs 。
下载 mongosql.gz。
创建一个新目录，然后将mongosql.gz解压缩到其中。

（可选）复制集群URI。

提供Atlas 集群URI可以让就绪报告工具分析您的集合模式并识别包含SQL工具未知数据类型的字段。

要查找Atlas 集群URI，请执行以下操作：

在 Atlas 用户界面中，请前往包含您想要分析的集合的集群。
单击 Connect（连接）。
从连接选项列表中选择 Shell。
仅复制您的连接URI 。
连接 URI 类似于：mongodb+srv://bicluster.example.mongodb.net/。排除Shell可执行文件 mongosh 和任何特定于 shell 的命令行选项。

生成报告。

在终端中，运行准备情况报告工具可执行文件，提供您下载的日志或集群 URI。

必须包含数据库用户名。
您必须包含--input和/或--uri 。如果包含URI ，就绪报告工具会提示您输入数据库用户密码。
您可以为生成的报告指定 --output 目的地。如未指定，它将在当前目录中生成。
您可以指定 --resolver 来为网络请求选择 DNS 解析程序。可能的值为：cloudflare、google 和 quad9。
您可以使用--include或--exclude来缩小命名空间列表的范围。支持 Global 语法。默认，包括所有命名空间。

--help选项返回就绪报告工具选项的完整列表：

<executable-filename> --help
Options:
     -i, --input <INPUT>        Sets the input file or directory to analyze BIC logs (optional). One of `--input` or `--uri` must be provided, or both
     -o, --output <OUTPUT>      Sets the output directory (optional). If not specified, the current directory is used
         --uri <URI>            The Atlas cluster URI to analyze schema (optional). One of `--input` or `--uri` must be provided, or both
     -u, --username <USERNAME>  Username for authentication (optional). This is required if the username and password is not provided in the URI
         --quiet                Enables quiet mode for less output
         --resolver <RESOLVER>  The specified resolver (optional) [possible values: cloudflare, google, quad9]
         --include <INCLUDE>    A list of namespaces to include (optional). If not provided, all namespaces are included. Glob syntax is supported
         --exclude <EXCLUDE>    A list of namespaces to exclude (optional). If not provided, no namespaces are excluded
     -h, --help                 Print help (see more with '--help')
     -V, --version              Print version