从 Azure Cosmos DB 导入

重要

对机器学习工作室（经典）的支持将于 2024 年 8 月 31 日结束。 建议在该日期之前转换到 Azure 机器学习。

从 2021 年 12 月 1 日开始，你将无法创建新的机器学习工作室（经典）资源。 在 2024 年 8 月 31 日之前，可继续使用现有的机器学习工作室（经典）资源。

• 请参阅有关将机器学习项目从 ML 工作室（经典）移到 Azure 机器学习的信息。
• 详细了解 Azure 机器学习。

ML 工作室（经典）文档即将停用，将来可能不会更新。

本文介绍如何使用机器学习 Studio (经典) 中的 "导入数据" 模块从 Azure Cosmos DB 导入数据，以便在机器学习试验中使用。

注意

适用于：仅限机器学习 Studio (经典)

可在 Azure 机器学习设计器中获取类似的拖放模块。

Azure Cosmos DB使用灵活的数据模型支持 NoSQL 数据库存储。 在此数据存储中使用 SQL api 来进行机器学习的优点包括：快速、可预测的性能、自动缩放、全局分发和丰富的查询功能。

与 Azure SQL 数据库一起，此选项可用于动态筛选传入的数据集。

了解其工作原理：了解 Azure Cosmos DB

• 若要开始使用 Azure Cosmos DB 中的数据进行机器学习，您必须有权访问包含相关文档集合的现有 Azure Cosmos DB 帐户。

注意

机器学习 Studio 中的用户界面 (经典) 仍在多个位置使用名称 DocumentDB。 因此，即使已将 API 合并到 Azure Cosmos DB 中，你也可以继续查看 DocumentDB 的引用。

如何将数据导入到 Azure Cosmos DB

我们强烈建议你在导入数据前对其进行分析，以确保架构符合预期。 导入过程扫描一些头行来确定架构，但后面的行可能包含额外的列或导致错误的数据。

使用向导导入数据

模块提供了一个新的向导，可帮助您选择存储选项，从现有订阅和帐户中选择，并快速配置所有选项。

1. 将 " 导入数据 " 模块添加到试验中。 您可以在 " 数据输入和输出" 下找到该模块。

2. 单击 " 启动导入数据向导 "，然后按照提示进行操作。

3. 完成配置后，若要实际将数据复制到试验中，请右键单击该模块，然后选择 " 运行所选项"。

提示

如果需要编辑现有的数据连接，向导将加载以前的所有配置详细信息。 无需从头开始重新启动。

手动设置 "导入数据" 模块中的属性

以下步骤说明如何手动配置导入源。

1. 将 " 导入数据 " 模块添加到试验中。 您可以在 " 数据输入和输出 " 类别中找到此模块。

2. 对于 " 数据源"，请选择 " Azure DocumentDB"。

   你可能需要提供文档数据库的连接信息。

   提示

   在机器学习 Studio 中查找选项的名称 (经典) ，以便在以后更改。 导入功能不受名称更改的影响。

3. 对于 终结点 URL，请在 Azure 门户中单击 " 密钥"，然后将 " URI " 字段的内容复制到页面顶部。

4. 对于 " 数据库 ID"，请粘贴要使用的数据库的名称。

   若要从 Azure 门户获取数据库名称，请单击 " 文档资源管理器"。 您可以在此窗格中查看数据库和集合的列表。

5. 对于 DocumentDB 密钥，粘贴帐户的访问密钥。

   若要查找密钥，请单击 " 密钥"，然后复制 "主密钥" 或 "辅助密钥 " 字段的内容。

6. 对于 " 集合 ID"，请键入集合的名称，如指定的 CosmosDB 数据库中所示。

7. 使用SQL 查询和SQL 查询参数选项，为数据定义 SQL 查询和筛选条件。

   对于SQL 查询，请键入一个查询，用于定义要从集合中检索的数据。 建议你提前使用 查询资源管理器 来创建和测试 CosmosDB 查询。

   对于SQL 查询参数，提供 JSON 格式的表达式，该表达式可用于动态筛选返回的数据。 通常，在将实验作为 Web 服务的一部分运行时，提供参数值的实际值。

   如果使用参数，则必须将筛选器变量名称定义为 " SQL 查询" 文本框中指定的 WHERE 子句的一部分。

   如果未指定筛选表达式，则默认情况下，该值设置为 " {} "，并返回所有记录。

   有关 CosmosDB 的详细 SQL 信息，请参阅技术说明部分。

8. 如果要重复使用现有结果，请选择 " 使用缓存的结果 " 选项。

   如果取消选择此选项，则每次运行实验时都会从源中读取数据，不管数据是否相同。

   机器学习无法将缓存的数据与 CosmosDB 帐户中的数据进行比较。 因此，无法从机器学习执行增量更新。

   如果要仅在数据发生更改时重新导入，则必须在其他应用程序中定义该逻辑，如 Azure 数据工厂。 有关详细信息，请参阅使用 Azure 数据工厂将数据移入和移出 Azure Cosmos DB。

9. 运行试验，或只选择 " 导入数据 " 模块，并单击 " 运行所选项"。

