# Geo、Runtime Field、Reactive 与 Testcontainers：一次查询组合文本、结构化、地理与实时计算

```text
旧方案：Geo 单独建索引、派生字段靠写入时计算、所有查询走同步客户端
→ 冲突：需求要求一次查询同时过滤距离、分类、关键词和低频派生字段
→ 后果：多索引拼接、写入链路复杂、同步阻塞拖垮网关
```

业务从“门店列表”演进为“附近正在营业且匹配分类与关键词的门店”，还要在结果里带一个不常变的派生分数字段。

我是老李，在深圳同盟的一次分享里听到一个说法：Elasticsearch 不是搜索引擎，而是一个能在一次查询里组合文本、结构化、地理和实时计算的分布式数据系统。

当时我半信半疑，直到一个门店查询需求把 Geo、Runtime Field、Reactive 和测试验证全部卷了进来。

如果 Geo 查询和关键词过滤不能在一次请求里完成，会发生什么？

Runtime Field 应该写入时算好，还是查询时实时算？

如果为了接口返回 Flux 而强行上 Reactive，选错的代价是什么？

# 01、故事

```text
周四 23:40 → 深圳南山 → 门店服务 V1 上线前 → 需求临时加“5公里内营业中”
```

那天晚上十一点四十，我在南山一个共享会议室里盯着发布清单。任务是让门店服务支持“附近门店”查询。

产品经理临时加了一句：用户要看到 5 公里内营业中的门店，还要能按分类和关键词过滤。

我打开 V1 代码，发现门店索引只有名称、分类、营业状态和地址文本，根本没有坐标字段。

搜索“Elasticsearch Geo 查询”，出来的文章要么只讲 geo_distance，要么只讲 keyword filter，没有一篇讲怎么和营业状态、分类、关键词一次组合。

我试着把地址文本拼进 match 查询，结果“海岸城”能搜到，“5公里内”完全没法判断。

> 深夜改索引，
> 坐标字段无处寻，
> 距离难过滤，
> 查询拆两半。

# 02、问题

```text
需求变化：门店列表 → 附近营业中 + 分类 + 关键词
→ 冲突：V1 索引无坐标、无派生字段、同步查询阻塞
→ 后果：距离过滤缺失、派生字段写入复杂、高并发下线程耗尽
```

V1 门店索引只有 text 和 keyword 字段，没有 geo_point，也没有派生分数字段。

距离过滤失效，因为地址文本无法直接参与地理距离计算。

派生分数字段如果写入时计算，需要额外更新链路；如果查询时计算，又担心拖慢响应。

同步 RestHighLevelClient 查询在高并发下会阻塞网关线程，导致线程池耗尽。

可验证验收：同一请求能同时过滤 5 公里、营业状态、分类、关键词，并返回实时计算的派生分数字段。

> 索引无坐标，
> 派生字段写入难，
> 同步线程满，
> 一次查询难全。

# 03、原理

```text
核心机制：geo_point 倒排索引 + Runtime Field 查询时计算 + Reactive 非阻塞 IO
```

Geo 查询依赖 geo_point 字段的 BKD 树索引，geo_distance 过滤会在树上做范围裁剪。

Runtime Field 不写磁盘，查询时在每个命中的文档上执行脚本，用查询 CPU 换 Schema 灵活性。

ReactiveElasticsearchOperations 基于 Reactor Netty 的非阻塞 IO，适合高并发和流式场景。

反直觉判断：Runtime Field 不是“慢查询”，低频派生字段在过滤后的小结果集上计算，开销远小于写入时维护。

另一个反直觉判断：Reactive 的价值不在返回 Flux，而在背压和连接复用；低并发下同步客户端反而更简单。

> 坐标建树索引，
> 脚本查询时算，
> 非阻塞背压，
> 边界要认清。

# 04、架构

```text
输入：用户位置、距离、营业状态、分类、关键词
→ 本模块：门店索引 + Geo 过滤 + Runtime Field 计算 + Reactive 查询
→ 输出：门店列表 + 距离 + 派生分数字段
```

门店索引包含 geo_point 坐标、keyword 营业状态、keyword 分类、text 名称和描述。

查询层用 ReactiveElasticsearchOperations 构建一次 bool 查询，组合 geo_distance、term、match。

Runtime Field 在查询时计算派生分数字段，不占用写入链路。

收益：一次查询完成多维度过滤，Schema 变更无需重建索引。

代价：Runtime Field 消耗查询 CPU，Reactive 增加调试复杂度。

适用条件：坐标字段已建立、派生字段低频、查询并发高或需要流式返回。

