如何用MarkLogic Java API实现搜索结果高亮并集成自定义词典？

MarkLogic作为企业级多模型数据库，其内置的搜索引擎支持对XML、JSON以及文本文档进行全文检索。通过Java Client API，开发者可以在不接触XQuery的前提下，用纯Java代码完成复杂查询、结果高亮以及词典扩展。高亮功能依赖服务端在返回结果时嵌入特定标记，而自定义词典则让分词器理解领域专有名词，两者结合能显著改善搜索可用性与准确率。

一、环境准备与依赖引入

在开始编码前，需要确保本地或测试环境已部署MarkLogic Server，并且目标数据库开启了全文索引。Java项目通常通过Maven管理依赖，核心包为marklogic-client-api，它封装了REST API的底层通信。版本选择需与服务器大版本保持一致，避免协议不兼容。

以下为典型的Maven依赖配置，其中marklogic-client-api提供了DatabaseClient等入口类，jaxb相关依赖用于对象与XML映射。若项目使用Gradle，可参照相同坐标进行转换。引入后，即可在代码中通过BasicAuthContext建立带认证的会话。

<dependency>
    <groupId>com.marklogic</groupId>
    <artifactId>marklogic-client-api</artifactId>
    <version>5.5.0</version>
</dependency>
<dependency>
    <groupId>javax.xml.bind</groupId>
    <artifactId>jaxb-api</artifactId>
    <version>2.3.1</version>
</dependency>

二、建立DatabaseClient与查询选项

DatabaseClient是全部操作的起点，它需要主机、端口、用户及认证上下文。生产环境中建议将连接参数外部化到配置文件，并通过连接池限制并发数。创建完成后，我们利用QueryOptionsBuilder构造查询选项，这是实现高亮的关键步骤。

QueryOptionsBuilder允许设置返回片段的长度、高亮标签名称以及是否包含匹配计数。通过returnMetrics和returnFacets可控制额外负载。下面的代码展示了如何声明高亮标签为em，并限定每个结果返回两段摘要。注意builder.build方法生成的是XML字符串，可直接随查询提交。

import com.marklogic.client.DatabaseClient;
import com.marklogic.client.DatabaseClientFactory;
import com.marklogic.client.query.QueryOptionsBuilder;
import com.marklogic.client.query.QueryManager;
import com.marklogic.client.query.StringQueryDefinition;

DatabaseClient client = DatabaseClientFactory.newClient(
    "localhost", 8000, "myDB",
    new DatabaseClientFactory.BasicAuthContext("admin", "password"));

QueryManager queryMgr = client.newQueryManager();
QueryOptionsBuilder builder = queryMgr.newQueryOptionsBuilder();
builder.returnResults(true)
       .returnMetrics(true)
       .highlight("em")
       .snippetMaxSnippets(2)
       .snippetMaxWords(30);
String options = builder.build();

三、提交高亮搜索请求

配置好选项后，使用StringQueryDefinition执行关键字检索。该定义接受原始查询字符串，服务端会按默认解析器处理。将前面生成的options通过setOptions方法绑定，即可在响应中得到带em标签的片段。提取时遍历MatchDocumentSummary，调用getMatchSnippet获取文本。

以下示例搜索“分布式事务”，并打印每个命中文档的URI与高亮片段。可以看到高亮逻辑完全由服务端完成，前端只需渲染em样式。这种方式减轻了浏览器负担，也避免了敏感词在客户端二次处理。若需调试，可先输出原始XML响应确认标签位置。

StringQueryDefinition query = queryMgr.newStringDefinition();
query.setCriteria("分布式事务");
query.setOptions(options);

queryMgr.search(query, 1).getMatchResults().forEach(result -> {
    System.out.println("URI: " + result.getUri());
    result.getMatchSnippet().forEach(snippet -> {
        System.out.println("片段: " + snippet.getText());
    });
});

四、自定义词典的集成方式

默认分词器对中文采用单字或二元切分，难以识别“联机分析处理”这类复合词。MarkLogic支持上传词典文件到指定数据库，并在查询选项里引用。词典通常为纯文本，每行一个词条，服务端加载后会在索引与查询解析阶段优先匹配。

在Java端，词典注册分两步：先通过REST API或QConsole将词典存入modules数据库，再在QueryOptionsBuilder中调用termDictionary方法关联。下例假设词典名为industry-terms.txt且已部署。集成后，搜索“联机分析处理”将整体命中，而非拆成散字，高亮也会标注整个词组。

builder.termDictionary("/dictionaries/industry-terms.txt");
String optionsWithDict = builder.build();

StringQueryDefinition q2 = queryMgr.newStringDefinition();
q2.setCriteria("联机分析处理");
q2.setOptions(optionsWithDict);
queryMgr.search(q2, 1);

五、方案对比与注意事项

服务端高亮加词典的方案，优势在于逻辑集中、结果一致，适合多端复用。劣势是每次变更词典需重新加载，且高亮标签样式受服务端约束。另一种常见思路是客户端高亮：服务端返回纯文本，前端用JavaScript替换关键词。这在词典动态性要求极高时更灵活，但需防范XSS注入。

实践中，若业务词库稳定，优先采用本文的服务端模式。同时应注意查询选项缓存，避免重复build造成性能浪费。对于大文档，建议配合fragment路径限定高亮范围，减少响应体积。掌握这些细节后，搜索体验优化便可控且易维护。

六、完整调用示例小结

将上述环节组合，可封装一个SearchService类，暴露searchWithHighlight方法。内部统一处理client生命周期与option构建，业务层仅传入关键词与词典路径。这样既能满足自定义词典集成，又让高亮成为默认能力，降低调用方认知成本。

最后提醒，MarkLogic的Java API随版本演进可能增加流式接口，编写时请查阅对应版本文档。遇到高亮失效，先检查数据库是否启用词元索引，再确认options是否正确提交。理清这两点，大部分集成问题都能快速定位。

MarkLogicJava_APIsearch_highlight修改时间：2026-08-05 04:39:30