如何通过Java API获取MarkLogic中的分面信息？

你遇到的核心问题是没有配置查询选项来启用分面返回，而且旧版的QueryOptionsBuilder确实在新的MarkLogic Java Client API中被移除了，现在我们需要用QueryOptionsManager或者动态的OptionsHandle来定义分面配置。下面是详细的解决方案：

第一步：确认元素范围索引配置正确 #

首先确保你创建的integerQuery元素范围索引满足：

• 类型为xs:int（匹配你的JSON字段值类型）
• 作用域是JSON属性（Element Range Index for JSON property）
• 索引状态为已启用

第二步：使用新版API配置分面选项 #

新版API推荐用JSON格式的查询选项来定义分面，你可以选择动态传递选项（无需保存到服务器）或者保存选项到服务器（可重复使用），下面分别给出两种方式：

方式1：动态传递分面选项（适合临时查询） #

这种方式不需要把配置保存到服务器，直接在查询时传递：

import com.marklogic.client.DatabaseClient;
import com.marklogic.client.DatabaseClientFactory;
import com.marklogic.client.auth.DigestAuthContext;
import com.marklogic.client.query.*;
import com.marklogic.client.io.JacksonHandle;
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class FacetExample {
    public static void main(String[] args) {
        // 创建数据库客户端
        DatabaseClient client = DatabaseClientFactory.newClient(
            "10.53.195.198", 6010, "nosql",
            new DigestAuthContext("admin", "admin")
        );
        
        try {
            QueryManager queryManager = client.newQueryManager();
            StructuredQueryBuilder queryBuilder = queryManager.newStructuredQueryBuilder();
            
            // 构建查询（这里用or匹配所有文档，可替换为实际过滤条件）
            StructuredQueryDefinition def = queryBuilder.or();
            
            // 1. 定义分面选项JSON
            ObjectMapper mapper = new ObjectMapper();
            String facetOptionsJson = "{\"facets\": {\"integerQuery\": {\"type\": \"xs:int\", \"facetValues\": true}}}";
            JsonNode optionsNode = mapper.readTree(facetOptionsJson);
            
            OptionsHandle optionsHandle = new OptionsHandle();
            optionsHandle.set(optionsNode);
            
            // 2. 执行搜索并应用分面选项
            SearchHandle handle = queryManager.search(def, new SearchHandle(), optionsHandle);
            
            // 3. 解析并打印分面结果
            FacetResult facetResult = handle.getFacetResult("integerQuery");
            if (facetResult != null) {
                System.out.println("分面名称: " + facetResult.getName());
                for (FacetValue facetValue : facetResult.getFacetValues()) {
                    System.out.println("值: " + facetValue.getName() + ", 匹配文档数: " + facetValue.getCount());
                }
            } else {
                System.out.println("未找到分面结果，请检查索引配置是否生效");
            }
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // 关闭客户端连接
            client.release();
        }
    }
}

方式2：保存分面选项到服务器（适合重复使用） #

如果多个查询需要用到相同的分面配置，可以把选项永久保存到服务器：

// 在客户端创建后，先保存选项到服务器
QueryOptionsManager optionsManager = client.newQueryOptionsManager();
String optionsName = "integer-facet-config";

// 定义分面选项JSON
String facetOptionsJson = "{\"facets\": {\"integerQuery\": {\"type\": \"xs:int\", \"facetValues\": true}}}";
JacksonHandle optionsHandle = new JacksonHandle(facetOptionsJson);

// 保存选项
optionsManager.writeOptions(optionsName, optionsHandle);

// 后续搜索时直接使用选项名称
SearchHandle handle = queryManager.search(def, new SearchHandle(), optionsName);

关键注意事项 #

1. 分面选项匹配索引类型：facets配置中的type必须和你创建的元素范围索引类型完全一致（这里是xs:int），否则无法正确关联索引。
2. 查询条件覆盖范围：如果你的or查询没有子条件，会匹配数据库中所有文档，这样才能返回完整的分面计数；如果需要过滤文档，在queryBuilder.or()中添加对应的子查询即可。
3. 索引生效验证：如果仍然返回null，建议通过MarkLogic管理界面检查integerQuery的范围索引是否已完成构建，数据库是否完成了重新索引操作。

内容的提问来源于stack exchange，提问作者Rakesh .p