> 一次查询组合，
> 多维过滤不拆，
> 实时计算字段，
> 边界要权衡。

# 05、第一版实战

```text
环境：Elasticsearch 8.x + Spring Boot 3.x + Testcontainers
→ 配置：门店索引 Mapping + 依赖
→ 代码：Reactive 查询 + Geo 过滤 + Runtime Field
→ 启动：Testcontainers 启动真实 ES
→ 验证：一次请求返回 5 公里内营业中门店 + 派生分数字段
→ V1：功能跑通
```

依赖配置：

```xml
<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-elasticsearch</artifactId>
</dependency>
<dependency>
  <groupId>org.testcontainers</groupId>
  <artifactId>elasticsearch</artifactId>
  <scope>test</scope>
</dependency>
<dependency>
  <groupId>io.projectreactor</groupId>
  <artifactId>reactor-test</artifactId>
  <scope>test</scope>
</dependency>
```

门店索引 Mapping：

```json
{
  "mappings": {
    "properties": {
      "name": { "type": "text" },
      "category": { "type": "keyword" },
      "status": { "type": "keyword" },
      "location": { "type": "geo_point" },
      "rating": { "type": "double" },
      "review_count": { "type": "integer" }
    }
  }
}
```

Testcontainers 启动真实 Elasticsearch：

```java
@Container
static ElasticsearchContainer es = new ElasticsearchContainer(
    DockerImageName.parse("docker.elastic.co/elasticsearch/elasticsearch")
        .withTag("8.11.0")
).withEnv("discovery.type", "single-node")
 .withEnv("xpack.security.enabled", "false");
```

Reactive 查询代码：

```java
public Flux<Store> searchNearby(double lat, double lon, double distanceKm,
                                String category, String keyword) {
    var criteria = new Criteria();
    criteria.and(new Criteria("location")
        .within(new GeoDistance(distanceKm, DistanceUnit.KILOMETERS, lat, lon)));
    criteria.and(new Criteria("status").is("OPEN"));
    criteria.and(new Criteria("category").is(category));
    if (keyword != null && !keyword.isBlank()) {
        criteria.and(new Criteria("name").matches(keyword));
    }
    var query = new CriteriaQuery(criteria);
    query.addRuntimeField("popularity_score",
        "emit(doc['rating'].value * Math.log(doc['review_count'].value + 1))");
    return operations.search(query, Store.class)
        .map(SearchHit::getContent);
}
```

验证请求与结果：

```text
请求：lat=22.52, lon=113.94, distance=5km, category=餐饮, keyword=火锅
示例输出：
[
  {"name":"海底捞火锅","category":"餐饮","status":"OPEN",
   "location":{"lat":22.53,"lon":113.95},
   "popularity_score":12.8}
]
```

成功标准：一次请求同时过滤距离、营业状态、分类、关键词，并返回 popularity_score 派生字段。

> 容器起真库，
> 坐标过滤距离，
> 脚本算分数，
> 一次查询成。

# 06、排查

```text
诊断树：
查询无结果 → 坐标格式错？→ 检查 Mapping 和写入
→ 脚本报错 → Runtime Field 语法？→ 检查脚本上下文
→ 响应慢 → 脚本在大结果集上跑？→ 调整过滤顺序
```

问题一：查询无结果。

怀疑坐标写入格式错误。

检查写入数据：

```bash
curl -s "http://localhost:9200/stores/_search?pretty" -H 'Content-Type: application/json' -d '{"query":{"match_all":{}}}'
```

证据：location 字段显示为字符串 "22.53,113.95"，不是 geo_point 对象。

根因：写入时把坐标拼成字符串，没有用 lat/lon 对象。

修复：写入时改为 {"lat":22.53,"lon":113.95}。

问题二：Runtime Field 脚本报错。

怀疑脚本语法在查询上下文不兼容。

检查脚本：

```bash
curl -s "http://localhost:9200/stores/_search?pretty" -H 'Content-Type: application/json' -d '{"runtime_mappings":{"popularity_score":{"type":"double","script":{"source":"emit(doc['\''rating'\''].value * Math.log(doc['\''review_count'\''].value + 1))"}}},"query":{"match_all":{}}}'
```

证据：报错提示 doc 值访问需要字段启用 doc_values。

根因：rating 和 review_count 字段默认启用 doc_values，但脚本里 Math.log 在 review_count 为 0 时返回 -Infinity。

修复：脚本改为 emit(doc['rating'].value * Math.log(doc['review_count'].value + 1))，并确保 review_count 非负。

