搜索引擎 on 方糖猫Blog

Elasticsearch 从原理到 IPTV 媒资搜索实战：基于 ftmao-meta 项目的完整复盘

Sat, 28 Aug 2021 14:00:00 +0800

Elasticsearch 从原理到 IPTV 媒资搜索实战：基于 ftmao-meta 项目的完整复盘

以我们线上运行的 IPTV 媒资元数据服务 ftmao-meta 为样本，讲清楚一个真实的 ES（实际为 AWS 托管 OpenSearch）应用是怎么设计索引、同步数据、支撑搜索和下游订阅的。所有配置、代码、索引设计均来自项目本身，踩过的坑也一并奉上。

一、项目背景：这是一个什么系统

ftmao-meta 是一个面向多地区运营的 IPTV/OTT 视频内容平台的媒资元数据微服务，Spring Boot 3.3 + Java 21，单模块 Gradle 工程，包结构 gtt.ftmao.meta，分 api / app / bean / core 四层。它管理的数据包括：

影视元数据：电影、剧集、季、集、短视频的多语言标题、简介、海报、演职员、分级、票房；
演职人员：多语言姓名、热度值（pgcHot / ugcHot / imdbHot）、代表作；
物料：剧照海报（artwork）、预告片（trailer）；
C 端搜索：全文检索 + 输入自动补全。

这些数据量巨大（千万级文档）、多语言（英语/西语/葡语，服务拉美市场）、多租户（多家运营商公司共用），而且需要被下游多个服务增量订阅。MySQL 是事实源（Source of Truth），ES 承担所有读路径的检索。

技术选型上的关键事实：

后端是 AWS 托管 OpenSearch，客户端用官方 opensearch-java 2.8.1（org.opensearch.client.opensearch.OpenSearchClient），没有用 spring-data-elasticsearch，也没有 RestHighLevelClient；
全文检索与自动补全能力封装在公司内部库 searchengine-api/core/sync 里，业务代码只调用 SearchApi / SearchSync 门面；
数据同步不走 MQ（Kafka 依赖在启动类里被显式排除），而是"MySQL 任务表 + 定时轮询 + 分布式锁"。

graph TB
    subgraph 上游["上游数据来源"]
        BOSS["运营后台 / 内容录入"]
        PP["PP 开放平台<br/>（REST 拉取外部媒资）"]
    end

    subgraph META["ftmao-meta 服务"]
        API["REST API 层"]
        SVC["业务 Service<br/>MetaService / ArtworkService ..."]
        JOB["定时 Job<br/>PpMetaSyncJob 每 15s"]
        LOCK["分布式锁<br/>AsyncJobExecutorManager"]
    end

    subgraph STORE["存储层"]
        MYSQL[("MySQL<br/>事实源 + 同步任务表")]
        subgraph OS["AWS OpenSearch"]
            DETAIL["meta_detail_index<br/>媒资详情（重索引）"]
            PERSON["meta_person_index<br/>人物详情"]
            ART["meta_artwork_index<br/>剧照物料"]
            TRAILER["meta_trailer_index<br/>预告片"]
            SEARCH["search_engine_index<br/>C端搜索（轻索引）"]
        end
    end

    subgraph DOWN["下游消费方"]
        PORTAL["门户/推荐服务"]
        SUB["增量订阅方<br/>（时间水位拉取变更）"]
    end

    BOSS --> SVC
    PP --> JOB
    SVC -->|"事务内：先写库，再直写 ES"| MYSQL
    SVC --> DETAIL
    SVC --> SEARCH
    JOB --> LOCK --> MYSQL
    JOB -->|"批量灌入"| SEARCH
    API -->|"全文搜索/补全"| SEARCH
    API -->|"mget 回查详情"| DETAIL
    API --> PERSON & ART & TRAILER
    DETAIL -->|"lastModifiedIndicator 水位"| SUB
    SEARCH --> PORTAL

二、先补原理：理解后面设计决策的三个支点

在进入项目细节前，用三句话回顾《Elasticsearch in Action》里最重要的原理，后面每个设计决策都会用到它们。

2.1 倒排索引与分词

ES 搜索快的根本原因是倒排索引：term → 文档列表。而文本进入倒排索引前要经过分析链：

graph LR
    A["原始文本<br/>O Auto da Compadecida"] --> B["Character Filter<br/>变音符号映射 á→a"]
    B --> C["Tokenizer<br/>standard 分词"]
    C --> D["Token Filter<br/>lowercase + stopword + stemmer"]
    D --> E["词项 Term<br/>auto / compadecida"]

一个字段建索引时用哪个 analyzer、搜索时用哪个 analyzer，直接决定了"搜不搜得到"。这就是为什么 mapping 必须在灌数据之前设计好——改 analyzer 意味着重建索引。

2.2 近实时（NRT）与 refresh

文档写入后先进内存缓冲区，默认 1 秒后 refresh 生成 segment 才可被搜索。批量灌数据时调大 refresh_interval、或显式控制 refresh 时机，是写入性能优化的第一手段——后面会看到项目里批量写入怎么用它。

2.3 Query 与 Filter 的区别

Query：算相关性得分 _score，用于全文匹配排序；
Filter：只判断 yes/no，不算分、结果可被缓存，用于精确过滤。

项目里几乎所有查询都是"filter 套 query"的 bool 结构：关键词进 must，租户、类型、软删除标记进 filter。

三、索引设计：一个搜索索引 + 四个详情索引

3.1 索引清单

