Azure Cosmos DB v2 (Beta)

总结

项目	说明
发布状态	Beta
产品	Power BI（语义模型） Power BI（数据流） Fabric（数据流 Gen2）
支持的身份验证类型	源密钥

先决条件

• 一个 Azure Cosmos DB 帐户。

支持的功能

• 导入
• DirectQuery（Power BI 语义模型）
• 高级选项
  • 重试次数
  • 启用“AVERAGE”函数向下传递
  • 为多个列启用“SORT”向下传递

连接到 Azure Cosmos DB

要连接到 Azure Cosmos DB 数据：

1. 启动 Power BI Desktop。

2. 在主页选项卡中，选择获取数据。

3. 在搜索框中，输入 Cosmos DB v2。

4. 选择 Azure Cosmos DB v2（测试版），然后选择连接。

   

5. 在 Azure Cosmos DB v2 连接页面上，对于 Cosmos 端点，输入要使用的 Azure Cosmos DB 帐户的 URI。 对于数据连接模式，选择适合用例的模式，遵循以下一般准则：

   • 对于较小的数据集，选择导入。 使用导入模式时，Power BI 使用 Cosmos DB 导入整个数据集的内容，以便在可视化效果中使用。

   • DirectQuery 模式允许查询下推到 Cosmos DB 容器，以便执行并改进连接器的性能。 对于分区的 Cosmos DB 容器，如果查询还包含分区键上的筛选器（WHERE 子句），则具有聚合函数的 SQL 查询将向下传递到 Cosmos DB。 例如，如果将分区键定义为“产品”，则可以在 Cosmos DB 服务器上向下传递和执行 SQL 查询：

     SELECT SUM(ColumnName) FROM TableName where Product = 'SampleValue'

   注意

   如果要对 Cosmos DB 容器执行跨分区聚合函数，请使用 Azure Synapse Link for Azure Cosmos DB。

   详细信息：

   • Power BI 服务中的语义模型模式

   • 在 Power BI Desktop 中使用 DirectQuery

   

6. 在提示配置数据源身份验证时，输入帐户密钥。 然后选择“连接”。 数据目录、数据库和表显示在导航器对话框中。

7. 在显示选项窗格中，选中要使用的数据集的对应复选框。

   

8. 指定分区键筛选器（以便可以将聚合函数向下推送到 Cosmos DB）的最佳方法是使用动态 M 参数。 要使用动态 M 参数，需要创建具有唯一分区键值的数据集，创建参数，将其添加为主数据集的筛选器，将其绑定到唯一分区键数据集，并将其用作主数据集的切片器。 使用以下步骤为分区键筛选启用动态 M 参数。

   a. 创建具有唯一分区键值的数据集：

   在导航器中，选择转换数据而不是加载，以打开 Power Query 编辑器。 右键单击查询数据集，然后选择复制以创建新数据集。

   

   重命名新的分区键模型，然后右键单击 Cosmos DB 分区键列。 在此示例中，产品是 Cosmos DB 分区键列。 选择删除其他列，然后选择删除重复项。

   

   b. 创建用于动态筛选的参数：

   在 Power Query 编辑器中，选择管理参数>新参数。 重命名新参数，以反映筛选器参数，并将有效值输入为当前值。

   

   c. 对主数据集应用参数化筛选器：

   选择分区键列的下拉列表图标，然后选择文本筛选器>等于。 将筛选器类型从“文本”更改为“参数”。 然后选择在步骤 b 中创建的参数。 选择Power Query 编辑器左上角的关闭并应用。

   

   d. 使用参数绑定创建分区键值切片器：

   在 Power BI 中，选择模型选项卡。然后选择“分区键”字段。 从“属性”窗格中，选择高级>绑定到参数。 选择在步骤 b 中创建的参数。

   

   选择报表选项卡，然后添加具有唯一分区键的切片器。

   

   e. 从切片器添加可视化效果并应用分区键筛选器：

   由于切片器上的所选分区键值绑定到参数（在步骤 d 中完成），并且将参数化筛选器应用于主数据集（在步骤 c 中完成），因此将作为主数据集的筛选器应用所选分区键值，并且分区键筛选器的查询将向下传递到所有可视化效果中的 Cosmos DB。

   

高级选项

Power Query 提供一组高级选项，可以根据需要将这些选项添加到查询中。

下表列出了可以在 Power Query 中设置的所有高级选项。