**错误尝试：** 曾尝试用 painless 的 params._source.rating 访问字段，结果在过滤后文档上触发 _source 加载，性能更差。

> 坐标写成串，
> 脚本访问错，
> 证据定位快，
> 修复不绕弯。

# 07、优化

```text
V1：Runtime Field 在 match_all 上计算 → 全量扫描慢
→ 证据：查询耗时 800ms，命中 10 万文档
→ V2：先 geo_distance + term 过滤，再在剩余文档上计算 Runtime Field
```

V1 把 Runtime Field 放在 match_all 查询里，脚本在 10 万文档上执行。

证据：查询耗时 800ms，CPU 飙高。

优化：把 geo_distance 和 term 过滤放在 bool query 的 filter 子句，Runtime Field 只在过滤后的小结果集上计算。

优化后查询：

```json
{
  "query": {
    "bool": {
      "filter": [
        { "geo_distance": { "distance": "5km", "location": { "lat": 22.52, "lon": 113.94 } } },
        { "term": { "status": "OPEN" } },
        { "term": { "category": "餐饮" } }
      ],
      "must": [
        { "match": { "name": "火锅" } }
      ]
    }
  },
  "runtime_mappings": {
    "popularity_score": {
      "type": "double",
      "script": {
        "source": "emit(doc['rating'].value * Math.log(doc['review_count'].value + 1))"
      }
    }
  }
}
```

优化后耗时降到 45ms，命中 12 个文档。

> 脚本全量跑，
> 过滤先裁剪，
> 小集上计算，
> 耗时降十倍。

# 08、演进

```text
V2：Geo 过滤 + Runtime Field 小集计算 + Reactive 非阻塞
→ 能力：一次查询组合文本、结构化、地理、实时计算
→ 遗留：Reactive 调试复杂、Runtime Field 不适合高频字段
```

用 V1 同一组请求前后验证：

```text
V1：耗时 800ms，命中 10 万文档，CPU 高
V2：耗时 45ms，命中 12 个文档，CPU 正常
```

收益：查询延迟降低 94%，Schema 变更无需重建索引。

代价：Runtime Field 消耗查询 CPU，Reactive 栈调试需要额外工具。

适用：低频派生字段、高并发查询、需要流式返回。

遗留：Runtime Field 不能用于排序和聚合的频繁场景，Reactive 在低并发下收益不明显。

> 过滤先裁剪，
> 小集上计算，
> 非阻塞查询，
> 边界要认清。

# 09、洞见

```text
从现象到判断：扩展能力的价值不在“都使用”，而在知道何时组合
```

## 扩展能力的价值在于组合判断，而非堆砌使用
```text
Geo + Runtime Field + Reactive 三者组合
→ 一次查询完成多维过滤与实时计算
→ 价值在知道何时用、何时不用
```

Elasticsearch 的 Geo、Runtime Field、Reactive 各有边界，真正的工程价值在于判断什么场景组合它们。

## 反直觉判断：Runtime Field 不是慢查询，写入时计算才是隐性成本
```text
写入时计算派生字段
→ 每次更新都要重算
→ 查询时计算只在命中文档上执行
```

低频派生字段在过滤后的小结果集上计算，开销远小于写入时维护。

## 反直觉判断：Reactive 的价值不在返回 Flux，而在背压和连接复用
```text
为了返回 Flux 而 Reactive
→ 低并发下调试复杂
→ 高并发下背压和连接复用才值得
```

ReactiveElasticsearchOperations 的适用边界是高并发非阻塞和流式场景，不要为了返回 Flux 而 Reactive。

## 测试用真实容器，不用 Mock 替代搜索行为
```text
Mock 搜索行为
→ 验证不了 Mapping、Query、Aggregation
→ Testcontainers 启动真实 ES 才能验证真实行为
```

Testcontainers 启动真实 Elasticsearch，验证 Mapping、Query、Aggregation 和 Search Result，不用 Mock 替代真正搜索行为。

> 组合有边界，
> 判断在场景，
> 真实容器验，
> 价值在权衡。

# 10、系统落地

```text
入口：门店服务 API
→ 服务：Spring Boot + ReactiveElasticsearchOperations
→ 本模块：门店索引 + Geo 过滤 + Runtime Field + Testcontainers 验证
→ 存储：Elasticsearch 8.x
→ 未实现：聚合统计与排序优化
```

原来门店服务只有同步查询和文本过滤。

本篇增加 Geo 距离过滤、Runtime Field 派生计算、Reactive 非阻塞查询和 Testcontainers 真实容器验证。

