Azure Cosmos DB（DocumentDB）在Java中是否有@Query替代注解？

首先明确：Azure Cosmos DB 的原生 Java SDK（包括旧的 DocumentDB SDK）并没有提供和 JPA/SQL 驱动完全一致的 @Query 注解，不过在 Spring 生态下，Spring Data for Azure Cosmos DB 提供了类似的注解来实现自定义查询，而原生 SDK 则需要通过代码构建查询逻辑。

1. Spring Data Azure Cosmos DB 中的替代：@Query 注解 #

如果你在使用 Spring 框架，Spring Data for Azure Cosmos DB 确实提供了 @Query 注解，用法和 JPA 里的非常相似，你可以直接在 Repository 接口的方法上标注它，传入 Cosmos DB 的 SQL 查询语句。

举个实际的代码示例：

import com.azure.spring.data.cosmos.repository.Query;
import com.azure.spring.data.cosmos.repository.CosmosRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.stereotype.Repository;
import java.util.List;

@Repository
public interface UserRepository extends CosmosRepository<User, String> {

    // 使用@Query自定义查询，参数绑定用@Param指定
    @Query("SELECT * FROM c WHERE c.email = @email")
    List<User> findByEmail(@Param("email") String email);
}

这里的@Query注解来自com.azure.spring.data.cosmos.repository.Query包，参数绑定逻辑和 JPA 完全一致，能满足你通过注解定义自定义查询的需求。

2. 原生 Azure Cosmos DB Java SDK（无 Spring）的替代方案 #

如果是直接使用原生 SDK（比如azure-cosmos客户端库），就需要手动构建SqlQuerySpec来执行自定义查询，没有现成的注解可以直接使用。示例代码如下：

import com.azure.cosmos.CosmosClient;
import com.azure.cosmos.CosmosClientBuilder;
import com.azure.cosmos.CosmosContainer;
import com.azure.cosmos.models.SqlQuerySpec;
import com.azure.cosmos.models.SqlParameter;
import com.azure.cosmos.util.CosmosPagedIterable;

// 初始化Cosmos客户端和目标容器
CosmosClient client = new CosmosClientBuilder()
        .endpoint("你的Cosmos DB端点")
        .key("你的Cosmos DB密钥")
        .buildClient();
CosmosContainer container = client.getDatabase("目标数据库名").getContainer("目标容器名");

// 构建自定义查询规范
String queryText = "SELECT * FROM c WHERE c.age > @age";
SqlQuerySpec querySpec = new SqlQuerySpec(queryText, 
        new SqlParameter("@age", 18));

// 执行查询并处理结果
CosmosPagedIterable<User> queryResults = container.queryItems(querySpec, null, User.class);
queryResults.forEach(user -> System.out.println("查询到用户：" + user.getName()));

这种方式需要手动创建查询规范，然后调用容器的queryItems方法执行，虽然没有注解那么简洁，但完全可以实现自定义查询的需求。

补充说明 #

旧的 DocumentDB SDK（比如azure-documentdb包）的逻辑和原生 SDK 类似，也是通过构建SqlQuerySpec来执行自定义查询，没有对应的注解支持。

总结一下：如果用 Spring 生态，直接用 Spring Data Cosmos DB 提供的@Query注解即可；如果用原生 SDK，就手动构建查询规范来实现自定义查询。

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