eXist-DB中XQuery未使用已配置范围索引的问题排查求助

一、索引未使用的常见排查点 #

• 命名空间一致性检查：确保@xlink:from的命名空间在查询语句和collection.xconf中完全一致。比如collection.xconf里需声明：

  <namespace prefix="xlink" uri="http://www.w3.org/1999/xlink"/>
  

  查询语句中也必须绑定相同URI的前缀：

  declare namespace xlink="http://www.w3.org/1999/xlink";
  

  前缀名可自定义，但URI必须完全匹配，否则索引无法关联。
• 索引路径准确性：检查collection.xconf中范围索引的<path>配置是否精准指向目标属性。比如要匹配所有含@xlink:from的节点，路径应写为//*[@xlink:from]，避免节点层级错误或属性名拼写失误（如xlink:form）。
• 索引重建验证：修改collection.xconf后，必须重启eXist-db或在Dashboard中对目标集合执行Rebuild Index操作。未重建的话，旧索引不会更新，新配置无法生效。
• 查询写法兼容性：范围索引仅支持等值、范围（<, >, <=, >=）或fn:exists()检查属性存在的场景。如果查询中使用fn:contains()等模糊匹配，或对属性值进行类型转换后再比较（如string(@xlink:from) = 'xxx'），会绕过范围索引，需改用全文索引或调整查询逻辑。
• 集合配置范围：确认collection.xconf放置在目标METS文件所在的集合目录下。eXist-db的索引配置按集合生效，放错位置会导致索引无法作用于目标文件。
• 索引类型匹配：若@xlink:from是日期、数值类型，需在collection.xconf中配置对应类型的范围索引（如<date>、<long>），而非默认的<string>类型。类型不匹配时，查询无法命中索引。

二、调试与日志工具 #

• Monex Query Profiler：重点查看「Index Usage」模块，确认是否存在全表扫描（full scan），以及索引命中的具体情况。执行计划会显示哪些步骤未利用索引，直接定位性能瓶颈。
• eXist-db日志调试：修改conf/log4j2.xml，将org.exist.indexing.range的日志级别设为DEBUG或TRACE，重启后运行查询，查看logs/exist.log中的索引加载、匹配日志，排查索引未命中的具体原因。
• 内置Query Profiler：用util:profile()包裹查询语句，例如：

  util:profile(
      for $doc in collection('/db/mets')//mets:div[@xlink:from = '202401']
      return $doc
  )
  

  该函数会返回详细的执行时间拆分，定位耗时最长的步骤，确认是否因全表扫描导致速度慢。
• Dashboard Index Inspector：在eXist-db的Dashboard中打开Index Inspector，查看目标集合的索引列表，验证@xlink:from的范围索引是否存在，以及索引条目数量是否符合预期（是否包含目标METS文件的属性值）。

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