项目中没有任何 @Document 注解或 mapping JSON 文件，索引 DDL 采用类似 Liquibase 的 changelog 形式管理（changelog/elasticsearch/*.yaml，HTTP method + path + body，由外部部署工具执行），别名字段统一管理：

代码中的别名	实体索引	分片	存什么
`meta_detail_index`	`ftmao-meta-detail-1`	6 主 2 副	媒资详情全集
`meta_person_index`	`ftmao-meta-person-detail`	6 主 2 副	演职人员详情
`meta_artwork_index`	`ftmao-meta-media-artwork`	6 主 2 副	剧照物料
`meta_trailer_index`	`ftmao-meta-media-trailer`	6 主 2 副	预告片
`search_engine_index`	`ftmao-meta-search-engine`	1 分片	C 端搜索/补全

别名与文档类的映射集中在一个枚举里（OpenSearchIndexEnum），业务代码只认别名——这是"换索引不改代码"的基本功，比如 ftmao-meta-detail-1 后面出现 -2，只需要 reindex 后切别名。

3.2 详情索引：重存储、轻检索

meta_detail_index 的 mapping 有个鲜明特征：几乎所有字段都是 keyword，标题、剧情简介都是 keyword + nested，不参与分词检索，大量 nested 对象（displayTitles / plots / posters / casts）配 dynamic: false。

为什么？因为详情索引的职责是**“按 ID/结构化条件精确取数”**，不是全文搜索。keyword 不做分词，聚合、terms 过滤、精确匹配都快；dynamic: false 防止上游数据乱塞字段把 mapping 撑爆（mapping explosion 是生产事故常客）。

3.3 搜索索引：整个项目最精彩的部分

search_engine_index 只有 1 个分片（轻量、追求查询 RT），但它的 analysis 配置是整个项目技术含量最高的地方。以主搜索字段 mainTitle 为例：

# 摘自 changelog（简化）
mainTitle:
  type: text
  store: true
  term_vector: with_positions_offsets   # 为 fast-vector-highlighter 高亮做准备
  analyzer: en_es_pt                     # 英/西/葡三语混合分词器
  fields:
    cut_word:    { analyzer: en_es_pt }              # 正常分词匹配
    all_letters: { analyzer: N_gram(4-15) }          # 长 ngram：前缀/模糊匹配
    word_letters:{ analyzer: N_gram(2-10) }          # 短 ngram：更激进的模糊匹配
    origin:      { type: keyword, normalizer: lowercase }  # 精确匹配/排序

配套自定义组件：

多语分析器 en_es_pt：standard tokenizer + 英语/西语/葡语三套 stopword + stemmer；
变音符号 char_filter：把 áéíóúàèç 等西葡变音符号映射为 ASCII——拉美用户搜 compadecida 也能命中 Compadecida，对多语言市场这是体验生死线；
ngram tokenizer 一批（1–10、4–15 等不同窗口），max_ngram_diff=14；
completion suggester：suggest 字段配 suggester_trigram 分析器，带 3 个 category context（markCate / tenantCate / comboCate）——自动补全可以按内容类型和租户隔离，A 运营商的用户不会看到 B 运营商专有的片名提示。

设计启示：一个"能搜"的字段，实际需要四层子字段分工——正常分词管召回、长 ngram 管前缀联想、短 ngram 管纠错、keyword 管精确和排序。这也正是《Elasticsearch in Action》里"多字段映射"思想的生产级演绎。

3.4 双索引架构：为什么搜索和详情要分开

graph LR
    subgraph 写入["写入侧"]
        D["MetaDetail 完整文档<br/>（几十 KB，含 nested 海报/演员/多语言）"] --> DETAIL["详情索引<br/>6分片 重存储"]
        D -->|"裁剪：docId + mainTitle +<br/>suggest + 过滤字段 + 租户"| SEARCH["搜索索引<br/>1分片 轻量"]
    end
    subgraph 查询["查询侧"]
        U["用户搜索 'auto'"] -->|"① matchSearch 命中<br/>返回 docId 列表"| SEARCH
        SEARCH -->|"② 按 docId mget"| DETAIL
        DETAIL -->|"组装完整详情返回"| U
    end

搜索索引里不存详情，只有：docId、mainTitle（及 ngram 子字段）、suggest、40+ 个 keyword 过滤字段（ext-field-to-index-map 里配置，如媒资类型、地区、年份、分级）、租户字段。好处有三个：

搜索索引小，1 个分片 + 内存友好，C 端 QPS 扛得住；
详情变更不用动搜索索引——海报换了只 update 详情索引；搜索索引只在标题/过滤字段变化时更新；
两类索引可以独立扩缩容、独立重建。

代价也很明显：多一次 mget 回查、数据一致性要维护两份。这个项目用下一节的同步机制来兜底。

四、数据同步：MySQL → ES 的三条路径

ES 是"读模型"，MySQL 才是事实源。项目没用 Canal/MQ，而是自己实现了一套事务内直写 + 任务表轮询的混合方案：

flowchart TD
    A["业务写请求<br/>MetaService.save()"] --> B{"@Transactional"}
    B --> C["① 写 MySQL 业务表"]
    B --> D["② 写 MySQL 同步任务表<br/>MixedMetaSyncTask"]
    B --> E["③ 同事务内直写详情索引<br/>bulkOperationByBatch(refresh=True)"]
    B --> F["④ saveMetaToSearchEngine<br/>同步搜索索引"]
    E --> G{"ES 写失败?"}
    G -->|"是，事务回滚或留下任务"| H["任务表残留记录"]
    D --> I["PpMetaSyncJob<br/>@Scheduled 每 15s"]
    H --> I
    I --> J["分布式锁<br/>executeWithLock"]
    J --> K["MetaTaskProcessService<br/>分批 Lists.partition(batchSize)"]
    K -->|"searchSync.save(batch)"| L["搜索索引"]
    M["失败重试 Job<br/>每小时"] --> J

三条路径各有分工：

同事务直写（主路径）：保证"后台保存完，前台立刻能搜到"。写入时统一刷新 updateTime 和 lastModifiedIndicator（格式：时间戳_docId 的版本游标，下一节详述）；
任务表 + 定时轮询（兜底路径）：15 秒一轮，分布式锁防多实例并发，分批灌入；
失败重试 Job（保险）：每小时扫描失败任务重放。

为什么不纯用 MQ？ 这个系统的写入量级不大（媒资是低频高价值数据，不是日志），事务内直写的一致性收益远大于引入 MQ 的复杂度。这是"按场景选方案"而不是"按潮流选方案"的好例子。

4.1 批量写入的性能细节

工具类 OpenSearchUtil.bulkUpsertDocuments 里有两个值得抄的实践：

// 按配置的 bulkSize（默认 200）分批，避免单个 bulk 过大压垮集群
// 每批显式 refresh(WaitFor)：写完后“等 refresh 完成再返回”，
// 保证同步接口的调用方“写完立即可见”，同时比 refresh=true（每文档刷新）省资源

对照第 2.2 节的 NRT 原理：refresh=WaitFor 是吞吐和可见性之间的甜点——批量场景不要无脑 refresh=true。

五、查询实战：从业务代码反推 ES 用法

5.1 一切查询的起点：软删除过滤

项目里文档不物理删除，而是软删除——所有读路径都要叠一层 isDeleted=0：

// OpenSearchUtil.getUndeletedQuery：所有查询都要过这层包装
Query undeletedQuery = openSearchUtil.getUndeletedQuery(boolQueryBuilder.build()._toQuery());
// 底层就是 bool.filter(terms(isDeleted, [0]))，可能再叠加 status=1（已发布）

业务侧的典型用法（ArtworkService，按媒资 ID 查剧照）：

Query metaIdQuery = Query.of(q -> q.terms(t -> t.field("metaId")
    .terms(tv -> tv.value(Stream.of(request.getMetaId())
        .map(FieldValue::of).toList()))));
boolQueryBuilder.filter(metaIdQuery);
Query undeletedQuery = openSearchUtil.getUndeletedQuery(boolQueryBuilder.build()._toQuery());
SortOptions sortOption = SortOptions.of(s -> s.field(
    f -> f.field("pos").order(SortOrder.Asc)));
List<MediaArtwork> artworks = openSearchUtil.searchDoc(
    OpenSearchIndexEnum.MEDIA_ARTWORK.getIndexName(),
    undeletedQuery, MediaArtwork.class,
    request.getPageId(), request.getPageSize(),
    Collections.singletonList(sortOption), totalCount);

这正是第 2.3 节"filter 不算分、可缓存"原理的落地：结构化条件全部进 filter。

5.2 软删除的实现：updateByQuery + Painless 脚本

删除不是 delete，而是 updateByQuery 打标记：

String script = " ctx._source.isDeleted = 1;"
      + "ctx._source.updateTime = params.currentTime;"
      + "ctx._source.lastModifiedIndicator = params.indicatorPrefix + '_' + ctx._id";
UpdateByQueryRequest request = new UpdateByQueryRequest.Builder()
    .index(indexName).query(query)
    .script(s -> s.inline(i -> i.source(finalScript)
        .params("currentTime", JsonData.of(currentTime))
        .params("indicatorPrefix", JsonData.of(String.valueOf(modifyTime)))))
    .build();

注意脚本里同时更新了 lastModifiedIndicator——软删除也是一次"变更"，必须让下游订阅方感知到（下游才能同步删）。这个细节是订阅体系能闭环的关键。

5.3 两阶段全文搜索

C 端搜索入口 SearchService.searchMedia 的分流逻辑：

if (StringUtils.isNotEmpty(fuzzyMatchingParams.getKeyword())) {
    // 有关键词：内部库全文检索 → 返回 docId + mark（类型）
    resp = searchApi.matchSearch(keyword, marks, pageId, pageSize, tenantIds, params);
} else {
    // 无关键词：纯结构化筛选（找片页、分类浏览）
    resp = searchApi.find(marks, pageId, pageSize, tenantIds, params);
}
// 按 mark 分流 person / meta，回查详情索引取完整数据
openSearchUtil.batchGetDocuments(PERSON_DETAIL.getIndexName(), personDocIds, PersonDetail.class);
openSearchUtil.batchGetDocuments(META_DETAIL.getIndexName(), metaDocIds, MetaDetail.class);

查询条件从哪来？API 层收的是 SQL 风格的 where 模板（MetaQuery.whereTemplate + parameters），WhereClauseUtil 用正则把 in (:x)、between and、JSON_CONTAINS_ALL/ANY 解析成 ES 的 Condition（IN / GREATER_THAN 等），字段名经 FieldNameMappingEnum 做外部名→索引字段名映射。

这个设计的好处：对前端/上游服务来说，查询语法是稳定的数据库风格，不暴露 ES DSL；ES mapping 改名、换引擎，外部无感。

5.4 自动补全：completion suggester + 租户隔离

// SearchService.suggest
List<Prompt> prompts = searchApi.getPromptList(keyword, marks, true, companyId, size, uuid);
// 底层 = 搜索索引 suggest 字段的 completion suggester，
// context 里带 tenantCate=companyId → 补全结果按运营商隔离
// 拿到 docId 后再回查详情索引组装标题和海报

举例如"用户输入 int"：

sequenceDiagram
    participant U as 用户(运营商A)
    participant S as SearchService
    participant SE as 搜索索引 suggester
    participant D as 详情索引
    U->>S: suggest("int", companyId=A)
    S->>SE: completion suggest<br/>context: tenantCate=A
    SE-->>S: ["Interestelar", "Intocáveis"]<br/>+ docId 列表
    S->>D: mget(docIds)
    D-->>S: 标题 + 海报 URL
    S-->>U: 补全列表（带封面）

5.5 一个常被忽略的性能点：只取 ID 就别加载 _source

// fastGetDocumentById：判断文档存在/取 ID 时
// storedFields("_id") + size(1) + trackTotalHits(false)
// 注释原话：类似 MySQL 的 LIMIT 1

trackTotalHits(false)：不精确统计总数（默认只算到 10000），省掉一次全量计数；
storedFields("_id")：不加载 _source，网络传输量从几十 KB 降到几十 B。

列表页"先查 ID 再回查"的场景，这两招能把响应时间砍掉一个量级。

六、增量订阅：ES 作为"变更数据源"

下游服务（推荐、缓存、其他中台）需要感知媒资变更。项目没有用 CDC 或 MQ 广播，而是让下游基于水位游标主动拉取 ES：

sequenceDiagram
    participant SUB as 下游订阅方
    participant Q as SubqueryService
    participant ES as 详情索引

    Note over SUB: 记录上次水位 W0<br/>（lastModifiedIndicator 字符串）
    SUB->>Q: querySubQuery(from=W0, size=500)
    Q->>ES: range(lastModifiedIndicator: gt W0, lt 当前时间-2s)<br/>+ 按 lastModifiedIndicator 升序
    ES-->>Q: 本批变更文档（含软删除的）
    Q-->>SUB: 文档 + 新水位 W1
    SUB->>SUB: 落库/更新缓存，记录 W1
    Note over Q,ES: 对账：subQueryCount 用 count + sort desc + size(1)<br/>取区间最大水位，生产方/消费方核对数量

几个工程细节值得细说：

水位是字符串而非时间戳：lastModifiedIndicator = 时间戳 + "_" + docId。纯时间戳会在同一毫秒内有多个文档时漏数；拼上 docId 后字典序唯一，range gt 翻页不会漏、不会重。这是项目用手写游标替代 search_after 的原因——行为完全可控，且不依赖 ES 的 PIT（point in time）上下文。
lt 当前时间 - 2s 的回调偏移：规避"刚写入还没 refresh 可见"的窗口（第 2.2 节 NRT 原理的直接应用），宁可晚 2 秒，不可漏数据。
软删除文档也带着新水位出现，下游据此删除本地副本——和第 5.2 节的脚本闭环。

七、多租户设计：docId 里藏着租户

// OpenSearchUtil.getDocId：文档 ID = companyId + "#" + metaId
// 例："1001#mv_8848123"、"public#mv_8848123"（公共库）

同一部影片，A 运营商和 B 运营商是两份文档（各自的标题、定价、上架状态可能不同），天然物理隔离；
sourceType 字段区分 PRIVATE（私有）/ PUBLIC（公共）/ MIXED（混合），公共内容用 public# 前缀，查询时按租户策略合并；
所有查询 filter 里都带 companyId / tenant_id，补全用 context 隔离（第 5.4 节）。

经验：多租户搜索系统，把租户编进 docId 比单纯加过滤字段更稳——docId 冲突本身就是一道防串租户的保险。

八、回到原理：这个项目验证了哪些书里的论断

书中原理	项目里的体现
Mapping 先行，改 analyzer 要重建索引	索引 DDL 用 changelog 版本化管理，上线流程化
Filter 不算分、可缓存	租户/类型/软删除/状态全部进 filter，只有关键词算分
多字段映射解决"一个字段多种搜法"	mainTitle 四层子字段：分词/长ngram/短ngram/keyword
NRT 的 refresh 是性能旋钮	批量写入用 `refresh=WaitFor`；订阅端留 2s 偏移
深度翻页要避免 from+size 深分页	手写 `lastModifiedIndicator` 游标替代 search_after
聚合昂贵，慎用	项目几乎零聚合；取最大值用 sort+size(1) 替代 max agg
分片数创建时定死，规划要前置	详情索引 6 分片按数据增长预估；搜索索引刻意 1 分片

九、总结

如果把这套架构压缩成一张图：

graph LR
    W["写路径<br/>MySQL 事务<br/>+ 任务表兜底"] --> ES
    subgraph ES["OpenSearch"]
        S["搜索索引<br/>小而快：ngram+suggester<br/>+租户 context"]
        D["详情索引<br/>大而全：keyword+nested<br/>dynamic:false"]
    end
    ES --> R1["读路径 ①<br/>搜索/补全 → docId"]
    R1 --> R2["读路径 ②<br/>mget 详情组装"]
    ES --> R3["订阅路径<br/>水位游标增量拉取"]

三条核心经验：

索引按"查询模式"而不是"数据表"来设计：搜索索引和详情索引分开，一个为召回优化（ngram、suggester、多语分析器），一个为取数优化（keyword、nested、禁动态字段）；
一致性靠机制不靠运气：事务内直写是主路径，任务表 + 定时 Job + 失败重试是兜底，水位游标让下游最终一致——三层防护各管一段；
所有"黑科技"都是基本原理的应用：refresh 偏移、filter 缓存、storedFields 取 ID、游标翻页……吃透《Elasticsearch in Action》那套原理，生产方案都是它的排列组合。

参考资料：Radu Gheorghe, Matthew Lee Hinman, Roy Russo. 《Elasticsearch in Action》. Manning Publications, 2015；ftmao-meta 项目源码（OpenSearchConfig / OpenSearchUtil / SearchService / SubqueryService / changelog/elasticsearch）。

《Elasticsearch 权威指南》详解：零基础读懂 ES 的核心知识体系

Sat, 20 Jun 2020 09:00:00 +0800

《Elasticsearch 权威指南》详解：零基础读懂 ES 的核心知识体系

《Elasticsearch 权威指南》（Elasticsearch: The Definitive Guide，Clinton Gormley & Zachary Tong 著）是学习 Elasticsearch 公认的第一本书。中文版由 looly 等人组织社区翻译。它不是 API 手册，而是沿着"为什么这样设计“的路线，把 ES 从安装、文档 CRUD 一路讲到分布式内核、分词、相关性算分和集群运维。

这本书基于 ES 1.x/2.x 时代写成，个别细节（如 type 概念、TF/IDF 默认评分）在新版本有变化，但核心思想至今不变。本文面向从未读过这本书的人，按"基础概念 → 分布式原理 → 搜索 → 语言处理 → 聚合 → 建模 → 运维"的顺序完整梳理，配图解和可直接运行的实例。

一、Elasticsearch 是什么：先建立直觉

书的开篇用一句话定义 ES：

Elasticsearch 是一个分布式的、实时的文档存储与搜索引擎，基于 Apache Lucene 构建，通过 RESTful API 暴露 Lucene 的全部威力。

Lucene 本身是一个 Java 搜索库，强大但难用——ES 的价值在于把 Lucene 包装成一个可以水平扩展、开箱即用的分布式系统。书中列举的典型用户包括 Wikipedia（全文搜索 + 高亮 + 输入即搜 + 拼写纠错）、GitHub（检索 1300 亿行代码）、StackOverflow（“你可能想问"的 more-like-this 推荐）。

与关系型数据库的概念对照（这是全书最重要的入门表格）：

关系型数据库	Elasticsearch	说明
Database（库）	Index（索引）	逻辑命名空间
Table（表）	Type（类型）	⚠️ 新版已废弃，理解旧书时需要
Row（行）	Document（文档）	一条 JSON 记录
Column（列）	Field（字段）	文档的属性
Schema（表结构）	Mapping（映射）	字段类型定义
SQL	Query DSL	查询语言
index（索引，动词）	index（索引，动词）	把文档写入

关键区别：数据库假设"每行结构相同”，ES 的文档是无模式的 JSON（虽然实际上有 mapping 约束）；数据库为"精确存取"优化，ES 为”相关性检索“优化——它回答的问题不是"有没有”，而是"有多相关"。

1.1 十分钟跑起来：书中的第一个例子

全书第一章用一家虚构公司 megacorp 的员工数据贯穿：

# 写入一个员工文档（PUT = 指定 ID 创建/覆盖）
PUT /megacorp/employee/1
{
  "first_name": "John",
  "last_name":  "Smith",
  "age":        25,
  "about":      "I love to go rock climbing",
  "interests": ["sports", "music"]
}

# 取回（GET）
GET /megacorp/employee/1

# 轻量搜索：查询字符串
GET /megacorp/employee/_search?q=last_name:Smith

# 正式搜索：Query DSL（JSON 请求体）
GET /megacorp/employee/_search
{
  "query": { "match": { "last_name": "Smith" } }
}

注意这里没有建库、没有建表、没有定义字段类型——这就是"无模式"体验。但书里马上提醒：无模式是假象，ES 在背后做了动态映射（dynamic mapping），第一次见 "age": 25 就推断 age 是 long。生产环境应该显式定义 mapping（第四章详解）。

1.2 一个展示"相关性"的例子

GET /megacorp/employee/_search
{
  "query": {
    "bool": {
      "must":     { "match": { "about": "rock climbing" } },
      "filter":   { "range": { "age": { "gt": 30 } } }
    }
  }
}

返回结果中每个文档带一个 _score（相关性得分），按得分降序排列。must 里的 match 参与算分，filter 里的 range 只过滤不算分——这是全书反复出现的 query/filter 二分法，第六章详解。

二、分布式内核：ES 为什么能水平扩展

这是全书的硬核部分，也是 ES 区别于"单机 Lucene"的根本。

2.1 集群、节点与分片

graph TB
    subgraph CLUSTER["集群 cluster（一个 cluster.name）"]
        N1["节点 Node 1<br/>（一个 ES 进程）"]
        N2["节点 Node 2"]
        N3["节点 Node 3"]
    end
    subgraph IDX["索引 blogs（3 主分片 × 1 副本）"]
        P0["主分片 P0"] --- R0["副本分片 R0"]
        P1["主分片 P1"] --- R1["副本分片 R1"]
        P2["主分片 P2"] --- R2["副本分片 R2"]
    end
    N1 -.承载.- P0
    N1 -.承载.- R1
    N2 -.承载.- P1
    N2 -.承载.- R2
    N3 -.承载.- P2
    N3 -.承载.- R0
    style CLUSTER fill:#e8f0fe

要点：

分片（shard）是 ES 分布式能力的最小单元：一个分片就是一个完整的 Lucene 实例。索引只是"一组分片的逻辑命名空间"。
主分片数在创建索引时定死（路由哈希依赖它），副本分片数可以随时调整。
主副本不允许在同一节点——这样任意一台机器宕机，数据不丢、搜索不中断。
集群健康三态：green（所有主副本都就位）/ yellow（主分片齐了，副本缺）/ red（有主分片丢失，数据不可用）。

GET /_cluster/health   # 全书最常用的运维命令

2.2 扩容为什么是"免费"的

graph LR
    subgraph 三节点["3 节点"]
        A1["P0 R1"] 
        B1["P1 R2"]
        C1["P2 R0"]
    end
    subgraph 加一节点["加入第 4 节点后：自动再平衡"]
        A2["P0"]
        B2["P1 R0"]
        C2["P2"]
        D2["R1 R2"]
    end
    三节点 -->|"分片自动迁移<br/>无需停机"| 加一节点

分片是 Lucene 实例，搬分片 = 搬一个独立的小搜索引擎。ES 自动把分片挪到新节点，流量自动均摊。垂直扩容（换大机器）之外，ES 天生支持水平扩容（加机器）——这是书里"scale up vs scale out"一节的核心论点。

2.3 文档是怎么找到家的：路由

写入/读取一个文档时，ES 用它定位分片：

shard = hash(routing) % number_of_primary_shards

routing 默认是文档的 _id，也可以自定义（比如按用户 ID 路由，让同一用户的数据落在同一分片）。这解释了主分片数为什么不能改：改了模数，所有已有文档的哈希结果全部失效。

2.4 写入与读取的分布式流程

sequenceDiagram
    participant C as 客户端
    participant N as 协调节点<br/>（收到请求的任意节点）
    participant P as 主分片所在节点
    participant R1 as 副本节点1
    participant R2 as 副本节点2

    Note over C,N: 写入流程
    C->>N: PUT /blogs/post/123
    N->>N: 计算路由 hash(_id)%3 → P1
    N->>P: 转发写入
    P->>P: 本地写 Lucene + translog
    par 并行同步副本
        P->>R1: 复制写入
        P->>R2: 复制写入
    end
    R1-->>P: ack
    R2-->>P: ack
    P-->>N: 成功
    N-->>C: 201 + _version

    Note over C,N: 读取流程
    C->>N: GET /blogs/post/123
    N->>N: 路由计算 → 分片 P1
    N->>R2: 主/副本轮询负载均衡
    R2-->>N: 文档
    N-->>C: 200 + _source

两个关键设计：

任何节点都能当协调节点——没有单点入口；
写走主分片，读可以走主或副本——副本不仅容灾，还分摊读流量。加副本 = 加读吞吐。

三、近实时的秘密：refresh、translog 与段合并

“文档写入后为什么默认 1 秒才能搜到？“回答这个问题需要理解 Lucene 的存储模型。

3.1 倒排索引与不可变段

ES 快的根源是倒排索引：

graph LR
    subgraph 词典["Term Dictionary"]
        T1["climbing"]
        T2["music"]
        T3["rock"]
    end
    subgraph 倒排表["Posting List"]
        L1["doc 1, doc 5"]
        L2["doc 1, doc 3"]
        L3["doc 1"]
    end
    T1 --> L1
    T2 --> L2
    T3 --> L3

Lucene 把倒排索引持久化为段（segment），段一旦写出就不可变（immutable）。不可变性带来一串好处：不需要锁、可以进文件系统缓存、删除只需打标记。代价是：更新 = 删旧 + 建新，新写的文档必须先攒成新段才能被搜索。

3.2 完整链路

flowchart TD
    W["文档写入请求"] --> MEM["内存缓冲区"]
    W --> TL["translog<br/>（先写 WAL，防宕机丢数据）"]
    MEM -->|"refresh<br/>默认每 1 秒"| SEG["新 segment<br/>写入文件系统缓存<br/>→ 立即可被搜索"]
    SEG -->|"flush<br/>translog 满或定时"| DISK["fsync 落盘<br/>清空 translog"]
    SEG -.->|"后台 merge"| BIG["小段合并成大段<br/>物理清除已删文档"]

三个动作的分工：

refresh：内存 → 新的可搜索 segment（在文件系统缓存里，不落盘）。这就是"近实时（NRT）“的来源——默认 1 秒延迟。批量导入时可以调大 refresh_interval 换吞吐。
translog：预写日志。每个写入先记 translog，节点宕机后用它重放还没 flush 的数据。这是"ES 不丢数据"的底气。
flush：真正 fsync 落盘 + 清空 translog。
merge：小段太多会拖慢搜索（每个查询都要遍历所有段），后台线程持续把小段合并成大段，并顺带物理删除被标记删除的文档。

给初学者的记忆法：refresh 管"搜得到”，flush 管"丢不了”，merge 管"搜得快”。

四、映射与分析：数据进 ES 之前发生了什么

4.1 Mapping：字段的类型决定它能怎么被查

PUT /blogs
{
  "mappings": {
    "properties": {
      "title":    { "type": "text", "analyzer": "ik_max_word" },
      "status":   { "type": "keyword" },
      "views":    { "type": "integer" },
      "created":  { "type": "date" }
    }
  }
}

最核心的类型二分：

text：全文字段，会被分词后存入倒排索引，用于 match 全文检索；
keyword：精确值字段，原样入索引，用于过滤、排序、聚合。

书中金句："exact value 和 full text 的区别，是 SQL 世界和搜索世界的分界"。用 keyword 字段做 match 全文搜索（或反过来）是新手最常见的错误。

⚠️ 版本提示：原书写作时还是 string + analyzed/not_analyzed 的写法，ES 5.x 起拆分为 text/keyword，思想完全一致。

4.2 分析链：分词是怎么发生的

graph LR
    A["原始文本<br/>'The Quick Brown Fox!'"] --> CF["Character Filter<br/>字符过滤<br/>（去 HTML、字符映射）"]
    CF --> TK["Tokenizer<br/>分词器<br/>'The','Quick','Brown','Fox'"]
    TK --> TF["Token Filter<br/>词项过滤器<br/>lowercase → 停用词 → 词干提取"]
    TF --> R["最终词项<br/>'quick','brown','fox'"]

Character Filter：分词前做字符级预处理；
Tokenizer：把文本切成词项（一个分析器只能有一个 tokenizer）；
Token Filter：对词项再加工，可串联多个（lowercase、停用词、同义词、词干提取）。

内置的 standard 分析器 = standard tokenizer + lowercase + stop。可以用 _analyze API 眼见为实：

POST /_analyze
{ "analyzer": "standard", "text": "The Quick Brown Fox!" }
# → the, quick, brown, fox（'The' 被小写化）

中文场景：标准分词器会把中文逐字切开，效果很差。社区方案是 IK 分词器（ik_max_word 细粒度建索引、ik_smart 粗粒度搜索），这是中文 ES 项目的标配。

索引时与搜索时的分析必须配套：文档里的 "Fox" 入库时被分析成 fox；搜索 "FOX" 时查询词也会被同一个分析器处理成 fox 去匹配——这就是为什么 ES 搜索"不区分大小写"：不是查询忽略了大小写，而是两边都被 lowercased 了。

五、搜索：Query DSL 的全景

5.1 Query 与 Filter：全书最重要的性能概念

graph TD
    Q["Query 上下文<br/>'这个文档和查询有多相关？'"]
    F["Filter 上下文<br/>'这个文档是否匹配？'"]
    Q --> A1["计算 _score<br/>结果按相关性排序"]
    F --> A2["只答 yes/no<br/>不算分、结果可被缓存"]
    style Q fill:#fef3e8
    style F fill:#e1f5e1

经验法则：能用 filter 就不用 query。过滤条件（状态、时间范围、ID 列表）放 filter，既省算分开销又能命中 bitset 缓存。

5.2 常用查询速查

查询	用途	例子
`match`	全文搜索（会分词）	标题含"登山装备"
`term`	精确匹配（不分词）	status 等于 “published”
`terms`	多值精确匹配	标签 in [“科幻”,“动作”]
`range`	范围	age ≥ 30
`exists`	字段非空	必须有 poster 字段
`multi_match`	跨多字段全文	同时在标题和简介里搜
`match_phrase`	短语匹配（词序相邻）	搜 “rock climbing” 不拆词
`bool`	组合一切	见下

5.3 bool 查询：乐高积木

GET /megacorp/employee/_search
{
  "query": {
    "bool": {
      "must":     [ { "match": { "about": "rock climbing" } } ],
      "should":   [ { "match": { "interests": "music" } } ],
      "must_not": [ { "term":  { "last_name": "smith" } } ],
      "filter":   [ { "range": { "age": { "gte": 30 } } } ]
    }
  }
}

must：必须匹配，参与算分；
should：最好匹配，匹配上加分（没有 must/filter 时至少命中一个）；
must_not：必须不匹配，不参与算分（在 filter 上下文执行）；
filter：必须匹配，不参与算分。

所有复杂查询都是这四块积木的嵌套。

5.4 相关性算分：_score 是怎么来的

书里讲了经典的 TF/IDF 模型（新版本默认换成 BM25，思想相同，多了文档长度归一化）：

词频 TF：词在本文档出现越多，越相关；
逆文档频率 IDF：词在所有文档中越罕见，区分度越高（“的"不值钱，“攀岩"值钱）；
字段长度：字段越短，匹配越"精悍”，得分越高。

对结果有疑问时用 _explain API 看算分过程——这是调搜索体验的第一件工具。

5.5 深分页陷阱

GET /_search?from=10000&size=10   # ⚠️ 危险

分布式搜索是 scatter-gather 模式：

sequenceDiagram
    participant C as 客户端
    participant CO as 协调节点
    participant S0 as 分片0
    participant S1 as 分片1
    participant S2 as 分片2
    C->>CO: from=10000, size=10
    par scatter
        CO->>S0: 各分片先取 Top 10010
        CO->>S1: 各分片先取 Top 10010
        CO->>S2: 各分片先取 Top 10010
    end
    S0-->>CO: 10010 条
    S1-->>CO: 10010 条
    S2-->>CO: 10010 条
    CO->>CO: 归并 30030 条，取 10001~10010
    CO-->>C: 10 条

取第 1001 页，要在每个分片各取 10010 条再归并。深度翻页成本线性爆炸，书里的忠告是"不要在搜索场景做深翻页”；确实需要遍历全量时，用 scroll（游标快照）或新版本的 search_after。

六、处理人类语言

这一部分是本书区别于普通教程的精华：搜索的本质对手是自然语言的模糊性。

语言分析器：英语词干提取（foxes→fox）、德语的复合词拆分、中文/日文的无空格分词。每种语言的正确处理方式完全不同——选对语言分析器比调任何参数都重要。
拼写纠错（did-you-mean）：term suggester / phrase suggester，“你搜的是不是 elasticsearch？”
输入即搜（search-as-you-type）：用 edge ngram（前缀 ngram）在索引时把 "elasticsearch" 切成 e, el, ela, ...，用户每敲一个字母就能命中。
近似匹配：match 的 fuzziness 参数基于编辑距离，容忍拼写错误（searching 打成 serching 也能命中）。
近似短语：match_phrase 的 slop 参数允许词与词之间隔着几个词仍算匹配。

这一部分的共同心法：召回率与准确率的权衡。ngram 开得越大、fuzziness 越高，召回越好但噪音越多；工程上常用"多层子字段"（精确字段 + 分词字段 + ngram 字段）分层兜底。

七、聚合：从搜索到分析

搜索回答"哪些文档匹配"，聚合（aggregations） 回答"数据整体长什么样"。聚合分两大类，可以无限嵌套：

桶（Bucket）聚合：把文档分组——terms（按字段值）、date_histogram（按时间）、range（按区间）；
度量（Metric）聚合：对组内文档算统计——avg/sum/min/max/stats/cardinality。

7.1 实例：员工数据统计

GET /megacorp/employee/_search
{
  "size": 0,
  "aggs": {
    "by_interest": {              # 桶：按兴趣分组
      "terms": { "field": "interests" },
      "aggs": {
        "avg_age": {              # 嵌套度量：每组平均年龄
          "avg": { "field": "age" }
        }
      }
    }
  }
}

graph TD
    A["全部员工文档"] -->|"terms 桶 by_interest"| B1["sports 组"]
    A --> B2["music 组"]
    A --> B3["forestry 组"]
    B1 --> C1["avg_age = 28.5"]
    B2 --> C2["avg_age = 31.2"]
    B3 --> C3["avg_age = 35.0"]

7.2 要点

size: 0：只要聚合不要文档，省掉无用传输；
聚合只能跑在 keyword/数值/日期等精确值字段上——在 text 字段上聚合会失败或慢到崩溃（需要 fielddata，默认关闭，这是个性能地雷）；
高基数 terms 聚合（如按 userId 分桶）吃内存，新版有 circuit breaker 兜底；
近似聚合是 ES 的特色：cardinality（去重计数）和 percentiles（百分位）都是近似算法，用微小误差换海量数据下的可用性。

八、关系建模：ES 不是数据库

书里最"劝退"也最重要的一章：ES 没有 join。建模关系的四种方式按推荐顺序：

方式	思路	代价	适用
反规范化（Denormalize）	把关联数据冗余进每个文档	数据重复、更新要改多处	首选，读多写少
应用层 join	查两次，在代码里拼接	多一次网络往返	一对多且"多"侧很大
nested 对象	对象数组整体索引，保持内部关联	查询稍慢，更新整文档重建	对象数组（如文章的评论列表）
parent-child（join 字段）	父子文档独立存储，同分片关联	查询开销最大	子文档频繁独立更新

默认答案永远是先反规范化。搜索系统的哲学是"用写入时的冗余，换查询时的简单"——磁盘便宜，join 昂贵。

九、集群管理与运维要点

最后一部分面向生产：

节点角色分工：master 节点管集群元数据（建议 3 个专职 master 防脑裂）、data 节点存数据、协调节点转发请求。大集群应该角色分离。
脑裂与 minimum_master_nodes：网络分区时两个子集群各自选主 = 数据写烂。经典配置是 master 节点数 / 2 + 1（新版本的集群选举机制已自动化）。
分片规划：分片不是越多越好——每个分片都有固定开销（文件句柄、内存、段管理）。单分片控制在几十 GB 量级、节点堆内存 32GB 以内（压指针上限）、堆内存不超过物理内存一半（另一半留给文件系统缓存）。
监控集群健康：green/yellow/red + hot_threads + cat API 家族。
升级与备份：滚动升级逐个节点来；快照（snapshot）到 S3/HDFS 做备份。

十、全书知识地图

graph TD
    CORE["倒排索引<br/>（一切的根基）"]
    CORE --> WRITE["写入链路<br/>refresh/translog/merge<br/>→ 近实时 + 不丢数据"]
    CORE --> SEARCH["搜索<br/>Query/Filter + bool 组合<br/>TF-IDF 相关性算分"]
    CORE --> AGG["聚合<br/>桶 × 度量嵌套"]
    WRITE --> DIST["分布式<br/>分片路由 scatter-gather<br/>主副本容灾"]
    SEARCH --> LANG["语言处理<br/>分析器/纠错/输入即搜"]
    SEARCH --> MODEL["建模<br/>反规范化优先"]
    DIST --> OPS["运维<br/>健康监控/分片规划/防脑裂"]
    style CORE fill:#e1f5e1

如果只能记住三句话：

一切性能与行为的答案都在倒排索引里：不可变段决定了 NRT，分词决定了查不查得到，keyword/text 之分决定了能不能聚合；
query 算分、filter 缓存——写任何查询前先想这一条；
分片是分布式的原子：路由公式决定了主分片数不能改，副本决定了读吞吐和容灾。

参考资料：Clinton Gormley, Zachary Tong. 《Elasticsearch: The Definitive Guide》. O’Reilly, 2015. 中文版：elasticsearch-definitive-guide-cn（looly 等译）。