从BI Connector过渡到SQL接口

本指南介绍了如何从MongoDB Connector for BI和Atlas BI Connector迁移到较新的SQL接口。

重要

MongoDB Connector for BI和Atlas BI Connector已于 9 月 2026结束生命周期 (EOL)。

SQL接口

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

与BI Connector相比， SQL接口具有以下优点：

您可以直接连接到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接口之前，请确认您的部署满足迁移目标的先决条件。 MongoDB还建议您生成过渡就绪报告，以帮助规划过渡。

先决条件

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

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

生成过渡就绪报告

MongoDB提供了 MongoSQL 过渡准备工具来帮助您规划从BI Connector到SQL接口的迁移。该工具会根据您过去的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日志后，准备情况报告工具就能报告以下信息：

历史查询数据，例如数量和频率。
在 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