通过Databricks连接Cosmos DB时查询无响应问题排查

以下是几个常见的排查方向，按优先级排序：

1. 验证核心配置的准确性 #

• 确认Cosmos DB端点是否带完整的https://前缀（比如https://<account-name>.documents.azure.com:443/），不要遗漏端口或协议。
• 检查账户密钥是否为Cosmos DB的主密钥（而非只读密钥，除非明确配置只读权限），避免复制时出现空格或特殊字符错误。
• 确认配置的数据库名、容器名与Cosmos DB中实际存在的完全一致（Cosmos DB对名称大小写敏感）。
• 检查Spark目录/表的配置是否包含必要参数：
  创建数据库时需指定账户端点、密钥、数据库名：

  CREATE DATABASE IF NOT EXISTS cosmos_db USING cosmosdb OPTIONS (
    spark.cosmos.accountEndpoint = 'https://your-account.documents.azure.com:443/',
    spark.cosmos.accountKey = 'your-primary-key',
    spark.cosmos.database = 'your-db-name'
  )
  

  创建容器映射表时必须指定容器名：

  CREATE TABLE IF NOT EXISTS cosmos_db.your_container USING cosmosdb OPTIONS (
    spark.cosmos.container = 'your-container-name',
    spark.cosmos.read.inferSchema.enabled = 'true'
  )
  

2. 排查网络与权限问题 #

• 如果Databricks集群部署在VNet中，确认Cosmos DB已配置VNet访问规则，允许集群所在VNet的流量进入。
• 检查Cosmos DB的防火墙设置：若启用IP白名单，需将Databricks集群的公网IP（或Nat网关IP）加入白名单；若允许所有网络访问，需确认该配置已生效。
• 若使用服务主体认证而非账户密钥，需确保服务主体已被授予Cosmos DB的Contributor或Cosmos DB Account Reader Writer角色，且配置中正确指定了spark.cosmos.auth.aad.clientId、spark.cosmos.auth.aad.tenantId、spark.cosmos.auth.aad.clientSecret参数。

3. 检查查询逻辑与数据状态 #

• 先执行最简单的全量查询SELECT * FROM cosmos_db.your_container，确认容器本身是否有数据（避免因过滤条件过严导致无返回）。
• 注意Cosmos DB的SQL语法细节：字段名大小写敏感，嵌套字段需用正确的路径（比如SELECT c.address.city FROM c而非SELECT address.city FROM your_container），避免语法错误导致隐性失败。
• 如果容器数据量较大，检查是否因分区键过滤缺失导致查询超时或扫描过慢：Cosmos DB连接器需要明确的分区键过滤才能高效查询，未指定分区键的全量查询可能需要更长时间，甚至因资源限制中断。

4. 验证连接器版本兼容性 #

• 确认Databricks Runtime版本与连接器版本匹配：azure-cosmos-spark_3-1_2-12:4.14.0对应Spark 3.1、Scala 2.12，需搭配Databricks Runtime 10.x~12.x版本。若使用更高版本的Runtime（如13.x+），需升级连接器到对应兼容版本（比如azure-cosmos-spark_3-3_2-12:4.22.0对应Spark 3.3）。

5. 启用调试日志与指标排查 #

• 在配置中添加spark.cosmos.read.queryMetrics.enabled = true，执行查询后查看返回的queryMetrics，可获取Cosmos DB侧的查询详情（如返回文档数、请求耗时、RU消耗），判断是无数据返回还是请求未到达Cosmos DB。
• 查看Databricks集群的Driver日志，搜索CosmosDB相关关键字，排查是否有认证失败、连接超时、容器不存在等错误信息。

内容的提问来源于stack exchange，提问作者Quynh-Mai Chu