结果

运行模块或实验后，可以右键单击模块的输出，以表格格式显示结果。

若要将机器学习工作区中的此数据的快照捕获为数据集，可以右键单击模块的输出并选择 "另存为数据集"。 不过，这样做只捕获导入时可用的数据。 如果预计数据经常更改，请根据需要重新运行 导入数据 。

示例

有关如何使用 Azure Cosmos DB 作为机器学习的数据源的详细演练，请参阅Azure AI 库。

• Azure Cosmos DB SQL 查询：本文介绍了如何对 Azure Cosmos DB 数据执行 SQL 查询。

技术说明

本部分包含高级配置选项以及常见问题的解答。

简单查询和参数化查询的示例

假设您只想在10000英尺下面的火山上使用数据。

简单查询

将以下查询粘贴到 " SQL 查询" 文本框中：Select * from volcanodb where volcanodb.Elevation < 10000

在这种情况下，筛选表达式的值设置为 " {} "，并返回所有记录。

参数化查询

若要仅获取与特定国家/地区相关的火山数据，可以将 "国家/地区" 值指定为在运行时传递给查询的参数。 这需要进行以下更改：

1. 在 " SQL 查询" 文本框中，定义一个作为 SQL 查询的一部分应用 Country 于字段的变量：

   Select * from volcanodb where volcanodb.Country = @param1

2. 在 " SQL 查询参数" 文本框中，以 JSON 格式指定参数名称和值，如下所示：

   {"@param1":"Turkey"}

资源

如果你没有现有的文档存储，请参阅以下文章开始使用。

• Azure Cosmos DB：使用 .NET 和 Azure 门户生成 SQL API Web 应用

• 快速入门：生成 .NET 控制台应用以管理 Azure Cosmos DB SQL API 资源

• Azure Cosmos DB 迁移工具

数据迁移和查询语法帮助

有关 JSON 数据存储的查询示例，请下载Azure Cosmos DB 查询备忘单。

如果需要将内容上载到 Azure Cosmos DB 中，我们建议Azure Cosmos DB 迁移工具。 它对你的数据进行验证、上传和索引。 该工具支持多个源，包括 MongoDB、Amazon DynamoDB、HBase、SQL Server 数据库和 CSV 文件。

使用无架构查询

如果数据一致且可预测，则可以使用简单的 SQL 类似语法，例如 SELECT * FROM <document collection> 。 这称为无 架构查询 ，因为尚未将要返回的确切属性命名为。 此类查询将返回指定集合中的所有字段和所有行。

但是，如果文档架构不一致，则不指定架构可能会导致意外结果或运行时错误。 这是因为导入 数据 模块尝试根据预先确定的行数推断架构，如下所示：

1. 如果未指定任何属性，模块将扫描 CosmosDB 数据库中的第一行。
2. 该模块基于属性创建列名，并基于示例行猜测列数据类型。
3. 如果以后的行包含任何新的或不同的属性，则生成运行时错误。

因此，建议始终指定从 CosmosDB 数据存储返回的属性和值。 例如，我们建议 SELECT * 命名查询检索到的所有属性，而不是使用 语法，如下所示：

SELECT MyTable.Gender, MyTable.Age, MyTable.Name FROM <document collection>

模块参数

下表仅包含适用于 Azure Cosmos DB 选项的导入数据模块的参数。

名称	范围	类型	必须	默认	说明
数据源	list	HTTP	必需	无	数据源可以是 HTTP、FTP、匿名 HTTPS 或 FTPS、Azure BLOB 存储中的文件、Azure 表、Azure SQL 数据库、Hive 表、OData 终结点或 Azure Cosmos dB。
端点 URL	any	字符串	必需	无	提供 Azure Cosmos DB 服务器的 URI
数据库 ID	any	字符串	必需	无	提供 Azure Cosmos DB 数据库的名称
DocumentDB 密钥	any	SecureString	必需	无	为 Azure Cosmos DB 帐户提供有效的 API 密钥
集合 ID	any	字符串	必需	无	在 Azure Cosmos DB 数据库中提供集合的名称
SQL 查询	any	字符串	必需	无	一SQL查询，指定从 Azure Cosmos DB 数据存储返回的记录

Outputs

名称	类型	说明
结果数据集	数据表	包含已下载数据的数据集

例外

异常	描述
错误 0003	如果一个或多个输入为 null 或为空，则会发生异常。
错误 0029	如果传递的 URI 无效，则会发生异常。
错误 0002	如果一个或多个参数无法分析或者无法从指定的类型转换成目标方法所需的类型，则会发生异常。
错误 0048	如果无法打开文件，则会发生异常。
错误 0049	如果无法分析文件，则会发生异常。

有关特定于工作室和经典 (模块) 的列表，请参阅机器学习代码。

有关 API 异常的列表，请参阅机器学习 REST API代码。

另请参阅

导入数据
导出数据
通过 HTTP 从 Web URL 导入
从配置单元查询导入
从 Azure SQL 数据库导入
从 Azure Blob 存储导入
从数据馈送提供程序导入
从本地 SQL Server 数据库导入