OpenSearch 刚导入的文档 _count 正常但 _search 返回 0 hits（refresh 间隔）

bulk 导入 OpenSearch 后立刻 _search 返回 0 hits，但 GET /movies/_count 已经是 5。根因是 OpenSearch 近实时搜索：文档先写 translog 和内存 buffer，refresh（默认每 1 秒）后才生成可搜索的 segment。解法是等一秒重搜，或导入时加 refresh=wait_for；?refresh=true 只适合本地体验。适用 OpenSearch 全版本，本文实测 3.9.0。

Issue & Env（案发现场与环境）

• 业务场景：跟着 从零跑通 OpenSearch 用 _bulk 导入 5 条电影文档，响应里 "errors" : false，每条 item 都是 "result" : "created"。紧接着搜 title: "wind rise"，返回 0 hits；同一条查询等一秒再跑，命中 3 条。
• 环境：OpenSearch 3.9.0，Docker 单节点，索引 movies（1 主分片、0 副本），security 插件开启（HTTPS + Basic Auth）。
• 关键区分：不是写入失败，也不是查询语法问题。_count 和 _search 查的数据源不同——前者统计已写入的文档，后者查已 refresh 的倒排索引。两者之间有最多一个 refresh 间隔的窗口期。

StackTrace（堆栈日志）

Bulk API 官方文档把这套行为讲得很直白，原话是：“OpenSearch uses a near-real-time search model where documents are not immediately searchable after indexing.”

bulk 返回后立刻执行 GET /movies/_count?pretty：

{
  "count" : 5,
  "_shards" : { "total" : 1, "successful" : 1, "skipped" : 0, "failed" : 0 }
}

紧接着执行 _search（查 title: "wind rise"，按示例数据应命中 3 条）：

{
  "took" : 1,
  "timed_out" : false,
  "_shards" : { "total" : 1, "successful" : 1, "skipped" : 0, "failed" : 0 },
  "hits" : {
    "total" : { "value" : 0, "relation" : "eq" },
    "max_score" : null,
    "hits" : []
  }
}

count 是 5，hits.total.value 是 0，两条命令间隔不到一秒。等一秒重跑 _search，value 变回 3。

这个“矛盾”在社区里出现过。OpenSearch 论坛有个 k-NN 召回率异常低的帖子（#3142，2020-06），维护者 jmazane 排查的第一步就是问写入可见性：“After indexing, the documents may not be immediately searchable.”——先确认文档真的能搜到，再怀疑算法。刚导入的文档，_search 查不到是常态。

Reproduce（复现代码）

前提：本地 OpenSearch 已启动，示例值沿用 quickstart（端口 9200、用户 admin、密码 Devfix@2026）。

建索引：

curl -sk -u admin:Devfix@2026 -X PUT "https://localhost:9200/movies?pretty" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": { "index.number_of_shards": 1, "index.number_of_replicas": 0 },
    "mappings": {
      "properties": {
        "title": { "type": "text" },
        "year":  { "type": "integer" },
        "genre": { "type": "keyword" }
      }
    }
  }'

导入 5 条文档：

cat > movies.ndjson <<'EOF'
{ "index": { "_index": "movies", "_id": "1" } }
{ "title": "Let the Wind Rise", "year": 2013, "genre": "drama" }
{ "index": { "_index": "movies", "_id": "2" } }
{ "title": "Gone with the Wind", "year": 1939, "genre": "drama" }
{ "index": { "_index": "movies", "_id": "3" } }
{ "title": "The Rise of Machines", "year": 2021, "genre": "scifi" }
{ "index": { "_index": "movies", "_id": "4" } }
{ "title": "Deep Sea Chronicles", "year": 2018, "genre": "documentary" }
{ "index": { "_index": "movies", "_id": "5" } }
{ "title": "Windmill Valley", "year": 2015, "genre": "drama" }
EOF

curl -sk -u admin:Devfix@2026 -X POST "https://localhost:9200/_bulk?pretty" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @movies.ndjson

连查两次，结果矛盾：

# 立刻查 _count：5 条都在
curl -sk -u admin:Devfix@2026 "https://localhost:9200/movies/_count?pretty"

# 紧接着 _search：0 hits
curl -sk -u admin:Devfix@2026 -X GET "https://localhost:9200/movies/_search?pretty" \
  -H "Content-Type: application/json" \
  -d '{ "query": { "match": { "title": "wind rise" } } }'

# 等一秒重跑上一条 _search：3 条命中
sleep 1

判定标准：_count 返回 "count" : 5 且首次 _search 返回 "value" : 0，即复现成功。

Root Cause（根因分析）

写入链路：translog + buffer → refresh → segment

Refresh Index API 文档给了写入链路的原话：“When you index a document, it is first written to a translog and added to in-memory buffers. The document is not searchable until a refresh operation converts these in-memory structures into searchable segments on disk.”

拆开看时间线：

