在 Azure Cosmos DB 的 SQL API 中，value 是保留关键字（用于 SELECT VALUE 等语法），直接在 WHERE 子句中使用 d.value 会导致解析错误；解决方法是改用方括号语法 d["value"] 或重命名字段。
在 azure cosmos db 的 sql api 中，`value` 是保留关键字（用于 `select value...` 等语法），直接在 `where` 子句中使用 `d.value` 会导致解析错误；解决方法是改用方括号语法 `d["value"]` 或重命名字段。
当你尝试执行如下查询时：
queryText = "SELECT * FROM test_data d WHERE d.value = 'foo'"
Cosmos DB 会抛出 BadRequest 错误，并提示：Failed to parse token 'value' at position 36
这是因为 value 在 Cosmos DB SQL 语法中具有特殊语义——它专用于 SELECT VALUE 子句（例如 SELECT VALUE d.name 返回裸值而非对象），因此不能作为普通属性名直接通过点号（.）访问。
✅ 正确写法：使用方括号语法（JSON 路径访问符）绕过关键字解析冲突：
queryText = "SELECT * FROM test_data d WHERE d[\"value\"] = 'foo'" # 或等价写法（单引号内转义更清晰） queryText = "SELECT * FROM test_data d WHERE d['value'] = 'foo'"
该语法明确告诉查询引擎：此处 "value" 是一个字符串键名，而非 SQL 关键字，从而成功匹配 {"id": "1", "value": "foo"} 类型的项。
⚠️ 注意事项：
- 所有 Cosmos DB 保留关键字（如
value,type,id,rid,self,array,object,string,number,boolean,null,true,false,undefined,min,max,sum,avg,count等）在用作属性名时，都应优先采用d["xxx"]形式； - 避免在建模阶段使用保留关键字作为属性名——尽管技术上可行（借助方括号），但会降低可读性、增加维护成本，并可能在工具链（如 SDK 自动生成、可视化查询编辑器、BI 连接器）中引发兼容性问题；
- 若已存在大量
value字段且无法重构，建议在应用层统一封装查询逻辑，例如封装为安全的查询构造函数：
def safe_eq(field_name: str, value: str) -> str:
return f"d[\"{field_name}\"] = '{value}'"
queryText = f"SELECT * FROM test_data d WHERE {safe_eq('value', 'foo')}"
? 总结：Cosmos DB 的 SQL 并非完全兼容标准 SQL，其保留字规则更严格。遇到解析失败时，优先检查字段名是否撞上保留关键字；使用 d["field"] 是最直接、零成本的修复方式，无需修改数据结构或迁移数据。
