MarkLogic中jsonPropertyValueQuery的wildcarded选项跨执行方式结果不一致

环境与场景 #

部署命令 #

我们通过以下Docker命令部署本地MarkLogic实例：

docker run --name marklogic-test -d -it -p 8000:8000 -p 8001:8001 -p 8002:8002 \
 -e MARKLOGIC_INIT=true \
 -e MARKLOGIC_ADMIN_USERNAME=admin \
 -e MARKLOGIC_ADMIN_PASSWORD='Areally!PowerfulPassword1337' \
 marklogicdb/marklogic-db:10.0-9.4-centos-1.0.0-ea4

数据情况 #

Documents数据库仅包含两个JSON文档：

• sample1.json：v3属性值为"0123456789"
• sample2.json：v3属性值为"9876543210"

问题描述 #

在Query Console中执行指定XQuery时，可正确返回仅匹配的sample1.json；但通过REST API调用逻辑一致的带wildcarded选项的jsonPropertyValueQuery查询时，却返回全部两个文档且置信度为0。请问该如何理解此行为？是REST API的Bug还是存在配置遗漏？

核心原因分析 #

这种差异大概率不是REST API的Bug，而是查询选项默认行为差异或索引配置未对齐导致的，具体可从以下方向排查：

1. 查询选项的默认处理差异 #

Query Console执行XQuery时的默认查询选项（如search:options）与REST API的默认选项可能存在差异：

• REST API的jsonPropertyValueQuery使用wildcarded时，是否默认开启了前后通配符匹配，而你在XQuery中使用的是精确前缀/后缀匹配？
• 检查REST API请求中是否正确传递wildcarded参数，是否存在拼写错误（比如误写为wildcard）。

2. 索引配置一致性问题 #

确认Documents数据库的索引配置：

• 检查是否开启了JSON属性值索引（json-property-value索引），且v3字段已被正确索引。Query Console可能会动态创建临时索引，而REST API通常依赖预定义索引。
• 若使用通配符查询，需确保数据库开启了通配符搜索索引（wildcard-searches），否则MarkLogic会退化为全文档扫描，导致不符合预期的结果。

3. 查询语法的细微差异 #

对比XQuery与REST API的查询语句：

• XQuery中的jsonPropertyValueQuery是否指定了额外选项（如"wildcarded=prefix"），而REST API中默认是wildcarded=true（允许前后通配符）？
• 确认REST API的请求格式是否正确，比如POST请求的JSON体是否正确构造查询：

{
  "query": {
    "jsonPropertyValueQuery": {
      "property": "v3",
      "value": "0123*",
      "wildcarded": true
    }
  }
}

4. 置信度为0的含义 #

置信度为0通常表示查询是无索引的全文档扫描，说明MarkLogic无法利用索引匹配查询条件，只能遍历所有文档判断。这进一步指向索引配置问题，或查询选项未正确触发索引使用。

排查步骤建议 #

• 检查Documents数据库索引配置：进入MarkLogic管理界面（8001端口），导航到Databases > Documents > Indexes，确认JSON Property Value Indexes包含v3字段，且Wildcard Searches已开启。
• 对齐查询选项：在Query Console中显式指定与REST API相同的search:options，观察是否出现相同结果。
• 启用查询跟踪：在MarkLogic管理界面开启查询跟踪，对比XQuery与REST API查询的执行计划，查看是否使用相同索引、查询条件解析是否一致。

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