现在能做什么：一次查询返回 5 公里内营业中且匹配分类与关键词的门店，并带实时计算的派生分数字段。

下一篇缺什么：聚合统计与排序优化，以及 Runtime Field 在聚合场景的替代方案。

官方链接：https://www.elastic.co/guide/en/elasticsearch/reference/current/geo-queries.html

> 入口到存储，
> 能力逐层加，
> 真实容器验，
> 下一篇聚合。

# 11、小结

```text
三问三答：
Geo 和关键词能否一次查询？能，用 bool query 组合 filter 和 must。
Runtime Field 写入时算还是查询时算？低频派生字段查询时算，用查询 CPU 换 Schema 灵活性。
为了返回 Flux 上 Reactive 值不值？不值，高并发非阻塞或流式才值得。
```

当前状态：门店服务已支持一次查询组合文本、结构化、地理和实时计算，测试用 Testcontainers 真实容器验证。

> 一次查询组合，
> 实时计算字段，
> 非阻塞边界，
> 真实容器验。

# 12、作业

```text
理解 → 实战 → 排障 → 架构判断
```

## 理解题：Runtime Field 为什么适合低频派生字段，不适合高频排序字段？

Runtime Field 查询时在命中文档上执行脚本，低频字段在过滤后的小结果集上计算开销小。高频排序字段需要全局排序，脚本计算会扫描大量文档，性能差。

## 实战题：用 Testcontainers 启动 Elasticsearch，验证一个 geo_distance + term + match 组合查询，并返回一个 Runtime Field 派生字段。

按本文第 05 章步骤，用 Testcontainers 启动 ES 8.x，写入带 geo_point 的门店数据，执行组合查询，验证返回结果包含 popularity_score 派生字段。

## 排障题：查询无结果，检查发现 location 字段是字符串 "22.53,113.95"，如何修复？

根因是坐标写入格式错误。修复：写入时改为 {"lat":22.53,"lon":113.95} 对象格式，并确认 Mapping 中 location 类型为 geo_point。

## 架构判断题：低并发下为了接口返回 Flux 而使用 ReactiveElasticsearchOperations，是否合理？

不合理。Reactive 的价值在高并发非阻塞和流式场景，低并发下同步客户端更简单，调试成本更低。

> 理解边界，
> 实战验证，
> 排障定位，
> 架构权衡。

# 13、升华

```text
工程结论：扩展能力的价值不在“都使用”，而在知道 Elasticsearch 已经可以在一次查询中组合文本、结构化数据、Geo 和实时计算
```

有依据的结论：Geo 用 BKD 树索引做距离过滤，Runtime Field 用查询 CPU 换 Schema 灵活性，Reactive 用非阻塞 IO 换高并发能力。

三者组合让门店服务一次查询完成多维过滤与实时计算，测试用真实容器验证真实搜索行为。

下一篇可写聚合统计与排序优化，以及 Runtime Field 在聚合场景的替代方案。

> 组合有边界，
> 判断在场景，
> 真实容器验，
> 价值在权衡。

**系列项目：** 门店服务系统，服务深圳本地用户

**已完成：** 门店索引、文本过滤、营业状态过滤

**本篇：** Geo 距离过滤、Runtime Field 派生计算、Reactive 非阻塞查询、Testcontainers 真实容器验证

**下一篇：** 聚合统计与排序优化，Runtime Field 聚合场景替代方案

业务从“门店列表”演进为“附近正在营业且匹配分类与关键词的门店”，还要在结果里带一个不常变的派生分数字段。

《Spring ES实战》第13招 搜索也有工程扩展

用真实 Elasticsearch 容器验证 Geo 距离过滤、Runtime Field 派生计算与 Reactive 边界，避免为 Flux 而 React

架构师

编程语言

后端

数据库

本文介绍Elasticsearch组合查询实践，通过Geo距离过滤、RuntimeField实时计算与Reactive非阻塞IO，实现一次查询完成文本、结构化、地理及派生字段多维过滤，用Testcontainers真实容器验证，降低94%延迟，解决门店“附近营业中且匹配分类关键词”的复杂查询需求。

腾讯云大数据特惠0.2折起


oceanus

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

《Spring ES实战》第13招 搜索也有工程扩展-腾讯云开发者社区-腾讯云

《Spring ES实战》第13招搜索也有工程扩展

《Spring ES实战》第13招搜索也有工程扩展

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring ES实战》第13招 搜索也有工程扩展

《Spring ES实战》第13招 搜索也有工程扩展

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

《Spring ES实战》第13招搜索也有工程扩展

《Spring ES实战》第13招搜索也有工程扩展