1. 文档到达，写 translog（宕机恢复用），同时进内存 buffer。此时倒排索引里还没有它。
2. 每隔 index.refresh_interval（默认 1s），refresh 把 buffer 里的文档构建成新 segment，并打开新的 searcher。
3. _search 只查 searcher 可见的 segment。refresh 没跑，文档就不在搜索的视野里。

_count 统计的是已写入的文档，走的是实时写入侧；_search 查的是已 refresh 的倒排索引。数据源不同，“count 对、search 空”就是窗口期内的正常状态。

近实时是设计取舍，不是 bug

为什么不每写一条就 refresh？官方博客《Optimize OpenSearch Refresh Interval》说得很清楚：“Refresh operations are resource intensive. The procedure of transferring data into new segments and rendering them searchable demands CPU, memory, and input/output (I/O) resources.”

每次 refresh 都生成一个新 segment。高频写入配高频 refresh，会产生大量小 segment，后台 merge 得花更多资源把它们合掉。所以 Lucene 系引擎（OpenSearch、Elasticsearch、Solr）统一选了“近实时”：攒一秒的写入，一次 refresh 生成一个 segment，用一秒的可见性延迟换索引吞吐。一秒延迟是特性，不是缺陷。

默认 1s 只对“活跃”分片生效

自动 refresh 还有个前提条件。文档里写的是：未显式设置 index.refresh_interval 时，分片每秒 refresh，直到连续 30 秒（index.search.idle.after，默认 30s）没有搜索请求，分片进入 idle 状态。idle 后不再自动 refresh，直到下一次搜索请求或手动调用 Refresh API——首个到达 idle 分片的搜索请求会等 refresh 完成再返回。

The Fix（解决方案）

方案一：等一秒重搜（默认行为，零改动）

本地体验什么都不用改，sleep 1 后重搜即可。默认 refresh_interval: 1s 保证了新文档最多一秒后可见。

方案二：导入时用 refresh 参数

Bulk、Index、Update、Delete 这些文档 API 都支持 refresh 查询参数，三个取值：

• false（默认）：不主动 refresh，按索引的 refresh 间隔（通常 1 秒）变可见。
• true：强制立即 refresh 受影响的分片，文档马上可搜，但有性能代价。
• wait_for：等下一次计划中的 refresh 完成再返回，兼顾可见性和性能。

本地演示，导入完立刻要搜：

curl -sk -u admin:Devfix@2026 -X POST "https://localhost:9200/_bulk?refresh=true&pretty" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @movies.ndjson

生产代码里“写完马上读”的场景，官方推荐 wait_for 而不是 true——它不强制立即 refresh，只是把请求挂到下一次周期性 refresh，不会打乱 segment 节奏：

curl -sk -u admin:Devfix@2026 -X POST "https://localhost:9200/_bulk?refresh=wait_for&pretty" \
  -H "Content-Type: application/x-ndjson" \
  --data-binary @movies.ndjson

方案三：批量导入前关自动 refresh，导完手动补

全量导入场景，refresh 一秒一次纯属浪费。先把间隔设成 -1 关掉自动 refresh（Index settings 文档原话：“Can be set to -1 to disable refreshing. Default is 1s.”），导完手动 refresh 一次，再恢复默认：

# 导入前关闭
curl -sk -u admin:Devfix@2026 -X PUT "https://localhost:9200/movies/_settings?pretty" \
  -H "Content-Type: application/json" \
  -d '{ "index": { "refresh_interval": "-1" } }'

# ……执行 bulk 导入……

# 导入完成，手动 refresh 一次
curl -sk -u admin:Devfix@2026 -X POST "https://localhost:9200/movies/_refresh?pretty"

# 恢复默认间隔
curl -sk -u admin:Devfix@2026 -X PUT "https://localhost:9200/movies/_settings?pretty" \
  -H "Content-Type: application/json" \
  -d '{ "index": { "refresh_interval": "1s" } }'

官方博客的建议与此一致：在已知的写入密集任务前关闭自动 refresh，结束后手动触发一次。

注意事项

• 生产别用 refresh=true。Refresh API 文档的 Best practices 写得很直接：“Using refresh=true on index, update, or delete operations forces an immediate refresh and creates inefficient index structures (small segments) that must later be merged, impacting both indexing and search performance.”
• refresh_interval 是动态设置，_settings 直接改，不用重建索引。
• 验证“写没写进去”用 _count，验证“能不能搜到”用 _search。两者结果不一致时，先看时间差有没有超过一个 refresh 间隔。
• 这个现象容易和查询语法问题混淆，分词行为见 从零跑通 OpenSearch 第五步。

References（参考来源）

• Refresh Index API — OpenSearch 官方文档opensearch-docs
• Bulk API — OpenSearch 官方文档opensearch-docs
• Index settings — OpenSearch 官方文档opensearch-docs
• Optimize OpenSearch Refresh Interval — OpenSearch 官方博客opensearch-blog
• Different results for Nmslib and Elastic Knn Search — OpenSearch 论坛opensearch-forum