Spring Boot中Azure Cosmos DB @Query查询无结果问题求助

我拥有一个Azure Cosmos DB容器RouteZipcodes，其中存储着包含路线及对应服务邮编的JSON文档，示例数据如下。在Azure门户执行指定SQL查询可正常返回对应的routeName，但在Spring Boot应用的CosmosRepository中使用@Query注解执行相同逻辑的查询时却无结果，其他Repository方法均可正常工作，请求排查解决。

示例数据 #

{
  "id": "2347z3e8-850d-364a-92d2-4fcae2fa5642",
  "routeName": "THORN1",
  "zips": [
    { "zipCode": "80373" },
    { "zipCode": "80371" },
    { "zipCode": "80020" },
    { "zipCode": "80370" },
    { "zipCode": "80021" },
    { "zipCode": "80040" },
    { "zipCode": "80602" },
    { "zipCode": "80372" }
  ],
  "status": "A"
}

Azure门户查询语句 #

SELECT r.routeName as routeName
FROM routeZipcodes r
JOIN rz in r.zips
where rz.zipCode = "80602"

门户查询结果 #

[ { "routeName": "THORN1" } ]

Spring Boot Repository代码 #

@Repository
public interface RouteZipcodesRepository extends CosmosRepository<RouteZipcodes, String> {
    
    Optional<RouteZipcodes> findById(String id);
    Optional<List<RouteZipcodes>> findByHubName(String hubName);
    Optional<RouteZipcodes> findByRouteName(String routeName);
    
//  @Query("SELECT r.routeName FROM routeZipcodes r JOIN rz in r.zips where rz.zipCode = \"@zipcode\"")
//  String findByZipCode (@Param("zipcode") String zipcode);
    
    @Query("SELECT r.routeName as routeName FROM routeZipcodes r JOIN rz in r.zips where rz.zipCode = \"@zipcode\"")
    List<IRouteNameByZipcode> findByZipCode (@Param("zipcode") String zipcode);
}

1. 参数绑定语法错误 #

Spring Data Cosmos DB中，参数占位符@zipcode不需要用双引号包裹。你当前的查询语句把参数放在双引号内，导致框架无法正确替换参数值，而是直接将"@zipcode"作为字符串去匹配zipCode，自然查不到结果。

修正后的查询代码：

@Query("SELECT r.routeName as routeName FROM routeZipcodes r JOIN rz in r.zips where rz.zipCode = @zipcode")
List<IRouteNameByZipcode> findByZipCode (@Param("zipcode") String zipcode);

2. 容器名称大小写不匹配 #

Azure Cosmos DB的容器名称是大小写敏感的。如果你的实际容器名称是RouteZipcodes（首字母大写），但查询语句中用了小写的routeZipcodes，会导致查询找不到目标容器。

修正方式：
将查询语句中的容器名称改为实际的RouteZipcodes：

@Query("SELECT r.routeName as routeName FROM RouteZipcodes r JOIN rz in r.zips where rz.zipCode = @zipcode")
List<IRouteNameByZipcode> findByZipCode (@Param("zipcode") String zipcode);

3. 投影结果与返回接口不匹配 #

确保IRouteNameByZipcode接口定义正确，必须包含与查询返回字段对应的 getter 方法，Spring Data才能正确映射结果。

示例接口定义：

public interface IRouteNameByZipcode {
    String getRouteName();
}

4. 索引策略验证（可选） #

虽然门户查询能返回结果，但可以确认容器的索引策略是否包含/zips/zipCode/*路径。如果索引未覆盖该字段，可能会影响查询性能，但通常不会导致无结果返回。若需要优化，可在容器索引配置中添加该路径。

内容的提问来源于stack exchange，提问作者Pavan