高级选项	说明
重试次数	存在 HTTP 返回代码 408 - Request Timeout、412 - Precondition Failed 或 429 - Too Many Requests 时的重试次数。 默认尝试次数为 5。
启用 AVERAGE 函数向下传递	指定连接器是否允许将 AVG 聚合函数向下传递到 Cosmos DB。 默认值为 1，连接器默认尝试将 AVG 聚合函数向下传递到 Cosmos DB。 如果参数包含 AVG 聚合函数的字符串、布尔值或 null 值，则 Cosmos DB 服务器将返回未定义的结果集。 设置为 0 值时，不会将 AVG 聚合函数向下传递到 Cosmos DB 服务器，并且连接器将处理执行 AVG 聚合操作本身。
为多个列启用 SORT 向下传递	指定连接器是否允许将在 SQL 查询的 ORDER BY 子句中指定的多个列向下传递到 Cosmos DB。 默认值为 0，如果在 ORDER BY 子句中指定了多个列，则连接器默认情况下不会向下传递列，而是自行处理执行顺序。 设置为值 1 时，连接器会在 SQL 查询的 ORDER BY 子句中指定时尝试将多个列向下传递到 Cosmos DB。 要允许将多个列向下传递到 Cosmos DB，请确保对相应集合中的列设置组合索引。 对于分区集合，仅当查询包含分区键的筛选器时，才会将 ORDER BY 的 SQL 查询向下传递到 Cosmos DB。 此外，如果在 ORDER BY 子句中指定了八个以上的列，连接器不会向下传递 ORDER BY 子句，而是处理排序执行本身。

已知问题和限制

• 对于分区的 Cosmos DB 容器，如果查询还包含分区键上的筛选器（WHERE 子句），则具有聚合函数的 SQL 查询将向下传递到 Cosmos DB。 如果聚合查询不包含分区键上的筛选器，则连接器将执行聚合。

• 如果在应用 TOP 或 LIMIT 后调用聚合函数，则连接器不会向下传递聚合函数。 Cosmos DB 在处理查询时处理 TOP 操作。 例如，在以下查询中，在子查询中应用 TOP，而将聚合函数应用于该结果集的顶部：

  SELECT COUNT(1) FROM (SELECT TOP 4 * FROM EMP) E

• 如果在聚合函数中提供了 DISTINCT，则连接器不会在聚合函数中提供 DISTINCT 子句时将聚合函数向下传递到 Cosmos DB。 聚合函数中存在时，Cosmos DB SQL API 不支持 DISTINCT。

• 对于 SUM 聚合函数，如果 SUM 中的任何参数是字符串、布尔值或 null，则 Cosmos DB 将返回未定义的结果集。 但是，如果有 null 值，连接器会将查询传递给 Cosmos DB，这样就会作为 SUM 计算的一部分，要求数据源将 null 值替换为零。

• 对于 AVG 聚合函数，如果 SUM 中的任何参数是字符串、布尔值或 null，则 Cosmos DB 将返回未定义的结果集。 连接器会公开连接属性，以禁用将 AVG 聚合函数向下传递给 Cosmos DB，以防需要替代此默认 Cosmos DB 行为。 禁用 AVG 向下传递时，不会将其向下传递到 Cosmos DB，连接器将处理执行 AVG 聚合操作本身。 有关详细信息，请转到高级选项中的“启用 AVERAGE 函数向下传递”。

• 连接器当前不支持具有大型分区键的 Azure Cosmos DB 容器。

• 由于服务器限制，对以下语法禁用聚合向下传递：

  • 当查询未筛选分区键或分区键筛选器在 WHERE 子句的顶层将 OR 运算符与另一个谓词一起使用时。

  • 当查询有一个或多个分区键出现在 WHERE 子句中的 IS NOT NULL 子句中时。

• V2 连接器不支持复杂的数据类型，如数组、对象和分层结构。 对于这些场景，我们建议使用适用于 Azure Cosmos DB 的 Fabric 镜像功能。

• V2 连接器使用前 1,000 个文档的采样来得出推断的架构。 仅更新文档的一部分时，不建议将其用于架构演变场景。 例如，包含数千个文档的容器中某个文档的新添加属性可能不会包含在推断的架构中。 对于这些场景，我们建议使用适用于 Azure Cosmos DB 的 Fabric 镜像功能。

• 目前，V2 连接器不支持对象属性中的非字符串值。

• 由于服务器限制，对以下语法禁用筛选器向下传递：

  • 在 WHERE 子句中引用包含一个或多个聚合列的查询时。