https://docs.infinilabs.com/easysearch/v2.2.0/Recent content in INFINI Easysearch on INFINI Easysearch (v2.2.0) | 分布式搜索型数据库Hugo -- gohugo.iohttps://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/query-filter-context/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/query-filter-context/查询与过滤上下文 # 查询由查询子句组成，这些子句可以在过滤（filter）上下文或查询上下文中运行。 在过滤（filter）上下文中的查询子句会询问"文档是否匹配查询子句？“并返回匹配的文档。在查询上下文中的查询子句会询问"文档与查询子句匹配程度如何？"，返回匹配的文档，并以相关性分数的形式提供每个文档的相关性。 相关指南（先读这些） # 查询 DSL 基础 结构化搜索 相关性分数 # 相关性分数衡量文档与查询的匹配程度。它是一个正浮点数，Easysearch 会记录在每个文档的 _score 元数据字段中： "hits" : [ { "_index" : "shakespeare", "_id" : "32437", "_score" : 18.781435, "_source" : { "type" : "line", "line_id" : 32438, "play_name" : "Hamlet", "speech_number" : 3, "line_number" : "1.1.3", "speaker" : "BERNARDO", "text_entry" : "Long live the king!" } }, ... 一个更高的分数表示文档更相关。虽然不同的查询类型计算相关性分数的方式不同，但所有查询类型都会考虑查询子句是在过滤（filter）上下文还是查询上下文中运行。 在查询上下文中使用你想影响相关性分数的查询子句，并在过滤（filter）上下文中使用所有其他查询子句。 过滤上下文 # 在过滤上下文中的查询子句会问“文档是否匹配查询子句？”，这个问题有二元答案。例如，如果你有一个包含学生数据的索引，你可以使用过滤上下文来回答以下关于学生的疑问:https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/agent-gui/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/agent-gui/通过 Agent 图形界面部署 Easysearch # Agent 支持图形化一键拉起新集群（开发/生产双模式），用户无需手动编辑任何配置文件，通过图形界面即可完成 Easysearch 集群的安装、配置和日常管理。 安装 Agent macOS/Linux 用户可以通过如下脚本进行快速安装： curl -sSL http://get.infini.cloud | bash -s -- -p agent Windows 用户可以手动下载安装包进行安装，见 安装 INFINI Agent。 运行 Agent Linux / macOS cd agent-x.y.z-xxxx ./agent-x.y.z Windows cd agent-x.y.z-xxxx .\agent-x.y.z.exe 浏览器访问 Agent Agent UI 默认监听在 http://127.0.0.1:9000，浏览器打开此地址。 登录 Agent 见 服务管理登录 创建 Easysearch 集群 图形化部署支持 2 种创建集群的方式，见:https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/audit-log/audit-config/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/audit-log/audit-config/审计配置 # 操作步骤 # 进入审计日志页面：在左侧导航栏点击「审计日志」，进入审计日志管理页。 打开审计配置弹窗：点击页面右上角的「审计配置」按钮，弹出「审计配置」配置窗口。 配置基础审计参数： 开启审计：打开「开启审计」总开关，启用系统审计功能。 合规配置：按需开启「记录日志差异」「仅读取元数据」「仅写入元数据」开关。 网络配置：按需开启「外部配置」「内部配置」开关。 读取监控字段：在输入框中填写自定义 JSON 格式的监控字段配置。 配置审计范围与规则： 读写过滤：按需填写「读取忽略用户」「写入监控索引」「写入忽略用户」。 审计开关：按需开启「开启 REST 审计」「开启 Transport 审计」「记录请求体」「解析索引」「解析批量请求」。 敏感信息处理：开启「排除敏感头」开关，自动过滤敏感头部信息。 精准过滤：按需填写「仅包含用户」「忽略用户」「忽略请求」。 类别禁用：在「禁用 REST 类别」「禁用 Transport 类别」中，选择需要排除审计的请求类别。 保存配置：完成所有配置后，点击弹窗右下角的「保存」按钮，生效审计规则。 查看审计日志：配置生效后，系统将采集符合规则的审计事件，可在审计日志列表中查看、刷新或导出日志。 注意事项 # 开启审计功能会对集群性能产生一定影响（尤其是「记录请求体」和「解析批量请求」），在高负载集群上建议根据实际需要有选择性地开启。 建议配置「忽略用户」排除系统内部用户和监控账号，避免产生大量无意义的审计记录。 「仅读取元数据」和「仅写入元数据」开启后将只记录操作元信息而不记录具体内容，可在满足合规要求的同时降低日志量。 「排除敏感头」建议始终保持开启，避免将认证凭据等敏感信息写入审计日志。 审计配置修改后立即生效，无需重启集群。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/bboss/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/bboss/Bboss 集成 # Bboss 是一款高性能、高兼容性的搜索引擎 Java REST 客户端框架，基于 Apache License 2.0 开源，原生支持 Elasticsearch、Easysearch 和 Opensearch。自带客户端集群节点负载均衡和容灾，多集群多数据源，自动索引托管，多种分页机制，傻瓜级 CRUD，脚本，SQL，JDBC，高亮，权重，聚合，IP，GEO 地理位置，父子嵌套，应有尽有。 源码仓库： https://gitee.com/bboss/bboss-elastic 官方文档： https://esdoc.bbossgroups.com/ Maven 中央仓库： bboss-datatran-jdbc 核心优势 # 特性 说明 学习成本低 无需学习额外 API，只需掌握 Elasticsearch DSL，极简使用方式 原生多引擎支持 完美支持 ES 1.x ~ 9.x、Easysearch 1.x ~ 2.x+、Opensearch 1.x ~ 2.x+ 开箱即用 Spring Boot 自动配置，无需复杂设置 高效异步处理 内置 BulkProcessor 异步批处理器，大幅提升写入性能 灵活查询方式 支持 DSL、SQL、O/R Mapping 多种查询模式 多数据源支持 一个应用可同时操作多个不同版本的搜索引擎集群 完整的结果封装 返回结果支持 JSON、PO 对象、List 集合、Map 等多种类型 客户端负载均衡 默认启用客户端负载均衡，容灾性更好 快速开始 # 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/easy-es/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/easy-es/Easy-ES 查询框架 # Easy-ES 是 Dromara 开源社区下的搜索引擎 ORM 框架，类似于 MyBatis-Plus 之于 MySQL。它在 Java 客户端的基础上只做增强不做改变，提供 Lambda 风格的简洁 API，可减少 50%~80% 的代码量。 Easy-ES 提供了专门的 Easysearch 原生分支，底层直接使用 Easysearch Java Client，无需 ES API 兼容模式，具备完整的原生性能和功能支持。 源码仓库： https://gitee.com/dromara/easy-es/tree/easy-es4easySearch Maven 中央仓库： easy-es-boot-starter 2.1.0-easysearch 核心优势 # 特性 说明 极简开发 一行代码完成查询，相比原生 API 代码量减少 50%~80% 自动索引管理 索引全生命周期由框架自动托管，零停机更新，无需手动管理 SQL 语法兼容 支持 MySQL 风格的 and、or、like、in 等常用语法查询 Lambda 表达式 类型安全的字段访问，避免手写字段名导致的错误 Spring Boot 集成 开箱即用的自动配置，完美融入 Spring Boot 生态 原生 Easysearch 支持 底层使用 Easysearch Java Client，无需兼容层 快速开始 # 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/embedding-service/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/embedding-service/Embedding 服务接入 # 要在 Easysearch 中使用向量检索，首先需要将文本（或其他数据）转换为向量表示。这个过程需要 Embedding 模型服务的支持。 相关指南（先读这些） # 向量检索 Ingest Text Embedding Search Text Embedding LangChain 集成 部署模式 # 模式一：写入链路嵌入（推荐） # 在数据写入 Easysearch 时，通过 Ingest Pipeline 自动调用 Embedding 服务： 应用数据 → Easysearch Ingest Pipeline → 调用 Embedding API → 写入向量字段 优势是写入后即可搜索，无需维护外部向量化流程。参见 Ingest Text Embedding。 模式二：查询链路嵌入 # 搜索时实时将查询文本转换为向量，在 Easysearch 中做 kNN 检索： 用户查询 → 调用 Embedding API → 向量化 → Easysearch kNN 搜索 参见 Search Text Embedding。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/java/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/java/Java 客户端集成与示例 # Easysearch Java API Client 是 Easysearch 的官方 Java 客户端，提供了强类型、流式构建器风格的 API 接口。新项目推荐使用此客户端。 全新重构的 2.0.x 版本，更轻量，移除冗余依赖 兼容 Easysearch 各版本 支持阻塞和异步两种调用方式 使用流式构建器和函数式模式，代码简洁易读 通过 Jackson 无缝集成应用类 相关指南 # 官方 Java Client API 文档 如何使用 Curl 操作 依赖引入 # Maven # <dependency> <groupId>com.infinilabs</groupId> <artifactId>easysearch-client</artifactId> <version>2.0.2</version> </dependency> Gradle # implementation 'com.infinilabs:easysearch-client:2.0.2' 已发布到 Maven 中央仓库： mvnrepository.com/artifact/com.infinilabs/easysearch-client，需要 JDK 8 或以上。 连接配置 # 基础连接（带认证 + HTTPS） # Easysearch 默认启用安全认证和 HTTPS，以下代码展示完整的连接初始化：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/normalizers/lowercase/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/normalizers/lowercase/Lowercase 规范化器 # lowercase 是 Easysearch 内置的规范化器，将 keyword 字段的整个值转换为小写形式。无需在 settings 中定义即可直接使用。 使用方式 # 在映射中直接引用： PUT my-index { "mappings": { "properties": { "status": { "type": "keyword", "normalizer": "lowercase" } } } } 效果演示 # 索引文档： PUT my-index/_doc/1 { "status": "OK" } PUT my-index/_doc/2 { "status": "Ok" } PUT my-index/_doc/3 { "status": "ok" } 查询时，无论使用哪种大小写形式都能匹配所有文档： GET my-index/_search { "query": { "term": { "status": "OK" } } } 三个文档都会被返回，因为 "OK"、"Ok"、"ok" 在索引时都被归一化为 "ok"。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/match-all/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/match-all/Match All 查询 # match_all 查询返回所有文档。如果需要返回整个文档集，这个查询在测试大量文档集时很有用。 相关指南（先读这些） # 查询 DSL 基础 结构化搜索 GET _search { "query": { "match_all": {} } } match_all 查询有一个 match_none 的对应查询，这个对应查询很少有用： GET _search { "query": { "match_none": {} } } 参数说明 # 全匹配和全不匹配查询都接受以下参数。所有参数都是可选的。 参数 数据类型 描述 boost Float 一个浮点数值，用于指定该字段对相关性分数的权重。大于 1.0 的值会增加字段的权重。介于 0.0 和 1.0 之间的值会降低字段的权重。默认值为 1.0。 _name String 用于查询标签的查询名称。可选。 常见使用场景 # 配合 filter 使用 # match_all 经常与过滤器结合使用，在不需要相关性评分的场景下获取文档子集：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/numa/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/numa/NUMA 配置指南 # 在多路服务器（2 路及以上 CPU）上部署 Easysearch 时，NUMA（Non-Uniform Memory Access）拓扑会显著影响性能。不当的配置可能导致跨节点内存访问，增加延迟 30%–50%。 NUMA 基础概念 # ┌──────────────┐ ┌──────────────┐ │ NUMA Node 0│ │ NUMA Node 1│ │ CPU 0-15 │ │ CPU 16-31 │ │ 本地内存 128G│◄──►│ 本地内存 128G│ │ 延迟 ~80ns │ QPI│ 延迟 ~80ns │ └──────────────┘ └──────────────┘ 本地访问快 跨节点访问慢 (~130ns) 每个 CPU 有自己的本地内存，访问本地内存最快 访问远端 NUMA 节点的内存需要通过互联总线（QPI/UPI），延迟更高 JVM 大堆 + 跨 NUMA 节点 = GC 停顿时间增加 查看 NUMA 拓扑 # # 查看 NUMA 节点信息 numactl --hardware # 输出示例 available: 2 nodes (0-1) node 0 cpus: 0 1 2 3 4 5 6 7 16 17 18 19 20 21 22 23 node 0 size: 131072 MB node 1 cpus: 8 9 10 11 12 13 14 15 24 25 26 27 28 29 30 31 node 1 size: 131072 MB node distances: node 0 1 0: 10 21 1: 21 10 # 查看当前内存分配策略 numactl --show 推荐配置方案 # 方案一：绑定单个 NUMA 节点（推荐） # 将 Easysearch 进程绑定到一个 NUMA 节点，确保所有内存访问都在本地：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/observability/opentelemetry/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/observability/opentelemetry/OpenTelemetry 集成 # 本页从架构和建模角度，讲清楚一件事：如果你已经用了 OpenTelemetry，怎么把指标/日志/Trace 稳定地落到 Easysearch 上，并跑起来统一分析？ 数据流：应用 → OTel SDK → OTel Collector → Easysearch 索引与 mapping：metrics / logs / traces 三类数据怎么按索引和字段建模 与现有监控/告警体系的分工：谁做实时告警，谁做长期存储与分析 不涉及具体 Collector 配置语法的全集，只给出 Easysearch 侧的“接入契约”与推荐套路。 1. OTel → Easysearch 的典型数据流 # 一个常见部署大致长这样： 应用侧：接入 OTel SDK（或通过语言/框架集成），上报 metrics / logs / traces OTel Collector：集中收集、处理、转发 OTel 数据 输出到 Easysearch： 通过支持 Easysearch/ES 协议的 exporter 或通过自定义 exporter / gateway，将数据转换为 Easysearch 可接受的 HTTP 请求（通常是 _bulk） 在 Easysearch 看来，本质上就是有一条“写入大量结构化/半结构化数据”的管道，区别只在于字段和索引设计。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/scripting/painless/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/scripting/painless/Painless 脚本语言 # Painless 是 Easysearch 内置的高性能脚本语言，也是默认脚本语言。它专为搜索引擎场景设计，具备以下特点： 高性能：编译为 Java 字节码，通过 JIT 直接在 JVM 上运行 安全沙盒：只允许访问白名单内的 Java API，无法执行文件、网络等危险操作 Java 风格语法：对 Java 开发者友好，学习成本低 专用优化：内置 doc、_source、ctx 等快捷访问方式 基本语法 # 变量与类型 # Painless 是强类型语言，支持类型推断： // 显式类型声明 int count = 10; double price = 99.5; String name = "Easysearch"; boolean active = true; // 类型推断（使用 def） def value = doc['price'].value; def list = [1, 2, 3]; def map = ['key': 'value', 'count': 42]; 支持的基本类型：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/query-dsl-basics/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/query-dsl-basics/Query DSL 基础 # 这一页的目标是：在不记任何 API 细节的前提下，先把 Query DSL 的“骨架”和核心概念讲清楚，后面看具体查询语法就会轻松很多。 JSON 结构而不是"SQL 语句" # Easysearch 的查询是 JSON 结构，而不是一条字符串语句。一个最小的查询大致长这样： GET /_search { "query": { "match": { "message": "hello world" } } } 要记住两个层级： 最外层的 "query"：说明这是一个"查询上下文" "match"、"term"、"range" 等：都是不同类型的"子查询" 查询语句的结构 # 一个查询语句的典型结构： { QUERY_NAME: { ARGUMENT: VALUE, ARGUMENT: VALUE,... } } 如果是针对某个字段，那么它的结构如下： { QUERY_NAME: { FIELD_NAME: { ARGUMENT: VALUE, ARGUMENT: VALUE,... } } } 例如，使用 match 查询语句来查询 tweet 字段中包含 easysearch 的文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ingest/logstash/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ingest/logstash/使用 Logstash 接入数据 # Logstash 适合做“重量级管道”：支持丰富的输入源、过滤器和输出插件。 这一页只解决几个核心问题： 最小可用的 Logstash → Easysearch pipeline 长什么样？ 和 Easysearch 的索引与 mapping 怎么配合，避免“写进去一团糊”？ 在生产环境里，批量大小、重试、幂等这些常见坑怎么规避？ 1. 最小可用 Pipeline 示例 # 下面是一个从文件读取日志、简单解析后写入 Easysearch 的最小示例（概念结构）： input { file { path => "/var/log/app/app.log" start_position => "beginning" sincedb_path => "/var/lib/logstash/.sincedb_app" } } filter { # 示例：按 JSON 日志解析 json { source => "message" } # 示例：统一时间字段名称 if [timestamp] { mutate { rename => { "timestamp" => "@timestamp" } } } } output { elasticsearch { hosts => ["http://easysearch:9200"] index => "app-logs-%{+YYYY.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/switch-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/switch-index/切换索引 # 在数据探索页面中，可以切换当前查询的目标索引。 操作步骤 # 打开索引选择下拉框：在数据探索页面顶部，点击当前索引名称（示例中为 nginx_zstd-1）旁的下拉箭头，展开索引选择列表。 选择目标索引：在展开的列表中，点击需要切换的目标索引（如 .security、.analysis_ik 等），列表会同步展示各索引的存储占用、文档数等信息。 完成切换：选中目标索引后，页面将自动加载该索引下的所有文档数据，完成索引切换。 快速检索索引：可在列表顶部的搜索框中输入索引名称，快速筛选定位目标索引，提升切换效率。 注意事项 # 切换索引后，当前已设置的过滤条件和搜索语句将被清空，如有需要请提前记录查询条件。 索引需包含时间字段才能使用时间范围筛选功能，无时间字段的索引将无法按时间过滤数据。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/create-ingest/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/create-ingest/创建管道 # 使用 PUT _ingest/pipeline API 创建或更新摄取管道。如果指定的 pipeline-id 已存在，则覆盖更新。 请求格式 # PUT _ingest/pipeline/<pipeline-id> 示例 # 创建一个包含 set 和 uppercase 处理器的管道： PUT _ingest/pipeline/my-pipeline { "description": "处理学生数据：设置毕业年份并转大写", "processors": [ { "set": { "description": "设置毕业年份", "field": "grad_year", "value": 2023 } }, { "set": { "description": "标记已毕业", "field": "graduated", "value": true } }, { "uppercase": { "field": "name" } } ] } 成功响应： { "acknowledged": true } 请求体参数 # 参数 必需 类型 说明 processors 是 array 有序处理器列表，按定义顺序依次执行 description 否 string 管道描述，出现在 GET _ingest/pipeline 的返回中 路径参数 # 参数 必需 类型 说明 pipeline-id 是 string 管道的唯一标识符 查询参数 # 参数 必需 类型 默认值 说明 cluster_manager_timeout 否 时长 30s 等待集群管理器节点响应的超时时间 timeout 否 时长 30s 等待整体响应的超时时间 Mustache 模板 # 处理器参数中可以使用 Mustache 模板引用文档字段。用三个花括号包裹字段名 {{{field_name}}} 可获取未转义的原始值：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/send-request/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/send-request/发送请求 # 操作步骤 # 进入开发工具页面：在左侧导航栏点击「开发工具」，进入开发工具编辑页。 编写请求语句：在左侧编辑区输入符合规范的请求语句（示例为 GET _search 查询语句）。 发送请求：点击编辑区右上角的绿色运行按钮，提交请求。 查看请求结果：请求执行完成后，在右侧「Result」标签页查看完整的响应结果，同时可查看响应状态、时延等信息。 补充说明 # 支持的 HTTP 方法包括 GET、POST、PUT、DELETE、HEAD 等。 请求语句格式为 METHOD endpoint，请求体使用 JSON 格式写在下一行，例如： GET _search { "query": { "match_all": {} } } 编辑区中可以同时编写多条请求，光标所在行的请求将被执行。 开发工具中的请求以当前登录用户的身份执行，请注意权限范围，避免在生产环境中执行写入或删除类操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/vector-search/vector-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/vector-search/vector-search/向量搜索指南 # 本页介绍如何在 Easysearch 中使用向量搜索——从创建索引到执行查询的完整流程。 前提条件 # 向量搜索需要 k-NN 插件。安装方法参见 插件安装。 注意：从 1.11.1 版本起，创建 k-NN 索引时不再需要配置 index.knn 参数。 步骤一：创建向量索引 # 稠密浮点向量（最常用） # 适用于文本 Embedding、图像特征等场景： PUT /my-vectors { "mappings": { "properties": { "title": { "type": "text" }, "embedding": { "type": "knn_dense_float_vector", "knn": { "dims": 768, "model": "lsh", "similarity": "cosine", "L": 99, "k": 1 } } } } } 映射参数、各索引模型和相似度函数的完整说明，请参阅 向量字段类型参考。 步骤二：索引文档 # 向量通常由外部 Embedding 模型生成，写入时附带向量数据：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/basics/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/basics/基础查询 # 概述 # SELECT 语句是从 Easysearch 索引中检索数据的核心语法。完整语法如下： SELECT [ALL | DISTINCT] (* | expression) [[AS] alias] [, ...] FROM index_name [WHERE predicates] [GROUP BY expression [, ...] [HAVING predicates]] [ORDER BY expression [ASC | DESC] [NULLS {FIRST | LAST}] [, ...]] [LIMIT [offset, ] size] 语句末尾允许加分号 ;，这对 BI 工具和 Excel 生成的查询很有用。 执行顺序 # SQL 各子句的实际执行顺序与书写顺序不同： FROM index -- ① 确定数据源 → WHERE -- ② 行级过滤 → GROUP BY -- ③ 分组 → HAVING -- ④ 组级过滤 → SELECT -- ⑤ 字段投影 → ORDER BY -- ⑥ 排序 → LIMIT -- ⑦ 分页 SELECT # SELECT 子句指定要检索的字段。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/conditional-execution/complex-conditionals/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/conditional-execution/complex-conditionals/复杂逻辑 # 在摄取管道中，处理器中的 if 参数可以使用 Painless 脚本来评估复杂条件。这些条件有助于微调文档处理，允许进行高级逻辑，例如类型检查、正则表达式和组合多个标准。 多条件检查 # 您可以将逻辑运算符如 && （与）、 || （或）和 ! （非）组合起来构建更复杂的条件。以下管道标签将文档标记为 spam ，如果它们包含一个高于 1000 的 error_code ，则将其丢弃： PUT _ingest/pipeline/spammy_error_handler { "processors": [ { "set": { "field": "tags", "value": ["spam"], "if": "ctx.message != null && ctx.message.contains('OutOfMemoryError')" } }, { "drop": { "if": "ctx.tags != null && ctx.tags.contains('spam') && ctx.error_code != null && ctx.error_code > 1000" } } ] } 您可以使用以下 _simulate 请求测试管道： POST _ingest/pipeline/spammy_error_handler/_simulate { "docs": [ { "_source": { "message": "OutOfMemoryError occurred", "error_code": 1200 } }, { "_source": { "message": "OutOfMemoryError occurred", "error_code": 800 } }, { "_source": { "message": "All good", "error_code": 200 } } ] } 第一份文档被丢弃，因为它包含一个 OutOfMemoryError 字符串和一个高于 1000 的 error_code ：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/audit-log/export-audit-log/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/audit-log/export-audit-log/导出审计日志 # 审计日志记录了用户的登录、权限变更、索引操作等安全事件，可按需导出用于合规审查。 操作步骤 # 进入审计日志页面：在左侧导航栏点击「审计日志」，进入日志列表页，可查看所有集群操作的审计记录（包含操作人、时间、事件类型、来源等信息）。 触发导出操作：点击页面右上角的「导出」按钮，系统将自动打包当前审计日志数据并生成下载文件。 完成下载：浏览器会自动下载审计日志文件，文件格式为 audit_log.json，下载完成后即可在本地查看、留存审计日志。 注意事项 # 审计日志功能需要在集群配置中预先开启，未开启时此页面可能无数据。 导出的日志文件为当前页面筛选条件下的审计记录，如需完整日志，请确认筛选条件已覆盖目标时间范围。 审计日志文件可能较大，建议定期导出并归档，避免一次性导出过多数据导致浏览器卡顿。https://docs.infinilabs.com/easysearch/v2.2.0/docs/api-reference/common-parameters/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/api-reference/common-parameters/常用 URL 参数 # Easysearch 的 REST API 支持以下通用参数，适用于大部分接口。 参数 说明 示例 pretty 以缩进格式返回 JSON，便于阅读和调试。 GET <index_name>/_search?pretty=true human 将输出中的数值转换为人类可读格式（如 1h 代替 3600000ms，1kb 代替 1024 bytes）。 GET <index_name>/_search?human=true error_trace 当请求出错时，在响应中包含完整的异常堆栈信息，便于排查问题。 GET <index_name>/_search?error_trace=true format 指定返回格式。CAT API 支持 json、yaml、text 等格式。 GET _cat/indices?format=json filter_path 过滤响应字段，只返回指定路径的内容，减少网络传输量。支持通配符 *。 GET _cluster/health?filter_path=status,number_of_nodes flat_settings 以扁平化格式返回设置（index.number_of_shards 而非嵌套对象）。 GET <index_name>/_settings?flat_settings=true Content-Type 请求头，指定请求体的内容类型。支持 application/json、application/yaml、application/cbor。 POST _scripts/<template> -H 'Content-Type: application/json' source / source_content_type 当客户端不支持在非 POST 请求中发送请求体时，可通过查询参数传递请求体内容及其类型。 GET _search?https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/tutorial/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/tutorial/快速入门 # 为了让大家对 Easysearch 能实现什么及其上手难易程度有一个基本印象，让我们从一个简单的教程开始并介绍索引、搜索及聚合等基础概念。 我们将一并介绍一些新的技术术语，即使无法立即全部理解它们也无妨，因为在本书后续内容中，我们将继续深入介绍这里提到的所有概念。 接下来尽情享受 Easysearch 探索之旅。 创建一个雇员目录 # 我们受雇于 Megacorp 公司，作为 HR 部门新的"热爱无人机"（“We love our drones!"）激励项目的一部分，我们的任务是为此创建一个员工目录。该目录应当能培养员工认同感及支持实时、高效、动态协作，因此有一些业务需求： 支持包含多值标签、数值、以及全文本的数据 检索任一员工的完整信息 允许结构化搜索，比如查询 30 岁以上的员工 允许简单的全文搜索以及较复杂的短语搜索 支持在匹配文档内容中高亮显示搜索片段 支持基于数据创建和管理分析仪表盘 索引员工文档 # 第一个业务需求是存储员工数据。这将会以员工文档的形式存储：一个文档代表一个员工。存储数据到 Easysearch 的行为叫做索引，但在索引一个文档之前，需要确定将文档存储在哪里。 一个 Easysearch 集群可以包含多个索引，相应的每个索引可以包含多个文档，每个文档又有多个属性。 注意：索引这个词在 Easysearch 语境中有多种含义： 索引（名词）：一个索引类似于传统关系数据库中的一个数据库，是一个存储关系型文档的地方。索引的复数词为 indices 或 indexes。 索引（动词）：索引一个文档就是存储一个文档到一个索引（名词）中以便被检索和查询。这非常类似于 SQL 语句中的 INSERT 关键词，除了文档已存在时，新文档会替换旧文档情况之外。 倒排索引：Easysearch 和 Lucene 使用了一个叫做倒排索引的结构来达到快速检索的目的。默认的，一个文档中的每一个属性都是被索引的（有一个倒排索引）和可搜索的。 对于员工目录，我们将做如下操作： 每个员工索引一个文档，文档包含该员工的所有信息 该类型位于索引 megacorp 内 该索引保存在我们的 Easysearch 集群中 实践中这非常简单（尽管看起来有很多步骤），我们可以通过一条命令完成所有这些动作：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/security/auth-integration/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/security/auth-integration/接入企业认证体系 # 在企业环境中，Easysearch 通常需要与已有的身份认证系统集成，实现统一的用户管理和单点登录。本文介绍常见的集成模式与配置要点。 相关指南 # 安全 API 概述 用户与角色管理 多租户与权限模型 认证模式概览 # 模式 适用场景 复杂度 说明 内置用户 小型团队、开发测试 低 直接在 Easysearch 中管理用户和密码 LDAP/AD 已有 Active Directory 中 对接企业目录服务，集中管理用户 OIDC/OAuth 2.0 SSO 场景、云原生架构 中 对接 Keycloak、Auth0、Azure AD 等 反向代理 + Header 已有统一认证网关 低 由网关完成认证，Header 传递身份信息 SAML 2.0 企业级 SSO 高 对接 ADFS、Okta 等 SAML IdP LDAP/Active Directory 集成 # LDAP 是最常见的企业认证集成方式，将 Easysearch 的用户验证委派给现有的 LDAP 或 Active Directory。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/plugins/getting-started/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/plugins/getting-started/插件开发入门 # 本页带你从克隆模板到本地验证，跑通第一个 Easysearch 插件。 1. 环境准备 # # 检查 Java（需要 11+） java -version # 检查 Gradle ./gradlew -v 2. 从官方模板初始化项目 # git clone https://github.com/infinilabs/easysearch-plugin-template.git my-plugin cd my-plugin 重命名包名和类名后即可开始开发。项目结构说明见： 结构与类型。 3. 配置 build.gradle（插件元信息） # plugin-descriptor.properties 由构建过程自动生成，通常不需要手写。你可以直接使用以下完整示例： buildscript { ext { easysearchVersion = System.getProperty("easysearch.version", "2.1.2") } repositories { mavenCentral() gradlePluginPortal() maven { url "https://maven.aliyun.com/repository/central" } maven { url "https://maven.aliyun.com/repository/gradle-plugin" } } dependencies { classpath "com.infinilabs.easysearch.gradle:build-tools:${easysearchVersion}" } } apply plugin: 'easysearch.https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/document-design/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/document-design/文档设计 # 这一页回答两个问题：应该把什么放进一个文档？字段怎么设计才适合搜索？ 这里聚焦单个文档层面的建模，跨文档关系（Nested、Parent-Child、反范式）放在后续章节。 什么是文档 # 在 Easysearch 中，一个 文档（Document） 是被序列化为 JSON 的最顶层对象，指定了唯一 ID 并存储到 Easysearch 中。例如： { "name": "John Smith", "age": 42, "confirmed": true, "join_date": "2014-06-01", "home": { "lat": 51.5, "lon": 0.1 }, "accounts": [ { "type": "facebook", "id": "johnsmith" }, { "type": "twitter", "id": "johnsmith" } ] } 文档可以包含字符串、数字、布尔、日期、嵌套对象、数组等多种类型。 文档元数据 # 每个文档都有三个核心元数据： 元数据 说明 _index 文档存放的索引，是逻辑命名空间 _id 文档的唯一标识符，可自定义或自动生成 _source 文档的原始 JSON 内容 此外，每个文档还有 _version 字段——每次对文档修改（包括删除）时版本号递增，用于并发控制。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/aliases/create-alias/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/aliases/create-alias/新增别名 # 索引别名可将一个或多个索引映射到一个虚拟名称，方便应用层透明切换索引。 操作步骤 # 进入别名管理页：在左侧导航栏点击「别名」，进入别名列表页面。 打开新增弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增别名」配置窗口。 配置别名信息： 别名：填写自定义的别名名称（如示例中的 test_alias）。 索引：在下拉列表中选择要关联的目标索引（如 testing_index_creation）。 （可选）按需配置过滤规则、索引路由、搜索路由，或开启「是否为写索引」开关。 完成创建：配置完成后，点击「确定」，系统将创建该别名。 查看结果：别名创建成功后，将在别名列表中展示，代表操作完成。 补充说明 # 一个别名可以关联多个索引，方便跨索引查询；但如果需要通过别名写入数据，则必须指定唯一的「写索引」。 别名名称不能与现有索引名称相同，否则会产生冲突。 过滤规则允许通过别名只暴露索引的部分数据（基于 Query DSL），适用于数据隔离或多租户场景。 索引路由 / 搜索路由可用于控制数据写入和查询时的分片路由策略，优化查询性能。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/create-backup/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/create-backup/新增备份 # 可以为指定索引创建快照备份，用于数据恢复和迁移。 操作步骤 # 进入备份管理页面：登录 Easysearch UI，在左侧导航栏点击「备份管理」，切换至「备份」标签页。 打开创建快照弹窗：点击页面右上角的「+ 新增」按钮，弹出「创建快照」配置窗口。 配置快照信息： 选择「存储库」，从下拉框中选取已配置的备份存储库（如 test_repository）。 填写「快照名称」，自定义快照标识（如 daily-policy-2026-04-21-17:00-i76tolf3）。 按需选择「索引」，指定需要备份的索引；不选择则默认备份所有索引。 按需开启「忽略不可用索引」「在快照中包含集群状态」「允许恢复部分快照」「等待完成」等开关。 确认创建：配置完成后，点击「确定」按钮，系统将开始执行快照备份。 查看备份进度：备份过程中，快照状态将显示为 IN_PROGRESS；备份完成后，状态更新为 SUCCESS，可在备份列表中查看该快照的索引数、分片数等信息。 注意事项 # 创建快照前，需确保存储库已正确配置并可正常访问，否则会导致备份失败。 若开启「包含集群状态」，快照将备份集群的元数据信息（如模板、索引设置等），备份耗时会相应增加。 备份过程中请勿关闭页面或中断网络连接，避免快照状态异常。 快照名称需唯一，不能与已存在的快照重名。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/security/create-user/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/security/create-user/新增用户 # 操作步骤 # 进入安全管理页面：在左侧导航栏点击「安全管理」，默认进入「用户」标签页，可查看现有用户列表。 打开新增用户弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增用户」配置窗口。 填写用户信息： 用户名：填写自定义的用户名称（如示例中的 test_user）。 密码：设置该用户的登录密码。 确认密码：再次输入相同密码，完成校验。 角色：在下拉列表中为用户分配对应权限角色（如 readonly）。 完成创建：信息填写无误后，点击「确定」，系统将创建该用户。 查看结果：用户创建成功后，将在用户列表中展示，代表操作完成。 注意事项 # 用户密码建议使用高强度组合（包含大小写字母、数字和特殊字符），长度不少于 8 位，避免使用常见弱密码。 为用户分配角色时，建议遵循最小权限原则，仅授予业务所需的最低权限，避免过度授权带来的安全风险。 用户名创建后不可修改，如需变更请删除后重新创建。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/lifecycle/create-policy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/lifecycle/create-policy/新增策略 # 通过新增生命周期策略，可以自动管理索引的生命周期阶段。 操作步骤 # 进入生命周期策略页面：登录 Easysearch UI，在左侧导航栏点击「生命周期」，默认进入「策略」标签页。 打开新增策略弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增策略」配置窗口。 配置生命周期策略： 填写必填项「名称」，自定义策略标识（如示例中的 test_strategy）。 按需开启「热阶段」「温阶段」「冷阶段」开关，配置数据在各阶段的存储策略。 开启「删除阶段」开关，设置数据移入删除阶段的条件（如 90 天以前的数据）。 完成创建：确认配置无误后，点击「确定」按钮。 查看新增结果：配置成功后，新的生命周期策略将展示在策略列表中，可查看其名称、关联索引模式和最后修改日期等信息。 注意事项 # 生命周期策略创建后，需将其关联到具体索引模式，才能对匹配的索引生效。 阶段配置需根据数据使用频率和存储成本合理设置，避免误删仍需保留的数据。 删除阶段的时间条件需谨慎设置，确保数据在业务生命周期结束后再执行删除操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/create-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/create-index/新增索引 # 创建一个新的索引，并可按需配置索引设置和 Mapping。 操作步骤 # 进入索引页面：在左侧导航栏点击「索引」，进入索引管理列表页。 打开新增索引弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增索引」配置窗口。 配置索引信息： 填写必填项「名称」，自定义索引标识（如示例中的 testing_index_creation）。 按需开启「索引设置」「Mapping 设置」的自定义开关，进行高级配置（默认关闭，使用系统默认配置）。 完成创建：配置完成后，点击「确定」按钮，系统将自动创建索引。 查看创建结果：索引创建成功后，将在索引列表中展示该索引的完整信息，包括健康状态、分片配置、文档数、存储占用等核心指标。 补充说明 # 索引命名规则：索引名称必须为小写字母，不能以 _、- 或 + 开头，不能包含空格、逗号、#、:、"、*、?、<、>、|、/ 等特殊字符，长度不得超过 255 个字节。 索引创建后，主分片数不可修改（需通过拆分或重建索引实现变更），副本数可随时调整，请提前规划好分片数量。 默认配置下系统会自动分配 1 个主分片和 1 个副本分片。如有高并发写入或海量数据需求，建议在创建时通过「索引设置」自定义分片参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/templates/create-legacy-template/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/templates/create-legacy-template/新增索引模板（旧版） # 旧版索引模板用于在创建索引时自动应用预定义的设置和映射。 操作步骤 # 进入模板页面：在左侧导航栏点击「模板」，切换至「索引模板（旧版）」标签页。 打开新增模板弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增模板」配置窗口。 配置模板基础信息： 填写必填项「名称」，自定义模板标识（如示例中的 test_template_old）。 填写必填项「索引模式」，设置模板匹配的索引规则（如示例中的 test_template_old*）。 填写必填项「优先级」，设置模板的匹配优先级（数值越大优先级越高，示例为10）。 按需开启「索引设置」「Mapping 设置」的自定义开关，进行高级配置（默认关闭，使用系统默认配置）。 完成创建：配置完成后，点击「确定」按钮，系统将自动创建索引模板。 查看创建结果：模板创建成功后，将在索引模板列表中展示该模板的完整信息，包括名称、索引模式、优先级等。 注意事项 # 旧版模板为向后兼容保留，新业务建议优先使用「索引模板」（新版）。 多个旧版模板匹配同一索引时，系统将按优先级数值从高到低合并配置，请合理设置优先级以避免配置冲突。 模板仅对新创建的索引生效，不会影响已存在的索引。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-basics/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-basics/映射基础 # 映射也叫 Mapping，定义了索引中文档的“字段结构与类型”，是搜索行为的基础。搞清楚 Mapping，很多“为什么搜不到/搜不准”的问题就会迎刃而解。 核心概念 # Mapping 负责什么？ # 字段类型：text / keyword / 数值 / 日期 / 布尔 / 对象 / nested 等 字段是否可搜索、是否可排序/聚合（doc_values、fielddata 等） 是否启用 _source、动态映射策略等 可以认为 Mapping 是 Easysearch 的"模式（schema）"，但比传统数据库更灵活。 精确值 vs 全文 # 在 Easysearch 里，大致可以把字段分成两类： 精确值：ID、日期、数值、状态码、枚举、用户名、邮箱等 Foo 与 foo 被视为不同 2014 与 2014-09-15 也被视为不同值 全文：自然语言文本，如标题、正文、评论内容等 我们更关心“匹不匹配、相关度高不高”，而不是完全相同 精确值的查询语义更像 SQL 里的： WHERE name = "John Smith" AND user_id = 2 AND date > "2014-09-15" 全文则是“相关性排序”的世界：搜索的是“像什么”“更接近什么”，而不是绝对等号。这也是为什么同样是字符串字段，有的该按精确值建模，有的该按全文建模。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/login/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/login/服务管理登录 # 操作步骤 # 进入服务管理登录页面：打开 Agent UI，进入服务管理模块的 Token 登录界面。 输入 Token：在文本框中填写有效的集群访问 Token，可点击「如何获取 Token」查看获取指引。 完成登录连接：确认 Token 无误后，点击「连接」按钮，完成身份验证。 进入服务管理主界面：登录成功后，系统将跳转至服务管理页面，可进行「创建集群」或「加入现有集群」等操作。 注意事项 # Token 是访问集群的身份凭证，需确保输入的 Token 完整、有效，且未过期或被撤销。 若 Token 无效或权限不足，将无法完成登录，需重新获取或申请对应的 Token。 登录成功后，Token 会被系统临时保存，如需切换集群，可退出后重新输入新的 Token。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/hot-threads/view-hot-threads/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/hot-threads/view-hot-threads/查看热点线程详情 # 热点线程（Hot Threads）分析可帮助定位 CPU 占用过高的线程，常用于性能排查。 操作步骤 # 进入热点线程页面：在左侧导航栏点击「热点线程」，进入线程监控列表页。 筛选目标线程：可通过页面顶部的筛选栏（节点、采样间隔、热度类型等），快速定位需要查看的目标线程。 展开线程详情：点击目标线程行左侧的「+」按钮，即可展开查看该线程的完整堆栈详情，包含线程的调用链、执行方法、代码栈等核心信息。 详情操作：展开的详情面板支持放大查看和复制堆栈内容，方便运维人员分析、导出线程堆栈数据，用于深度定位性能问题。 收起详情：再次点击线程行左侧的「-」按钮，可收起线程详情，恢复列表视图。 补充说明 # 何时使用：当集群出现 CPU 使用率持续偏高、查询延迟异常增大、节点响应缓慢等性能问题时，可通过热点线程分析快速定位消耗资源最多的线程及其调用栈。 采样间隔建议设置为 500ms 以上，过短的采样间隔可能无法捕获完整的线程活动。 热度类型支持按 CPU、等待（Wait）、阻塞（Block）进行筛选，排查不同类型的性能瓶颈。 导出的堆栈信息可配合日志分析工具使用，帮助开发团队进行深度性能调优。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/nodes/view-node-details/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/nodes/view-node-details/查看节点详情 # 通过节点详情页，可一站式查看节点的完整运行数据。 操作步骤 # 进入节点列表页：在左侧导航栏点击「节点」，进入节点管理列表页面，可查看集群内所有节点的基础运行信息。 进入节点详情页：点击目标节点的名称（如带星号标识的 easysearch-9jtew92c978t-data0-0），即可进入该节点的详情页面。 查看核心信息：在详情页中，可一站式查看该节点的完整运行数据，包括： 基础信息：节点 ID、传输地址、节点角色、数据路径 运行状态：运行时间、CPU 使用率、JVM 堆内存使用率 存储信息：可用存储、已用存储、分片数、文档数 性能指标：CPU 使用率趋势、JVM 堆内存用量、索引延迟、索引吞吐等https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/concepts/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/concepts/核心概念 # Easysearch 是一个分布式搜索分析引擎，建立在 Apache Lucene 基础之上。本页介绍 Easysearch 的核心概念，帮助你快速建立正确的心智模型。 什么是 Easysearch # Easysearch 是一个高性能的分布式搜索引擎，建立在全文搜索引擎库 Apache Lucene 基础之上。Lucene 可以说是当下最先进、高性能、全功能的搜索引擎库。 但 Lucene 仅仅只是一个库。为了充分发挥其功能，你需要使用 Java 并将 Lucene 直接集成到应用程序中。Easysearch 在此基础上提供了一套简单一致的 RESTful API，使全文检索变得简单。 Easysearch 不仅仅是全文搜索引擎，它可以被准确地形容为： 一个分布式的实时文档存储，每个字段可以被索引与搜索 一个分布式实时分析搜索引擎 能胜任上百个服务节点的扩展，并支持 PB 级别的结构化或非结构化数据 面向文档 # Easysearch 是面向文档（Document-Oriented）的：它存储整个对象或文档，并索引每个文档的内容使之可以被检索。在 Easysearch 中，我们对文档进行索引、检索、排序和过滤——而不是对行列数据。 JSON # Easysearch 使用 JSON 作为文档的序列化格式： { "email": "john@smith.com", "first_name": "John", "last_name": "Smith", "info": { "bio": "Eco-warrior and defender of the weak", "age": 25, "interests": [ "dolphins", "whales" ] }, "join_date": "2014/05/01" } 在 Easysearch 中将对象转化为 JSON 后构建索引，要比在扁平的表结构中简单得多。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/overview/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/overview/集群概览 # 本页面为 Easysearch 集群的核心监控仪表盘，用于集中展示集群整体运行状态与关键指标。 页面主要分为以下几个部分： 集群基础信息：显示集群名称、UUID、版本、运行时长及访问地址。 核心健康与资源指标：通过卡片形式直观展示集群健康状态、CPU / 内存 / JVM / 磁盘使用率、节点数、索引数、分片数、文档数等关键数据。 分片与任务状态：包含分片分配、待处理任务等状态统计，以及 “集群任务” 和 “分片恢复任务” 列表，用于监控后台运行任务。 集群拓扑视图：可视化展示集群内各节点的分布与状态，方便快速了解集群节点构成。 通过本页面，管理员可一站式掌握集群整体健康度与运行情况，是日常运维监控的首要入口。 补充说明 # 集群健康状态含义：🟢 Green 表示所有主分片和副本分片均已正常分配；🟡 Yellow 表示所有主分片已分配，但存在未分配的副本分片；🔴 Red 表示存在未分配的主分片，部分数据不可用。 概览页数据为近实时刷新，如需获取最新状态，可手动刷新页面。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/test-env/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/test-env/测试环境部署指南 # 用最少资源快速搭建一个可运行的 Easysearch 实例，适合功能验证、开发联调和学习使用。 最低硬件要求 # 项目 最低配置 建议配置 CPU 2 核 4 核 内存 4 GB 8 GB 磁盘 20 GB 50 GB SSD JDK 11+ 17+ 测试环境可使用 HDD，但 SSD 体验更佳。 一键安装（推荐） # # 使用一键安装脚本 curl -sSL http://get.infini.cloud | bash -s -- -p easysearch # 调小 JVM 堆（测试环境 512MB 即可） sed -i 's/1g/512m/g' /data/easysearch/config/jvm.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/append/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/append/添加处理器 # append 处理器用于向字段添加值： 如果该字段是数组， append 处理器会将指定的值追加到该数组中。 如果该字段是标量字段， append 处理器将其转换为数组，并将指定的值追加到该数组中。 如果该字段不存在， append 处理器会创建一个包含指定值的数组。 语法 # 以下是为 append 处理器提供的语法： { "append": { "field": "your_target_field", "value": ["your_appended_value"] } } 配置参数 # 下表列出了 append 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要附加数据的字段名称。支持模板使用。 value 必填 要附加的值。这可以是一个静态值或从现有字段派生的动态值。支持模板使用。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 allow_duplicates 可选 指定是否将字段中已存在的值附加。如果为 true ，则附加重复值。否则，将跳过。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/shards/move-shard/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/shards/move-shard/移动分片 # 分片移动（Reroute）允许将特定分片手动迁移到指定节点，常用于负载均衡或节点下线前的数据迁移。 操作步骤 # 进入分片管理页：在左侧导航栏点击「分片」，进入分片分布可视化页面，可查看所有索引在各节点的分片分配情况。 发起移动操作：找到需要迁移的目标分片，点击该分片所在的单元格，在弹出的菜单中选择「移动分片」。 选择目标节点：点击目标节点对应列中带有灰色箭头的空白单元格，指定分片迁移的目标位置。 确认迁移操作：在弹出的「移动分片」确认窗口中，核对索引、分片、当前节点、目标节点等信息，确认无误后点击「确定」，系统将执行分片迁移。 查看操作结果：迁移完成后，页面将自动更新分片分布，目标分片会显示在新节点的对应位置，代表移动成功。 注意事项 # 分片迁移过程中会产生网络传输和磁盘 I/O 开销，大分片的迁移可能影响集群性能，建议在业务低峰期操作。 不能将主分片和它的副本分片移动到同一个节点上，系统会阻止此类操作。 迁移完成前，相关分片可能处于 RELOCATING 状态，此为正常现象，数据读写不受影响。 如集群开启了自动分片均衡策略，手动移动的分片可能在后续被自动重新均衡。如需保持手动分配结果，可临时关闭分片自动均衡。https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/index-design/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/index-design/索引与分片设计实践 # 这篇更偏“工程实践”：不讲所有细节，只给你一套在大多数场景下都靠谱的索引设计思路，帮你少走弯路。 1. 先确定“索引边界”，再谈分片 # 思考顺序建议是： 这一坨数据是否应该是一个索引？ 典型边界：数据生命周期、访问模式、隔离需求（权限/多租户）、硬件拓扑（可用区） 在它内部，需要多少主分片、多少副本？ 常用的索引边界模式： 按业务域：orders、products、logs_app、logs_security… 按时间：logs-2026.02.01、logs-2026.02.02（时间序列，见数据建模章节） 按租户/大客户：大客户单独索引，小客户共享索引（见多租户建模章节） 建议：先控制“索引颗粒度”合理，再通过分片做水平扩展；不要指望一个索引撑住所有业务。 2. 分片与副本：从“目标分片大小”倒推 # 分片设计没有万能数字，但可以从一个直觉出发：希望单个分片的大小 & 负载落在一个可控区间内。实践中常见的经验值： 单分片 10–50GB 对大多数场景比较健康（结合你的磁盘/快照策略微调） 对于热点写入较猛的日志类索引，可以略小一点，便于滚动与恢复 一个简单的倒推流程： 用测试环境或历史数据估算：一个分片大概能承载多少数据 & QPS（参考“容量规划”章节） 预估未来一段时间的索引规模（例如：单日日志量、订单增长等） 用 总数据量 / 目标分片大小 ≈ 主分片数 算一个初始值，再按机器数/故障域稍微调整 副本数则更多取决于： 可用性（能容忍多少节点故障） 读流量（读多写少时可以多一点副本当读节点） 生产上常见组合： 写多读少：number_of_replicas = 0/1 读多写少：number_of_replicas = 1+，甚至为查询集群设独立的 follower 3. 时间序列：按时间切索引，而不是疯狂加分片 # 日志、指标、行为埋点这些“时间序列”场景，最容易踩坑的设计就是：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/autocomplete/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/autocomplete/自动补全 # 自动补全是在用户输入过程中，实时给出可能的搜索词建议。Easysearch 支持三种实现方式，各有适用场景： 方式 时机 性能 适用场景 前缀匹配（match_phrase_prefix） 查询时 一般 快速原型，无需特殊 mapping Edge N-gram 索引时 好 大规模数据的前缀补全 Completion Suggester 索引时 最优 高并发自动补全，支持权重控制 相关指南 # 建议与纠错 部分匹配 前缀匹配（match_phrase_prefix） # 前缀匹配会在查询时，对最后一个 term 做前缀展开。典型做法是使用 match_phrase_prefix 在 text 字段上做查询。 不需要特殊 mapping，可以直接在现有 text 字段上使用。 GET shakespeare/_search { "query": { "match_phrase_prefix": { "text_entry": { "query": "qui", "slop": 3 } } } } 参数说明 # 参数 说明 默认值 query 查询文本 必填 slop 允许的词项位置偏移量 0 max_expansions 最后一个词项的最大前缀展开数量 50 analyzer 覆盖默认分析器 字段默认分析器 zero_terms_query 当分析器移除所有词项时的行为（none 或 all） none 性能注意：前缀匹配属于相对昂贵的查询。例如前缀为 a 时，可能会匹配到几十万 terms。建议通过 max_expansions 限制展开规模：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/relevance/scoring-basics/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/relevance/scoring-basics/评分基础 # 处理结构化数据（比如：时间、数字、字符串、枚举）的数据库，只需检查文档（或关系数据库里的行）是否与查询匹配。 布尔的是/非匹配是全文搜索的基础，但不止如此，我们还要知道每个文档与查询的相关度，在全文搜索引擎中不仅需要找到匹配的文档，还需根据它们相关度的高低进行排序。 全文相关的公式或相似算法（similarity algorithms）会将多个因素合并起来，为每个文档生成一个相关度评分 _score。本章中，我们会验证各种可变部分，然后讨论如何来控制它们。 当然，相关度不只与全文查询有关，也需要将结构化的数据考虑其中。可能我们正在找一个度假屋，需要一些的详细特征（空调、海景、免费 WiFi），匹配的特征越多相关度越高。可能我们还希望有一些其他的考虑因素，如回头率、价格、受欢迎度或距离，当然也同时考虑全文查询的相关度。 所有的这些都可以通过 Easysearch 强大的评分基础来实现。 相关度评分背后的理论 # Easysearch 使用布尔模型（Boolean Model）查找匹配文档，并用一个名为实用评分函数（practical scoring function）的公式来计算相关度。这个公式借鉴了词频/逆向文档频率（term frequency/inverse document frequency）和向量空间模型（vector space model），同时也加入了一些现代的新特性，如字段长度归一化（field length normalization），以及词或查询语句权重提升。 注意：Easysearch 默认使用 BM25 相似度算法，而非经典的 TF/IDF。BM25 基于概率信息检索模型，在大多数场景下效果更好。下面先介绍 TF/IDF 的基本概念（有助于理解评分原理），然后说明 BM25 的改进。 不要紧张！这些概念并没有像它们字面看起来那么复杂，尽管本小节提到了算法、公式和数学模型，但内容还是让人容易理解的，与理解算法本身相比，了解这些因素如何影响结果更为重要。 布尔模型 # 布尔模型（Boolean Model）只是在查询中使用 AND、OR 和 NOT（与、或和非）这样的条件来查找匹配的文档，以下查询： full AND text AND search AND (elasticsearch OR lucene) 会将所有包括词 full、text 和 search，以及 elasticsearch 或 lucene 的文档作为结果集。 这个过程简单且快速，它将所有可能不匹配的文档排除在外。 词频/逆向文档频率（TF/IDF） # 当匹配到一组文档后，需要根据相关度排序这些文档，不是所有的文档都包含所有词，有些词比其他的词更重要。一个文档的相关度评分部分取决于每个查询词在文档中的权重。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/deploy_operator/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/deploy_operator/部署 Easysearch Operator # Easysearch Operator 只能在 k8s 环境下部署安装，请准备好一套 k8s 环境 部署前准备 # k8s 环境 要求Kubernetes 1.9以上版本，自 1.9 版本以后，StatefulSet成为了在Kubernetes中管理有状态应用的标准方式。 StorageClass StorageClass 允许集群管理员定义多种存储方案，如快速的 SSD、标准的硬盘，或者其他的存储系统。无需手动预先创建存储资源，用户只需要在 PersistentVolumeClaim (PVC) 中指定需要的 StorageClass，存储资源就可以根据需求动态地创建。 ServiceAccount 创建一个 ServiceAccount 用于 Easysearch Operator 获取和操作 k8s 资源 apiVersion: v1 kind: ServiceAccount metadata: labels: app.kubernetes.io/name: serviceaccount app.kubernetes.io/instance: controller-manager-sa app.kubernetes.io/component: rbac app.kubernetes.io/created-by: k8s-operator app.kubernetes.io/part-of: k8s-operator app.kubernetes.io/managed-by: kustomize name: controller-manager # ServiceAccount 的名字是 controller-manager namespace: default ClusterRole 创建 ClusterRole，用于定义访问 k8s 集群的角色权限 展开查看完整代码 apiVersion: rbac.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/configuration_file/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/configuration_file/配置文件 # 可以在每个 Easysearch 节点上找到 easysearch.yml ，通常位于 Easysearch 安装目录下 config/easysearch.yml。 配置文件一览 # Easysearch 主要有以下几类配置文件： easysearch.yml：节点与集群配置的主文件，包括网络、发现、角色、路径等。 只放“本机相关”和“集群引导”类配置（如 cluster.name、node.name、network.host、discovery.seed_hosts 等）更易维护。 jvm.options：JVM 启动参数，如堆大小（-Xms/-Xmx）、GC 设置等。 log4j2.properties：日志配置，控制日志级别、输出格式与输出位置。 config/security/*.yml：安全模块本地配置，用于内置用户、角色等，详见 安全配置。 配置目录位置 # 默认情况下，配置目录位于 $ES_HOME/config。 你可以通过环境变量 ES_PATH_CONF 指定一个自定义配置目录，例如： ES_PATH_CONF=/path/to/my/config ./bin/easysearch 在使用 systemd、Docker 或自带脚本运行服务时，通常需要在对应的服务配置里设置 ES_PATH_CONF，而不是只在当前 shell 里导出。 配置文件格式要点（YAML） # Easysearch 的配置文件使用 YAML 格式，几个常用规则： 缩进代表层级： path: data: /var/lib/easysearch logs: /var/log/easysearch 同样的内容也可以写成“扁平 key”： path.data: /var/lib/easysearch path.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/cluster-node/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/cluster-node/集群与节点配置 # 本页介绍 easysearch.yml 中与集群身份和节点角色相关的配置项。这些都是静态设置，修改后需要重启节点生效。 集群名称 # cluster.name: easysearch 项目 说明 参数 cluster.name 默认值 easysearch 属性 静态 说明 集群的唯一名称。所有节点必须配置相同的集群名称才能组成一个集群。不同环境（开发、测试、生产）应使用不同的集群名称以防止节点误加入 注意事项： 集群名称不能包含冒号（:），建议仅使用小写字母、数字和连字符。 集群名称一旦投入使用后不建议更改，因为它会影响数据目录结构。 同一网络中如果有多个集群，务必确保集群名称各不相同。 示例： # 开发环境 cluster.name: dev-cluster # 生产环境 cluster.name: prod-search 节点名称 # node.name: node-1 项目 说明 参数 node.name 默认值 主机名（hostname） 属性 静态 说明 节点在集群中的唯一标识符。如果未显式设置，默认使用机器主机名。用于日志输出、集群状态显示、API 返回信息中。建议使用有意义的名称便于运维定位 命名建议：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/transient-settings/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/transient-settings/集群临时设置 # 操作步骤 # 进入集群临时设置页面：在左侧导航栏点击「集群设置」，默认进入「临时配置」标签页。 选择配置项：点击「配置项」下拉框，在列表中选择需要调整的集群参数。 填写参数值：在右侧输入框中，填写该参数对应的配置值。 （可选）批量添加：点击「+」按钮，可新增多行配置，一次性设置多个参数。 生效配置：点击「更新」按钮，配置立即生效，无需重启集群。 注意事项 # 临时配置仅在集群运行期间生效，重启后自动清空，不做永久保存。 错误配置可能导致集群异常，修改前请确认参数含义，建议在业务低峰期操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/index-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/index-api/Index API # 将一个 JSON 文档写入指定索引。若文档 ID 已存在，则整文档覆盖并递增 _version。 请求格式 # PUT /<index>/_doc/<_id> POST /<index>/_doc/<_id> POST /<index>/_doc # 自动生成 _id 仅创建（文档存在时返回 409 Conflict）： PUT /<index>/_create/<_id> POST /<index>/_create/<_id> 路径参数 # 参数 必需 说明 <index> 是 目标索引名称 <_id> 否 文档 ID。使用 POST /<index>/_doc 时可省略，由系统自动生成 查询参数 # 参数 类型 默认值 说明 op_type string index 写入类型。index = 创建或覆盖；create = 仅创建（已存在时返回 409）。使用 _create 端点时强制为 create routing string — 自定义路由值，决定文档落入哪个分片 pipeline string — 写入前执行的 Ingest Pipeline 名称 refresh string false 写入后是否刷新。true = 立即刷新；wait_for = 等待下一次自动刷新完成后返回；false = 不等待 timeout time 1m 等待主分片可用的超时时间 version long — 用于外部版本控制的版本号 version_type string internal 版本类型：internal、external、external_gte if_seq_no long — 乐观并发控制：仅当文档的 _seq_no 等于此值时才执行写入 if_primary_term long — 乐观并发控制：仅当文档的 _primary_term 等于此值时才执行写入 wait_for_active_shards string 1 写入前需要的活跃分片数量。1 = 仅主分片；all = 全部分片 require_alias boolean false 为 true 时要求 <index> 必须是别名，否则返回错误 请求体 # 完整的 JSON 文档，即 _source 的内容。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/minimum-should-match/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/minimum-should-match/Minimum Should Match 参数 # minimum_should_match 参数可用于全文搜索，并指定文档必须匹配的最小词项数量才能在搜索结果中返回。 以下示例要求文档至少匹配三个搜索词中的两个才能作为搜索结果返回： 相关指南（先读这些） # 查询 DSL 基础 全文搜索 GET /shakespeare/_search { "query": { "match": { "text_entry": { "query": "prince king star", "minimum_should_match": "2" } } } } 在这个示例中，查询有三个可选子句，它们通过 OR 结合，因此文档必须匹配 prince 和 king ，或者 prince 和 star ，或者 king 和 star 。 参数值说明 # 您可以指定 minimum_should_match 参数为以下值之一。 值类型 示例 描述 非负整数 2 一个文档必须匹配这个数量的可选子句。 负整数 -1 一个文档必须匹配可选子句总数减去这个数。 非负百分比 70% 一个文档必须匹配可选子句总数的这个百分比。要匹配的子句数向下取整到最接近的整数。 负百分比 -30% 一个文档可以有这个百分比的不匹配的可选子句。文档允许不匹配的子句数向下取整到最接近的整数。 组合 2<75% n<p% 格式的表达式。如果可选子句的数量小于或等于 n ，文档必须匹配所有可选子句。如果可选子句的数量大于 n ，则文档必须匹配 p 百分比的可选子句。 多种组合 3<-1 5<50% 用空格分隔的多个组合。每个条件适用于 < 符号左侧数字更多的可选子句数量。在这个例子中，如果有三个或更少可选子句，文档必须匹配所有它们。如果有四或五个可选子句，文档必须匹配所有但一个。如果有 6 个或更多可选子句，文档必须匹配 50% 的它们。 设 n 为文档必须匹配的可选子句数量。当 n 计算为百分比时，如果 n 小于 1，则使用 1。如果 n 大于可选子句的数量，则使用可选子句的数量。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/bytes/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/bytes/字节处理器 # bytes 处理器将可读的字节值转换为等效的字节数值。字段可以是标量或数组。如果字段是标量，则值将被转换并存储在该字段中。如果字段是数组，则转换数组中的所有值。 语法 # 以下是为 bytes 处理器提供的语法： { "bytes": { "field": "your_field_name" } } 配置参数 # 下表列出了 bytes 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要转换的数据的字段名称。支持模板使用。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true ，则处理器在字段不存在或为 null 时不会修改文档。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 target_field 可选 指定存储解析数据的字段名称。如果没有指定，则值将存储在 field 字段中。默认为 field 。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/lowercase/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/lowercase/Lowercase 分词过滤器 # lowercase 分词过滤器用于将分词流中的所有字符转换为小写，从而使搜索不区分大小写。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参数 # 小写分词过滤器可以使用以下参数进行配置。 参数 必填/可选 描述 language 可选 指定一个特定语言的分词过滤器。有效值为： - 希腊语 greek - 爱尔兰语irish - 土耳其语turkish。 默认值是 Lucene 的小写过滤器。 参考样例 # 以下示例请求创建了一个名为 custom_lowercase_example 的新索引。它配置了一个带有小写过滤器的分析器，并指定语言为希腊语。 PUT /custom_lowercase_example { "settings": { "analysis": { "analyzer": { "greek_lowercase_example": { "type": "custom", "tokenizer": "standard", "filter": ["greek_lowercase"] } }, "filter": { "greek_lowercase": { "type": "lowercase", "language": "greek" } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/conditional-execution/conditional-pipeline-processor/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/conditional-execution/conditional-pipeline-processor/控制条件和处理器 # 在摄取管道中， pipeline 处理器允许根据文档内容条件性地执行不同的子管道。当不同类型的文档需要单独的处理逻辑时，这提供了强大的灵活性。您可以使用 if 参数在 pipeline 处理器中根据字段值、数据类型或内容结构将文档路由到不同的管道。然后，每个管道可以独立应用自己的处理器集。这种方法通过仅在相关位置应用逻辑，保持了管道的模块化和可维护性。 示例：按服务路由日志 # 以下示例演示了如何根据文档中的 service.name 字段将日志路由到不同的子管道。 创建第一个名为 webapp_logs 的管道： PUT _ingest/pipeline/webapp_logs { "processors": [ { "set": { "field": "log_type", "value": "webapp" } } ] } 创建第二个名为 api_logs 的管道： PUT _ingest/pipeline/api_logs { "processors": [ { "set": { "field": "log_type", "value": "api" } } ] } 创建主路由管道名为 service_router ，根据 service.name 将文档路由到相应的管道： PUT _ingest/pipeline/service_router { "processors": [ { "pipeline": { "name": "webapp_logs", "if": "ctx.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/query-parser-syntax/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/query-parser-syntax/查询字符串语法 # Easysearch 的 query_string 和 simple_query_string 查询底层使用 Lucene 查询解析器（Query Parser）将查询字符串解析为查询对象。本页详细描述查询解析器支持的完整语法。 相关指南 # Query String 查询 — query_string 查询的 API 参数 Simple Query String 查询 — 更宽松的查询字符串语法 正则表达式语法 — regexp 查询和 query_string 中使用的正则语法 词项（Terms） # 查询字符串由词项和操作符组成。词项有两种类型： 单个词项：一个单词，如 test、hello 短语：用双引号包围的一组词，如 "hello dolly" 多个词项可以通过布尔操作符组合成更复杂的查询。 注意：查询字符串中的词项和短语会经过索引时使用的相同分析器处理。因此，选择不会干扰查询词项的分析器非常重要。 字段（Fields） # Easysearch 支持按字段搜索。搜索时可以指定字段名，也可以使用默认字段。 语法为字段名后跟冒号 :，然后是要搜索的词项： title:"The Right Way" AND content:go 上面的查询在 title 字段中查找短语 “The Right Way”，在 content 字段中查找词 “go”。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/standard-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/standard-analyzer/Standard 分析器 # standard 分析器是在未指定其他分析器时默认使用的分析器。它旨在为通用文本处理提供一种基础且高效的方法。 该分析器由以下分词器和分词过滤器组成： standard 分词器：去除大部分标点符号，并依据空格和其他常见分隔符对文本进行分割。 lowercase 分词过滤器：将所有词元转换为小写，以确保匹配时不区分大小写。 stop 分词过滤器：从分词后的输出中移除常见的停用词，例如 “the”、“is” 和 “and”。 相关指南（先读这些） # 文本分析基础 文本分析：识别词元 参考样例 # 以下命令创建一个名为 my_standard_index 并使用标准分词器的索引： PUT /my_standard_index { "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "standard" } } } } 参数说明 # 你可以使用以下参数来配置标准分词器。 参数 必填/可选 数据类型 描述 max_token_length 可选 整数 设置生成的词元的最大长度。如果超过此长度，词元将按照 max_token_length 中配置的长度拆分为多个词元。默认值为 255。 stopwords 可选 字符串或字符串列表 一个包含自定义停用词列表（如 _english）的字符串，或者一个自定义停用词列表的数组。默认值为 _none_。 stopwords_path 可选 字符串 包含停用词列表的文件的路径（相对于配置目录的绝对路径或相对路径）。 配置自定义分词器 # 以下命令配置一个索引，该索引带有一个等同于标准分词器的自定义分词器：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/standard/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/standard/Standard 分词器 # standard 分词器是 Easysearch 中的默认分词器。它基于单词边界，采用一种基于语法的方法对文本进行分词，这种方法能够识别字母、数字以及标点等其他字符。它具有高度的通用性，适用于多种语言，它使用了 Unicode 文本分割规则（ UAX#29）来将文本分割成词元。 相关指南（先读这些） # 词汇识别 文本分析基础 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个使用标准词元生成器的分词器： PUT /my_index { "settings": { "analysis": { "analyzer": { "my_standard_analyzer": { "type": "standard" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_standard_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /my_index/_analyze { "analyzer": "my_standard_analyzer", "text": "Easysearch is powerful, fast, and scalable.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/simulate-ingest/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/simulate-ingest/模拟管道 # 使用 _simulate API 测试管道效果，不会实际索引文档。这是调试管道逻辑的最佳工具。 请求格式 # 模拟已创建的管道： POST _ingest/pipeline/<pipeline-id>/_simulate 在请求体中内联定义管道进行模拟（无需先创建）： POST _ingest/pipeline/_simulate 请求内容字段 # 下表列出了用于模拟管道的请求正文字段。 参数名 是否必需 类型 描述 docs 必需的 数组 用于测试管道的文档内容。 pipeline 可选 对象 要模拟的管道。如果未包含管道标识符，则模拟使用的是最新创建的管道。 docs 字段可以包含下表中列出的子字段。 参数名 是否必需 类型 描述 source 必需的 对象 文档的 JSON 正文。 id 可选 字符串 一个独特的文档标识符。该标识符不能在索引的其它地方使用。 index 可选 字符串 文档的转换数据出现的索引。 查询参数 # 下表列出了模拟管道的查询参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/configuration/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/configuration/配置 # Easysearch 默认配置已针对多数场景优化。本文聚焦生产环境必须关注的配置项。 原则：如果不确定是否需要改，就不要改。过度调优往往适得其反。 配置速查表 # 类别 关键配置 修改方式 风险等级 标识 cluster.name、node.name 静态（重启生效） 低 路径 path.data、path.logs 静态（重启生效） 高 网络 network.host、http.port、transport.port 静态（重启生效） 中 发现 discovery.seed_hosts、cluster.initial_master_nodes 静态（重启生效） 高 内存 ES_HEAP_SIZE、jvm.options 静态（重启生效） 高 恢复 gateway.recover_after_* 静态（重启生效） 中 集群级 大部分 cluster.*、indices.* 动态 API 视具体配置 必须配置 # 集群和节点名称 # # easysearch.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/get-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/get-api/Get API # 按 ID 检索单条文档，返回完整 _source 及元数据。 请求格式 # GET /<index>/_doc/<_id> HEAD /<index>/_doc/<_id> 仅返回 _source（不含元数据）： GET /<index>/_source/<_id> HEAD /<index>/_source/<_id> 路径参数 # 参数 必需 说明 <index> 是 目标索引 <_id> 是 文档 ID 查询参数 # 参数 类型 默认值 说明 _source string/boolean true true/false 启用或禁用 _source 返回，或传逗号分隔字段名仅返回指定字段 _source_includes string — _source 中要包含的字段（逗号分隔，支持通配符） _source_excludes string — _source 中要排除的字段（逗号分隔，支持通配符） stored_fields string — 要返回的 stored 字段（逗号分隔） routing string — 自定义路由值。若文档写入时使用了自定义路由，检索时必须指定相同的值 preference string — 查询偏好。_local = 优先本地分片；_primary = 仅主分片；或自定义字符串 realtime boolean true 实时读取。为 true 时不依赖刷新即可读到最新写入 refresh boolean false 读取前是否强制刷新 version long — 期望的版本号，不匹配时返回 409 version_type string internal 版本类型 示例 # 获取完整文档 # GET /website/_doc/123 响应：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/uppercase/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/uppercase/Uppercase 分词过滤器 # uppercase 分词过滤器用于在分析过程中将所有词元（单词）转换为大写形式。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参考样例 # 以下示例请求创建了一个名为 uppercase_example 的新索引，并配置了一个带有大写过滤器的分词器。 PUT /uppercase_example { "settings": { "analysis": { "filter": { "uppercase_filter": { "type": "uppercase" } }, "analyzer": { "uppercase_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "uppercase_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： GET /uppercase_example/_analyze { "analyzer": "uppercase_analyzer", "text": "Easysearch is powerful" } 返回内容包含产生的词元 { "tokens": [ { "token": "EASYSEARCH", "start_offset": 0, "end_offset": 10, "type": "<ALPHANUM>", "position": 0 }, { "token": "IS", "start_offset": 11, "end_offset": 13, "type": "<ALPHANUM>", "position": 1 }, { "token": "POWERFUL", "start_offset": 14, "end_offset": 22, "type": "<ALPHANUM>", "position": 2 } ] }https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/letter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/letter/Letter 分词器 # letter 分词器会根据任何非字母字符将文本拆分成单词。它在处理许多欧洲语种时效果良好，但对于一些亚洲语种却不太有效，因为在亚洲语种中，单词之间不是由空格来分隔的。 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 参考样例 # 下面的示例请求创建了一个名为 my_index 的新索引，并配置了一个使用字母词元生成器的分词器。 PUT /my_index { "settings": { "analysis": { "analyzer": { "my_letter_analyzer": { "type": "custom", "tokenizer": "letter" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_letter_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： POST _analyze { "tokenizer": "letter", "text": "Cats 4EVER love chasing butterflies!" } 返回内容包含产生的词元https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/configuration/yaml/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/configuration/yaml/本地配置（YAML） # config/security/ 目录下包含 Easysearch 安全模块的本地 YAML 配置文件。这些文件在 bin/initialize.sh 初始化时自动加载到安全索引中，也可以手动编辑后重新加载。 通过本地 YAML 配置文件可以管理默认的内置用户或 隐藏的保留资源，例如 admin 管理员用户。除内置资源外，通过 INFINI Console 或 REST API 来创建其他用户、角色、映射和权限组通常更方便。 相关指南（先读这些） # 安全与多租户最佳实践 权限控制总览 配置文件概览 # 文件 用途 编辑方式 user.yml 内置用户定义 手动编辑或 API role.yml 角色定义 手动编辑或 API role_mapping.yml 角色映射 手动编辑或 API privilege.yml 权限组（Action Group） 手动编辑或 API config.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/conditional-execution/regex-conditionals/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/conditional-execution/regex-conditionals/正则表达式条件 # 摄取管道支持使用正则表达式（regex）和 Painless 脚本语言进行条件逻辑。这允许根据文本字段的结构和内容对哪些文档进行处理进行精细控制。正则表达式可以用于 if 参数中评估字符串模式。这对于匹配 IP 格式、验证电子邮件地址、识别 UUID 或处理包含特定关键字的日志特别有用。 示例：电子邮件名过滤 # 以下管道使用正则表达式来识别来自 @example.com 电子邮件域的用户，并相应地标记这些文档： PUT _ingest/pipeline/tag_example_com_users { "processors": [ { "set": { "field": "user_domain", "value": "example.com", "if": "ctx.email != null && ctx.email =~ /@example.com$/" } } ] } 使用以下请求来模拟管道： POST _ingest/pipeline/tag_example_com_users/_simulate { "docs": [ { "_source": { "email": "alice@example.com" } }, { "_source": { "email": "bob@another.com" } } ] } 只有第一份文档添加了 user_domain ： { "docs": [ { "doc": { "_source": { "email": "alice@example.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/regex-syntax/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/regex-syntax/正则表达式语法 # 正则表达式（regex）是一种使用特殊符号和运算符定义搜索模式的方法。这些模式允许你在字符串中匹配字符序列。 在 Easysearch 中，你可以在以下查询类型中使用正则表达式： regexp query_string 注意：Easysearch 使用 Apache Lucene 正则表达式引擎，该引擎有自己的语法和限制。它不使用 Perl 兼容正则表达式（PCRE），因此某些熟悉的正则表达式功能可能会表现不同或不受支持。 相关指南（先读这些） # 部分匹配 正则查询 字符串查询 查询字符串语法 — 通配符、模糊、范围、布尔等完整语法参考 在 regexp 和 query_string 查询之间进行选择 # regexp 和 query_string 查询都支持正则表达式，但它们的行为不同，适用于不同的使用场景。 特性 regexp 查询 query_string 查询 模式匹配 正则表达式模式必须匹配整个字段值 正则表达式模式可以匹配字段中的任何部分 flags 支持 flags 启用可选正则表达式运算符 flags 不支持 查询类型 词级查询（未评分） 全文检索（评分和解析） 最佳使用场景 对关键字或精确字段进行严格模式匹配 使用支持正则表达式模式的灵活查询字符串在分析字段中进行搜索 复杂查询组合 仅限于正则表达式模式 支持 AND 、 OR 、通配符、字段、提升值以及其他功能。参见查询字符串查询。 保留字符 # Lucene 的正则表达式引擎支持所有 Unicode 字符。然而，以下字符被视为特殊运算符：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/simple-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/simple-analyzer/Simple 分析器 # simple 分析器是一种非常基础的分析器，它会将文本中的非字母字符串拆分成词项，并将这些词项转换为小写形式。与 standard 分析器不同的是，simple 分析器将除字母字符之外的所有内容都视为分隔符，这意味着它不会把数字、标点符号或特殊字符识别为词元的一部分。 相关指南（先读这些） # 文本分析基础 文本分析：识别词元 参考样例 # 以下命令创建一个名为 my_simple_index 并使用简单分词器的索引： PUT /my_simple_index { "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "simple" } } } } 配置自定义分词器 # 以下命令配置了一个索引，该索引带有一个自定义分词器，这个自定义分词器等同于添加了 html_strip 字符过滤器的简单分词器： PUT /my_custom_simple_index { "settings": { "analysis": { "char_filter": { "html_strip": { "type": "html_strip" } }, "tokenizer": { "my_lowercase_tokenizer": { "type": "lowercase" } }, "analyzer": { "my_custom_simple_analyzer": { "type": "custom", "char_filter": ["html_strip"], "tokenizer": "my_lowercase_tokenizer", "filter": ["lowercase"] } } } }, "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "my_custom_simple_analyzer" } } } } 产生的词元 # 以下请求用来检查分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/get-ingest/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/get-ingest/获取管道 # 使用 GET _ingest/pipeline API 检索管道的定义信息。 请求格式 # GET _ingest/pipeline/<pipeline-id> 获取所有管道 # GET _ingest/pipeline 获取指定管道 # GET _ingest/pipeline/my-pipeline 响应示例： { "my-pipeline": { "description": "处理学生数据：设置毕业年份并转大写", "processors": [ { "set": { "description": "设置毕业年份", "field": "grad_year", "value": 2023 } }, { "set": { "description": "标记已毕业", "field": "graduated", "value": true } }, { "uppercase": { "field": "name" } } ] } } 通配符匹配 # 支持通配符查询多个管道： GET _ingest/pipeline/log-* 查询参数 # 参数 必需 类型 默认值 说明 cluster_manager_timeout 否 时长 30s 等待集群管理器节点响应的超时时间https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/ascii-folding/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/ascii-folding/ASCII Folding 分词过滤器 # asciifolding 分词过滤器将非 ASCII 字符转换为与其最接近的 ASCII 等效字符。例如，“é” 变为 “e”，“ü” 变为 “u”，“ñ” 变为 “n”。这个过程被称为"音译"。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 ASCII 折叠分词过滤器有许多优点： 增强搜索灵活性：用户在输入查询内容时常常会省略重音符号或特殊字符。ASCII 折叠分词过滤器可确保即使是这样的查询也仍然能返回相关结果。 规范化：通过确保重音字符始终被转换为其 ASCII 等效字符，使索引编制过程标准化。 国际化：对于包含多种语言和字符集的应用程序特别有用。 尽管 ASCII 折叠分词过滤器可以简化搜索，但它也可能导致特定信息的丢失，尤其是当数据集中重音字符和非重音字符之间的区别很重要的时候。 参数说明 # 你可以使用 preserve_original 参数来配置 ASCII 折叠分词过滤器。将此参数设置为 true 时，会在词元流中同时保留原始词元及其 ASCII 折叠后的版本。当你希望在搜索查询中同时匹配一个词项的原始版本（带重音符号）和规范化版本（不带重音符号）时，这一点会特别有用。该参数的默认值为 false。 参考样例 # 以下示例请求创建了一个名为 example_index 的新索引，并定义了一个分词器，该分词器使用了 ASCII 折叠过滤器，且将 preserve_original 参数设置为 true： PUT /example_index { "settings": { "analysis": { "filter": { "custom_ascii_folding": { "type": "asciifolding", "preserve_original": true } }, "analyzer": { "custom_ascii_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "custom_ascii_folding" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/rewrite-parameter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/rewrite-parameter/Rewrite 参数 # 像 wildcard、prefix、regexp、fuzzy 和 range 这样的多词查询在内部会重组成一组词。rewrite 参数允许你控制这些词重写的执行和评分。 当多词查询扩展成很多词（例如 prefix: "error*" 匹配数百个词）时，它们在内部会转换成 term 查询。这个过程可能会有以下缺点： 超出 indices.query.bool.max_clause_count 限制（默认是 1024）。 影响匹配文档的评分计算方式。 根据所使用的重写方法，影响内存和延迟。 rewrite 参数让你能够控制多词查询的内部行为。 模式 评分规则 性能 注释 constant_score 所有匹配具有相同分数 最佳 默认模式，适合过滤器 scoring_boolean 基于 TF/IDF 中等 完整相关性评分 constant_score_boolean 相同分数但使用布尔结构 中等 与 must_not 或 minimum_should_match 一起使用 top_terms_N 在顶部 N 个词上使用 TF/IDF 高效 截断扩展 top_terms_boost_N 静态提升 快速 较低准确度 top_terms_blended_freqs_N 混合评分 平衡 最佳评分/效率权衡 相关指南（先读这些） # 部分匹配 查询 DSL 基础 可用的重写方法 # 下表总结了可用的重写方法。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/update-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/update-api/Update API # 基于现有文档做部分字段更新或脚本更新。 内部流程：读取当前 _source → 合并修改 → 写入新文档（不是原地修改）。 请求格式 # POST /<index>/_update/<_id> 路径参数 # 参数 必需 说明 <index> 是 目标索引 <_id> 是 文档 ID 查询参数 # 参数 类型 默认值 说明 retry_on_conflict int 0 版本冲突时自动重试次数。适合"计数器累加"等顺序不敏感场景 routing string — 自定义路由 timeout time 1m 等待主分片可用的超时 refresh string false 更新后刷新策略：true、false、wait_for _source string/boolean true 控制响应中是否返回 _source _source_includes string — 响应中 _source 要包含的字段 _source_excludes string — 响应中 _source 要排除的字段 if_seq_no long — 乐观并发控制 if_primary_term long — 乐观并发控制 wait_for_active_shards string — 活跃分片数量 require_alias boolean false 要求目标必须是别名 注意：Update API 不支持 version / version_type 参数。如需乐观并发控制，请使用 if_seq_no + if_primary_term。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/delete-ingest/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/delete-ingest/删除管道 # 使用 DELETE _ingest/pipeline API 删除摄取管道。 请求格式 # 删除指定管道： DELETE _ingest/pipeline/<pipeline-id> 使用通配符删除匹配的管道： DELETE _ingest/pipeline/log-* 删除所有管道（慎用）： DELETE _ingest/pipeline/* 参数 # 参数 必需 类型 默认值 说明 pipeline-id 是 string — 要删除的管道 ID，支持通配符 * cluster_manager_timeout 否 时长 30s 等待集群管理器节点响应的超时时间 timeout 否 时长 30s 等待整体响应的超时时间 响应示例 # { "acknowledged": true } 注意事项 # 删除一个正在被 index.https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/configuration/backend/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/configuration/backend/后端配置 # 配置安全模块的第一步是确定如何验证用户身份。尽管 Easysearch 本身可以充当一个内部用户数据库，但许多人更喜欢集成企业现有的身份认证体系，例如 LDAP/Active Directory 服务器，或两者组合。设置身份验证和授权服务端的主要配置文件位于 config/security/config.yml。它定义了安全模块如何检索用户凭据、如何验证这些凭据以及如何从后端系统获取其他角色（可选）。 config.yml 主要包含三大部分： config: dynamic: http: ... authc: ... authz: ... HTTP # http 部分具有以下配置项： http: anonymous_auth_enabled: <true|false> xff: enabled: <true|false> internalProxies: '<regex pattern>' remoteIpHeader: '<header name>' 匿名认证 # 设置 anonymous_auth_enabled 可以选择是否开启匿名访问。如果启用，当请求中未提供任何凭据时，用户将以 anonymous 身份通过认证，并被分配 anonymous_backendrole 角色。如果禁用匿名身份验证，则至少在 authc 里面提供一个认证后端，否则安全模块将不予初始化。默认为 false。 提示： 如果启用匿名认证，所有 HTTP 认证器将不会发起 challenge（即不会返回 401 要求客户端提供凭据）。 XFF（X-Forwarded-For）配置 # 如果 Easysearch 位于一个或多个代理或负载均衡器之后，xff 部分可用于配置从 HTTP 头中解析客户端真实 IP 地址的行为。这对于 IP 速率限制和代理认证尤为重要。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/lowercase/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/lowercase/Lowercase 分词器 # lowercase 分词器会在空白处将文本拆分成词条，然后把所有词条转换为小写形式。从功能上来说，这与配置一个 letter 分词器并搭配一个 lowercase 词元过滤器的效果是一样的。不过，使用 lowercase 分词器效率更高，因为分词操作是在一步之内完成的。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 文本分析基础 参考样例 # 以下示例请求创建了一个名为 my-lowercase-index 的新索引，并配置了一个使用小写词元生成器的分词器： PUT /my-lowercase-index { "settings": { "analysis": { "tokenizer": { "my_lowercase_tokenizer": { "type": "lowercase" } }, "analyzer": { "my_lowercase_analyzer": { "type": "custom", "tokenizer": "my_lowercase_tokenizer" } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /my-lowercase-index/_analyze { "analyzer": "my_lowercase_analyzer", "text": "This is a Test.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/whitespace-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/whitespace-analyzer/Whitespace 分析器 # whitespace 分析器仅基于空白字符（例如，空格和制表符）将文本拆分为词元。比如转换为小写形式或移除停用词这样的转换操作，它都不会应用，因此文本的原始大小写形式会被保留，并且标点符号也会作为词元的一部分包含在内。 相关指南（先读这些） # 文本分析基础 文本分析：识别词元 参考样例 # 以下命令创建一个名为 my_whitespace_index 并使用空格分词器的索引： PUT /my_whitespace_index { "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "whitespace" } } } } 配置自定义分词器 # 以下命令来配置一个自定义分词器的索引，该自定义分词器的作用等同于空格分词器： PUT /my_custom_whitespace_index { "settings": { "analysis": { "analyzer": { "my_custom_whitespace_analyzer": { "type": "custom", "tokenizer": "whitespace", "filter": ["lowercase"] } } } }, "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "my_custom_whitespace_analyzer" } } } } 产生的词元 # 以下请求用来检查分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/convert/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/convert/转换处理器 # convert 处理器将文档中的字段转换为不同的类型，例如，将字符串转换为整数或将整数转换为字符串。对于数组字段，数组中的所有值都会被转换。 语法 # 以下是为 convert 处理器提供的语法： { "convert": { "field": "field_name", "type": "type-value" } } 配置参数 # 下表列出了 convert 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要转换的数据的字段名称。支持模板使用。 type 必填 要将字段值转换为的类型。支持的类型有 integer 、 long 、 float 、 double 、 string 、 boolean 、 ip 和 auto 。如果 type 是 boolean ，则如果字段值是字符串 true （忽略大小写），则将其设置为 true ；如果字段值是字符串 false （忽略大小写），则将其设置为 false 。如果类型设置为 ip ，则此处理器将验证字段值是否遵循 IPv4 或 IPv6 地址的正确格式；如果值无效，将引发错误。如果值不是允许的值之一，将发生错误。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true ，则处理器在字段不存在或为 null 时不会修改文档。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 target_field 可选 字段名称，用于存储解析后的数据。如果未指定，值将存储在 field 字段中。默认为 field 。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/delete-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/delete-api/Delete API # 按 ID 删除单条文档。 请求格式 # DELETE /<index>/_doc/<_id> 路径参数 # 参数 必需 说明 <index> 是 目标索引 <_id> 是 文档 ID 查询参数 # 参数 类型 默认值 说明 routing string — 自定义路由值 timeout time 1m 等待主分片可用的超时 refresh string false 删除后刷新策略 version long — 期望版本号 version_type string internal 版本类型 if_seq_no long — 乐观并发控制 if_primary_term long — 乐观并发控制 wait_for_active_shards string — 活跃分片数量 示例 # DELETE /website/_doc/123 响应：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/stop-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/stop-analyzer/Stop 分析器 # stop 分析器会在文本中移除预定义的停用词。该分析器由一个小写分词器和一个停用词分词过滤器组成。 相关指南（先读这些） # 文本分析基础 文本分析：停用词 文本分析：识别词元 参数说明 # 你可以使用以下参数来配置一个停用词分词器。 参数 必填/可选 数据类型 描述 stopwords 可选 字符串或字符串列表 一个包含自定义停用词列表（如 _english）的字符串，或者一个自定义停用词列表的数组。默认值为 _none_。 stopwords_path 可选 字符串 包含停用词列表的文件的路径（相对于配置目录的绝对路径或相对路径）。 参考样例 # 以下命令创建一个名为 my_stop_index 并使用停词器分词器的索引： PUT /my_stop_index { "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "stop" } } } } 配置自定义分词器 # 以下命令来配置一个自定义分词器的索引，该自定义分词器的作用等同于停用词分词器：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/decimal-digit/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/decimal-digit/Decimal Digit 分词过滤器 # decimal_digit 分词过滤器用于将各种字符集中的十进制数字字符（0 到 9）规范化为它们对应的 ASCII 字符。当你希望在文本分析中确保所有数字都能被统一处理，而不管这些数字是以何种字符集书写时，这个过滤器就非常有用。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个带有十进制数字过滤器的分词器： PUT /my_index { "settings": { "analysis": { "filter": { "my_decimal_digit_filter": { "type": "decimal_digit" } }, "analyzer": { "my_analyzer": { "type": "custom", "tokenizer": "standard", "filter": ["my_decimal_digit_filter"] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /my_index/_analyze { "analyzer": "my_analyzer", "text": "123 ١٢٣ १२३" } text分词：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/accessing-data/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/accessing-data/在管道中访问数据 # 在摄取管道中，您可以使用 ctx 对象访问文档数据。此对象表示已处理的文档，并允许您读取、修改或丰富文档字段。管道处理器对文档的 _source 字段及其元数据字段都具有读写访问权限。 访问文档字段 # ctx 对象公开了所有文档字段。您可以直接使用点符号访问它们。 示例：访问顶级字段 # 给定以下示例文档： { "user": "alice" } 您可以通过以下方式访问 user ： "field": "ctx.user" 示例：访问嵌套字段 # 给定以下示例文档： { "user": { "name": "alice" } } 您可以通过以下方式访问 user.name ： "field": "ctx.user.name" 访问源中的字段 # 要访问文档中的字段 _source ，请通过字段名称进行引用： { "set": { "field": "environment", "value": "production" } } 或者，您可以显式使用 _source ： { "set": { "field": "_source.environment", "value": "production" } } 访问元数据字段 # 您可以读取或写入以下元数据字段：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/whitespace/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/whitespace/Whitespace 分词器 # whitespace 分词器会依据空白字符（如空格、制表符和换行符）对文本进行拆分。它将由空白字符分隔开的每个单词都视为一个词元，并且不会执行诸如转换为小写形式或去除标点符号等额外的规范化操作。 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 参考样例 # 以下示例请求创建一个名为 my_index 的新索引，并配置一个使用空格词元生成器的分词器： PUT /my_index { "settings": { "analysis": { "tokenizer": { "whitespace_tokenizer": { "type": "whitespace" } }, "analyzer": { "my_whitespace_analyzer": { "type": "custom", "tokenizer": "whitespace_tokenizer" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_whitespace_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /my_index/_analyze { "analyzer": "my_whitespace_analyzer", "text": "Easysearch is fast!https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/configuration/tls/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/configuration/tls/配置 TLS 证书 # Easysearch 可以通过启用 TLS 传输加密来保护您数据的网络传输安全。 TLS 的相关设置在配置文件 easysearch.yml 中进行，主要包括两个部分：传输层和 HTTP 层。 传输层（Transport）：节点之间的通信。传输层 TLS 是必需的（默认启用）。 HTTP 层：客户端与节点之间的通信。HTTP 层 TLS 是可选的（默认关闭）。 默认的配置如下： security.ssl.transport.cert_file: instance.crt security.ssl.transport.key_file: instance.key security.ssl.transport.ca_file: ca.crt security.ssl.http.enabled: true security.ssl.http.cert_file: instance.crt security.ssl.http.key_file: instance.key security.ssl.http.ca_file: ca.crt 一键生成证书 # 启用 TLS 需要设置证书才能工作，通过执行命令 ./bin/initialize.sh 可以一键生成 TLS 证书，如下： ➨ ./bin/initialize.sh Generating RSA private key, 2048 bit long modulus .......................+++ ...............................+++ e is 65537 (0x10001) Generating RSA private key, 2048 bit long modulus .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/csv/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/csv/CSV 处理器 # csv 处理器用于解析 CSV 文件并将它们作为单独的字段存储在文档中。该处理器会忽略空字段。 语法 # 以下是为 csv 处理器提供的语法： { "csv": { "field": "field_name", "target_fields": ["field1, field2, ..."] } } 配置参数 # 下表列出了 csv 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要转换的数据的字段名称。支持模板使用。 target_fields 必填 字段名称，用于存储解析后的数据。 description 可选 处理器的一个简要描述。 empty_value 可选 表示可选参数，这些参数不是必需的或不适用的。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true ，则处理器在字段不存在或为 null 时不会修改文档。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 quote 可选 用于在 CSV 数据中引用字段的字符。默认为 " 。 separator 可选 用于在 CSV 数据中分隔字段的分隔符。默认为 , 。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 trim 可选 如果设置为 true ，处理器将删除文本开头和结尾的空白字符。默认是 false 。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/lucene-internals/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/lucene-internals/Lucene 底层原理 # Easysearch 的搜索能力建立在 Apache Lucene 之上。理解 Lucene 的核心概念，有助于更好地使用 Easysearch 和进行性能调优。 Lucene 与 Easysearch 的关系 # 用户请求 → Easysearch (分布式协调、REST API、集群管理) ↓ 每个分片 = 一个 Lucene Index ↓ Lucene (倒排索引、评分、段合并) Easysearch 负责：分布式路由、副本复制、集群管理、REST API、安全 Lucene 负责：文本分析、倒排索引构建、查询执行、评分计算 每个 Easysearch 分片（shard） 对应一个完整的 Lucene Index。 术语对齐：Lucene 的"索引"在 Easysearch 里更接近"分片"；而 Easysearch 的"索引"是多个分片的集合。 倒排索引：全文检索的核心 # 要理解 Easysearch 的搜索行为，必须先回答一个基础问题：文本是怎么变成"可搜索"的？ 关系型数据库通常把一个字段当作一个整体来索引；而全文检索需要把一个字段里的每个"词"都变成可检索的索引项。这就需要倒排索引（Inverted Index）——一个天然支持"一个字段对应很多词项"的数据结构。 正排 vs 倒排 # 正排索引（文档 → 词项）：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/mem0/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/mem0/Mem0 集成 # Mem0 是一个为 AI Agent 提供持久化记忆的开源框架。通过将 Easysearch 作为向量存储后端，Mem0 可以对记忆进行语义检索，让 Agent 在跨会话、跨项目的场景下依然能精准调取历史上下文。 架构概览 # 用户对话 → AI Agent ↓ MCP Server (Mem0 OpenMemory) ↓ ┌─────────────────────┐ │ Easysearch │ │ · 记忆向量索引 │ │ · kNN 语义检索 │ └─────────────────────┘ 整体流程： Agent 通过 MCP 协议调用 add_memories 将重要信息写入 Easysearch； Agent 通过 MCP 协议调用 search_memory 对 Easysearch 进行 kNN 语义检索，取回相关记忆； 检索结果注入 Prompt，辅助 Agent 决策。 前置条件 # 条件 说明 Easysearch 集群 已部署并可访问的 Easysearch 集群 Python 3.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/multi-get-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/multi-get-api/Multi Get API # 一次请求获取多条文档。协调节点按分片拆分请求并行转发，比循环调用 GET 更高效。 请求格式 # GET /_mget POST /_mget GET /<index>/_mget POST /<index>/_mget 路径参数 # 参数 必需 说明 <index> 否 默认索引。在 URL 中指定后，请求体中的文档可省略 _index 查询参数 # 参数 类型 默认值 说明 routing string — 默认路由值 preference string — 查询偏好 realtime boolean true 实时读取 refresh boolean false 读取前是否刷新 stored_fields string — 默认返回的 stored 字段 _source string/boolean true 默认 _source 过滤 _source_includes string — 默认包含的字段 _source_excludes string — 默认排除的字段 请求体 # 标准格式 # { "docs": [ { "_index": "website", "_id": "1" }, { "_index": "website", "_id": "2", "_source": ["title"] }, { "_index": "blog", "_id": "3", "routing": "user1" } ] } 每条文档可单独指定 _index、_source、routing、stored_fields。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/scripting/painless-examples/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/scripting/painless-examples/Painless 常用示例 # 本页收集了各种场景下常用的 Painless 脚本示例，可直接复制使用或按需修改。 脚本字段（Script Fields） # 在搜索结果中返回动态计算的字段值。 计算折扣价格 # GET products/_search { "query": { "match_all": {} }, "script_fields": { "discounted_price": { "script": { "source": "doc['price'].value * (1 - params.discount)", "params": { "discount": 0.2 } } } } } 拼接姓名字段 # GET employees/_search { "script_fields": { "full_name": { "script": { "source": """ def first = doc['first_name.keyword'].size() > 0 ? doc['first_name.keyword'].value : ''; def last = doc['last_name.https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/easysearch-ui/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/easysearch-ui/使用 Easysearch UI 访问 # Easysearch 1.15.0+ 版本内置了可视化管理界面（Easysearch UI），无需安装任何第三方工具，启动服务后直接在浏览器访问即可。部署成本为零、服务端零资源占用，界面默认支持中文。 💡 如果你需要多集群统一管理、告警通知等企业级功能，请参阅 使用 INFINI Console 管理。 访问方式 # 启动 Easysearch 后，在浏览器中打开： https://localhost:9200/_ui/ 输入用户名（admin）和初始化时终端输出的密码即可登录。 如果 Easysearch 部署在远程服务器上，将 localhost 替换为服务器 IP 地址即可。 集群概览：全局状态一目了然 # 登录后首页直接展示集群全景监控面板，核心指标全覆盖： 健康状态：醒目的色块（Green / Yellow / Red），进门就知道系统安危 资源仪表盘：CPU、内存、JVM 堆内存、磁盘使用率实时展示，性能瓶颈一眼便知 数据规模：文档数、索引数、分片数实时更新 拓扑视图：直观展示节点分布，多节点集群管理不再抽象 不像只能看到一行 status: yellow 的 JSON 字符串，Easysearch 的概览页用卡片式设计把关键信息全部呈现在首屏。 更多 UI 操作详情请参阅 管理手册。 节点与分片可视化 # 当集群状态出现异常时，需要深入细节排查： 节点管理：清晰展示每个节点的 IP、角色、存储占用和负载情况，对于多节点集群的负载均衡分析至关重要 分片视图：直观展示主分片和副本分片在不同节点上的分布，故障排查效率提升十倍不止 索引列表：查看每个索引的文档数、分片数、存储大小，支持创建/删除/别名管理 开发工具（Dev Tools）：开发者的瑞士军刀 # 内置的开发工具是开发者最常用的功能，提供了支持语法高亮和自动补全的 Web 编辑器：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/keyword-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/keyword-analyzer/Keyword 分析器 # keyword 分析器根本不会对文本进行分词。相反，它将整个输入视为单个词元，不会将其拆分成单个的词项。keyword 分析器常用于包含电子邮件地址、网址或产品 ID 的字段，以及其他不需要进行分词的情况。 相关指南（先读这些） # 文本分析基础 文本分析：识别词元 参考样例 # 以下命令创建一个名为 my_keyword_index 使用关键词分词器的索引： PUT /my_keyword_index { "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "keyword" } } } } 配置自定义分词器 # 以下命令来配置一个自定义分词器的索引，该自定义分词器的作用等同于关键词分词器： PUT /my_custom_keyword_index { "settings": { "analysis": { "analyzer": { "my_keyword_analyzer": { "tokenizer": "keyword" } } } } } 产生的词元 # 以下请求来检查使用该分词器生成的词元： POST /my_custom_keyword_index/_analyze { "analyzer": "my_keyword_analyzer", "text": "Just one token" } 返回内容包含产生的词元https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/keyword/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/keyword/Keyword 分词器 # keyword 分词器接收文本并将其原封不动地作为单个词元输出。当你希望输入内容保持完整时，比如在管理像姓名、产品代码或电子邮件地址这类结构化数据时，这个分词器就特别有用。 keyword 分词器可以与词元过滤器搭配使用来处理文本。例如，对文本进行规范化处理或去除多余的字符。 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个使用关键字词元生成器的分词器： PUT /my_index { "settings": { "analysis": { "analyzer": { "my_keyword_analyzer": { "type": "custom", "tokenizer": "keyword" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_keyword_analyzer" } } } } 生成的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /my_index/_analyze { "analyzer": "my_keyword_analyzer", "text": "Easysearch Example" } 返回内容会是包含原始内容的单个词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/pipeline-failures/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/pipeline-failures/处理管道故障 # 摄取管道由一系列按顺序执行的处理器组成。如果某个处理器失败，默认行为是整条管道中止，文档不会被索引。 你有两种方式应对处理器失败： 中止管道（默认）：处理器失败后整条管道停止，文档不被索引 跳过失败继续执行：通过 ignore_failure 或 on_failure 让管道在失败后继续运行 默认情况下，如果管道中的某个处理器失败，则摄取管道会停止。如果您希望在处理器失败时继续运行管道，您可以在创建管道时将该处理器的 ignore_failure 参数设置为 true ： PUT _ingest/pipeline/my-pipeline/ { "description": "Rename 'provider' field to 'cloud.provider'", "processors": [ { "rename": { "field": "provider", "target_field": "cloud.provider", "ignore_failure": true } } ] } 您可以将 on_failure 参数指定为在处理器失败后立即运行。如果您已指定 on_failure ，即使 on_failure 配置为空，Easysearch 也会运行管道中的其他处理器： PUT _ingest/pipeline/my-pipeline/ { "description": "Add timestamp to the document", "processors": [ { "date": { "field": "timestamp_field", "formats": ["yyyy-MM-dd HH:mm:ss"], "target_field": "@timestamp", "on_failure": [ { "set": { "field": "ingest_error", "value": "failed" } } ] } } ] } 如果处理器失败，Easysearch 会记录失败并继续运行搜索管道中剩余的所有处理器。要检查是否有任何失败，您可以使用摄取管道指标。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/lifecycle/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/lifecycle/数据保留与生命周期管理 # 时间序列数据（日志/指标/审计）有个现实：越新的越值钱，越老的越偶尔被翻。当数据规模持续增长，你面临三个经典问题： 性能与成本的平衡：最近数据要快速可查，历史数据如何低成本保留？ 合规与可追溯：历史数据要留多久？ 自动化运维：如何减少手工干预？ 本页给你一套完整的数据保留策略体系。建议先了解 时间序列数据建模。 快速决策树 # 开始 → 数据还在写入? ├─ 是 → 放在"热"节点，使用好硬件 │ ├─ 准备自动化? → 用 ILM（推荐） │ └─ 手动管理? → 按时间切索引 │ └─ 不再写入 → 迁移到"温/冷"节点 ├─ 还会经常查询? → 温节点，forcemerge 优化 │ ├─ 很少查询? → 冷节点或关闭索引 │ └─ 长期存档? ├─ 快照 → 删索引（完全清除） └─ 或用 Rollup 汇总压缩 核心策略详解 # 1. 按时间切索引：最简单的删除策略 # 时间序列数据治理的第一优先：按时间切索引。 这样做的好处： 删除旧数据变成"删整个索引"，而不是"给 N 个文档标记删除" 删索引是异步的、无锁的，不阻塞查询和写入 可以精确控制数据保留窗口 示例：按天切索引https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/add-remote-cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/add-remote-cluster/新增远程集群 # 通过新增远程集群，可以建立与其他 Easysearch 集群的连接，用于跨集群搜索和复制等功能。 操作步骤 # 进入远程集群配置页面：登录 Easysearch UI，在左侧导航栏点击「集群设置」，切换至「远程集群」标签页。 打开新增远程集群弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增远程集群」配置窗口。 配置远程集群信息： 填写必填项「名称」，自定义远程集群标识（如示例中的 test_remote_cluster）。 选择访问模式，默认推荐使用「Sniff」模式。 填写入口地址（TCP 协议），输入远程集群的节点地址与端口（如 easysearch-1ls64n5quf37:9300）。 按需开启「连接不可用时跳过」开关。 完成创建：确认配置无误后，点击「确定」按钮。 查看新增结果：配置成功后，新的远程集群将出现在远程集群列表中，可查看其地址、访问模式和连接数等信息。 注意事项 # 添加远程集群前，请确保两端集群的安全配置一致，并正确设置权限和证书互信，避免连接失败。 目标集群需满足跨集群复制的版本与插件要求，且 Follower 节点需包含 remote_cluster_client 角色。 入口地址需填写 TCP 协议对应的端口（默认 9300），而非 HTTP 端口（默认 9200）。 若开启「连接不可用时跳过」，配置过程中若检测到连接异常，将跳过当前地址继续配置。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/bulk-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/bulk-api/Bulk API # 在单个请求中执行多个 index、create、update、delete 操作。是高吞吐写入的核心能力。 请求格式 # POST /_bulk POST /<index>/_bulk 路径参数 # 参数 必需 说明 <index> 否 默认索引。指定后操作行中可省略 _index 查询参数 # 参数 类型 默认值 说明 routing string — 默认路由值 pipeline string — 默认 Ingest Pipeline refresh string false 所有操作完成后的刷新策略 timeout time 1m 超时时间 wait_for_active_shards string — 活跃分片数量 require_alias boolean — 要求目标必须是别名 _source string/boolean — 默认 _source 过滤 _source_includes string — 默认包含字段 _source_excludes string — 默认排除字段 请求体格式（NDJSON） # 请求体是逐行 JSON（Newline Delimited JSON）格式，每行一个 JSON 对象：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/n-gram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/n-gram/N-gram 分词器 # ngram 分词器会将文本拆分为指定长度的重叠 n-gram（固定长度为 n 的字符序列）。当你希望实现部分单词匹配或自动补全搜索功能时，这个分词器特别有用，因为它会生成原始输入文本的子字符串（n-gram 字符串）。 相关指南（先读这些） # 文本分析：识别词元 部分匹配 文本分析基础 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个使用 n-gram 词元生成器的分词器。 PUT /my_index { "settings": { "analysis": { "tokenizer": { "my_ngram_tokenizer": { "type": "ngram", "min_gram": 3, "max_gram": 4, "token_chars": ["letter", "digit"] } }, "analyzer": { "my_ngram_analyzer": { "type": "custom", "tokenizer": "my_ngram_tokenizer" } } } } } 生成的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /my_index/_analyze { "analyzer": "my_ngram_analyzer", "text": "Search" } 返回内容包含产生的词元https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/porter-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/porter-stem/Porter Stem 分词过滤器 # porter_stem 分词过滤器会将单词还原为其基本（或词干）形式，并去除单词中常见的后缀，这有助于通过单词的词根来匹配相似的单词。例如，单词"running"会被词干提取为"run"。此分词过滤器主要用于英语，并基于 波特词干提取算法进行词干提取操作。 相关指南（先读这些） # 文本分析：词干提取 文本分析：规范化 参考样例 # 以下示例请求创建了一个名为 my_stem_index 的新索引，并配置了一个带有波特词干提取过滤器的分词器。 PUT /my_stem_index { "settings": { "analysis": { "filter": { "my_porter_stem": { "type": "porter_stem" } }, "analyzer": { "porter_analyzer": { "tokenizer": "standard", "filter": [ "lowercase", "my_porter_stem" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /my_stem_index/_analyze { "text": "running runners ran", "analyzer": "porter_analyzer" } 返回内容包含产生的词元 { "tokens": [ { "token": "run", "start_offset": 0, "end_offset": 7, "type": "<ALPHANUM>", "position": 0 }, { "token": "runner", "start_offset": 8, "end_offset": 15, "type": "<ALPHANUM>", "position": 1 }, { "token": "ran", "start_offset": 16, "end_offset": 19, "type": "<ALPHANUM>", "position": 2 } ] }https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/delete-remote-cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/delete-remote-cluster/删除远程集群 # 可以删除不再需要的远程集群连接。 操作步骤 # 进入远程集群配置页面：登录 Easysearch UI，在左侧导航栏点击「集群设置」，切换至「远程集群」标签页。 触发删除操作：在远程集群列表中，找到目标集群，点击「操作」列的更多按钮，在下拉菜单中选择「删除」选项。 确认删除操作：在弹出的提示窗口中，核对集群名称，点击「确定」按钮。 验证删除结果：删除完成后，目标集群将从远程集群列表中消失，列表仅保留剩余的远程集群配置。 注意事项 # 删除远程集群前，请确认已停止依赖该集群的跨集群复制、跨集群搜索等相关业务，避免影响业务正常运行。 删除操作仅移除当前集群对远程集群的配置，不会影响远程集群本身的运行状态。 删除后若需再次使用该远程集群，需重新执行新增配置操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/date-index-name/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/date-index-name/日期索引名称处理器 # date_index_name 处理器用于根据文档中的日期或时间戳字段将文档指向正确的基于时间的索引。处理器将 _index 元数据字段设置为日期数学索引名称表达式。然后处理器从正在处理的文档的 field 字段中获取日期或时间戳并将其格式化为日期数学索引名称表达式。然后提取的日期、index_name_prefix 值和 date_rounding 值被组合以创建日期数学索引表达式。例如，如果 field 字段包含值 2023-10-30T12:43:29.000Z，且 index_name_prefix 设置为 week_index-，date_rounding 设置为 w，则日期数学索引名称表达式为 week_index-2023-10-30。您可以使用 date_formats 字段指定日期数学索引表达式中的日期应如何格式化。 以下是为 date_index_name 处理器提供的语法： { "date_index_name": { "field": "your_date_field or your_timestamp_field", "date_rounding": "rounding_value" } } 配置参数 # 下表列出了 date_index_name 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要附加数据的字段名称。支持模板使用。 date_rounding 必填 索引名称中的日期格式为圆整格式。有效值包括 y （年）、 M （月）、 w （周）、 d （日）、 h （小时）、 m （分钟）和 s （秒）。 date_formats 可选 用于解析日期或时间戳字段的日期格式数组。有效选项包括 Java 时间模式或以下格式之一：ISO8601、UNIX、UNIX_MS 或 TAI64N。默认为 yyyy-MM-dd'T'HH:mm:ss.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/pattern-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/pattern-analyzer/Pattern 分析器 # pattern 分析器允许你定义一个自定义分析器，该分析器使用正则表达式（regex）将输入文本分割成词元。它还提供了应用正则表达式、将词元转换为小写以及过滤掉停用词的功能。 相关指南（先读这些） # 文本分析基础 文本分析：识别词元 参数说明 # 匹配模式分词器可以使用以下参数进行配置。 参数 必填/可选 数据类型 描述 pattern 可选 字符串 用于对输入内容进行分词匹配的 Java 正则表达式。默认值是 \W+。 flags 可选 字符串 以竖线分隔的 Java 正则表达式的字符串标志，这些标志会修改正则表达式的行为。 lowercase 可选 布尔值 是否将词元转换为小写。默认值为 true。 stopwords 可选 字符串或字符串列表 个包含自定义停用词列表（如 _english）的字符串，或者一个自定义停用词列表的数组。默认值为 _none_。 stopwords_path 可选 字符串 包含停用词列表的文件的路径（相对于配置目录的绝对路径或相对路径）。 参考样例 # 以下命令创建一个名为 my_pattern_index 并使用匹配模式分词器的索引：https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/configuration/system-indices/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/configuration/system-indices/系统索引 # Easysearch 默认的身份信息存放在一个受保护的系统索引里面，名称为：.security， 将索引设置为系统索引可以对该索引的数据进行额外的保护，因为即使您的用户帐户对所有索引具有读取权限，也无法直接访问此系统索引中的数据。 您可以在 easysearch.yml 中添加其它您希望需要受到保护的索引。 security.system_indices.enabled: true security.system_indices.indices: [".infini-*"] 如果要访问系统索引，必须使用管理员证书的方式来进行： 配置管理证书: curl -k --cert ./admin.crt --key ./admin.key -XGET 'https://localhost:9200/.security/_search' 另一种方法是从每个节点上的 security.system_indices.index 列表中删除该索引，然后重新启动 Easysearch 即可正常操作该索引。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/count-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/count-api/Count API # 返回匹配查询的文档数量，不返回文档内容。 请求格式 # GET /<index>/_count POST /<index>/_count GET /_count POST /_count 路径参数 # 参数 必需 说明 <index> 否 目标索引，支持逗号分隔多索引和通配符 查询参数 # 参数 类型 默认值 说明 q string — 简单查询字符串 df string — q 参数的默认搜索字段 default_operator string OR q 参数的默认逻辑运算符：AND 或 OR analyzer string — q 参数使用的分析器 analyze_wildcard boolean false 是否分析通配符 lenient boolean — 宽松解析模式 routing string — 路由值 preference string — 查询偏好 min_score float — 最低分数过滤 terminate_after int 0 每分片最多计数的文档数（0 = 不限制） expand_wildcards string open 通配符展开方式：open、closed、hidden、all、none ignore_unavailable boolean false 忽略不存在的索引 allow_no_indices boolean true 允许通配符不匹配任何索引 请求体（可选） # { "query": { "term": { "status": "published" } } } 示例 # 使用查询字符串：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/kstem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/kstem/KStem 分词过滤器 # kstem 分词过滤器是一种词干提取过滤器，用于将单词还原为其词根形式。该过滤器是一种专为英语设计的轻量级算法词干提取器，它执行以下词干提取操作： 将复数形式的单词还原为单数形式。 将不同的动词时态转换为其基本形式。 去除常见的派生词尾，例如 “-ing” 或 “-ed”。 kstem 分词过滤器等同于配置了 light_english 语言的词干提取器过滤器。与其他词干提取过滤器（如 porter_stem）相比，它提供了更为保守的词干提取方式。 相关指南（先读这些） # 文本分析：词干提取 文本分析：规范化 KStem 分词过滤器基于 Lucene 的 KStemFilter。如需了解更多信息，请参阅 Lucene 文档。 参考样例 # 以下示例请求创建了一个名为 my_kstem_index 的新索引，并配置了一个带有 KStem 过滤器的分词器： PUT /my_kstem_index { "settings": { "analysis": { "filter": { "kstem_filter": { "type": "kstem" } }, "analyzer": { "my_kstem_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "kstem_filter" ] } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_kstem_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/fingerprint-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/fingerprint-analyzer/Fingerprint 分析器 # fingerprint 分析器会创建一个文本指纹。该分析器对从输入生成的词项（词元）进行排序和去重，然后使用一个分隔符将它们连接起来。它通常用于数据去重，对于包含相同单词的相似输入，无论单词顺序如何，它都可以产生相同的输出结果。 fingerprint 分析器由以下组件组成： standard 分词器 lowercase 分词过滤器 asciifolding 分词过滤器 stop 分词过滤器 fingerprint 分词过滤器 相关指南（先读这些） # 文本分析基础 文本分析：规范化 参数说明 # 指纹分词器可以使用以下参数进行配置。 参数 必填/可选 数据类型 描述 separator 可选 字符串 在对词项进行词元生成、排序和去重后，用于连接这些词项的字符。默认值为一个空格（ ）。 max_output_size 可选 整数 定义输出词元的最大大小。如果连接后的指纹超过此大小，将被截断。默认值为 255。 stopwords 可选 字符串或字符串列表 自定义的停用词列表。默认值为 _none_。 stopwords_path 可选 字符串 包含停用词列表的文件的路径（相对于配置目录的绝对路径或相对路径）。 参考样例 # 以下命令创建一个名为 my_custom_fingerprint_index 带有指纹分词器的索引：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/date/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/date/日期处理器 # date 处理器用于从文档字段中解析日期，并将解析后的数据添加到新字段中。默认情况下，解析后的数据存储在 @timestamp 字段中。 语法 # 以下是为 date 处理器提供的语法： { "date": { "field": "date_field", "formats": ["yyyy-MM-dd'T'HH:mm:ss.SSSZZ"] } } 配置参数 # 下表列出了 date 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要转换的数据的字段名称。支持模板使用。 formats 必填 期望的日期格式数组。可以是日期格式或以下格式之一：ISO8601、UNIX、UNIX_MS 或 TAI64N。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 locale 可选 解析日期时使用的区域设置。默认为 ENGLISH 。支持模板片段。 on_failure 可选 在处理器失败时运行的处理器列表。 output_format 可选 用于目标字段的日期格式。默认为 yyyy-MM-dd'T'HH:mm:ss.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/edge-n-gram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/edge-n-gram/Edge N-gram 分词器 # edge_ngram 分词器会从每个单词的开头生成部分单词词元，也就是 n 元组。它会根据指定的字符分割文本，并在定义的最小和最大长度范围内生成词元。这种分词器在实现即输即搜（search-as-you-type）功能时特别有用。 前缀 n 元组非常适合用于自动补全搜索，在这种搜索中单词的顺序可能会有所不同，例如在搜索产品名称或地址时。有关更多信息，请参阅"自动补全"相关内容。不过，对于像电影或歌曲标题这种顺序固定的文本，完成建议器（completion suggester）可能会更准确。 默认情况下，edge_ngram 分词器生成的词元最小长度为 1，最大长度为 2。例如，当分析文本 Easysearch 时，默认配置会生成 “E” 和 “Ea” 这两个 n 元组。这些短的 n 元组常常会匹配到太多不相关的词条，所以调整 n 元组的长度，对分词器进行优化是很有必要的。 相关指南（先读这些） # 文本分析：识别词元 部分匹配 文本分析基础 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个使用前缀 n 元词元生成器的分词器。该词元生成器生成长度为 3 到 6 个字符的词元，且将字母和符号都视为有效的词元字符。 PUT /edge_n_gram_index { "settings": { "analysis": { "analyzer": { "my_custom_analyzer": { "tokenizer": "my_custom_tokenizer" } }, "tokenizer": { "my_custom_tokenizer": { "type": "edge_ngram", "min_gram": 3, "max_gram": 6, "token_chars": [ "letter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/term-vectors-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/term-vectors-api/Term Vectors API # 返回文档中特定字段的词项信息（词频、位置、偏移量等），用于文本分析和调试。 请求格式 # GET /<index>/_termvectors/<_id> POST /<index>/_termvectors/<_id> GET /<index>/_termvectors # 在请求体中提供临时文档 POST /<index>/_termvectors 批量获取： GET /_mtermvectors POST /_mtermvectors GET /<index>/_mtermvectors POST /<index>/_mtermvectors 路径参数 # 参数 必需 说明 <index> 是 目标索引 <_id> 否 文档 ID。省略时需在请求体中通过 doc 提供临时文档 查询参数 # 参数 类型 默认值 说明 fields string — 逗号分隔的字段列表 offsets boolean true 返回词项偏移量 positions boolean true 返回词项位置 payloads boolean true 返回词项负载 term_statistics boolean false 返回词项的总词频和文档频率 field_statistics boolean true 返回文档计数、文档频率之和、总词频之和 realtime boolean true 实时读取 routing string — 路由值 preference string — 查询偏好 示例 # GET /website/_termvectors/1?https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/pattern/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/pattern/Pattern 分词器 # pattern 分词器是一种高度灵活的分词器，它允许你根据自定义的 Java 正则表达式将文本拆分为词元。与使用 Lucene 正则表达式的 simple_pattern 分词器和 simple_pattern_split 分词器不同，pattern 分词器能够处理更复杂、更细致的正则表达式模式，从而让你对文本的分词方式拥有更强的掌控力。 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个使用匹配词元生成器的分词器。该分词器会在 -、_ 或 . 字符处对文本进行分割。 PUT /my_index { "settings": { "analysis": { "tokenizer": { "my_pattern_tokenizer": { "type": "pattern", "pattern": "[-_.]" } }, "analyzer": { "my_pattern_analyzer": { "type": "custom", "tokenizer": "my_pattern_tokenizer" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_pattern_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/dissect/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/dissect/解析处理器 # dissect 处理器从文档文本字段中提取值，并根据解析模式将它们映射到单个字段。该处理器非常适合从具有已知结构的日志消息中提取字段。与 grok 处理器不同，dissect 不使用正则表达式，语法更简单。 语法 # 以下是为 dissect 处理器提供的语法： { "dissect": { "field": "source_field", "pattern": "%{dissect_pattern}" } } 配置参数 # 下表列出了 dissect 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 要解析的数据所包含的字段名称。支持模板使用。 pattern 必填 用于从指定字段提取数据的 dissect 模式。 append_separator 可选 分隔字符或字符串，用于分隔附加字段。默认为 "" （空字符串）。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true ，则处理器在字段不存在或为 null 时不会修改文档。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/stemmer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/stemmer/Stemmer 分词过滤器 # stemmer 分词过滤器会将单词缩减为其词根或基本形式（也称为词干 stem）。 相关指南（先读这些） # 词干提取 文本分析基础 参数说明 # 词干提取分词过滤器可以通过一个 language（语言）参数进行配置，该参数接受以下值： 阿拉伯语：arabic 亚美尼亚语：armenian 巴斯克语：basque 孟加拉语：bengali 巴西葡萄牙语：brazilian 保加利亚语：bulgarian 加泰罗尼亚语：catalan 捷克语：czech 丹麦语：danish 荷兰语：dutch、dutch_kp 英语：english（默认）、light_english、lovins、minimal_english、porter2、possessive_english 爱沙尼亚语：estonian 芬兰语：finnish、light_finnish 法语：light_french、french、minimal_french 加利西亚语：galician、minimal_galician（仅复数处理步骤） 德语：light_german、german、german2、minimal_german 希腊语：greek 印地语：hindi 匈牙利语：hungarian、light_hungarian 印尼语：indonesian 爱尔兰语：irish 意大利语：light_italian、italian 库尔德语（索拉尼方言）：sorani 拉脱维亚语：latvian 立陶宛语：lithuanian 挪威语（书面挪威语）：norwegian、light_norwegian、minimal_norwegian 挪威语（新挪威语）：light_nynorsk、minimal_nynorsk 葡萄牙语：light_portuguese、minimal_portuguese、portuguese、portuguese_rslp 罗马尼亚语：romanian 俄语：russian、light_russian 西班牙语：light_spanish、spanish 瑞典语：swedish、light_swedish 土耳其语：turkish 你也可以使用 name 参数作为 language 参数的别名。如果两个参数都被设置，name 参数将被忽略。 参考样例 # 以下示例请求创建了一个名为 my-stemmer-index 的新索引，并配置了一个带有词干提取过滤器的分词器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/snowball/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/snowball/Snowball 分词过滤器 # snowball 分词过滤器是一种基于 雪球算法的词干提取过滤器。它支持多种语言，并且比波特词干提取算法更加高效和准确。 相关指南（先读这些） # 文本分析：词干提取 文本分析：规范化 参数说明 # 雪球分词过滤器可以通过一个 language（语言）参数进行配置，该参数接受以下值： 阿拉伯语（Arabic） 亚美尼亚语（Armenian） 巴斯克语（Basque） 加泰罗尼亚语（Catalan） 丹麦语（Danish） 荷兰语（Dutch） 英语（English，默认值） 爱沙尼亚语（Estonian） 芬兰语（Finnish） 法语（French） 德语（German） 德语 2（German2） 匈牙利语（Hungarian） 意大利语（Italian） 爱尔兰语（Irish） Kp 立陶宛语（Lithuanian） 洛文斯（Lovins） 挪威语（Norwegian） 波特（Porter） 葡萄牙语（Portuguese） 罗马尼亚语（Romanian） 俄语（Russian） 西班牙语（Spanish） 瑞典语（Swedish） 土耳其语（Turkish） 参考样例 # 以下示例请求创建了一个名为 my-snowball-index 的新索引，并配置了一个带有雪球过滤器的分词器。 PUT /my-snowball-index { "settings": { "analysis": { "filter": { "my_snowball_filter": { "type": "snowball", "language": "English" } }, "analyzer": { "my_snowball_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "my_snowball_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/dot-expander/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/dot-expander/点展开器 # dot_expander 处理器是一个帮助你处理层次化数据的工具。它将包含点的字段转换为对象字段，使它们能够被管道中的其他处理器访问。如果没有这种转换，包含点的字段将无法被处理。 以下是为 dot_expander 处理器提供的语法： { "dot_expander": { "field": "field.to.expand" } } 配置参数 # 下表列出了 dot_expander 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 要展开成对象字段的字段。支持模板使用。 path 可选 此字段仅在要展开的字段嵌套在其他对象字段内时才需要。这是因为 field 参数仅识别叶字段。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/simple-pattern/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/simple-pattern/Simple Pattern 分词器 # simple_pattern 分词器使用正则表达式匹配文本，将匹配到的内容作为词元输出。它与 simple_pattern_split 的区别在于：simple_pattern 输出匹配的部分，而 simple_pattern_split 输出被分隔的部分。 该分词器使用 Lucene 正则表达式，语法是标准正则表达式的子集。 参数 # 参数 说明 默认值 pattern Lucene 正则表达式模式 空字符串（匹配空串） 示例 # PUT my_index { "settings": { "analysis": { "tokenizer": { "my_tokenizer": { "type": "simple_pattern", "pattern": "[0-9]{3}" } }, "analyzer": { "my_analyzer": { "tokenizer": "my_tokenizer" } } } } } POST my_index/_analyze { "analyzer": "my_analyzer", "text": "fd]]]-%]afd][ 123 fd-ede 456" } 以上示例将产生 123 和 456 两个词元。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/drop/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/drop/Drop 处理器 # drop 处理器用于丢弃不进行索引的文档。这可以用于根据某些条件防止文档被索引。例如，您可能使用 drop 处理器来防止缺少重要字段或包含敏感信息的文档被索引。 当 drop 处理器丢弃文档时，它不会引发任何错误，这使得它对于防止索引问题而不会在您的 Easysearch 日志中充斥错误消息非常有用。 语法 # 以下是为 drop 处理器提供的语法： { "drop": { "if": "ctx.foo == 'bar'" } } 配置参数 # 下表列出了 drop 处理器所需的和可选参数。 参数 是否必填 描述 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/linux/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/linux/Linux 环境下使用 Easysearch # 为了安全起见，Easysearch 不支持通过 root 身份来运行，需要新建普通用户，如 easysearch 用户来快速运行 Easysearch。 一键安装 # 通过我们提供的自动安装脚本可自动下载最新版本的 easysearch 进行解压安装，默认解压到 /data/easysearch curl -sSL http://get.infini.cloud | bash -s -- -p easysearch 脚本的可选参数如下： -v [版本号]（默认采用最新版本号） -d [安装目录]（默认安装到/data/easysearch） bundle 包运行 # bundle 是内置 JDK 的安装包，不需要额外下载 JDK，可直接解压运行。 # 创建 easysearch 用户 groupadd -g 602 easysearch useradd -u 602 -g easysearch -m -d /home/easysearch -c 'easysearch' -s /bin/bash easysearch # 创建 easysearch 安装目录 mkdir -p /data/easysearch # 下载 bundle 包并解压到安装目录 wget -O - https://release.https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/mapping-patterns/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/mapping-patterns/Mapping 模式与最佳实践 # 在理解了 Mapping 基础之后，本页给出几种最常用、最实用的 Mapping 设计模式，帮助你避免常见坑。 复杂数据类型：数组、对象与内部对象 # 多值字段（数组） # 任何字段都可以包含多个值，以数组形式索引： { "tag": [ "search", "nosql" ] } 要点： 数组中所有值必须是相同数据类型（不能混用日期和字符串） 如果通过索引数组创建新字段，Easysearch 会用第一个值的数据类型作为字段类型 数组在索引时被处理为“多值字段”，可以搜索，但无序 搜索时不能指定“第一个”或“最后一个”元素 注意：从 Easysearch 获取文档时，_source 中的数组顺序与索引时一致；但索引层面是无序的，可以把数组想象成“装在袋子里的值”。 空字段 # 以下三种情况被认为是空字段，不会被索引： { "null_value": null, "empty_array": [], "array_with_null_value": [ null ] } 在 Lucene 中不能存储 null 值，所以空字段等同于不存在。 内部对象（嵌套对象） # JSON 支持嵌套对象，例如： { "tweet": "Easysearch is very flexible", "user": { "id": "@johnsmith", "gender": "male", "age": 26, "name": { "full": "John Smith", "first": "John", "last": "Smith" } } } Easysearch 会自动将内部对象映射为 object 类型，并在 properties 下列出内部字段：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/nvme/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/nvme/NVMe 配置指南 # NVMe SSD 提供极高的 IOPS 和带宽，是 Easysearch 生产环境的首选存储。 为什么选择 NVMe # 指标 SATA SSD NVMe SSD 随机读 IOPS ~90K ~500K+ 随机写 IOPS ~50K ~200K+ 顺序读带宽 ~550 MB/s ~3,500 MB/s 延迟 ~100us ~20us Easysearch 的段合并、translog 写入、倒排索引读取都受益于低延迟和高 IOPS。 磁盘格式化与挂载 # # 查看 NVMe 设备 lsblk | grep nvme # 格式化（推荐 xfs 或 ext4） mkfs.https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/orm/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/orm/ORM 框架集成 # 在使用关系数据库的应用中，常见需求是将数据库数据同步到 Easysearch 以实现搜索功能。本文介绍常见 ORM 框架与 Easysearch 的集成方式。 架构模式 # 模式一：应用层双写 # 应用程序 → 写入 MySQL (ORM) → 同时写入 Easysearch (ES Client) 优点：实现简单，实时性好 缺点：一致性难保障，应用耦合度高 模式二：CDC 同步（推荐） # 应用程序 → 写入 MySQL ↓ Canal / Debezium 监听 binlog ↓ 同步到 Easysearch 优点：应用无感知，一致性好 缺点：需要额外组件 模式三：定时全量/增量同步 # 定时任务 → 查询 MySQL 增量数据 → 批量写入 Easysearch 优点：简单可靠 缺点：有延迟（取决于同步周期） Spring Data Elasticsearch # Spring Data 提供了对 Elasticsearch 的原生支持，可直接连接 Easysearch：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/python/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/python/Python 客户端 # 本页面帮助你快速跑通 Python 客户端连接 Easysearch 的完整流程。 推荐：Easysearch 官方 Python 客户端 # Easysearch 提供了官方 Python 客户端 easysearch-py（Apache 2.0 开源），包名 easysearch。 兼容说明：也可继续使用 elasticsearch-py 7.10.x 兼容连接，API 调用方式相同，仅导入路径不同。下文示例以官方客户端为主，兼容用法见 备选方案。 安装依赖 # # 官方客户端（推荐） pip install https://github.com/infinilabs/easysearch-py/releases/download/v0.1.0/easysearch-0.1.0-py2.py3-none-any.whl # 如需 async/await 支持 pip install "easysearch[async] @ https://github.com/infinilabs/easysearch-py/releases/download/v0.1.0/easysearch-0.1.0-py2.py3-none-any.whl" 建立连接 # from easysearch import Easysearch es = Easysearch( ["https://localhost:9200"], http_auth=("admin", "your_password"), verify_certs=False, # 开发环境；生产环境请配置 CA 证书 timeout=30, max_retries=3, retry_on_timeout=True, ) # 验证连接 print(es.https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/observability/skywalking/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/observability/skywalking/SkyWalking 存储后端集成 # Apache SkyWalking 是一款广泛使用的分布式应用性能监控（APM）系统。Easysearch 可以作为其存储后端，存储链路追踪和指标数据。 相关指南（先读这些） # OpenTelemetry 集成 集群监控 架构说明 # 应用服务（Agent） ↓ gRPC / HTTP SkyWalking OAP Server ↓ ES 协议 Easysearch（存储后端） ↓ SkyWalking UI / Grafana（可视化） SkyWalking OAP Server 使用 Elasticsearch 协议写入和查询数据。由于 Easysearch 兼容 ES 7.x API，可以直接配置为存储后端。 配置步骤 # 1. 修改 OAP Server 配置 # 编辑 application.yml，将存储类型设为 elasticsearch： storage: selector: elasticsearch elasticsearch: namespace: sw clusterNodes: https://easysearch-node1:9200 protocol: https user: admin password: your_password trustStorePath: /path/to/truststore.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/update-by-query/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/update-by-query/Update by Query # Update by Query 对所有匹配查询条件的文档执行更新操作。 常用于批量修改字段值、数据迁移补丁、通过脚本做批量计算等场景。 内部流程：scroll 遍历匹配文档 → 逐批执行 bulk update → 返回统计结果。 请求格式 # POST /<index>/_update_by_query 路径参数 # 参数 必需 说明 <index> 是 目标索引，支持逗号分隔多索引和通配符 查询参数 # 参数 类型 默认值 说明 refresh boolean false 操作完成后是否刷新受影响的分片 timeout time 1m 超时时间 wait_for_completion boolean true 为 true 时同步等待完成后返回结果；为 false 时立即返回 task ID，可通过 Task API 查询进度 wait_for_active_shards string — 操作前需要的活跃分片数量 requests_per_second float 无限制 每秒请求数限制（流量控制）。-1 = 不限制 slices int/string 1 并行切片数。"auto" = 自动按分片数拆分 scroll time — scroll 上下文存活时间（如 5m） scroll_size int 1000 每批 scroll 获取的文档数 conflicts string abort 版本冲突处理方式：abort = 遇到冲突即中止；proceed = 跳过冲突继续执行 max_docs int 全部 最多处理的文档数量 pipeline string — 对匹配文档执行的 Ingest Pipeline search_timeout time — 搜索阶段超时 q string — 简单查询字符串（替代请求体中的 query） df string — q 参数的默认字段 default_operator string OR q 参数的默认运算符 analyzer string — q 参数使用的分析器 analyze_wildcard boolean false 是否分析通配符 lenient boolean — 宽松解析模式 routing string — 路由值 preference string — 查询偏好 terminate_after int 0 每分片最多处理的文档数（0 = 不限制） expand_wildcards string open 通配符展开：open、closed、hidden、all、none ignore_unavailable boolean false 忽略不存在的索引 allow_no_indices boolean true 允许通配符不匹配任何索引 请求体 # { "query": { .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/chinese-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/chinese-analyzer/Chinese 分析器 # chinese 分析器为中文文本设计，提供基础的中文处理能力。对于更复杂的中文分词需求，建议使用专门的中文分词插件如 IK、HanLP 或 Jieba。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： cjk 分词器：将 CJK（中日韩）字符分解为二元组（bigrams） lowercase 分词过滤器：转换为小写 示例 # POST _analyze { "analyzer": "chinese", "text": "快速的棕色狐狸跳过懒惰的狗" } 分析结果 # [ "快", "速", "的", "棕", "色", "狐", "狸", "跳", "过", "懒", "惰", "的", "狗" ] 推荐用法 # 对于生产环境的中文处理，建议使用专门的中文分词插件： IK 分词器 - 中文分词的常用选择 HanLP 分词器 - 功能完整的中文 NLP 分词 Jieba 分词器 - 基于 Python Jieba 的分词 详见相关插件文档。https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/curl/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/curl/使用 Curl 访问 Easysearch # Easysearch 提供 RESTful API，任何能发送 HTTP 请求的工具都可以与它交互。curl 是最常用的命令行工具，非常适合快速验证和学习。 请求格式 # 一个典型的 Easysearch 请求由以下部分组成： curl -X<VERB> '<PROTOCOL>://<HOST>:<PORT>/<PATH>?<QUERY_STRING>' \ -H 'Content-Type: application/json' \ -d '<BODY>' 部件 说明 VERB HTTP 方法：GET、POST、PUT、DELETE、HEAD PROTOCOL http 或 https（Easysearch 默认启用 HTTPS） HOST 节点主机名，本地为 localhost PORT HTTP 服务端口，默认 9200 PATH API 路径，例如 _search、_count、my-index/_doc/1 QUERY_STRING 可选参数，例如 ?https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/console/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/console/使用 INFINI Console 管理 # 如果你需要多集群统一管理、告警通知、数据探索等企业级功能，推荐使用 INFINI Console。它是 INFINI Labs 提供的独立可视化管理平台，支持同时管理 Easysearch 和 Elasticsearch 集群。 💡 如果你只需要管理单个集群并进行日常开发调试，Easysearch 还提供了 内置 Web UI，零部署，开箱即用。 安装 Console # 方式一：一键启动（推荐） # 同时启动 Console + Easysearch，最快体验完整管理功能： curl -fsSL http://get.infini.cloud/start-local | sh -s 支持更多参数： # 启动 3 个 Easysearch 节点，自定义密码，开启 Agent 指标采集 curl -fsSL http://get.infini.cloud/start-local | sh -s -- up \ --nodes 3 --password "MyDevPass123." --metrics-agent 方式二：单独安装 # # Linux 一键安装 curl -sSL http://get.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/fulltext/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/fulltext/全文搜索 # Easysearch SQL 提供了一组相关性函数，可以在 WHERE 子句中使用，将 SQL 查询与 Easysearch 强大的全文搜索能力相结合。这些函数在底层会翻译为对应的 Easysearch DSL 查询。 函数一览 # 函数 等价函数 底层 DSL 用途 MATCH_QUERY MATCHQUERY match 单字段全文匹配 MULTI_MATCH MULTIMATCH、MULTIMATCHQUERY multi_match 多字段全文匹配 MATCH_PHRASE MATCHPHRASE、MATCHPHRASEQUERY match_phrase 短语匹配 QUERY — query_string Lucene 查询字符串 SCORE SCOREQUERY、SCORE_QUERY constant_score 相关性评分包装 MATCH_QUERY # 在单个文本字段上执行全文匹配查询。 语法 # MATCH_QUERY(field, text) -- 或 field = MATCH_QUERY(text) 参数 说明 field 要搜索的字段名（必须是 text 类型） text 搜索文本 示例 # POST /_sql { "query": "SELECT account_number, address FROM accounts WHERE MATCH_QUERY(address, 'Holmes')" } 等价 DSL：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/close-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/close-index/关闭索引 # 对运行中的索引执行关闭操作，使其停止读写服务，仅保留数据存储。 操作步骤 # 进入索引列表：在「索引」页面，找到需要关闭的目标索引（如 testing_index_creation）。 打开操作菜单：点击该索引行「操作」列的更多按钮（...），在弹出的下拉菜单中选择「关闭索引」。 确认关闭操作：在弹出的确认提示框中，点击「确定」，系统将执行索引关闭操作。 查看操作结果：操作完成后，索引列表中该索引的「索引状态」将更新为Close，代表索引已成功关闭。 补充说明 # 索引关闭后，将停止对外提供读写服务，仅保留数据存储，可用于索引运维、数据归档等场景。 关闭的索引仍会占用磁盘空间，但不再消耗内存和 CPU 等计算资源。 如有应用正在读写该索引，关闭后相关请求将返回错误，请提前通知相关业务方。 如需重新使用该索引，可通过「打开索引」操作恢复。https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/distributed/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/distributed/分布式基础 # Easysearch 的主旨是随时可用和按需扩容。真正的扩容能力来自于水平扩容——为集群添加更多的节点，并且将负载压力和稳定性分散到这些节点中。Easysearch 天生就是分布式的，它知道如何通过管理多节点来提高扩容性和可用性。 本页通过从 1 节点到 3 节点的演进，直观展示分片分配、故障转移和水平扩容的过程。 空集群 # 启动一个单独的节点，里面不包含任何数据和索引——这就是一个空集群。 此时这个节点既是唯一的数据节点，也是主节点。作为用户，我们可以将请求发送到集群中的任何节点（包括主节点），每个节点都知道任意文档所处的位置，并能将请求直接转发到正确的节点。 集群健康 # Easysearch 的集群监控信息中最重要的一项是集群健康，status 字段展示为 green、yellow 或 red： GET /_cluster/health 颜色 含义 green 所有的主分片和副本分片都正常运行 yellow 所有的主分片都正常运行，但不是所有的副本分片都正常运行 red 有主分片没能正常运行 添加索引 # 索引是指向一个或者多个物理分片的逻辑命名空间。一个分片是一个底层的工作单元，它本身就是一个完整的搜索引擎（一个 Lucene 实例）。 Easysearch 利用分片将数据分发到集群内各处。当集群规模扩大或缩小时，Easysearch 会自动在各节点间迁移分片，使数据均匀分布。 让我们创建一个名为 blogs 的索引，分配 3 个主分片和 1 份副本： PUT /blogs { "settings" : { "number_of_shards" : 3, "number_of_replicas" : 1 } } 此时只有一个节点，3 个主分片都分配在该节点上。集群健康状态为 yellow——主分片正常，但 3 个副本分片无处分配（在同一节点上保存原始数据和副本没有意义）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/paginate-and-scroll/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/paginate-and-scroll/分页与滚动 # Easysearch 提供多种分页机制，适用于不同场景： 方式 适用场景 一致性 深度限制 from/size 小规模翻页（前几页） 无（实时数据） 默认 10,000 search_after + sort 深分页、增量翻页 无（实时数据） 无 search_after + PIT 深分页、一致性翻页 快照一致 无 Scroll 批量导出、离线处理 快照一致 无 相关指南 # 分页与排序 from/size 基础分页 # 最基础的分页依赖 from 和 size 两个参数： 参数 说明 默认值 from 起始偏移（0 基） 0 size 本页返回条数 10 GET shakespeare/_search { "from": 0, "size": 10, "query": { "match": { "play_name": "Hamlet" } } } 计算页码对应的 from：from = size × (page_number - 1)https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/create-dev-cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/create-dev-cluster/创建开发模式集群 # 操作步骤 # 进入服务管理页面：登录 Agent UI 后，在服务管理页面，点击「安装 Easysearch」区域的「创建集群」按钮。 完成系统环境检测：进入安装向导，系统会自动检测操作系统、内存、JDK 等安装前置条件，确认所有项均通过后，点击「开始安装」。 选择开发模式集群：在安装模式选择页，点击「开发模式 | 新集群」卡片，进入开发模式配置流程。 配置基础环境信息： 选择 Easysearch 版本、JDK 版本。 填写网络配置：监听地址（默认 127.0.0.1）、HTTP 端口（默认 9200），点击「检测端口」确保端口可用。 设置管理员密码，可使用「生成密码并复制」快速生成强密码。 配置 JVM 内存，建议根据系统可用内存分配。 完成高级配置项： 配置集群名称、节点名称，可按需开启自定义数据目录、日志目录。 配置安全模式，可选择自动生成 CA 和节点证书或上传现有证书。 - 勾选需要安装的插件（如 ai、analysis-ik 等）。 启动集群创建流程：配置完成后，点击页面底部的「开始安装」，系统将自动执行下载、解压、配置证书、启动服务等步骤。 确认集群创建结果：等待安装进度完成，页面提示「集群创建成功」后，可查看集群状态、节点信息，点击「打开 Easysearch」进入集群管理界面。 注意事项 # 开发模式仅监听本地地址，外部无法访问，仅适用于本地开发测试，不支持集群扩展。 开发模式下数据存储在本地目录，删除集群会清空所有数据，不建议用于生产环境。 端口配置需确保未被其他进程占用，HTTP 端口默认 9200，如已被占用需手动修改。 管理员密码需妥善保存，若使用自动生成密码，需提前复制保存，避免后续无法登录集群。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/aliases/delete-alias/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/aliases/delete-alias/删除别名 # 删除别名不会影响底层索引的数据。 操作步骤 # 进入别名管理页：在左侧导航栏点击「别名」，进入别名列表页面。 打开操作菜单：找到需要删除的目标别名（如 test_alias），点击该行「操作」列的更多按钮（...），在弹出菜单中选择「删除」。 确认删除操作：在弹出的确认提示框中，点击「确定」，系统将执行别名删除。 查看操作结果：操作完成后，该别名将从列表中移除，代表删除成功。 注意事项 # 删除别名不会删除底层索引及其数据，仅移除别名与索引之间的映射关系。 如果有应用通过该别名进行读写操作，删除后相关请求将返回错误，请提前通知业务方切换到新的别名或直接使用索引名称。 如果该别名关联了多个索引，删除后所有关联索引的别名映射均会被解除。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/security/delete-user/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/security/delete-user/删除用户 # 操作步骤 # 进入安全管理页面：在左侧导航栏点击「安全管理」，默认进入「用户」标签页，查看现有用户列表。 打开操作菜单：找到需要删除的目标用户（如 test_user），点击该行「操作」列的更多按钮（...），在弹出菜单中选择「删除」。 确认删除操作：在弹出的确认提示框中，点击「确定」，系统将执行用户删除。 查看操作结果：操作完成后，该用户将从列表中移除，代表删除成功。 注意事项 # 请勿删除管理员账户（如 admin），否则可能导致无法登录管理界面或无法执行管理操作。 删除用户后，该用户的所有活跃会话将立即失效。 用户删除操作不可撤销，如需恢复请重新创建用户并分配相同角色。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/lifecycle/delete-policy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/lifecycle/delete-policy/删除策略 # 当生命周期策略不再需要时，可以将其删除。 操作步骤 # 进入生命周期策略页面：登录 Easysearch UI，在左侧导航栏点击「生命周期」，进入「策略」标签页。 触发删除操作：在策略列表中，找到目标策略，点击「操作」列的更多按钮，在下拉菜单中选择「删除」选项。 确认删除操作：系统会自动执行删除，等待操作完成。 验证删除结果：删除完成后，目标策略将从策略列表中移除。 注意事项 # 删除策略前，请确保已解除该策略与所有索引模式的关联，否则索引将失去生命周期管理规则。 删除操作不可恢复，删除前请确认该策略已不再被业务使用。 策略删除后，已关联的索引将停止执行生命周期阶段操作，数据不会被自动删除或迁移。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/templates/delete-legacy-template/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/templates/delete-legacy-template/删除索引模板（旧版） # 当旧版索引模板不再需要时，可以通过 UI 进行删除操作。 操作步骤 # 进入模板页面：在左侧导航栏点击「模板」，切换至「索引模板（旧版）」标签页。 打开操作菜单：找到需要删除的模板，点击「操作」列的更多按钮，展开操作菜单。 选择删除操作：在菜单中点击「删除」选项，弹出删除确认提示框。 确认删除：在提示框中点击「确定」按钮，完成模板删除。 验证删除结果：删除成功后，该模板将从列表中消失，代表删除操作完成。 注意事项 # 删除模板不会影响已通过该模板创建的索引，已有索引的设置和映射保持不变。 删除操作不可撤销，如需恢复请重新创建模板。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/relevance/boosting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/relevance/boosting/加权与调参 # 当默认 _score 排序不符合业务预期时，就需要通过"加权"来让某些字段或条件更重要。本页给出常见手段和使用建议。 查询时权重提升 # 查询时的权重提升是可以用来影响相关度的主要工具，任意类型的查询都能接受 boost 参数。将 boost 设置为 2，并不代表最终的评分 _score 是原值的两倍；实际的权重值会经过归一化和一些其他内部优化过程。尽管如此，它确实想要表明一个提升值为 2 的句子的重要性是提升值为 1 语句的两倍。 在实际应用中，无法通过简单的公式得出某个特定查询语句的"正确"权重提升值，只能通过不断尝试获得。需要记住的是 boost 只是影响相关度评分的其中一个因子；它还需要与其他因子相互竞争。在前例中，title 字段相对 content 字段可能已经有一个"缺省的"权重提升值，这因为在字段长度归一值中，标题往往比相关内容要短，所以不要想当然的去盲目提升一些字段的权重。选择权重，检查结果，如此反复。 字段级别 Boost：标题 > 标签 > 正文 # 最常见的需求： 标题匹配比正文匹配更重要 关键字段（品牌、类目）权重大于辅助字段 常见做法是在 multi_match 中给字段加权，例如： { "query": { "multi_match": { "query": "搜索 引擎", "fields": [ "title^3", "tags^2", "content" ] } } } 或者在 bool 查询中： GET /_search { "query": { "bool": { "should": [ { "match": { "title": { "query": "quick brown fox", "boost": 2 } } }, { "match": { "content": "quick brown fox" } } ] } } } title 查询语句的重要性是 content 查询的 2 倍，因为它的权重提升值为 2。没有设置 boost 的查询语句的值为 1。https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/denormalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/denormalization/反范式与权衡 # 在关系型数据库中，规范化（范式）是黄金法则。但在 Easysearch 这样的搜索系统中，反范式（denormalization）往往是更好的选择。本页解释为什么，以及如何在一致性和性能之间做权衡。 搜索系统中的规范化与冗余 # 与传统数据库"强规范化"不同，面向搜索的文档往往会有适度冗余： 预先把常用的派生信息存进文档（如标准化后的地区名、拼音、缩写） 把查询高频的外键信息"带过来"，减少查询时的 join 需求 但冗余也要有边界： 冗余会放大存储与更新成本 冗余字段过多，会让 mapping 变得臃肿、难以维护 经验做法： 只冗余"确实会被高频查询/排序/聚合"的字段 对变动频率极高的冗余信息，要慎重评估更新成本 为什么需要反范式？ # 使用 Easysearch 得到最好搜索性能的方法是有目的地在索引时进行反范式。对每个文档保持一定数量的冗余副本可以在需要访问时避免进行关联操作。 示例：博客文章与用户 # 如果我们希望通过用户姓名找到他写的博客文章，可以在博客文档中包含这个用户的姓名： PUT /my_index/_doc/1 { "name": "John Smith", "email": "john@smith.com", "dob": "1970/10/24" } PUT /my_index/_doc/2 { "title": "Relationships", "body": "It's complicated...", "user": { "id": 1, "name": "John Smith" } } 通过单次查询就能找到用户 John 的博客文章： GET /my_index/_search { "query": { "bool": { "must": [ { "match": { "title": "relationships" }}, { "match": { "user.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/vector-search/vector-fields/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/vector-search/vector-fields/向量字段建模 # 本页聚焦向量字段的设计策略——在已经理解字段类型和映射参数的基础上，如何为实际业务做出合理的字段规划。 关于两种向量字段类型（knn_dense_float_vector / knn_sparse_bool_vector）的映射参数、数据格式、各索引模型的详细说明，请参阅 向量字段类型参考。 文本字段 + 向量字段 # 一个典型的混合搜索文档同时包含文本字段和向量字段： PUT /hybrid-index { "mappings": { "properties": { "title": { "type": "text" }, "content": { "type": "text" }, "embedding": { "type": "knn_dense_float_vector", "knn": { "dims": 768, "model": "lsh", "similarity": "cosine", "L": 99, "k": 1 } } } } } 这样同一份文档既支持 BM25 全文搜索，也支持 kNN 向量搜索，为 Hybrid 检索打基础。 多向量字段 # 为同一文档存储多个向量表示，例如标题和正文各一个 Embedding： PUT /multi-vec-index { "mappings": { "properties": { "title": { "type": "text" }, "content": { "type": "text" }, "title_vec": { "type": "knn_dense_float_vector", "knn": { "dims": 768, "model": "lsh", "similarity": "cosine", "L": 99, "k": 1 } }, "content_vec": { "type": "knn_dense_float_vector", "knn": { "dims": 768, "model": "lsh", "similarity": "cosine", "L": 99, "k": 1 } } } } } 注意：每个向量字段都消耗存储和索引资源。只为线上查询真正需要的维度建向量字段，避免无节制堆积。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/vector-workflow/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/vector-workflow/向量工作流与 Hybrid 检索 # 本文完整介绍在 Easysearch 中使用向量检索的全流程——从索引设计、向量写入到混合检索策略。 相关指南（先读这些） # Embedding 服务接入 向量检索功能 Hybrid Search API 索引设计 # 创建向量索引 # 从 1.11.1 版本开始，index.knn 参数已弃用，创建 knn 索引时无需配置。 PUT knowledge_base { "settings": { "number_of_shards": 2, "number_of_replicas": 1 }, "mappings": { "properties": { "title": { "type": "text", "analyzer": "ik_max_word", "search_analyzer": "ik_smart" }, "content": { "type": "text", "analyzer": "ik_max_word" }, "content_vector": { "type": "knn_dense_float_vector", "knn": { "dims": 768, "model": "lsh", "similarity": "cosine", "L": 99, "k": 1 } }, "category": { "type": "keyword" }, "created_at": { "type": "date" } } } } 向量字段参数 # 参数 说明 dims 向量维度，必须与 Embedding 模型输出维度一致 model 索引模型：lsh（近似搜索）或 exact（精确搜索） similarity 相似度度量：cosine、l1、l2 L LSH 模型参数：哈希表数量，增大可提高召回率 k LSH 模型参数：哈希函数数量，增大可提高精度 向量写入 # 方式一：Ingest Pipeline 自动向量化 # 配置 Ingest Pipeline 在写入时自动调用 Embedding 服务：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/copy-curl-command/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/copy-curl-command/复制 curl 命令 # 操作步骤 # 进入开发工具页面：在左侧导航栏点击「开发工具」，进入开发工具编辑页。 编写请求语句：在左侧编辑区输入符合规范的请求语句。 生成并复制 curl 命令：点击编辑区右上角的「curl 命令」按钮，系统将自动生成对应 curl 命令并复制到剪贴板。 查看复制结果： curl -XGET "http://xxx.xxx.xxx/_search" -H 'Content-Type: application/json' -d' { "query": { "match_all": {} } }' 补充说明 # 复制的 curl 命令中会自动包含请求方法、地址、请求头和请求体，可直接在终端中执行。 如果集群启用了 HTTPS 或认证，请在粘贴后根据实际情况补充 -k（跳过证书校验）或 -u user:password（认证信息）等参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/security/multi-tenant-access-control/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/security/multi-tenant-access-control/多租户与权限模型实践 # 在 SaaS 平台或企业多部门共享 Easysearch 集群的场景下，需要一套完善的多租户隔离与权限控制方案。Easysearch 提供了索引级、文档级和字段级三层安全能力来支撑这一需求。 相关指南 # 用户与角色管理 接入企业认证体系 多租户隔离模式 # 模式一：按索引隔离 # 每个租户使用独立的索引（或索引前缀），通过角色控制访问范围。 tenant_a_orders tenant_a_products tenant_b_orders tenant_b_products 角色定义示例： PUT _security/role/tenant_a_role { "cluster_permissions": ["cluster_composite_ops_ro"], "index_permissions": [ { "index_patterns": ["tenant_a_*"], "allowed_actions": ["crud", "create_index"] } ] } 优点 缺点 隔离彻底，互不影响 索引数量随租户增长 性能可独立调优 跨租户查询需要额外聚合 易于理解和调试 集群管理复杂度较高 模式二：按字段标记隔离 # 所有租户共享索引，通过 tenant_id 字段区分，利用文档级安全（DLS）实现隔离。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/scripting/stored-scripts/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/scripting/stored-scripts/存储脚本 # 存储脚本（Stored Scripts）允许您将常用的脚本预先保存在集群中，之后通过 ID 引用执行。使用存储脚本可以减少请求体大小、避免重复编译、并集中管理脚本逻辑。 创建存储脚本 # 使用 POST _scripts/<script_id> 创建或更新存储脚本： POST _scripts/calculate_discount { "script": { "lang": "painless", "source": "doc['price'].value * (1 - params.discount_rate)" } } 指定脚本上下文 # 可以在创建时指定脚本的使用上下文，Easysearch 会在存储时进行上下文相关的语法校验： POST _scripts/my_score_script/score { "script": { "lang": "painless", "source": "_score * doc['boost'].value" } } 上下文名称放在 URL 路径的第二段（/score），可选值包括：score、filter、update、ingest 等。 获取存储脚本 # GET _scripts/calculate_discount 响应： { "_id": "calculate_discount", "found": true, "script": { "lang": "painless", "source": "doc['price'].value * (1 - params.https://docs.infinilabs.com/easysearch/v2.2.0/docs/api-reference/units/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/api-reference/units/支持的单位清单 # Easysearch 在 REST API 中支持以下几类单位，适用于查询、索引设置和集群配置。 时间单位 # 缩写 含义 示例 d 天 5d h 小时 12h m 分钟 30m s 秒 60s ms 毫秒 500ms micros 微秒 100micros nanos 纳秒 1000nanos 常见使用场景：timeout、scroll、interval、ILM 策略中的 min_age 等。 字节大小单位 # 缩写 含义 换算 b 字节 1 B kb Kibibyte 1024 B mb Mebibyte 1024 KB gb Gibibyte 1024 MB tb Tebibyte 1024 GB pb Pebibyte 1024 TB 注意：虽然缩写看起来是十进制（kb），但实际按二进制计算（1 kb = 1024 bytes）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/create-follower-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/create-follower-index/新增跟随者索引 # 通过新增跟随者索引，可以将远程集群的索引数据复制到本地集群。 操作步骤 # 进入主从复制页面：登录 Easysearch UI，在左侧导航栏点击「主从复制」，默认进入「跟随者索引」标签页。 打开新增跟随者索引弹窗：点击页面右上角的「+ 新增」按钮，弹出配置窗口。 配置跟随者索引信息： 选择远端集群：从下拉框中选取已配置的远程集群（如示例中的 leader）。 填写主导索引：输入远端集群中需同步的主索引名称（如 cloud_resource_usage_billing）。 填写跟随者索引：自定义本地集群中用于接收同步数据的索引名称（可与主导索引同名，如 cloud_resource_usage_billing）。 完成创建：确认所有必填项配置无误后，点击「确定」按钮。 查看新增结果：配置成功后，新的跟随者索引将展示在列表中，状态变为 RUNNING，表示同步任务正常运行。 注意事项 # 新增前需确保远端集群已在「远程集群」中完成配置，且该集群的主导索引已存在。 主导索引名称需与远端集群实际索引名完全一致，否则会导致同步失败。 同步过程中请勿删除远端集群配置，否则跟随者索引将中断同步。 状态显示 SYNCING 表示正在同步，RUNNING 表示同步任务正常，可查看数据一致性。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/add-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/add-filter/新增过滤条件 # 通过添加过滤条件，可以精确筛选数据探索中展示的数据。 操作步骤 # 打开过滤条件配置窗口：在数据探索页面的搜索栏左侧，点击「+」图标，弹出「新增过滤条件」配置窗口。 配置可视化过滤规则： 在「字段」下拉框中，选择需要过滤的目标字段（示例中为 _id）。 在「运算」下拉框中，选择匹配逻辑（如等于、大于、包含等，示例中为「等于」）。 在「值」输入框中，填写过滤条件的目标值（示例中为 LJAUJ0BlYzaDM3kYDbw）。 （可选）使用 Query DSL 自定义过滤：点击窗口右上角的「编辑 Query DSL」，可切换至代码编辑模式，直接编写 Elasticsearch 查询 DSL 语句，实现复杂过滤逻辑。 保存过滤条件：配置完成后，点击「保存」按钮，系统将自动应用过滤条件。 查看过滤结果：过滤条件生效后，将在搜索栏下方展示已生效的过滤标签，右侧数据列表将仅显示符合条件的文档记录。 注意事项 # 使用「编辑 Query DSL」模式时，需确保查询语句符合 Elasticsearch Query DSL 语法规范，语法错误将导致过滤失败。 不同字段类型支持的运算符不同，例如 text 类型字段不支持精确匹配（等于），建议使用「包含」运算符或切换到对应的 keyword 子字段进行过滤。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/view-backup-details/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/view-backup-details/查看备份详情 # 可以查看已创建备份的详细信息，包括备份状态、包含的索引等。 操作步骤 # 进入备份管理页面：登录 Easysearch UI，在左侧导航栏点击「备份管理」，切换至「备份」标签页。 打开备份详情：在备份列表中，找到目标快照（如 daily-policy-2026-04-21-17:00-i76tolf3），点击「操作」列的更多按钮，选择「详情」选项。 查看备份信息：在弹出的详情窗口中，可查看快照的基础信息（版本、UUID、存储库、状态、开始/结束时间、耗时），以及备份索引列表、失败索引列表等详细内容。 关闭详情窗口：查看完成后，点击窗口右上角的关闭按钮即可返回备份列表。 注意事项 # 详情窗口会完整展示快照的所有备份索引，可通过此列表确认是否有重要数据遗漏备份。 若存在失败索引，可根据列表排查备份失败的原因，重新进行备份操作。 备份状态为 SUCCESS 时，代表所有索引均备份成功，数据可正常恢复。https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/query-tuning/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/query-tuning/查询调优与慢查询排查 # 这篇不是“参数大全”，而是一个从症状出发的调优路线：给你一套在遇到“搜索慢/结果怪”时可以照着走的步骤，并总结几类典型反模式。 1. 先确认：是“慢”，还是“查不准”？ # 调优之前先判断你面对的是哪类问题： 性能问题：延迟高、QPS 上不去、偶发长尾 相关性问题：该上的内容没上来、不该上的跑前面 资源问题：CPU/内存/磁盘/网络被拖垮 很多时候，这三类是纠缠在一起的，但你要先选一个“主目标”：是要先跑得稳，还是先查得准。 2. 性能调优：从慢查询样本开始 # 2.1 收集慢查询样本 # 打开搜索 slowlog（按索引粒度）： 记录超过某个阈值的查询（P95/P99 级别） 从 slowlog 和客户端日志里挑出： 最常出现的慢查询模式 最耗资源的异常查询（比如 fan-out 到海量分片） 2.2 用 profile 看“时间花在哪” # 对代表性查询加上一层 profile: true，观察： 是哪一部分耗时最长： filter 还是 query？ 排序/聚合 是否拖慢了整体？ 是否在某些字段上做了昂贵操作： 对高基数字段做排序/聚合 对海量分片做全量 scan 2.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/simple-pattern-split/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/simple-pattern-split/Simple Pattern Split 分词器 # simple_pattern_split 分词器使用正则表达式将文本分割成词元。该正则表达式定义了用于确定文本分割位置的模式。文本中任何匹配该模式的部分都会被用作分隔符，分隔符之间的文本则成为一个词元。当你想定义分隔符，并根据某个模式对文本的其余部分进行分词时，可以使用此分词器。 该分词器仅将输入文本中匹配到的部分（基于正则表达式）用作分隔符或边界，以将文本分割成词条。匹配到的部分不会包含在生成的词元中。例如，如果将分词器配置为在点号（.）处分割文本，输入文本为 one.two.three，那么生成的词元就是 one、two 和 three。点号本身不会包含在生成的词条中。 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个使用简单分割匹配词元生成器的分词器。该分词器被配置为在连字符（-）处分割文本： PUT /my_index { "settings": { "analysis": { "tokenizer": { "my_pattern_split_tokenizer": { "type": "simple_pattern_split", "pattern": "-" } }, "analyzer": { "my_pattern_split_analyzer": { "type": "custom", "tokenizer": "my_pattern_split_tokenizer" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_pattern_split_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/plugins/architecture-and-types/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/plugins/architecture-and-types/结构与类型 # 本页聚焦“结构与选型参考”。如果你要先跑通一个可安装的最小插件，请先看： 插件开发入门。 项目结构 # my-plugin/ ├── build.gradle # 构建配置 ├── settings.gradle # 项目名称 └── src/ ├── main/java/com/example/myplugin/ │ ├── MyPlugin.java # 插件入口 │ └── analysis/ │ └── MyTokenFilterFactory.java └── test/java/com/example/myplugin/ └── MyPluginTests.java 关键文件 # plugin-descriptor.properties（构建生成） # 该文件由 Gradle 插件在构建时生成，通常不需要在插件项目里手写；加载时仍会对字段做校验。 name=my-plugin description=My Easysearch Plugin version=0.1.0 easysearch.version=2.1.2 java.version=11 classname=com.example.myplugin.MyPlugin 字段 说明 name 插件唯一标识，用于安装和卸载命令（来源于 esplugin.name） classname 插件入口类全限定名，必须与代码一致 easysearch.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/structured-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/structured-search/结构化搜索 # 结构化搜索针对的是“精确可判定”的字段：ID、枚举、时间、数值、状态位等。本页重点讲如何用好 term/terms/range/exists 这几类基础查询，并配合 filter 上下文使用。 适用字段与“不适用”的情况 # 适合用结构化查询的典型字段： 关键词/编码：订单号、用户 ID、设备 ID、状态码 数值：价格、年龄、计数、评分 时间：创建时间、更新时间、业务时间 标志位/枚举：is_deleted、status、type 等 不适合用结构化查询的字段： 需要做全文检索的长文本（标题、描述、评论等） → 应使用 match/match_phrase 等全文查询，详见“全文检索”章节。 term：精确匹配 # term 查询不会做分词，也不会自动大小写转换，适合： keyword 字段 数值字段 布尔/枚举字段 典型用法（以伪 JSON 示意）： { "query": { "term": { "status": "active" } } } 建议： 对 text 字段做 term 查询通常是错误的（除非你非常明确知道底层分析行为） 业务 ID、编码类字段建议使用 keyword 类型并用 term 查询 terms：在一组值中匹配 # terms 用于“IN 列表”场景：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/normalizers/custom/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/normalizers/custom/自定义规范化器 # 通过组合字符过滤器和词元过滤器，可以创建满足特定需求的自定义规范化器（normalizer）。 基本结构 # PUT my-index { "settings": { "analysis": { "normalizer": { "<normalizer_name>": { "type": "custom", "char_filter": [], "filter": [] } } } } } 参数 # 参数 类型 必选 说明 type string 是 固定为 custom char_filter array 否 字符过滤器列表，在词元过滤器之前执行 filter array 否 词元过滤器列表 示例 # 大小写 + ASCII 折叠 # 最常用的组合——同时忽略大小写和变音符号：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/stemmer-override/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/stemmer-override/Stemmer Override 分词过滤器 # stemmer_override 分词过滤器允许你定义自定义的词干提取规则，这些规则可以覆盖像波特（Porter）或雪球（Snowball）等默认词干提取器的行为。当你希望对某些特定的单词应用特殊的词干提取方式，而这些单词可能无法被标准的词干提取算法正确处理时，这个过滤器就会非常有用。 相关指南（先读这些） # 文本分析：词干提取 文本分析：规范化 参数说明 # 词干覆盖分词过滤器必须使用以下参数中的一个进行配置。 参数 数据类型 描述 rules 字符串 直接在设置中定义覆盖规则。 rules_path 字符串 指定包含自定义规则（映射）的文件的路径。该路径可以是绝对路径，也可以是相对于配置目录的相对路径。 参考样例 # 以下示例请求创建了一个名为 my-index 的新索引，并配置了一个带有词干覆盖过滤器的分词器。 PUT /my-index { "settings": { "analysis": { "filter": { "my_stemmer_override_filter": { "type": "stemmer_override", "rules": [ "running, runner => run", "bought => buy", "best => good" ] } }, "analyzer": { "my_custom_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "my_stemmer_override_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/language-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/language-analyzer/Language 分析器 # Easysearch 内置了 34 种语言专用分析器，每种都针对该语言的停用词、词干提取和字符归一化进行了优化。使用时只需将 analyzer 设置为对应的语言名称即可。 支持的语言列表 # 语言 分析器名称 特点 阿拉伯语 arabic 阿拉伯语归一化 + 词干提取 亚美尼亚语 armenian Snowball 词干提取 巴斯克语 basque Snowball 词干提取 孟加拉语 bengali 印度语系归一化 + 词干提取 巴西葡萄牙语 brazilian 巴西葡萄牙语词干提取 保加利亚语 bulgarian 保加利亚语词干提取 加泰罗尼亚语 catalan 省音处理 + Snowball 词干提取 捷克语 czech 捷克语词干提取 丹麦语 danish Snowball 词干提取 荷兰语 dutch 词干覆盖字典 + Snowball 英语 english 所有格处理 + Porter 词干提取 爱沙尼亚语 estonian Snowball 词干提取 芬兰语 finnish Snowball 词干提取 法语 french 省音处理 + 轻量词干提取 加利西亚语 galician 加利西亚语词干提取 德语 german 字符归一化 + 轻量词干提取 希腊语 greek 希腊语专用小写 + 词干提取 印地语 hindi 印度语系归一化 + 词干提取 匈牙利语 hungarian Snowball 词干提取 印度尼西亚语 indonesian 印度尼西亚语词干提取 爱尔兰语 irish 专用小写 + 双重停用词过滤 意大利语 italian 省音处理 + 轻量词干提取 拉脱维亚语 latvian 拉脱维亚语词干提取 立陶宛语 lithuanian Snowball 词干提取 挪威语 norwegian Snowball 词干提取 波斯语 persian 字符过滤 + 阿拉伯语/波斯语归一化 波兰语 polish 波兰语词干提取 葡萄牙语 portuguese 轻量词干提取 罗马尼亚语 romanian 字符归一化 + Snowball 词干提取 俄语 russian Snowball 词干提取 索拉尼语 sorani 索拉尼语归一化 + 词干提取 西班牙语 spanish 轻量词干提取 瑞典语 swedish Snowball 词干提取 泰语 thai Java BreakIterator 泰语分词 土耳其语 turkish 专用小写（İ/I）+ Snowball 使用方式 # 在映射中指定对应语言名称即可：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/path/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/path/路径配置 # 本页介绍 easysearch.yml 中与文件存储路径相关的配置项。这些都是静态设置，修改后需要重启节点生效。 path.data # path.data: /data/easysearch/data 项目 说明 参数 path.data 默认值 $ES_HOME/data 属性 静态 说明 索引数据的存储目录。Easysearch 的所有分片数据（Lucene 段文件、translog）都存储在此目录下。这是磁盘 I/O 最密集的路径 注意事项 # 不要使用默认路径：默认路径在安装目录内（$ES_HOME/data），升级时可能被覆盖。生产环境必须设置独立路径。 目录权限：运行 Easysearch 的用户必须对该目录拥有读写权限。 磁盘选择：建议使用 SSD 存储，可显著提升索引和查询性能。 不要在多个节点之间共享：每个节点的 path.data 必须是独立的目录。 多路径（JBOD） # 支持配置多个数据路径，实现 JBOD（Just a Bunch of Disks）条带化，将分片分散到多块磁盘上： # YAML 列表形式 path.data: - /data1/easysearch - /data2/easysearch - /data3/easysearch 多路径行为说明：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ingest/filebeat-fluentbit/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ingest/filebeat-fluentbit/轻量 Agent 接入：Filebeat / Fluent Bit # Filebeat 和 Fluent Bit 是两款常用的轻量级日志采集 Agent，均可将日志数据直接发送到 Easysearch。 相关指南（先读这些） # Logstash 接入 摄取管道 Agent 对比 # 特性 Filebeat Fluent Bit 语言 Go C 内存占用 ~30-50 MB ~5-10 MB 配置方式 YAML INI / YAML 输出到 ES ✅ 原生支持 ✅ 原生支持（es output） Ingest Pipeline ✅ 支持指定 ✅ 支持指定 多行日志 ✅ multiline 模块 ✅ multiline parser 生态模块 丰富（modules for nginx等） 较少，但灵活的 parser 体系 适用场景 通用日志采集 边缘设备、资源受限环境 Filebeat 配置示例 # 基础配置 # # filebeat.https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/sql/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/sql/通过 SQL 访问 Easysearch # Easysearch 提供 SQL 查询接口，允许你用熟悉的 SQL 语法查询索引中的数据。这对于 BI 分析师、报表开发者和需要快速进行数据探索的场景非常方便。 相关指南（先读这些） # SQL 查询功能 REST Client API 能力概览 # 功能 支持情况 说明 SELECT ✅ 支持列选择、别名 WHERE ✅ 支持 AND/OR/NOT、比较运算、LIKE、IN ORDER BY ✅ 支持多列排序 GROUP BY ✅ 支持分组聚合 聚合函数 ✅ COUNT、SUM、AVG、MIN、MAX 等 LIMIT ✅ 支持分页 HAVING ✅ 聚合后过滤 JOIN ⚠️ 有限支持 子查询 ⚠️ 部分场景支持 DDL (CREATE/DROP) ❌ 不支持，使用 REST API 管理索引 使用方式 # REST API 直接查询 # POST _sql { "query": "SELECT speaker, COUNT(*) as cnt FROM shakespeare GROUP BY speaker ORDER BY cnt DESC LIMIT 5" } 返回表格格式的结果：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/deploy_easysearch/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/deploy_easysearch/部署Easysearch Operator # 这里我们准备部署一个 3 节点的Easysearch 集群，准备 three-nodes-easysearch-cluster.yaml 文件，文件内容如下所示，并对关键字段都进行了注释。 apiVersion: infinilabs.infinilabs.com/v1 kind: SearchCluster # 自定义的资源类型 metadata: name: threenodes # Easysearch 集群的名称 namespace: default # Easysearch 集群所在的命名空间 spec: # 规格 security: # 安全相关 config: adminSecret: # admin证书配置 name: easysearch-admin-certs adminCredentialsSecret: # 账户密码配置 name: threenodes-admin-password tls: # tls 协议配置，包括节点间的transport，以及访问集群的http http: # 访问集群http配置 generate: false # 是否需要集群自动生成证书 secret: # 自定义证书配置 name: easysearch-certs transport: # 集群间访问配置 generate: false perNode: false # 是否给每一个节点配置证书 secret: # 自定义证书配置 name: easysearch-certs nodesDn: ["CN=Easysearch_Node"] adminDn: ["CN=Easysearch_Admin"] general: # 通用配置 snapshotRepositories: # s3 快照配置 - name: s3_repository # 配置的s3快照的名称 type: s3 # 快照类型 settings: # 快照配置 bucket: es-operator-bucket # s3中的桶，需提前建好 access_key: minioadmin # 访问s3密钥 secret_key: minioadmin endpoint: http://192.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/rate-limiting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/rate-limiting/集群设置限速限流 # 操作步骤 # 进入限流限速配置页：在左侧导航栏点击「集群设置」，切换到「限流限速」标签页。 开启限流开关：按需开启「节点限流」或「分片限流」的开关，激活对应配置项。 配置节点限流参数：填写节点写入限流时间间隔、单个节点最大写入请求数、最大写入请求字节数，选择字节单位，并设置超限处理动作（如丢弃）。 配置分片限流参数：填写分片写入限流时间间隔、单个分片最大写入请求数、最大写入请求字节数，选择字节单位，并设置超限处理动作（如丢弃）。 配置写入恢复控制：在「写入设置」区域，填写恢复速率限制数值，选择对应单位（如 MB）。 生效配置：确认所有参数配置无误后，点击「更新」按钮，配置立即生效。 注意事项 # 限流配置主要用于保护集群在高并发写入场景下的稳定性，避免因突发流量导致节点过载或 OOM。 超限处理动作设为「丢弃」时，超出限流阈值的请求将被直接拒绝，客户端会收到错误响应，请确保业务侧具备重试机制。 建议根据集群的实际硬件配置和业务负载逐步调整限流参数，避免设置过於激进导致正常请求被误拦截。 写入恢复速率限制用于控制分片恢复（如节点重启、副本分配）时的网络带宽占用，设置过低可能导致分片恢复时间显著延长。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/fail/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/fail/Fail 处理器 # fail 处理器在索引过程中执行数据转换和丰富化非常有用。fail 处理器的主要用例是在满足某些条件时失败索引操作。 以下是为 fail 处理器提供的语法： "fail": { "if": "ctx.foo == 'bar'", "message": "Custom error message" } 配置参数 # 下表列出了 fail 处理器所需的和可选参数。 参数 是否必填 描述 message 必填 要包含在失败响应中的自定义错误消息。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/danish-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/danish-analyzer/Danish 分析器 # danish 分析器是为丹麦语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤丹麦语停用词 snowball(Danish) 分词过滤器：丹麦语词干提取 示例 # POST _analyze { "analyzer": "danish", "text": "Hundene løber i parken" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _danish_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/armenian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/armenian-analyzer/Armenian 分析器 # armenian 分析器是为亚美尼亚语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤亚美尼亚语停用词 snowball(Armenian) 分词过滤器：亚美尼亚语词干提取 示例 # POST _analyze { "analyzer": "armenian", "text": "Վիdelays հայերենի տեքdelays" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _armenian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/russian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/russian-analyzer/Russian 分析器 # russian 分析器是为俄语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤俄语停用词 snowball(Russian) 分词过滤器：俄语词干提取 示例 # POST _analyze { "analyzer": "russian", "text": "Собаки бегают в парке" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _russian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/bulgarian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/bulgarian-analyzer/Bulgarian 分析器 # bulgarian 分析器是为保加利亚语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤保加利亚语停用词 bulgarian_stem 分词过滤器：保加利亚语词干提取 示例 # POST _analyze { "analyzer": "bulgarian", "text": "Кучетата тичат в парка" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _bulgarian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/stop/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/stop/Stop 分词过滤器 # stop 分词过滤器用于在分词过程中从词元流中去除常见词汇（也称为停用词）。停用词通常是冠词和介词，比如 “a” 或 “for”。这些词在搜索查询中意义不大，并且常常被排除在外，以提高搜索效率和相关性。 默认的英语停用词列表包含以下单词：a、an、and、are、as、at、be、but、by、for、if、in、into、is、it、no、not、of、on、or、such、that、the、their、then、there、these、they、this、to、was、will 以及 with。 相关指南（先读这些） # 停用词 文本分析基础 参数说明 # 停用词分词过滤器可以使用以下参数进行配置： 参数 必需/可选 数据类型 描述 stopwords 可选 字符串 既可以指定自定义的停用词数组，也可以指定一种语言以获取预定义的 Lucene 停用词列表。可指定的语言如下： - _arabic_ - _armenian_ - _basque_ - _bengali_ - _brazilian_（巴西葡萄牙语） - _bulgarian_ - _catalan_ - _cjk_（中文、日语和韩语） - _czech_ - _danish_ - _dutch_ - _english_（默认值） - _estonian_ - _finnish_https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/galician-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/galician-analyzer/Galician 分析器 # galician 分析器是为加利西亚语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤加利西亚语停用词 galician_stem 分词过滤器：加利西亚语词干提取 示例 # POST _analyze { "analyzer": "galician", "text": "Os cans corren no parque" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _galician_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/catalan-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/catalan-analyzer/Catalan 分析器 # catalan 分析器是为加泰罗尼亚语文本特别设计的语言分析器，包含省音处理。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 elision 分词过滤器：移除加泰罗尼亚语省音符号 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤加泰罗尼亚语停用词 snowball(Catalan) 分词过滤器：加泰罗尼亚语词干提取 示例 # POST _analyze { "analyzer": "catalan", "text": "Els gossos corren al parc" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _catalan_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hungarian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hungarian-analyzer/Hungarian 分析器 # hungarian 分析器是为匈牙利语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤匈牙利语停用词 snowball(Hungarian) 分词过滤器：匈牙利语词干提取 示例 # POST _analyze { "analyzer": "hungarian", "text": "A kutyák futnak a parkban" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _hungarian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hindi-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hindi-analyzer/Hindi 分析器 # hindi 分析器是为印地语文本特别设计的语言分析器，包含印度语系归一化处理。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 decimal_digit 分词过滤器：将各种 Unicode 数字转换为 ASCII 数字 indic_normalization 分词过滤器：印度语系字符归一化 hindi_normalization 分词过滤器：印地语字符归一化 stop 分词过滤器：过滤印地语停用词 hindi_stem 分词过滤器：印地语词干提取 示例 # POST _analyze { "analyzer": "hindi", "text": "कुत्ते पार्क में दौड़ रहे हैं" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _hindi_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/indonesian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/indonesian-analyzer/Indonesian 分析器 # indonesian 分析器是为印度尼西亚语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤印度尼西亚语停用词 indonesian_stem 分词过滤器：印度尼西亚语词干提取 示例 # POST _analyze { "analyzer": "indonesian", "text": "Anjing-anjing berlari di taman" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _indonesian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/turkish-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/turkish-analyzer/Turkish 分析器 # turkish 分析器是为土耳其语文本特别设计的语言分析器，使用土耳其语专用的小写转换。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 apostrophe 分词过滤器：移除撇号及其后字符 turkish_lowercase 分词过滤器：土耳其语专用小写转换（正确处理 İ/I） stop 分词过滤器：过滤土耳其语停用词 snowball(Turkish) 分词过滤器：土耳其语词干提取 示例 # POST _analyze { "analyzer": "turkish", "text": "Köpekler parkta koşuyor" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _turkish_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/bengali-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/bengali-analyzer/Bengali 分析器 # bengali 分析器是为孟加拉语文本特别设计的语言分析器，包含印度语系归一化处理。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 decimal_digit 分词过滤器：将各种 Unicode 数字转换为 ASCII 数字 indic_normalization 分词过滤器：印度语系字符归一化 bengali_normalization 分词过滤器：孟加拉语字符归一化 stop 分词过滤器：过滤孟加拉语停用词 bengali_stem 分词过滤器：孟加拉语词干提取 示例 # POST _analyze { "analyzer": "bengali", "text": "বাংলা ভাষার বিশ্লেষণ" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _bengali_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/basque-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/basque-analyzer/Basque 分析器 # basque 分析器是为巴斯克语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤巴斯克语停用词 snowball(Basque) 分词过滤器：巴斯克语词干提取 示例 # POST _analyze { "analyzer": "basque", "text": "Euskara hizkuntza da" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _basque_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/brazilian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/brazilian-analyzer/Brazilian 分析器 # brazilian 分析器是为巴西葡萄牙语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤巴西葡萄牙语停用词 brazilian_stem 分词过滤器：巴西葡萄牙语词干提取 示例 # POST _analyze { "analyzer": "brazilian", "text": "Os cachorros correm no parque" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _brazilian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/greek-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/greek-analyzer/Greek 分析器 # greek 分析器是为希腊语文本特别设计的语言分析器，使用专用的希腊语小写转换。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 greek_lowercase 分词过滤器：希腊语专用小写转换 stop 分词过滤器：过滤希腊语停用词 greek_stem 分词过滤器：希腊语词干提取 示例 # POST _analyze { "analyzer": "greek", "text": "Τα σκυλιά τρέχουν στο πάρκο" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _greek_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/german-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/german-analyzer/German 分析器 # german 分析器是为德语文本特别设计的语言分析器，包含德语归一化和轻量词干提取。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤德语停用词 german_normalization 分词过滤器：德语字符归一化（ä→a, ö→o, ü→u, ß→ss） german_light_stem 分词过滤器：德语轻量词干提取 示例 # POST _analyze { "analyzer": "german", "text": "Die Hunde laufen im Park" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _german_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/italian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/italian-analyzer/Italian 分析器 # italian 分析器是为意大利语文本特别设计的语言分析器，包含省音处理。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 elision 分词过滤器：移除意大利语省音符号 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤意大利语停用词 italian_light_stem 分词过滤器：意大利语轻量词干提取 示例 # POST _analyze { "analyzer": "italian", "text": "I cani corrono nel parco" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _italian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/latvian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/latvian-analyzer/Latvian 分析器 # latvian 分析器是为拉脱维亚语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤拉脱维亚语停用词 latvian_stem 分词过滤器：拉脱维亚语词干提取 示例 # POST _analyze { "analyzer": "latvian", "text": "Suņi skrien parkā" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _latvian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/norwegian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/norwegian-analyzer/Norwegian 分析器 # norwegian 分析器是为挪威语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤挪威语停用词 snowball(Norwegian) 分词过滤器：挪威语词干提取 示例 # POST _analyze { "analyzer": "norwegian", "text": "Hundene løper i parken" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _norwegian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/czech-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/czech-analyzer/Czech 分析器 # czech 分析器是为捷克语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤捷克语停用词 czech_stem 分词过滤器：捷克语词干提取 示例 # POST _analyze { "analyzer": "czech", "text": "Psi běží v parku" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _czech_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/japanese-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/japanese-analyzer/Japanese 分析器 # japanese 分析器是为日语文本设计的基础语言分析器，使用 CJK 二元组分词方式。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： cjk 分词器：将 CJK（中日韩）字符分解为二元组（bigrams） lowercase 分词过滤器：转换为小写 cjk_width 分词过滤器：全角/半角字符归一化 示例 # POST _analyze { "analyzer": "japanese", "text": "東京都の天気は晴れです" } 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/french-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/french-analyzer/French 分析器 # french 分析器是为法语文本特别设计的语言分析器，包含省音处理。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 elision 分词过滤器：移除法语省音符号（l', d', qu' 等） lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤法语停用词 french_light_stem 分词过滤器：法语轻量词干提取 示例 # POST _analyze { "analyzer": "french", "text": "Les chiens courent dans le parc" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _french_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/polish-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/polish-analyzer/Polish 分析器 # polish 分析器是为波兰语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤波兰语停用词 polish_stem 分词过滤器：波兰语词干提取 示例 # POST _analyze { "analyzer": "polish", "text": "Psy biegają w parku" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _polish_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/persian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/persian-analyzer/Persian 分析器 # persian 分析器是为波斯语文本特别设计的语言分析器，包含阿拉伯语归一化和波斯语字符过滤。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： persian_char_filter 字符过滤器：将零宽非连接符替换为空格 standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 decimal_digit 分词过滤器：将各种 Unicode 数字转换为 ASCII 数字 arabic_normalization 分词过滤器：阿拉伯语字符归一化 persian_normalization 分词过滤器：波斯语字符归一化 stop 分词过滤器：过滤波斯语停用词 示例 # POST _analyze { "analyzer": "persian", "text": "سگ‌ها در پارک می‌دوند" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _persian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/thai-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/thai-analyzer/Thai 分析器 # thai 分析器是为泰语文本特别设计的语言分析器，使用 Java 内置的泰语分词算法。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： thai 分词器：使用 Java BreakIterator 进行泰语分词 lowercase 分词过滤器：转换为小写 decimal_digit 分词过滤器：将各种 Unicode 数字转换为 ASCII 数字 stop 分词过滤器：过滤泰语停用词 示例 # POST _analyze { "analyzer": "thai", "text": "สุนัขวิ่งในสวน" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _thai_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/irish-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/irish-analyzer/Irish 分析器 # irish 分析器是为爱尔兰语文本特别设计的语言分析器，使用爱尔兰语专用的小写转换和双重停用词过滤。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 stop(hyphenations) 分词过滤器：移除连字符 elision 分词过滤器：移除爱尔兰语省音符号 irish_lowercase 分词过滤器：爱尔兰语专用小写转换 stop 分词过滤器：过滤爱尔兰语停用词 snowball(Irish) 分词过滤器：爱尔兰语词干提取 示例 # POST _analyze { "analyzer": "irish", "text": "Rithfidh na madraí sa pháirc" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _irish_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/estonian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/estonian-analyzer/Estonian 分析器 # estonian 分析器是为爱沙尼亚语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤爱沙尼亚语停用词 snowball(Estonian) 分词过滤器：爱沙尼亚语词干提取 示例 # POST _analyze { "analyzer": "estonian", "text": "Koerad jooksevad pargis" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _estonian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/swedish-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/swedish-analyzer/Swedish 分析器 # swedish 分析器是为瑞典语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤瑞典语停用词 snowball(Swedish) 分词过滤器：瑞典语词干提取 示例 # POST _analyze { "analyzer": "swedish", "text": "Hundarna springer i parken" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _swedish_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/users-roles/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/users-roles/用户与角色 # 安全模块包括一个内部用户数据库。可以使用此数据库代替外部身份验证系统（如 LDAP 或 Active Directory），或作为外部身份验证系统的补充。 角色是控制对集群访问的核心方式。角色包含集群范围权限、特定于索引的权限、文档和字段级安全性以及租户的任意组合。然后，将用户映射到这些角色，以便用户获得这些权限。 除非您需要创建新的 只读或隐藏用户，我们强烈建议使用 REST API 来创建新的用户、角色和角色映射。.yml 文件更适合初始设置，而不是持续维护。 相关指南（先读这些） # 安全与多租户最佳实践 权限控制总览 创建用户 # user.yml # 参照 本地文件配置。 REST API # 参照 创建用户。 创建角色 # role.yml # 参照 本地文件配置。 REST API # 参照 创建角色。 常见注意事项：如果一个角色需要执行常见的文档写入 REST API，例如 PUT /<index>/_doc/<id>、POST /<index>/_bulk、POST /<index>/_update/<id> 或 DELETE /<index>/_doc/<id>，当前实现下通常不仅要在 indices[*].privileges 中授予 write / index / delete 等索引级权限，还需要在 cluster 中额外授予 cluster_composite_ops。详细说明见 权限列表。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/lithuanian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/lithuanian-analyzer/Lithuanian 分析器 # lithuanian 分析器是为立陶宛语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤立陶宛语停用词 snowball(Lithuanian) 分词过滤器：立陶宛语词干提取 示例 # POST _analyze { "analyzer": "lithuanian", "text": "Šunys bėga parke" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _lithuanian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/sorani-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/sorani-analyzer/Sorani 分析器 # sorani 分析器是为索拉尼库尔德语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 sorani_normalization 分词过滤器：索拉尼语字符归一化 lowercase 分词过滤器：转换为小写 decimal_digit 分词过滤器：将各种 Unicode 数字转换为 ASCII 数字 stop 分词过滤器：过滤索拉尼语停用词 sorani_stem 分词过滤器：索拉尼语词干提取 示例 # POST _analyze { "analyzer": "sorani", "text": "سەگەکان لە پارکەکەدا ڕادەکەن" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _sorani_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/romanian-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/romanian-analyzer/Romanian 分析器 # romanian 分析器是为罗马尼亚语文本特别设计的语言分析器，包含罗马尼亚语字符归一化。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤罗马尼亚语停用词 romanian_normalization 分词过滤器：罗马尼亚语字符归一化 snowball(Romanian) 分词过滤器：罗马尼亚语词干提取 示例 # POST _analyze { "analyzer": "romanian", "text": "Câinii aleargă în parc" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _romanian_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/finnish-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/finnish-analyzer/Finnish 分析器 # finnish 分析器是为芬兰语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤芬兰语停用词 snowball(Finnish) 分词过滤器：芬兰语词干提取 示例 # POST _analyze { "analyzer": "finnish", "text": "Koirat juoksevat puistossa" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _finnish_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/english-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/english-analyzer/English 分析器 # english 分析器是为英语文本特别设计的语言分析器，包含了英语特定的处理规则和停用词。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤英语停用词（the, a, an, and 等） porter_stem 分词过滤器：英语词干提取 示例 # POST _analyze { "analyzer": "english", "text": "The quick brown foxes jumping over the lazy dogs" } 分析结果 # 停用词（the, over 等）被移除，词根被提取： [ "quick", "brown", "fox", "jump", "lazi", "dog" ] 相关指南 # 文本分析：词干提取 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/dutch-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/dutch-analyzer/Dutch 分析器 # dutch 分析器是为荷兰语文本特别设计的语言分析器，包含词干覆盖字典。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤荷兰语停用词 stemmer_override 分词过滤器：应用荷兰语词干覆盖字典 snowball(Dutch) 分词过滤器：荷兰语词干提取 示例 # POST _analyze { "analyzer": "dutch", "text": "De honden rennen in het park" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _dutch_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/portuguese-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/portuguese-analyzer/Portuguese 分析器 # portuguese 分析器是为葡萄牙语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤葡萄牙语停用词 portuguese_light_stem 分词过滤器：葡萄牙语轻量词干提取 示例 # POST _analyze { "analyzer": "portuguese", "text": "Os cães correm no parque" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _portuguese_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/spanish-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/spanish-analyzer/Spanish 分析器 # spanish 分析器是为西班牙语文本特别设计的语言分析器。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 stop 分词过滤器：过滤西班牙语停用词 spanish_light_stem 分词过滤器：西班牙语轻量词干提取 示例 # POST _analyze { "analyzer": "spanish", "text": "Los perros corren en el parque" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _spanish_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/path-hierarchy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/path-hierarchy/Path Hierarchy 分词器 # path_hierarchy 分词器可以把文件路径（或类似的层次结构）的文本按照各个层级分解为词元。当处理诸如文件路径、网址或其他有分隔符的层次结构数据时，这个分词器特别有用。 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 参考样例 # 以下示例请求创建一个名为 my_index 的新索引，并配置一个使用路径词元生成器的分词器： PUT /my_index { "settings": { "analysis": { "tokenizer": { "my_path_tokenizer": { "type": "path_hierarchy" } }, "analyzer": { "my_path_analyzer": { "type": "custom", "tokenizer": "my_path_tokenizer" } } } } } 生成的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /my_index/_analyze { "analyzer": "my_path_analyzer", "text": "/users/john/documents/report.txt" } 返回内容包含产生的词元 { "tokens": [ { "token": "/users", "start_offset": 0, "end_offset": 6, "type": "word", "position": 0 }, { "token": "/users/john", "start_offset": 0, "end_offset": 11, "type": "word", "position": 0 }, { "token": "/users/john/documents", "start_offset": 0, "end_offset": 21, "type": "word", "position": 0 }, { "token": "/users/john/documents/report.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/arabic-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/arabic-analyzer/Arabic 分析器 # arabic 分析器是为阿拉伯语文本特别设计的语言分析器，包含了阿拉伯语特有的归一化和词干提取规则。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： standard 分词器：标准的文本分割 lowercase 分词过滤器：转换为小写 decimal_digit 分词过滤器：将各种 Unicode 数字转换为 ASCII 数字 stop 分词过滤器：过滤阿拉伯语停用词 arabic_normalization 分词过滤器：阿拉伯语字符归一化 arabic_stem 分词过滤器：阿拉伯语词干提取 示例 # POST _analyze { "analyzer": "arabic", "text": "الكلاب تركض في الحديقة" } 自定义配置 # 可通过以下参数自定义该分析器： 参数 说明 stopwords 自定义停用词列表，默认 _arabic_ stem_exclusion 不进行词干提取的词语列表 相关指南 # 语言分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/monitoring/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/monitoring/监控 # 本文从"如何判断集群是否健康"出发，给出最小可行的监控指标与告警建议，并提供具体的 API 示例。 监控三层模型 # Easysearch 集群的监控可以分为三个层次： ┌─────────────────────────────────────────────────────────────┐ │ Layer 1: 服务可用性 │ │ • 集群是否整体可用？节点是否存活？ │ ├─────────────────────────────────────────────────────────────┤ │ Layer 2: 资源与性能 │ │ • CPU/内存/磁盘/网络是否有瓶颈？延迟是否异常？ │ ├─────────────────────────────────────────────────────────────┤ │ Layer 3: 业务行为 │ │ • 慢查询、错误率、索引状态是否正常？ │ └─────────────────────────────────────────────────────────────┘ 监控目标： 出问题前能看到"趋势变坏"（而不是只在宕机后才收到告警） 告警有明确的处理指引，而不是一堆噪音 集群健康检查 # 快速健康检查 # GET _cluster/health 响应示例： { "cluster_name": "production", "status": "green", "timed_out": false, "number_of_nodes": 5, "number_of_data_nodes": 3, "active_primary_shards": 50, "active_shards": 100, "relocating_shards": 0, "initializing_shards": 0, "unassigned_shards": 0, "delayed_unassigned_shards": 0, "number_of_pending_tasks": 0, "number_of_in_flight_fetch": 0, "task_max_waiting_in_queue_millis": 0, "active_shards_percent_as_number": 100.https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/distributed-write/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/distributed-write/分布式读取写入过程 # Easysearch 隐藏了分布式系统的大部分底层细节，让你可以专注在业务开发上。但线上出问题时你真正需要的是：这条请求在集群里到底走了哪几步。本页把分布式 CRUD 的关键流程串起来，读完你会更容易理解： 为什么同一条数据总能"找到回家的路"（routing） 为什么写入一定要先到主分片（primary） 为什么副本不吃"补丁"，只吃"整份文档"（复制语义） 为什么 bulk 要用看起来奇怪的 NDJSON（性能与内存） 术语提示：你可以把请求发到集群中的任意节点。接收请求并负责"拆分、转发、汇总"的那个节点，称为协调节点（coordinating node）。为了均衡负载，更好的做法是轮询集群中所有节点发送请求。 路由：文档如何找到分片 # 当索引一个文档时，Easysearch 需要确定它属于哪个主分片。这个过程是确定性的，基于以下公式： shard = hash(routing) % number_of_primary_shards routing 是一个可变值，默认是文档的 _id，也可以设置成一个自定义的值 routing 通过 Murmur3 x86 32-bit 哈希算法（种子为 0）生成一个数字，然后除以主分片数量取余 余数就是文档所在分片的编号（范围 0 到 number_of_primary_shards - 1） 这就解释了为什么主分片数量在索引创建后不能改变：分片数变了，取模结果就变了，所有之前路由的值都会无效，老文档的"地址"全得重算。工程上一般通过新索引 + 重建索引 + 别名切换来实现扩容（见 别名）。 所有的文档 API（get、index、delete、bulk、update、mget）都接受一个 routing 参数。自定义路由常用于"把相关数据放在一起"——例如把同一租户/同一用户的数据路由到同一分片，减少查询时的 fan-out（参见 多租户建模）。 写入流程：新建、索引和删除 # 新建、索引和删除请求都是写操作，必须在主分片上完成之后才能被复制到副本分片。 执行步骤： 客户端向 Node 1（协调节点）发送写入请求 Node 1 使用文档的 _id（或自定义 routing）计算出文档属于分片 0，请求被转发到分片 0 的主分片所在节点（例如 Node 3） Node 3 在主分片上执行请求。成功后，将新版本的完整文档（或删除标记）并行转发到所有副本分片节点 一旦所有副本分片都报告成功，Node 3 向协调节点报告成功，协调节点再向客户端返回成功 在客户端收到成功响应时，文档变更已经在主分片和所有副本分片执行完成。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/synonym/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/synonym/Synonym 分词过滤器 # synonym 分词过滤器允许将多个术语映射到单个术语，或在单词之间创建等价组，从而提高搜索的灵活性。 相关指南（先读这些） # 同义词 文本分析基础 参数说明 # 同义词分词过滤器可以使用以下参数进行配置： 参数 必需/可选 数据类型 描述 synonyms 必须指定 synonyms 或 synonyms_path 字符串 在配置中直接定义的同义词规则列表。 synonyms_path 必须指定 synonyms 或 synonyms_path 字符串 包含同义词规则的文件的路径（可以是绝对路径，也可以是相对于配置目录的相对路径）。 lenient 可选 布尔值 加载规则配置时是否忽略异常。默认值为 false。 format 可选 字符串 指定用于确定 Easysearch 如何定义和解释同义词的格式。有效值为： - solr - wordnet 默认值为 solr。 expand 可选 布尔值 是否扩展等效的同义词规则。默认值为 true。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/alerting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/alerting/监控告警 # 为 Easysearch 集群构建完整的告警体系，及时发现和处理问题，确保集群的稳定运行。 告警体系概览 # Easysearch 的告警体系由以下核心组件组成： ┌──────────────────────────────────────────────────────────────┐ │ 告警生命周期 │ ├──────────────────────────────────────────────────────────────┤ │ │ │ 数据采集 → 指标评估 → 告警触发 → 告警发送 → 告警处理 │ │ │ │ │ │ │ │ │ └───┬───────┴───────────┴─────────┴────────┘ │ │ │ │ │ └─→ INFINI Console 告警管理平台 │ │ │ └──────────────────────────────────────────────────────────────┘ 告警规则体系 # 1. 可用性告警 # 集群的基础可用性监控。 告警规则 触发条件 建议阈值 处理建议 集群不健康 _cluster/health 返回 yellow 或 red 立即告警 检查节点是否掉线，运行 GET _cluster/allocation/explain 诊断未分配分片 节点离线 节点掉线或无响应 立即告警（超 1 分钟） 检查节点进程、网络连通性、磁盘空间 分片未分配 存在未分配的主分片或副本分片 立即告警 检查集群容量、节点约束、路由配置 集群脑裂 多个 master 节点并存 立即告警 紧急处理，可能需要恢复集群 2.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/character-group/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/character-group/Character Group 分词器 # char_group 分词器使用特定字符作为分隔符将文本拆分为词元。它适用于需要简单直接进行分词的场景，为基于分词器的匹配模式提供了一种更简单的替代方案，避免了额外的复杂性。 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 参考样例 # 以下示例请求创建了一个名为my_index的新索引，并配置了一个带有 char_group 字符组词元生成器的分词器。该词元生成器会依据空格、连字符 - 和冒号 : 来分割文本。 PUT /my_index { "settings": { "analysis": { "tokenizer": { "my_char_group_tokenizer": { "type": "char_group", "tokenize_on_chars": [ "whitespace", "-", ":" ] } }, "analyzer": { "my_char_group_analyzer": { "type": "custom", "tokenizer": "my_char_group_tokenizer" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_char_group_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/document-level-security/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/document-level-security/文档级权限 # 文档级权限允许您将角色限制为索引中文档的一部分子集。 相关指南（先读这些） # 权限控制总览 安全与多租户最佳实践 参考设置 # 文档级权限使用 Easysearch 查询 DSL 来定义角色授予对哪些文档的访问权限。 { "bool": { "must": { "match": { "public": "true" } } } } 上面的查询指定了该角色访问的文档里面，其字段 public 必须匹配 true。 指定字段 query 并设置为将上面的查询，并对查询字符串进行转义，最后的角色设置如下： PUT _security/role/public_data { "cluster": [ "*" ], "indices": [{ "names": [ "pub*" ], "query": "{\"term\": { \"public\": true}}", "privileges": [ "read" ] }] } 上面的查询也可以根据需要写的很复杂，但是我们建议保持简单，以最大程度地减少文档级安全功能对集群的性能影响。 参数替换 # 查询过程中可以利用上下文变量，可根据当前用户的属性来强制实施规则替换。例如 ${user.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/foreach/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/foreach/遍历处理器 # foreach 处理器用于遍历输入文档中的值列表并对每个值应用转换。这可以用于处理数组中的所有元素，例如将字符串中的所有元素转换为小写或大写等任务。 以下是为 foreach 处理器提供的语法： { "foreach": { "field": "<field_name>", "processor": { "<processor_type>": { "<processor_config>": "<processor_value>" } } } } 配置参数 # 下表列出了 foreach 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 要遍历的数组字段。 processor 必填 处理器用于对每个字段执行操作。 ignore_missing 可选 如果 true 指定的字段不存在或为 null，则处理器将静默退出，不会修改文档。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/grok/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/grok/Grok 处理器 # grok 处理器用于通过模式匹配解析和结构化非结构化数据。您可以使用 grok 处理器从日志消息、Web 服务器访问日志、应用程序日志和其他遵循一致格式的日志数据中提取字段。 Grok 基础 # grok 处理器使用一组预定义的模式来匹配输入文本的部分。每个模式由一个名称和一个正则表达式组成。例如，模式 %{IP:ip_address} 匹配 IP 地址并将其分配给字段 ip_address 。您可以将多个模式组合起来创建更复杂的表达式。例如，模式 %{IP:client} %{WORD:method} %{URIPATHPARM:request} %{NUMBER:bytes %NUMBER:duration} 匹配来自 Web 服务器访问日志的一行，并提取客户端 IP 地址、HTTP 方法、请求 URI、发送的字节数和请求持续时间。 有关可用预定义模式的列表，请参阅 Grok 模式。 grok 处理器基于 Oniguruma 正则表达式库构建，并支持该库中的所有模式。您可以使用 Grok 调试器工具测试和调试您的 grok 表达式。 请注意，模式不是锚定的。为了性能和可靠性，请在您的模式中包含行首锚点（ ^ ）。 语法 # 以下是为 grok 处理器的基本语法： { "grok": { "field": "your_message", "patterns": ["your_patterns"] } } 配置参数 # 要配置 grok 处理器，您有多种选项，允许您定义模式、匹配特定键和控制处理器的行为。下表列出了 grok 处理器的必选和可选参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/uax-url-email/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/uax-url-email/UAX URL Email 分词器 # 除了常规文本之外，uax_url_email 分词器还专门用于处理网址、电子邮件地址和域名。它基于 Unicode 文本分割算法（ UAX #29），这使得它能够正确地对复杂文本（包括网址和电子邮件地址）进行分词处理。 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个使用 UAX URL 邮件词元生成器的分词器： PUT /my_index { "settings": { "analysis": { "tokenizer": { "uax_url_email_tokenizer": { "type": "uax_url_email" } }, "analyzer": { "my_uax_analyzer": { "type": "custom", "tokenizer": "uax_url_email_tokenizer" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_uax_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/synonym-graph/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/synonym-graph/Synonym Graph 分词过滤器 # synonym_graph 分词过滤器是同义词分词过滤器的更高级版本。它支持多词同义词，并能跨多个词元处理同义词，这使得它非常适合处理短语或者那些词元之间关系很重要的场景。 相关指南（先读这些） # 文本分析：同义词 文本分析：规范化 参数说明 # 同义词图分词过滤器可以使用以下参数进行配置： 参数 必需/可选 数据类型 描述 synonyms 必须指定 synonyms 或 synonyms_path 字符串 在配置中直接定义的同义词规则列表。 synonyms_path 必须指定 synonyms 或 synonyms_path 字符串 包含同义词规则的文件的路径（可以是绝对路径，也可以是相对于配置目录的相对路径）。 lenient 可选 布尔值 在加载规则配置时是否忽略异常。默认值为 false。 format 可选 字符串 指定用于确定 Easysearch 如何定义和解释同义词的格式。有效值为： - solr - wordnet 默认值为 solr。 expand 可选 布尔值 是否扩展等效的同义词规则。默认值为 true。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/field-level-security/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/field-level-security/字段级权限 # 字段级权限允许您控制用户可以查看文档中的哪些字段。就像 文档级权限，可以通过角色配置中的索引块来控制访问。 相关指南（先读这些） # 权限控制总览 安全与多租户最佳实践 包括或排除字段 # 配置字段级权限时，有两个选项：包括或排除字段。如果包含字段，则用户在检索文档时 只能看到 这些字段。例如，如果您包含 actors、title 和 year 字段，则搜索结果可能如下所示： POST movies/_doc/1 { "year": 2013, "title": "Rush", "actors": [ "Daniel Brühl", "Chris Hemsworth", "Olivia Wilde" ] } 如果是排除字段，则用户在检索文档时会看到除这些字段之外的所有内容。例如，如果排除这些相同的字段，则相同的搜索结果可能如下所示： POST movies/_doc/2 { "directors": [ "Ron Howard" ], "plot": "A re-creation of the merciless 1970s rivalry between Formula One rivals James Hunt and Niki Lauda.", "genres": [ "Action", "Biography", "Drama", "Sport" ] } 您可以使用配置文件 role.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/bool/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/bool/Bool 查询 # bool 查询可以将多个查询子句组合成一个高级查询。这些子句通过布尔逻辑组合起来，以在结果中找到匹配的文档。 相关指南（先读这些） # Query DSL 基础 结构化搜索 查询子句 # 在布尔（ bool ）查询中使用以下查询子句： 子句 行为 must 逻辑 and 运算符。结果必须匹配此子句中的所有查询。 must_not 逻辑 not 运算符。所有匹配项都将被排除在结果之外。如果 must_not 包含多个子句，则只返回不匹配任何这些子句的文档。例如， "must_not":[{clause_A}, {clause_B}] 等同于 NOT(A OR B) 。 should 逻辑 or 运算符。结果必须匹配至少一个查询。匹配更多 should 子句会增加文档的相关性分数。您可以使用 minimum_should_match 参数设置必须匹配的最小查询数量。如果一个查询包含 must 或 filter 子句，默认 minimum_should_match 值为 0。否则，默认 minimum_should_match 值为 1。 filter 逻辑 and 运算符，在应用查询之前首先应用于减少您的数据集。过滤器子句中的查询是一个是或否选项。如果文档匹配查询，则它将出现在结果中；否则，它将不会出现。过滤器查询的结果通常会被缓存以允许更快的返回。使用过滤器查询根据精确匹配、范围、日期或数字来过滤结果。 一个布尔查询具有以下结构：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/boosting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/boosting/Boosting 查询 # 如果你搜索"pitcher"这个词，你的结果可能既与棒球运动员有关，也与盛液体的容器有关。在棒球语境下搜索时，你可能想通过使用 must_not 子句完全排除包含"glass"或"water"的搜索结果。然而，如果你想保留这些结果但降低它们的关联度，可以使用 boosting 查询。 一个 boosting 查询返回与 positive 查询匹配的文档。在这些文档中，与 negative 查询也匹配的文档的关联度得分会降低（它们的关联度得分会乘以负的提升因子）。 相关指南（先读这些） # 查询 DSL 基础 相关性：加权与调参 参考用例 # 考虑一个包含两个文档的索引，你以如下方式索引： PUT testindex/_doc/1 { "article_name": "The greatest pitcher in baseball history" } PUT testindex/_doc/2 { "article_name": "The making of a glass pitcher" } 使用以下匹配查询来搜索包含单词“pitcher”的文档： GET testindex/_search { "query": { "match": { "article_name": "pitcher" } } } 返回的两个文档具有相同的相关性分数： { "took": 5, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 2, "relation": "eq" }, "max_score": 0.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/constant-score/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/constant-score/Constant Score 查询 # 如果您需要返回包含某个词的文档，而不管该词出现多少次，您可以使用 constant_score 查询。constant_score 查询包装一个过滤器查询，并将结果中的所有文档的关联分数设置为 boost 参数的值。因此，所有返回的文档具有相同的关联分数，并且不考虑词频/逆文档频率（TF/IDF）。过滤器查询不会计算关联分数。此外，Easysearch 会缓存常用的过滤器查询以提高性能。 相关指南（先读这些） # 查询 DSL 基础 结构化搜索 参考样例 # 使用以下查询返回 shakespeare 索引中包含单词“Hamlet”的文档： GET shakespeare/_search { "query": { "constant_score": { "filter": { "match": { "text_entry": "Hamlet" } }, "boost": 1.2 } } } 结果中的所有文档都被分配了 1.2 的相关性分数： { "took": 8, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 96, "relation": "eq" }, "max_score": 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/disjunction-max/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/disjunction-max/Dis Max 查询 # dis_max 查询返回与一个或多个查询子句匹配的任何文档。对于与多个查询子句匹配的文档，相关性得分设置为所有匹配查询子句中的最高相关性得分。 当返回的文档的相关性分数相同时，您可以使用 tie_breaker 参数来增加匹配多个查询子句的文档的权重。 相关指南（先读这些） # 多字段搜索 Query DSL 基础 参考样例 # 考虑一个包含两个文档的索引，您按照以下方式索引这些文档： PUT testindex1/_doc/1 { "title": " The Top 10 Shakespeare Poems", "description": "Top 10 sonnets of England's national poet and the Bard of Avon" } PUT testindex1/_doc/2 { "title": "Sonnets of the 16th Century", "body": "The poems written by various 16-th century poets" } 使用 dis_max 查询来搜索包含单词“莎士比亚诗歌”的文档https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/distance-feature/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/distance-feature/Distance Feature 查询 # 使用 distance_feature 查询来提升与特定日期或地理位置更近的文档的相关性。这可以帮助你在搜索结果中优先显示更近期的或附近的内容。例如，你可以为近期生产的产品分配更高的权重，或提升最接近用户指定位置的项目。 你可以将此查询应用于包含日期或位置数据的字段。它通常用于 bool 查询的 should 子句中，以改进相关性评分而不过滤掉结果。 相关指南（先读这些） # 相关性与打分策略 地理位置搜索 Query DSL 基础 配置索引 # 在使用 distance_feature 查询之前，请确保您的索引至少包含以下字段类型之一：date,date_nanos,geo_point 在此示例中，您将配置 opening_date 和 coordinates 字段，用于运行距离特征查询： PUT /stores { "mappings": { "properties": { "opening_date": { "type": "date" }, "coordinates": { "type": "geo_point" } } } } 向索引中添加示例文档： PUT /stores/_doc/1 { "store_name": "Green Market", "opening_date": "2025-03-10", "coordinates": [74.00, 40.70] } PUT /stores/_doc/2 { "store_name": "Fresh Foods", "opening_date": "2025-04-01", "coordinates": [73.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/exists/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/exists/Exists 查询 # 使用 exists 查询来搜索包含特定字段的文档。 相关指南（先读这些） # 结构化搜索 Query DSL 基础 如果出现以下任一情况，索引值将不会存在于文档字段中： 该字段在映射中指定了 "index" : false 。 源 JSON 中的字段为 null 或 [] 。 字段值的长度超过了映射中 ignore_above 的设置。 字段值格式错误，并且映射中定义了 ignore_malformed 。 索引值将在以下情况下存在于文档字段中： 该值是一个包含一个或多个 null 元素和一个或多个非 null 元素的数组（例如， ["one", null] ）。 该值是一个空字符串（ "" 或 "-" ）。 该值是一个自定义的 null_value ，如字段映射中所定义。 参考样例 # 例如，假设索引包含以下两个文档： PUT testindex/_doc/1 { "title": "The wind rises" } PUT testindex/_doc/2 { "title": "Gone with the wind", "description": "A 1939 American epic historical film" } 以下查询搜索包含 description 字段的文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/function-score/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/compound-query/function-score/Function Score 查询 # 如果您需要更改结果中返回的文档的相关性评分，请使用 function_score 查询。function_score 查询定义了一个查询和一个或多个函数，这些函数可以应用于所有结果或结果的一部分，以重新计算它们的相关性评分。 相关指南（先读这些） # 查询 DSL 基础 相关性：加权与调参 使用一个评分函数 # 最基础的 function_score 查询示例使用一个函数来重新计算分数。以下查询使用一个 weight 函数将所有相关性分数加倍。此函数适用于所有结果文档，因为没有在 function_score 中指定 query 参数： GET shakespeare/_search { "query": { "function_score": { "weight": "2" } } } 将评分函数应用于文档子集 # 要将评分函数应用于文档子集，在函数中提供一个查询： GET shakespeare/_search { "query": { "function_score": { "query": { "match": { "play_name": "Hamlet" } }, "weight": "2" } } } 支持的功能 # function_score 查询类型支持以下功能：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/fuzzy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/fuzzy/Fuzzy 查询 # fuzzy 查询用于搜索包含与搜索词相似的词条的文档，相似度在允许的最大 Damerau-Levenshtein 距离范围内。Damerau-Levenshtein 距离衡量将一个词条变为另一个词条所需的一字符变化的数量。这些变化包括： 相关指南（先读这些） # 文本分析：模糊匹配 全文搜索 Replacements: 替换，cat 变为 bat Insertions: 插入，cat 变为 cats Deletions: 删除，cat 变为 at Transpositions: 转换，cat 变为 act 模糊查询会生成一个包含所有可能扩展的搜索词列表，这些扩展在 Damerau-Levenshtein 距离内。你可以在 max_expansions 字段中指定此类扩展的最大数量。查询然后会搜索匹配任何扩展的文档。如果你将 transpositions 参数设置为 false ，则搜索将使用经典的 Levenshtein 距离。 以下示例查询搜索发言者 HALET （误写为 HAMLET ）。未指定最大编辑距离，因此使用默认的 AUTO 编辑距离： GET shakespeare/_search { "query": { "fuzzy": { "speaker": { "value": "HALET" } } } } 返回内容包含所有发言者为 HAMLET 的文档。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/gsub/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/gsub/Gsub 处理器 # gsub 处理器在传入的文档中对字符串字段执行正则表达式搜索和替换操作。如果字段包含字符串数组，则操作应用于数组中的所有元素。然而，如果字段包含非字符串值，处理器将抛出异常。gsub 处理器的用例包括从日志消息或用户生成的内容中删除敏感信息、规范化数据格式或约定（例如，转换日期格式、删除特殊字符），以及从字段值中提取或转换子字符串以进行进一步处理或分析。 以下是为 gsub 处理器提供的语法： "gsub": { "field": "field_name", "pattern": "regex_pattern", "replacement": "replacement_string" } 配置参数 # 下表列出了 gsub 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 要应用替换的字段。 pattern 必填 要替换的模式。 replacement 必填 将替换匹配模式的字符串。 target_field 可选 要存储解析数据的字段名称。如果未指定 target_field ，则解析数据将替换 field 字段中的原始数据。默认为 field 。 if 可选 处理器运行的条件。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。默认为 false 。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/joining/has-child/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/joining/has-child/Has Child 查询 # has_child 查询返回匹配特定查询的子文档的父文档。您可以通过使用连接字段类型在相同索引中的文档之间建立父子关系。 相关指南（先读这些） # Parent-Child 建模 关联查询（Joining） 性能注意：has_child 查询比其他查询慢，因为它执行了连接操作。随着指向不同父文档的匹配子文档数量的增加，性能会降低。您搜索中的每个 has_child 查询都可能显著影响查询性能。如果您优先考虑速度，请避免使用此查询或尽可能限制其使用。更多性能考虑，请参考 Parent-Child 建模章节。 参考样例 # 在您运行一个 has_child 查询之前，您的索引必须包含一个连接字段，以便建立父子关系。索引映射请求使用以下格式： PUT /example_index { "mappings": { "properties": { "relationship_field": { "type": "join", "relations": { "parent_doc": "child_doc" } } } } } 在这个例子中，您将配置一个包含代表产品和其品牌的文档的索引。 首先，创建索引并建立 brand 和 product 之间的父子关系： PUT testindex1 { "mappings": { "properties": { "product_to_brand": { "type": "join", "relations": { "brand": "product" } } } } } 创建两个父（品牌）文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/joining/has-parent/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/joining/has-parent/Has Parent 查询 # has_parent 查询返回匹配特定查询的父文档的子文档。您可以通过使用连接字段类型在相同索引中的文档之间建立父子关系。 相关指南（先读这些） # Parent-Child 建模 关联查询（Joining） 性能注意：has_parent 查询比其他查询慢，因为它执行了连接操作。随着匹配的父文档数量的增加，性能会降低。您搜索中的每个 has_parent 查询都可能显著影响查询性能。如果您优先考虑速度，请避免使用此查询或尽可能限制其使用。更多性能考虑，请参考 Parent-Child 建模章节。 参考样例 # 在您运行一个 has_parent 查询之前，您的索引必须包含一个连接字段，以便建立父子关系。索引映射请求使用以下格式： PUT /example_index { "mappings": { "properties": { "relationship_field": { "type": "join", "relations": { "parent_doc": "child_doc" } } } } } 对于这个示例，首先配置一个包含代表产品和其品牌的文档的索引，这些文档如查询示例 has_child 中所述。 要搜索父项的子项，请使用 has_parent 查询。以下查询返回与查询 economy 匹配的品牌生产的子文档（产品）： GET testindex1/_search { "query" : { "has_parent": { "parent_type":"brand", "query": { "match" : { "name": "economy" } } } } } 返回由该品牌生产的所有产品：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/html-strip/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/html-strip/HTML Strip 字符过滤器 # html_strip 字符过滤器会从输入文本中移除 HTML 标签（例如 <div>、<p> 和 <a> 等）并输出纯文本。该过滤器可以配置保留某些标签，或者配置把特定的 HTML 标签实体（如  ）解码为空格。 相关指南（先读这些） # 文本分析基础 文本分析：识别词元 参考样例 # 以下请求展示将 html_strip 字符过滤器应用于文本： GET /_analyze { "tokenizer": "keyword", "char_filter": [ "html_strip" ], "text": "<p>Commonly used calculus symbols include α, β and θ </p>" } 返回内容中包含的词元里，可以看到 HTML 字符已被转换为它们的解码后的值： { "tokens": [ { "token": "\nCommonly used calculus symbols include α, β and θ \n", "start_offset": 0, "end_offset": 74, "type": "word", "position": 0 } ] } 参数说明 # html_strip 字符过滤器可以使用以下参数进行配置。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/ids/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/ids/IDs 查询 # 使用 ids 查询在 _id 字段中搜索具有一个或多个特定文档 ID 值的文档。例如，以下查询请求 ID 为 34229 和 91296 的文档： 相关指南（先读这些） # 结构化搜索 Query DSL 基础 GET shakespeare/_search { "query": { "ids": { "values": [ 34229, 91296 ] } } } 参数说明 # 查询接受以下参数。 参数 数据类型 描述 values Array of strings 要搜索的文档 ID。必填。 boost Float 一个浮点值，用于指定此字段相对于相关性分数的权重。值高于 1.0 会增加字段的相关性。值介于 0.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/intervals/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/intervals/Intervals 查询 # intervals 查询根据匹配词的邻近度和顺序来匹配文档。它将一组匹配规则应用于指定字段中的词。该查询生成跨越文本中词的最小间隔序列。你可以组合间隔并按父源进行过滤。 相关指南（先读这些） # 邻近匹配 全文搜索 考虑一个包含以下文档的索引： PUT testindex/_doc/1 { "title": "key-value pairs are efficiently stored in a hash table" } PUT /testindex/_doc/2 { "title": "store key-value pairs in a hash map" } 例如，以下查询搜索包含短语 key-value pairs （词之间没有间隔）后跟 hash table 或 hash map 的文档： GET /testindex/_search { "query": { "intervals": { "title": { "all_of": { "ordered": true, "intervals": [ { "match": { "query": "key-value pairs", "max_gaps": 0, "ordered": true } }, { "any_of": { "intervals": [ { "match": { "query": "hash table" } }, { "match": { "query": "hash map" } } ] } } ] } } } } } 该查询返回两个文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/ip-range/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/ip-range/IP 范围聚合 # ip_range 聚合用于 IP 地址。它适用于 ip 类型字段。您可以在 CIDR 表示法中定义 IP 范围和掩码。 相关指南（先读这些） # 聚合基础 聚合场景实践 GET sample_data_logs/_search { "size": 0, "aggs": { "access": { "ip_range": { "field": "ip", "ranges": [ { "from": "1.0.0.0", "to": "126.158.155.183" }, { "mask": "1.0.0.0/8" } ] } } } } 返回内容 ... "aggregations" : { "access" : { "buckets" : [ { "key" : "1.0.0.0/8", "from" : "1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/match-bool-prefix/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/match-bool-prefix/Match Bool Prefix 查询 # match_bool_prefix 查询分析提供的搜索字符串，并从字符串的词项中创建一个布尔查询。它将除最后一个词项外的每个词项作为完整单词进行匹配。最后一个词项用作前缀。match_bool_prefix 查询返回包含完整单词词项或以前缀词项开头的词项的文档，顺序不限。 相关指南（先读这些） # 部分匹配 全文搜索 以下示例展示了一个基本的 match_bool_prefix 查询： GET _search { "query": { "match_bool_prefix": { "title": "the wind" } } } 要传递额外参数，您可以使用扩展语法： GET _search { "query": { "match_bool_prefix": { "title": { "query": "the wind", "analyzer": "stop" } } } } 参考样例 # 例如，考虑一个包含以下文档的索引： PUT testindex/_doc/1 { "title": "The wind rises" } PUT testindex/_doc/2 { "title": "Gone with the wind" } 以下 match_bool_prefix 查询会搜索整个词 rises 以及以 wi 开头的词，顺序不限：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/match-phrase-prefix/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/match-phrase-prefix/Match Phrase Prefix 查询 # 使用 match_phrase_prefix 查询来指定要匹配的短语。包含您指定短语的文档将被返回。短语中的最后一个部分词被解释为前缀，因此任何包含以该短语和最后一个词的前缀开头的短语的文档都将被返回。 与 match_phrase 类似，但会从查询字符串中的最后一个词创建一个前缀查询。 相关指南（先读这些） # 部分匹配 邻近匹配 对于 match_phrase_prefix 和 match_bool_prefix 查询之间的差异，请参阅 match_bool_prefix 和 match_phrase_prefix 查询。 以下示例展示了一个基本的 match_phrase_prefix 查询： GET _search { "query": { "match_phrase_prefix": { "title": "the wind" } } } 要传递附加参数，您可以使用扩展语法： GET _search { "query": { "match_phrase_prefix": { "title": { "query": "the wind", "analyzer": "stop" } } } } 参考用例 # 例如，创建一个包含以下文档的索引： PUT testindex/_doc/1 { "title": "The wind rises" } PUT testindex/_doc/2 { "title": "Gone with the wind" } 以下 match_phrase_prefix 查询会搜索完整单词 wind ，后跟一个以 ri 开头的单词：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/match-phrase/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/match-phrase/Match Phrase 查询 # 使用 match_phrase 查询来匹配包含指定顺序中确切的短语的文档。您可以通过提供 slop 参数来增加短语匹配的灵活性。 match_phrase 查询创建一个匹配词项序列的短语查询。 相关指南（先读这些） # 邻近匹配 全文搜索 以下示例展示了一个基本的 match_phrase 查询： GET _search { "query": { "match_phrase": { "title": "the wind" } } } 要传递额外的参数，您可以使用扩展语法： GET _search { "query": { "match_phrase": { "title": { "query": "the wind", "analyzer": "stop" } } } } 参考用例 # 例如，创建一个包含以下文档的索引： PUT testindex/_doc/1 { "title": "The wind rises" } PUT testindex/_doc/2 { "title": "Gone with the wind" } 以下 match_phrase 查询搜索短语 wind rises ，其中单词 wind 后面跟着单词 rises ：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/match/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/match/Match 查询 # 使用 match 查询在特定文档字段上执行全文搜索。如果你在 text 字段上运行 match 查询，match 查询会分析提供的搜索字符串，并返回匹配字符串中任意词的文档。如果你在精确值字段上运行 match 查询，它会返回匹配精确值的文档。搜索精确值字段的推荐方式是使用过滤（filter）查询，因为与普通查询不同，过滤（filter）查询会被缓存。 相关指南（先读这些） # 全文检索 Query DSL 基础 以下示例展示了在 title 中对 wind 的基本 match 查询： GET _search { "query": { "match": { "title": "wind" } } } 通过传递其他参数，您可以使用扩展语法： GET _search { "query": { "match": { "title": { "query": "wind", "analyzer": "stop" } } } } 参考样例 # 在以下示例中，您将使用包含以下文档的索引： PUT testindex/_doc/1 { "title": "Let the wind rise" } PUT testindex/_doc/2 { "title": "Gone with the wind" } PUT testindex/_doc/3 { "title": "Rise is gone" } 运算符（operator） # operator 参数控制多个词元之间的逻辑关系：or（默认）或 and。默认操作符是 OR，查询 wind rise 会被改为 wind OR rise。要指定 and 操作符，请使用以下查询：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/more-like-this/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/more-like-this/More Like This 查询 # 使用 more_like_this 查询查找与一个或多个给定文档相似的文档。这对于推荐引擎、内容发现以及识别数据集中的相关项目很有用。 more_like_this 查询分析输入文档或文本，并选择最能描述它们的词项。然后，它搜索包含这些重要词项的其他文档。 相关指南（先读这些） # 相关性与打分策略 Query DSL 基础 前提条件 # 在使用 more_like_this 查询之前，请确保您目标字段已索引，且其数据类型为 text 或 keyword 。 如果您在 like 部分引用文档，Easysearch 需要访问其内容。这通常通过 _source 字段完成，该字段默认启用。如果 _source 被禁用，您必须单独存储这些字段，或配置它们以保存 term_vector 数据。 在索引文档时保存 term_vector 信息可以大大加速 more_like_this 查询，因为引擎可以直接检索重要词项，而无需在查询时重新分析字段文本。 示例：无词向量优化 # 使用以下映射创建名为 articles-basic 的索引： PUT /articles-basic { "mappings": { "properties": { "title": { "type": "text" }, "content": { "type": "text" } } } } 添加示例文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/multi-match/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/multi-match/Multi Match 查询 # multi_match 查询与 match 查询类似。您可以使用 multi_match 查询来搜索多个字段。 相关指南（先读这些） # 多字段搜索 全文搜索 字段权重 # ^ 会"提升"某些字段的权重。提升是乘数，用于使一个字段中的匹配比其他字段中的匹配更重要。在以下示例中，title字段中匹配 “wind” 的权重比 plot 字段中匹配的权重高 _score 四倍： GET _search { "query": { "multi_match": { "query": "wind", "fields": ["title^4", "plot"] } } } 结果是，像《The Wind Rises》和《Gone with the Wind》这样的电影出现在搜索结果的顶部附近，而像《Twister》这样的电影，其剧情简介中可能包含“wind”字，则出现在底部附近。 您可以在字段名中使用通配符。例如，以下查询将搜索 speaker 字段以及所有以 play_ 开头的字段，例如 play_name 或 play_title ： GET _search { "query": { "multi_match": { "query": "hamlet", "fields": ["speaker", "play_*"] } } } 如果您不提供 fields 参数，multi_match 查询将搜索 index.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/joining/nested/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/joining/nested/Nested 查询 # nested 查询充当其他查询的包装器，用于搜索嵌套字段。嵌套字段对象被视为单独的文档进行搜索。如果对象匹配搜索条件，nested 查询将返回根级别的父文档。 相关指南（先读这些） # Nested 建模 关联查询（Joining） 参考样例 # 在运行 nested 查询之前，您的索引必须包含一个嵌套字段。 要配置一个包含嵌套字段的示例索引，请发送以下请求： PUT /testindex { "mappings": { "properties": { "patient": { "type": "nested", "properties": { "name": { "type": "text" }, "age": { "type": "integer" } } } } } } 接下来，将一个文档索引到示例索引中： PUT /testindex/_doc/1 { "patient": { "name": "John Doe", "age": 56 } } 要搜索嵌套的 patient 字段，请将您的查询包裹在 nested 查询中，并提供 path 给嵌套字段：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/joining/parent-id/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/joining/parent-id/Parent ID 查询 # parent_id 查询返回具有指定 ID 的父文档的子文档。您可以通过使用连接字段类型在相同索引中的文档之间建立父子关系。 相关指南（先读这些） # Parent-Child 建模 关联查询（Joining） 参考样例 # 在您运行一个 parent_id 查询之前，您的索引必须包含一个连接字段，以便建立父子关系。索引映射请求使用以下格式： PUT /example_index { "mappings": { "properties": { "relationship_field": { "type": "join", "relations": { "parent_doc": "child_doc" } } } } } 对于此示例，首先配置一个包含代表产品和其品牌的文档的索引，这些文档在 has_child 查询示例中有所描述。 要搜索特定父文档的子文档，请使用 parent_id 查询。以下查询返回具有 ID 1 的父文档的子文档（产品）： GET testindex1/_search { "query": { "parent_id": { "type": "product", "id": "1" } } } 返回子产品： { "took": 57, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 1, "relation": "eq" }, "max_score": 0.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/percolate/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/percolate/Percolate 查询 # 使用 percolate 查询来查找与给定文档匹配的已存储查询。此操作与常规搜索相反：常规搜索是查找与查询匹配的文档，而 percolate 查询是查找与文档匹配的查询。percolate 查询通常用于告警、通知和反向搜索用例。 相关指南（先读这些） # Query DSL 基础 专业查询（Specialized queries） 在使用 percolate 查询时，请考虑以下几点： 您可以在线提供文档进行 percolate 操作，或者从索引中获取现有文档。 文档和存储的查询必须使用相同的字段名称和类型。 您可以结合使用透查、过滤和评分来构建复杂的匹配系统。 percolate 查询被视为昂贵的查询，并且只有在集群设置 search.allow_expensive_queries 被设置为 true （默认值）时才会运行。如果此设置是 false ， percolate 查询将被拒绝。 percolate 查询在各种实时匹配场景中非常有用。一些常见的用例包括： 电子商务通知：用户可以注册对产品的兴趣，例如，“有新的苹果笔记本电脑时通知我”。当新产品文档被索引时，系统会找到所有匹配保存的查询的用户并发送警报。 工作警报：求职者根据首选的工作标题或地点保存查询，新的职位发布将与这些查询匹配以触发警报。 安全和警报系统：Percolate 传入的日志或事件数据与保存的规则或异常模式进行匹配。 新闻筛选：将传入的文章与保存的主题配置文件进行匹配，以分类或提供相关内容。 工作过程 # 保存的查询存储在一个特殊的 percolator 字段类型中。 文档会与所有保存的查询进行比较。 每个匹配的查询都会返回其 _id 。 如果启用了高亮显示，匹配的文本片段也会被返回。 如果发送了多个文档， _percolator_document_slot 会显示匹配的文档。 参考样例 # 以下示例展示了如何存储 percolate 查询，并使用不同方法对它们进行测试。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/prefix/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/prefix/Prefix 查询 # 使用 prefix 查询可以搜索以特定前缀开头的词。例如，以下查询会搜索 speaker 字段包含以 KING H 开头的词的文档。 相关指南（先读这些） # 部分匹配 结构化搜索 GET shakespeare/_search { "query": { "prefix": { "speaker": "KING H" } } } 为了提供参数，您可以使用与前面的查询相同的形式，并使用以下扩展语法 GET shakespeare/_search { "query": { "prefix": { "speaker": { "value": "KING H" } } } } 参数说明 # 查询接受字段名称（ <field> ）作为顶级参数： GET _search { "query": { "prefix": { "<field>": { "value": "sample", ... } } } } <field> 接受以下参数。除了 value 之外，所有参数都是可选的。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/query-string/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/query-string/Query String 查询 # query_string 查询根据查询字符串语法解析查询字符串。它提供了创建强大而简洁的查询的功能，这些查询可以包含通配符并搜索多个字段。 相关指南（先读这些） # 全文搜索 Query DSL 基础 查询字符串语法 — 通配符、模糊、范围、布尔等完整语法参考 使用注意：使用 query_string 查询的搜索不会返回嵌套文档。要搜索嵌套字段，请使用 nested 查询。 语法严格性：查询字符串查询具有严格的语法，在语法无效时会返回错误。因此，它不适合搜索框应用程序。对于不太严格的替代方案，可以考虑使用 simple_query_string 查询。如果你不需要查询语法支持，使用 match 查询。 参考样例 # 运行以下搜索时， query_string 查询会将 (new york city) OR (big apple) 拆分为两部分： new york city 和 big apple 。 content 字段的分词器随后会分别将每个部分转换为标记，然后返回匹配的文档。由于查询语法不使用空格作为运算符，因此 new york city 会按原样传递给分词器。 GET /_search { "query": { "query_string": { "query": "(new york city) OR (big apple)", "default_field": "content" } } } 参数说明 # 下表列出了 query_string 查询支持的参数。除 query 外，所有参数都是可选的。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/range/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/range/Range 查询 # 您可以使用 range 查询搜索字段中的值范围。 相关指南（先读这些） # 结构化搜索 Query DSL 基础 要搜索 line_id 值为 >= 10 和 <= 20 的文档，请使用以下请求： GET shakespeare/_search { "query": { "range": { "line_id": { "gte": 10, "lte": 20 } } } } 运算符 # 范围查询中的字段参数接受以下可选运算符参数： gte：大于或等于 gt：大于 lte：小于或等于 lt：小于 日期字段 # 您可以对包含日期的字段使用范围查询。例如，假设您有一个products索引，并且想要查找 2019 年添加的所有产品： GET products/_search { "query": { "range": { "created": { "gte": "2019/01/01", "lte": "2019/12/31" } } } } 日期格式 # 要在查询中使用字段映射格式以外的日期格式，请在 format 字段中指定它。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/rank-feature/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/rank-feature/Rank Feature 查询 # 使用 rank_feature 查询根据文档中的数值（如相关性分数、人气或新鲜度）提升文档分数。如果你希望使用数值特征微调相关性排名，这种查询非常理想。与全文检索不同，rank_feature 仅关注数值信号；在复合查询（如 bool）中与其他查询结合时效果最佳。 rank_feature 查询要求目标字段映射为 rank_feature 字段类型。这可以启用内部优化的评分，从而实现快速高效的提升。 相关指南（先读这些） # 相关性与打分策略 Query DSL 基础 分数影响取决于字段值以及可选的 saturation 、 log 或 sigmoid 函数。这些函数在查询时动态应用以计算最终文档分数；它们不会更改或存储文档中的任何值。 参数说明 # rank_feature 查询支持以下参数。 参数 数据类型 必需/可选 描述 field String 必需 一个 rank_feature 或 rank_features 字段，用于影响文档评分。 boost Float 可选 应用于评分的乘数。默认值为 1.0 。0 到 1 之间的值会降低评分；大于 1 的值会提高评分。 saturation Object 可选 对特征值应用饱和函数。随着值的增加，增益会增长，但在 pivot 之后会趋于平稳。如果没有提供其他函数，则使用此默认函数。一次只能使用 saturation 、 log 或 sigmoid 中的一个函数。 log Object 可选 使用基于字段值的对数评分函数。适用于大范围值的场景。一次只能使用 saturation 、 log 或 sigmoid 中的一个函数。 sigmoid Object 可选 对评分影响应用 S 形曲线，由 pivot 和 exponent 控制。一次只能使用 saturation 、 log 或 sigmoid 中的一个函数。 positive_score_impact Boolean 可选 当 false 时，较低值会获得更高的评分。适用于像价格这样的特征，其中较小值更好。作为映射的一部分定义。默认值为 true 。 参考样例 # 以下示例展示了如何定义和使用 rank_feature 字段来影响文档评分。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/regexp/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/regexp/Regexp 查询 # 使用 regexp 查询来搜索符合正则表达式的词项。有关编写正则表达式的更多信息，请参见正则表达式语法。 相关指南（先读这些） # 部分匹配 结构化搜索 以下查询搜索以任何大写或小写字母开头的任何词项 amlet ： GET shakespeare/_search { "query": { "regexp": { "play_name": "[a-zA-Z]amlet" } } } 重要注意事项： 正则表达式应用于字段中的词条（即，标记/token），而不是整个字段。 默认情况下，正则表达式的最大长度为 1,000 个字符。要更改最大长度，请更新 index.max_regex_length 设置。 正则表达式使用 Lucene 语法，这与更标准的实现有所不同。请充分测试以确保获得预期的结果。 为了提高正则表达式查询的性能，避免使用没有前缀或后缀的通配符模式，例如 .* 或 .*?+ 。 regexp 查询可能会非常耗时，并且需要将 search.allow_expensive_queries 设置为 true 。在频繁执行 regexp 查询之前，请测试其对集群性能的影响，并考虑使用其他可能达到类似效果的查询。更多性能优化建议，请参考 部分匹配章节。 参数说明 # 查询接受字段名称（ <field> ）作为顶级参数： GET _search { "query": { "regexp": { "<field>": { "value": "[Ss]ample", .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/script-score/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/script-score/Script Score 查询 # 使用 script_score 查询通过脚本自定义分数计算。对于昂贵的评分函数，您可以使用 script_score 查询仅计算已过滤的返回文档的分数。 相关指南（先读这些） # 相关性与打分策略 Query DSL 基础 参考样例 # 例如，以下请求创建一个包含一个文档的索引： PUT testindex1/_doc/1 { "name": "John Doe", "multiplier": 0.5 } 您可以使用 match 查询返回所有在 name 字段中包含 John 的文档： GET testindex1/_search { "query": { "match": { "name": "John" } } } 在返回内容中，文档 1 的得分为 0.2876821 ： { "took": 7, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 1, "relation": "eq" }, "max_score": 0.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/script/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/script/Script 查询 # 使用 script 查询基于 Painless 脚本语言编写的自定义条件来过滤文档。此查询返回脚本评估结果为 true 的文档，从而实现无法使用标准查询表达的高级过滤逻辑。 相关指南（先读这些） # Query DSL 基础 结构化搜索 专业查询（Specialized queries） 性能注意：script 查询计算成本高，应谨慎使用。仅在必要时使用，并确保 search.allow_expensive_queries 已启用（默认为 true ）。有关更多信息，请参阅昂贵查询。 参考样例 # 使用以下映射创建一个名为 products 的索引： PUT /products { "mappings": { "properties": { "title": { "type": "text" }, "price": { "type": "float" }, "rating": { "type": "float" } } } } 使用以下请求索引示例文档： POST /products/_bulk { "index": { "_id": 1 } } { "title": "Wireless Earbuds", "price": 99.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/simple-query-string/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/full-text/simple-query-string/Simple Query String 查询 # 使用 simple_query_string 查询在查询字符串中直接指定由正则表达式分隔的多个参数。简单查询字符串的语法比 query_string 查询宽松，因为它会丢弃字符串中的任何无效部分，并且不会因无效语法而返回错误。 此查询使用简单语法根据特殊运算符解析查询字符串，并将字符串拆分为词项。解析后，查询会独立分析每个词项，然后返回匹配的文档。 相关指南（先读这些） # 全文搜索 Query DSL 基础 以下查询对 title 字段执行模糊搜索： GET _search { "query": { "simple_query_string": { "query": "\"rises wind the\"~4 | *ising~2", "fields": ["title"] } } } 简单字符串语法 # 查询字符串由词项和运算符组成。词项是一个单词（例如，在查询 wind rises 中，词项是 wind 和 rises ）。如果多个词项被引号包围，它们被视为一个短语，其中单词按出现的顺序匹配（例如， “wind rises” ）。 + 、 | 和 - 等运算符指定用于解释查询字符串中文本的布尔逻辑。 操作符 # 简单查询字符串语法支持以下运算符。 操作符 描述 + 作为 AND 操作符。 \| 作为 OR 操作符。 * 在词尾使用时，表示前缀查询。 " 将多个词括起来组成短语（例如，"wind rises"）。 (, ) 为优先级包装子句（例如，wind + (rises \| rising)）。 ~n 在词后面使用时（例如，wnid~3），设置 fuzziness。在短语后面使用时，设置 slop。 - 否定该词。 所有前面的操作符都是保留字符。要将其作为原始字符而不是操作符引用，用反斜杠转义它们中的任何一个。在发送 JSON 请求时，使用 \\ 转义保留字符（因为反斜杠字符本身也是保留的，你必须用另一个反斜杠转义反斜杠）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-containing/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-containing/Span Containing 查询 # span_containing 查询会在较大的文本模式（如短语或一组单词）的边界内查找包含较小文本模式的匹配项。可以将其视为仅在特定更大的上下文中出现时才查找单词或短语。 例如，您可以使用 span_containing 查询来执行以下搜索： 查找单词"quick"，但仅当它出现在同时提到狐狸和行为的句子中时。 确保某些词项出现在其他词项的上下文中——而不仅仅是在文档的任何地方。 搜索在更长的有意义的短语中出现的特定单词。 相关指南（先读这些） # Span 查询 邻近匹配 查询 DSL 基础 参考样例 # 以下查询搜索在包含“silk”和“dress”词语的较大词组（不一定按该顺序）中，与“red”一词出现且彼此之间不超过 5 个词的情况： GET /clothing/_search { "query": { "span_containing": { "little": { "span_term": { "description": "red" } }, "big": { "span_near": { "clauses": [ { "span_term": { "description": "silk" } }, { "span_term": { "description": "dress" } } ], "slop": 5, "in_order": false } } } } } 该查询匹配文档 1 的原因是：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-field-masking/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-field-masking/Span Field Masking 查询 # field_masking_span 查询允许 span 查询通过"掩饰"查询的真实字段来匹配不同字段。这在处理多字段（相同内容使用不同分析器索引）或需要跨不同字段运行 span 查询（如 span_near 或 span_or，这通常是不允许的）时特别有用。 例如，您可以使用 field_masking_span 查询来： 匹配原始字段及其词干版本中的词项。 在一个 span 操作中组合不同字段的 span 查询。 使用不同分析器索引的相同内容进行操作。 注意：在使用字段遮罩时，相关性分数是根据遮罩字段的特性（范数）计算的，而不是实际搜索的字段。这意味着如果遮罩字段与被搜索字段具有不同的属性（如长度或提升值），您可能会收到意外的评分结果。 相关指南（先读这些） # Span 查询 多字段搜索 查询 DSL 基础 参考样例 # 以下查询在词干化字段中搜索单词“long”，并查找“sleeve”一词的变体附近： GET /clothing/_search { "query": { "span_near": { "clauses": [ { "span_term": { "description": "long" } }, { "field_masking_span": { "query": { "span_term": { "description.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-first/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-first/Span First 查询 # span_first 查询匹配从字段开头开始并在指定位置结束的跨度。当您想要查找出现在文档开头附近的词项或短语时，此查询很有用。 例如，您可以使用 span_first 查询来执行以下搜索： 查找在字段的最初几个词中出现的特定词项的文档。 确保某些短语出现在文本的开头或附近。 仅在模式出现在指定距离内时匹配。 相关指南（先读这些） # Span 查询 查询 DSL 基础 参考样例 # 以下查询搜索词干“dress”出现在描述的前 4 个位置： GET /clothing/_search { "query": { "span_first": { "match": { "span_term": { "description.stemmed": "dress" } }, "end": 4 } } } 该查询匹配文档 1 和 2： 文档 1 和 2 在第三位置包含单词 dress （“长袖连衣裙…”和“漂亮的连衣裙”）。索引单词的起始位置为 0，因此单词“dress”位于位置 2。 单词 dress 的位置必须小于 4 ，如 end 参数指定。 { "took": 13, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 2, "relation": "eq" }, "max_score": 0.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-multi-term/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-multi-term/Span Multi Term 查询 # span_multi 查询允许您将多词查询（如 wildcard、fuzzy、prefix、range 或 regexp）包装为 span 查询。这使您能够在其他 span 查询中使用这些更灵活的匹配查询。 例如，您可以使用 span_multi 查询来： 查找具有相同前缀的词语，并与其他词语靠近。 匹配跨度内单词的模糊变体。 在跨度查询中使用正则表达式。 注意：span_multi 查询可能匹配多个词。为了避免过度内存使用，您可以： 为多词查询设置 rewrite 参数。 使用 top_terms_* 重写方法。 如果你仅使用 span_multi 进行 prefix 查询，请考虑为文本字段启用 index_prefixes 选项。这将自动将字段上的任何 prefix 查询重写为匹配索引前缀的单词查询。 相关指南（先读这些） # Span 查询 部分匹配 查询 DSL 基础 参考样例 # span_multi 查询使用以下语法来包装 prefix 查询： "span_multi": { "match": { "prefix": { "description": { "value": "flutter" } } } } 以下查询搜索以“dress”开头的单词，在彼此最多 5 个单词的距离内靠近任何形式的“sleeve”：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-near/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-near/Span Near 查询 # span_near 查询匹配彼此靠近的跨度。您可以指定跨度之间的距离，并指定它们是否需要按特定顺序出现。 例如，您可以使用 span_near 查询来： 查找彼此之间距离在特定范围内的词项。 匹配词语按特定顺序出现的短语。 查找文本中彼此靠近的相关概念。 相关指南（先读这些） # Span 查询 邻近匹配 查询 DSL 基础 参考样例 # 以下查询搜索任何形式的“sleeve”和“long”相邻出现，顺序不限： GET /clothing/_search { "query": { "span_near": { "clauses": [ { "span_term": { "description.stemmed": "sleev" } }, { "span_term": { "description.stemmed": "long" } } ], "slop": 1, "in_order": false } } } 该查询匹配文档 1（“Long-sleeved…”）和文档 2（“…long fluttered sleeves…”）。在文档 1 中，词语是相邻的，而在文档 2 中，它们在指定的 slop 距离 1 内（它们之间有一个词）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-not/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-not/Span Not 查询 # span_not 查询会排除与另一个 span 查询重叠的跨度。您还可以指定在排除的跨度之前或之后不允许匹配的距离范围。 例如，您可以使用 span_not 查询来： 查找除在特定短语中出现时的词项外。 除非它们靠近特定词项，否则匹配跨度。 排除在特定距离内出现的其他模式匹配。 相关指南（先读这些） # Span 查询 查询 DSL 基础 参考样例 # 以下查询搜索单词“dress”，但当它出现在短语“dress shirt”中时不搜索： GET /clothing/_search { "query": { "span_not": { "include": { "span_term": { "description": "dress" } }, "exclude": { "span_near": { "clauses": [ { "span_term": { "description": "dress" } }, { "span_term": { "description": "shirt" } } ], "slop": 0, "in_order": true } } } } } 该查询匹配文档 2，因为它包含单词“dress”（“Beautiful long dress…”）。文档 1 未匹配，因为它包含短语“dress shirt”，该短语被排除。文档 3 和 4 未匹配，因为它们包含单词“dress”的变体（“dressed”和“dresses”），并且查询是在原始字段中进行的。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-or/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-or/Span Or 查询 # span_or 查询组合多个 span 查询，并匹配它们 span 的并集。如果其中至少一个包含的 span 查询匹配，则发生匹配。 例如，您可以使用 span_or 查询来： 查找匹配多个模式中的任意一个的 span。 将不同的 span 模式作为备选项组合。 在一个查询中匹配多个 span 变体。 相关指南（先读这些） # Span 查询 查询 DSL 基础 参考样例 # 以下查询搜索“formal collar”或“button collar”在彼此 2 个词距离内出现： GET /clothing/_search { "query": { "span_or": { "clauses": [ { "span_near": { "clauses": [ { "span_term": { "description": "formal" } }, { "span_term": { "description": "collar" } } ], "slop": 0, "in_order": true } }, { "span_near": { "clauses": [ { "span_term": { "description": "button" } }, { "span_term": { "description": "collar" } } ], "slop": 2, "in_order": true } } ] } } } 该查询在指定的 slop 距离内匹配文档 1（“…formal collar…”）和文档 3（“…button-down collar…”）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-term/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-term/Span Term 查询 # span_term 查询是最基本的 span 查询，它匹配包含单个词的 span。它是更复杂的 span 查询的构建模块。 例如，您可以使用 span_term 查询来： 查找可用于其他 span 查询的精确词匹配。 匹配特定单词同时保持位置信息。 创建可与其他 span 查询组合的基本 span。 相关指南（先读这些） # Span 查询 查询 DSL 基础 参考样例 # 以下查询搜索确切的词“formal”： GET /clothing/_search { "query": { "span_term": { "description": "formal" } } } 或者，您可以在 value 参数中指定搜索词： GET /clothing/_search { "query": { "span_term": { "description": { "value": "formal" } } } } 您也可以指定 boost 值来提升文档得分：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-within/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/span/span-within/Span Within 查询 # span_within 查询匹配被另一个 span 查询所包围的跨度。它是 span_containing 的相反操作：span_containing 返回包含较小跨度的较大跨度，而 span_within 返回被较大跨度包围的较小跨度。 例如，您可以使用 span_within 查询来： 查找出现在较长短语中的较短短语。 匹配在特定上下文中出现的词项。 识别被较大模式包围的小模式。 相关指南（先读这些） # Span 查询 邻近匹配 查询 DSL 基础 参考样例 # 以下查询在包含“shirt”和“long”的跨度中搜索单词“dress”： GET /clothing/_search { "query": { "span_within": { "little": { "span_term": { "description": "dress" } }, "big": { "span_near": { "clauses": [ { "span_term": { "description": "shirt" } }, { "span_term": { "description": "long" } } ], "slop": 2, "in_order": false } } } } } 该查询匹配文档 1 的原因是：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/term/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/term/Term 查询 # 使用 term 查询在字段中搜索确切的词项。例如，以下查询搜索包含确切的行号的行： 相关指南（先读这些） # 结构化搜索 Query DSL 基础 GET shakespeare/_search { "query": { "term": { "line_id": { "value": "61809" } } } } 注意：term 查询仅匹配确切的词项，不会对查询文本进行分词。避免在 text 字段上使用 term 查询，应使用 keyword 字段或 match 查询。更多信息，请参阅 结构化搜索。 您可以在 case_insensitive 参数中指定查询应不区分大小写： GET shakespeare/_search { "query": { "term": { "speaker": { "value": "HAMLET", "case_insensitive": true } } } } 返回内容包含匹配的文档，无论大小写是否有差异： "hits": { "total": { "value": 1582, "relation": "eq" }, "max_score": 2, "hits": [ { "_index": "shakespeare", "_id": "32700", "_score": 2, "_source": { "type": "line", "line_id": 32701, "play_name": "Hamlet", "speech_number": 9, "line_number": "1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/terms-set/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/terms-set/Terms Set 查询 # 使用 terms_set 查询，您可以在指定字段中搜索匹配一定数量的精确词的文档。与 terms 查询类似，您可以指定返回文档所需的匹配词的最小数量。您可以直接在索引字段中指定这个数量，也可以通过脚本指定。 相关指南（先读这些） # 结构化搜索 查询 DSL 基础 例如，假设有一个索引，其中包含学生的姓名和他们所选的课程。在设置该索引的映射时，您需要提供一个数值字段，以指定返回文档所需的最小匹配项数量： PUT students { "mappings": { "properties": { "name": { "type": "keyword" }, "classes": { "type": "keyword" }, "min_required": { "type": "integer" } } } } 接下来，索引两个与学生相关的文档： PUT students/_doc/1 { "name": "Mary Major", "classes": [ "CS101", "CS102", "MATH101" ], "min_required": 2 } PUT students/_doc/2 { "name": "John Doe", "classes": [ "CS101", "MATH101", "ENG101" ], "min_required": 2 } 现在搜索已经修读了以下至少两门课程的学生： CS101 ， CS102 ， MATH101 ：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/terms/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/terms/Terms 查询 # 使用 terms 查询在同一字段中搜索多个词项。例如，以下查询搜索具有 ID 61809 和 61810 的文档： 相关指南（先读这些） # 结构化搜索 Query DSL 基础 GET shakespeare/_search { "query": { "terms": { "line_id": [ "61809", "61810" ] } } } 如果文档与数组中的任何词项匹配，则会返回该文档。 默认情况下， terms 查询中允许的最大词项数量为 65,536。要更改最大词项数量，请更新 index.max_terms_count 设置。 为了更好的查询性能，请传递包含已排序词项的长期数组（按 UTF-8 字节值升序排序）。 根据高亮器类型和查询中词项的数量，高亮显示词项查询结果的能力可能无法保证。 参数说明 # 该查询接受以下参数。所有参数都是可选的。 参数 数据类型 描述 <field> String 要搜索的字段。只有当文档的字段值与查询中至少一个词项完全匹配（包括正确的空格和大小写）时，该文档才会出现在结果中。 boost Float 一个浮点数值，用于指定该字段对相关性分数的权重。大于 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/wildcard/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/wildcard/Wildcard 查询 # 使用 wildcard 查询来搜索匹配通配符模式的词项。通配符查询支持以下操作符。 相关指南（先读这些） # 部分匹配 结构化搜索 通配符字段类型（Wildcard） — 专为高效通配符匹配设计的字段类型 操作符 描述 * 匹配零个或多个字符。 ? 匹配任意单个字符。 case_insensitive 若 true 为真，则通配符查询不区分大小写；若 false 为真，则通配符查询区分大小写。默认情况下 false 为真（区分大小写）。 若进行区分大小写的搜索，查找以 H 开头且以 Y 结尾的词，可使用以下请求： GET shakespeare/_search { "query": { "wildcard": { "speaker": { "value": "H*Y", "case_insensitive": false } } } } 如果你将 * 更改为 ?https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/wrapper/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/specialized/wrapper/Wrapper 查询 # wrapper 查询允许您以 Base64 编码的 JSON 格式提交完整的查询。当查询必须嵌入到仅支持字符串值的上下文中时，它非常有用。 仅当需要管理系统约束时才使用此查询。为了提高可读性和可维护性，最好尽可能使用基于 JSON 的标准查询。 相关指南（先读这些） # Query DSL 基础 专业查询（Specialized queries） 参考样例 # 使用以下映射创建名为 products 的索引： PUT /products { "mappings": { "properties": { "title": { "type": "text" } } } } 索引示例文档： POST /products/_bulk { "index": { "_id": 1 } } { "title": "Wireless headphones with noise cancellation" } { "index": { "_id": 2 } } { "title": "Bluetooth speaker" } { "index": { "_id": 3 } } { "title": "Over-ear headphones with rich bass" } 以 Base64 格式编码以下查询：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/median-absolute-deviation/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/median-absolute-deviation/中位数绝对偏差聚合 # median_absolute_deviation 聚合是一个单值指标聚合。中位数绝对偏差是一种变异性指标，用于衡量相对于中位数的离散程度。 相关指南（先读这些） # 聚合基础 聚合场景实践 与依赖平方误差项的标准偏差相比，中位数绝对偏差受异常值的影响较小，适用于描述非正态分布的数据。 中位数绝对偏差按以下方式计算： median_absolute_deviation = median( | x<sub>i</sub> - median(x<sub>i</sub>) | ) 由于内存限制，Easysearch 估计 median_absolute_deviation ，而不是直接计算它。这种估计在计算上很昂贵。您可以调整估计精度和性能之间的权衡。有关更多信息，请参阅调整估计精度。 参数说明 # median_absolute_deviation 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 要计算中位数绝对偏差的数值字段的名称。 missing 可选 Numeric 分配给字段缺失实例的值。如果未提供，则从估计中排除具有缺失值的文档。 compression 可选 Numeric 一个调整估计精度和性能之间平衡的参数。 compression 的值必须大于 0 。默认值为 1000 。 参考样例 # 以下示例计算数据集中 DistanceMiles 字段的绝对中位数偏差：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/keep-types/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/keep-types/Keep Types 分词过滤器 # keep_types 分词过滤器是一种用于文本分析的分词过滤器，它可用于控制保留或丢弃哪些词元类型。不同的分词器会产生不同的词元类型，例如 <HOST>、<NUM> 或 <ALPHANUM>。 注意：keyword 分词器、simple_pattern 分词器和 simple_pattern_split 分词器不支持 keep_types 分词过滤器，因为这些分词器不支持词元类型属性。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # 保留类型分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 types 必需 字符串列表 要保留或丢弃的词元类型列表（由 mode 参数决定）。 mode 可选 字符串 是要包含(include)还是排除(exclude) types 中指定的词元类型。默认值为 include（包含）。 参考样例 # 以下示例请求创建了一个名为 test_index 的新索引，并配置了一个带有保留类型过滤器的分析器： PUT /test_index { "settings": { "analysis": { "analyzer": { "custom_analyzer": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "keep_types_filter"] } }, "filter": { "keep_types_filter": { "type": "keep_types", "types": ["<ALPHANUM>"] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/keep-words/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/keep-words/Keep Words 分词过滤器 # keep_words 分词过滤器旨在在分析过程中仅保留特定的词。如果你有大量文本，但只对某些关键字或术语感兴趣，那么这个过滤器就会很有用。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # 词保留分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 keep_words 若未配置 keep_words_path 则为必需 字符串列表 要保留的词的列表。 keep_words_path 若未配置 keep_words 则为必需 字符串 包含要保留的词列表的文件的路径。 keep_words_case 可选 布尔值 在比较时是否将所有词转换为小写。默认值为 false。 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个带有词保留过滤器的分词器： PUT my_index { "settings": { "analysis": { "analyzer": { "custom_keep_word": { "tokenizer": "standard", "filter": [ "keep_words_filter" ] } }, "filter": { "keep_words_filter": { "type": "keep", "keep_words": ["example", "world", "easysearch"], "keep_words_case": true } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/value-count/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/value-count/值计数聚合 # value_count 聚合是一个单值指标聚合，用于计算聚合所基于的值的数量。 例如，您可以将 value_count 指标与 avg 指标一起使用来查找聚合使用多少个数字来计算平均值。 相关指南（先读这些） # 聚合基础 聚合场景实践 GET sample_data_ecommerce/_search { "size": 0, "aggs": { "number_of_values": { "value_count": { "field": "taxful_total_price" } } } } 返回内容 ... "aggregations" : { "number_of_values" : { "value" : 4675 } } } 参数说明 # 参数 必需/可选 数据类型 描述 field 必填 String 要计数的字段名称。 script 可选 Object 使用脚本生成要计数的值，替代 field。 missing 可选 任意 为缺失该字段的文档提供默认值。 value_count vs.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/global/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/global/全局聚合 # global 聚合让你能跳出过滤聚合的聚合上下文。即使你包含了一个缩小文档集的过滤查询，global 聚合仍然对所有文档进行聚合，就好像过滤查询不存在一样。它忽略 filter 聚合，并隐式地假设 match_all 查询。 相关指南（先读这些） # 聚合基础 聚合场景实践 以下示例返回索引中所有文档的 taxful_total_price 字段的 avg 值： GET sample_data_ecommerce/_search { "size": 0, "query": { "range": { "taxful_total_price": { "lte": 50 } } }, "aggs": { "total_avg_amount": { "global": {}, "aggs": { "avg_price": { "avg": { "field": "taxful_total_price" } } } } } } 返回内容 ... "aggregations" : { "total_avg_amount" : { "doc_count" : 4675, "avg_price" : { "value" : 75.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/string-field-type/keyword/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/string-field-type/keyword/Keyword 字段类型 # keyword 字段类型包含未经分析的字符串。它只允许精确的大小写敏感匹配。 默认情况下，keyword 字段既被索引（因为 index 已启用）也存储在磁盘上（因为 doc_values 已启用）。为了减少磁盘空间，您可以通过将 index 设置为 false 来指定不索引 keyword 字段。 提示：如果您需要对字段进行全文搜索，请将其映射为 text 类型。 相关指南（先读这些） # 映射基础 映射模式 结构化搜索 代码样例 # 以下查询创建了一个带有 keyword 字段的映射。将 index 设置为 false 指定将 genre 字段存储在磁盘上，并使用 doc_values 检索它： PUT movies { "mappings" : { "properties" : { "genre" : { "type" : "keyword", "index" : false } } } } 参数说明 # 下表列出了 keyword 字段类型接受的参数。所有参数都是可选的。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/keyword-marker/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/keyword-marker/Keyword Marker 分词过滤器 # keyword_marker 分词过滤器用于防止某些词元被词干提取器或其他过滤器修改。该过滤器通过将指定的词元标记为关键词来实现这一点，这样就能避免词干提取或其他方式的处理。这确保了特定的单词能保持其原始形式。 相关指南（先读这些） # 文本分析：词干提取 文本分析：规范化 参数说明 # 关键词标记分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 ignore_case 可选 布尔值 在匹配关键词时是否忽略字母大小写。默认值为false。 keywords 若未设置 keywords_path 或 keywords_pattern 则为必需 字符串列表 要标记为关键词的词元列表。 keywords_path 若未设置 keywords 或 keywords_pattern 则为必需 字符串 关键词列表的路径（相对于配置目录或绝对路径）。 keywords_pattern 若未设置 keywords 或 keywords_path 则为必需 字符串 用于匹配要标记为关键词的词元的正则表达式。 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个带有关键词标记过滤器的分词器。该过滤器将单词 example 标记为关键词：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/keyword-repeat/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/keyword-repeat/Keyword Repeat 分词过滤器 # keyword_repeat 分词过滤器会将词元的关键词版本发送到词元流中。当你希望在经过进一步的词元转换（例如词干提取或同义词扩展）之后，既保留原始词元，又保留其修改后的版本时，通常会使用这个过滤器。这些重复的词元使得原始的、未改变的词元版本能够与修改后的版本一起保留在最终的分析结果中。 注意：keyword_repeat 分词过滤器应该放置在词干提取过滤器之前。词干提取并非应用于每个词元，因此在词干提取之后，你可能会在同一位置得到重复的词元。为了去除重复词元，可以在词干提取器之后使用 remove_duplicates 分词过滤器。 相关指南（先读这些） # 文本分析：词干提取 文本分析：规范化 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个带有关键词重复过滤器的分词器： PUT /my_index { "settings": { "analysis": { "filter": { "my_kstem": { "type": "kstem" }, "my_lowercase": { "type": "lowercase" } }, "analyzer": { "my_custom_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "my_lowercase", "keyword_repeat", "my_kstem" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/distributed-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/distributed-search/分布式搜索执行过程 # 当你向 Easysearch 发起一个 /_search 请求时，集群内部会发生一系列分布式协作。理解这个过程能帮助你解释很多“看起来奇怪”的现象：为什么分页越深越慢、为什么结果顺序会抖动、为什么加副本能提高吞吐、为什么有时相关性会“不一致”。 在一个典型的搜索执行中，Easysearch 会经历两个阶段： Query phase（查询阶段）：找出每个分片上的 top-n 候选，并在协调节点合并成全局 top-n Fetch phase（取回阶段）：只取回最终需要返回的那一页文档内容，并做必要的“丰富” Query phase：每个分片产出本地 top-n # 查询阶段会把请求广播到目标索引涉及的每个分片拷贝（主分片或副本分片）。每个分片本地执行查询，并构建一个 优先队列（priority queue），保存本分片的 top-n 匹配结果。 优先队列的大小取决于分页参数： GET /_search { "from": 90, "size": 10 } 这个请求意味着需要找出“第 91～100 条”结果，所以每个分片需要构建长度为 from + size = 100 的优先队列，才有可能保证全局合并后不漏掉候选。 查询阶段（概念流程）： 客户端把 search 请求发给某个节点，该节点成为协调节点 协调节点将请求转发到所有相关分片（主或副本） 每个分片本地执行查询，返回： 文档 ID 排序所需的值（例如 _score，或排序字段的值） 协调节点把所有分片返回的候选合并到全局优先队列，得到“全局有序的 top-(from+size)” 为什么副本能提高吞吐：搜索请求可以由主分片或副本分片处理，副本越多、硬件越多，可并行处理的搜索请求也越多。 Fetch phase：只取回最终需要返回的那一页 # 查询阶段只确定“哪些文档应该在结果里”，但并没有把文档内容取回。取回阶段会：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/weighted-avg/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/weighted-avg/加权平均聚合 # weighted_avg 聚合计算跨文档数值的加权平均值。当您想计算平均值，但希望某些数据点的权重大于其他数据点时，此功能非常有用。 相关指南（先读这些） # 聚合基础 聚合场景实践 加权平均值使用公式 $\frac{\sum_{i=1}^n value_i \cdot weight_i}{\sum_{i=1}^n weight_i}$ 计算。 参数说明 # weighted_avg 聚合采用以下参数。 参数 必需/可选 描述 value 必需 定义如何获取要计算平均值的数值。需要 field 或 script 。 weight 必需 定义如何获取每个值的权重。需要 field 或 script 。 format 可选 DecimalFormat 格式字符串。返回聚合的 value_as_string 属性中的格式化输出。 value_type 可选 使用脚本或未映射字段时的值的类型提示。 可以在 value 或 weight 内指定以下参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/reverse-nested/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/reverse-nested/反向嵌套聚合 # 您可以将嵌套文档中的值聚合到其父文档中；这种聚合称为 reverse_nested。您可以使用 reverse_nested 在按嵌套对象中的字段分组后，聚合父文档中的字段。reverse_nested 聚合将"连接回"根页面，并为您的各种变体获取 load_time。 reverse_nested 聚合是嵌套聚合中的一个子聚合。它接受一个名为 path 的选项。此选项定义 Easysearch 在计算聚合时在文档层次结构中向后退多少步。 相关指南（先读这些） # 聚合基础 Nested 建模 聚合场景实践 GET logs/_search { "query": { "match": { "response": "200" } }, "aggs": { "pages": { "nested": { "path": "pages" }, "aggs": { "top_pages_per_load_time": { "terms": { "field": "pages.load_time" }, "aggs": { "comment_to_logs": { "reverse_nested": {}, "aggs": { "min_load_time": { "min": { "field": "pages.load_time" } } } } } } } } } } 返回内容https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/variable-width-histogram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/variable-width-histogram/可变宽度直方图聚合 # variable_width_histogram 聚合与标准 histogram 聚合类似，但它会自动调整每个桶的宽度，使数据点在各桶之间尽可能均匀分布。该聚合使用聚类算法，根据数据的实际分布动态确定最优的桶边界，而不是使用固定间隔。 这在数据分布不均匀时特别有用 —— 例如，大部分值集中在某个范围内，但也有少量离群值。使用固定间隔的 histogram 可能导致大量空桶或单个桶内文档过多，而 variable_width_histogram 能自适应地解决这些问题。 相关指南（先读这些） # 聚合基础 聚合场景实践 直方图聚合（固定宽度版本） 参数说明 # 参数 必需/可选 数据类型 描述 field 必填 String 要聚合的数值字段。必须为数值类型。也可使用 script 替代。 buckets 可选 Integer 期望的桶数量。实际返回的桶数量可能小于或等于此值。默认 10。必须大于 0。 shard_size 可选 Integer 每个分片上用于聚类的文档数量。值越大结果越精确，但内存消耗越大。默认为 buckets * 50。必须大于 1。 initial_buffer 可选 Integer 初始缓冲区大小，用于收集初始数据点以启动聚类算法。默认为 min(10 * shard_size, 50000)。必须大于 0 且不小于 buckets。 script 可选 Object 使用脚本动态生成聚合值。 missing 可选 Numeric 缺少字段值的文档所使用的替代值。 基本用法 # 以下示例将商品价格分成 5 个自适应宽度的桶：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/geocentroid/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/geocentroid/地理中心点聚合 # geo_centroid 聚合计算一组 geo_point 值的地理中心或焦点。它将中心位置作为纬度-经度对返回。 相关指南（先读这些） # 聚合基础 地理位置搜索 Geo 场景实践 参数说明 # geo_centroid 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 包含计算中心的地理点的字段的名称。 参考样例 # 以下示例返回数据中每个订单的 geo_centroid 的 geoip.location 。每个 geoip.location 都是一个地理点： GET /sample_data_ecommerce/_search { "size": 0, "aggs": { "centroid": { "geo_centroid": { "field": "geoip.location" } } } } 返回内容 # 返回内容包括一个 centroid 对象，该对象具有 lat 和 lon 属性，表示所有索引数据点的中心位置：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/geo-distance/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/geo-distance/地理距离聚合 # geo_distance 聚合根据与一个起始 geo_point 字段距离将文档分组到同心圆中。它与 range 聚合相同，只是它作用于地理位置。 相关指南（先读这些） # 聚合基础 地理位置搜索 Geo 场景实践 例如，你可以使用 geo_distance 聚合来查找你 1 公里范围内的所有披萨店。搜索结果仅限于你指定的 1 公里半径范围内，但你还可以添加另一个在 2 公里范围内找到的结果。 您只能对映射为 geo_point 的字段使用 geo_distance 聚合。 点是一个单一的地理坐标，例如您智能手机显示的当前位置。在 Easysearch 中，点表示如下： { "location": { "type": "point", "coordinates": { "lat": 83.76, "lon": -81.2 } } } 您还可以将纬度和经度指定为数组 [-81.20, 83.76] 或字符串 "83.76, -81.20" 此表列出了 geo_distance 聚合的相关字段： 字段 必需/可选 描述 field 必需 指定您要处理的地理点字段。 origin 必需 指定用于计算距离的地理点。 ranges 必需 指定一组范围，根据文档与目标点的距离收集文档。 unit 可选 定义 ranges 数组中使用的单位。 unit 默认为 m （米），但你可以切换到其他单位，如 km （千米）、 mi （英里）、 in （英寸）、 yd （码）、 cm （厘米）和 mm （毫米）。 distance_type 可选 指定 Easysearch 如何计算距离。默认值为 sloppy_arc （更快但精度较低），也可以设置为 arc （较慢但最精确）或 plane （最快但精度最低）。由于误差范围较大，仅适用于小地理区域使用 plane 。 语法如下：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/geobounds/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/geobounds/地理边界聚合 # geo_bounds 聚合是一个多值指标聚合，用于计算包含一组 geo_point 或 geo_shape 对象的地理边界框。边界框以十进制编码的经纬度（lat-lon）对形式返回，作为矩形的左上角和右下角顶点。 相关指南（先读这些） # 聚合基础 地理位置搜索 Geo 场景实践 参数说明 # geo_bounds 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 计算地理边界所使用的包含地理点或地理形状的字段的名称。 wrap_longitude 可选 Boolean 是否允许边界框与国际日期变更线重叠。默认值为 true 。 参考样例 # 以下示例查询数据中每个订单的 geo_bounds 的 geoip.location （每个 geoip.location 是一个地理点）： GET sample_data_ecommerce/_search { "size": 0, "aggs": { "geo": { "geo_bounds": { "field": "geoip.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/cardinality/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/cardinality/基数聚合 # cardinality 聚合是一种单值指标聚合，用于计算字段的唯一值或不同值的数量。 基数计数为近似值。有关更多信息，请参阅下面的控制精度。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # cardinality 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需的 String 估计基数的字段。 precision_threshold 可选 Numeric 阈值，低于该阈值的计数预计接近准确值。有关更多信息，请参阅控制精度 。 execution_hint 可选 String 如何运行聚合，该参数会影响资源使用和聚合效率。有效值为 ordinals 和 direct 。 missing 可选 与 field 类型相同 用于存储字段缺失实例的 bucket。如果未提供，则忽略缺失值。 参考样例 # 以下示例请求查找数据中唯一产品 ID 的数量：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/composite/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/composite/复合聚合 # composite 聚合基于一个或多个文档字段或源创建分组。composite 聚合为每个单独源值的组合创建一个分组。默认情况下，如果一个或多个字段中缺少值，则这些组合会从结果中省略。 相关指南（先读这些） # 聚合基础 聚合场景实践 每个源有四种类型的聚合之一： terms 类型按唯一（通常是 String ）值分组。 histogram 类型按指定宽度数值分组。 date_histogram 类型按指定宽度的日期或时间范围分组。 geotile_grid 类型按指定分辨率将地理点分组到网格中。 composite 聚合通过将其源键组合到分组中来工作。生成的分组是有序的，跨源(Across)和源内部(Within)都是： Across：分组按聚合请求中源的顺序嵌套。 Within:每个源中值的顺序决定了该源的分组顺序。排序方式根据源类型适当选择，可以是字母顺序、数字顺序、日期时间顺序或地理切片顺序。 考虑一下来自马拉松参与者索引的这些字段： {... "city": "Albuquerque", "place": "Bronze" ...} {... "city": "Boston", ...} {... "city": "Chicago", "place": "Bronze" ...} {... "city": "Albuquerque", "place": "Gold" ...} {... "city": "Chicago", "place": "Silver" ...} {... "city": "Boston", "place": "Bronze" ...} {... "city": "Chicago", "place": "Gold" .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/diversified-sampler/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/diversified-sampler/多样性采样聚合 # diversified_sampler 聚合允许你通过去重包含相同 field 的文档来减少样本池分布的偏差。它通过使用 max_docs_per_value 和 field 设置来实现，这些设置限制了在分片上收集的 field 的最大文档数。max_docs_per_value 设置是一个可选参数，用于确定每个 field 将返回的最大文档数。此设置的默认值为 1。 与 sampler 聚合类似，你可以使用 shard_size 设置来控制在任何单个分片上收集的最大文档数，如下面的示例所示： 相关指南（先读这些） # 聚合基础 聚合性能优化 聚合场景实践 GET sample_data_logs/_search { "size": 0, "aggs": { "sample": { "diversified_sampler": { "shard_size": 1000, "field": "response.keyword" }, "aggs": { "terms": { "terms": { "field": "agent.keyword" } } } } } } 返回内容 ... "aggregations" : { "sample" : { "doc_count" : 3, "terms" : { "doc_count_error_upper_bound" : 0, "sum_other_doc_count" : 0, "buckets" : [ { "key" : "Mozilla/5.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/filters/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/filters/多过滤器聚合 # filters 聚合与 filter 聚合相同，但它允许你使用多个过滤器聚合。filter 聚合结果为一个分组，而 filters 聚合会返回多个分组，每个定义的过滤器对应一个分组。 相关指南（先读这些） # 聚合基础 聚合场景实践 要为所有未匹配任何过滤器查询的文档创建一个分组，将 other_bucket 属性设置为 true ： GET sample_data_logs/_search { "size": 0, "aggs": { "200_os": { "filters": { "other_bucket": true, "filters": [ { "term": { "response.keyword": "200" } }, { "term": { "machine.os.keyword": "osx" } } ] }, "aggs": { "avg_amount": { "avg": { "field": "bytes" } } } } } } 返回内容https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/children/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/children/子文档聚合 # children 聚合是一种存储分组聚合，它根据索引中定义的父子关系创建包含子文档的单个存储分组。 children 聚合与 join 字段类型配合使用，以聚合与父文档关联的子文档。 children 聚合标识与特定子关系名称匹配的子文档，而 parent 聚合标识具有匹配子文档的父文档。这两个聚合都采用子关系名称作为输入。 相关指南（先读这些） # 聚合基础 Parent-Child 建模 聚合场景实践 参数说明 # children 聚合采用以下参数。 参数 必需/可选 数据类型 描述 type 必填 String join 字段中的子类型的名称。这标识了要使用的父子关系。 参考样例 # 以下示例构建一个包含三名员工的小型公司数据库。每个员工记录都与父部门记录具有子联接关系。 首先，创建一个 company 索引，其中包含一个将部门（父级）映射到员工（子级）的联接字段： PUT /company { "mappings": { "properties": { "join_field": { "type": "join", "relations": { "department": "employee" } }, "department_name": { "type": "keyword" }, "employee_name": { "type": "keyword" }, "salary": { "type": "double" }, "hire_date": { "type": "date" } } } } 接下来，使用三个部门和三名员工填充数据。下表显示了父子分配。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/derivative/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/derivative/导数聚合 # derivative 聚合是一个父聚合，用于计算聚合每个分组的一阶和二阶导数。 对于有序的分组序列，derivative 将当前分组和前一个分组中的指标值之差近似为一阶导数。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # derivative 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as_string 属性中的格式化输出。 示例：一阶导数 # 以下示例创建一个每月间隔的日期直方图。 sum 子聚合计算每个月所有字节的和。最后， derivative 聚合计算 sum 子聚合的一阶导数。一阶导数估计为当前月份和上个月字节数之间的差值：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/nested/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/nested/嵌套聚合 # nested 聚合让你能够对嵌套对象内的字段进行聚合。nested 类型是对象数据类型的特殊版本，它允许对象数组以独立于彼此的方式进行索引，从而可以独立于彼此进行查询。 相关指南（先读这些） # 聚合基础 Nested 建模 聚合场景实践 使用 object 类型，所有数据都存储在同一个文档中，因此搜索匹配可以跨越子文档。例如，想象一个 logs 索引，其中 pages 映射为 object 数据类型： PUT logs/_doc/0 { "response": "200", "pages": [ { "page": "landing", "load_time": 200 }, { "page": "blog", "load_time": 500 } ] } Easysearch 合并所有看起来像这样的实体关系的子属性： { "logs": { "pages": ["landing", "blog"], "load_time": ["200", "500"] } } 所以，如果你想要用 pages=landing 和 load_time=500 搜索这个索引，即使 load_time 的 landing 值为 200，这个文档也符合条件。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/average/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/average/平均值聚合 # avg 聚合是一个单值指标聚合，它返回某个字段的平均值。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # avg 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 计算平均值的字段。 missing 可选 Float 要分配给字段缺失实例的值。默认情况下， avg 会在计算中忽略缺失值。 参考样例 # 以下示例请求计算示例数据中 taxful_total_price 字段的平均值： GET sample_data_ecommerce/_search { "size": 0, "aggs": { "avg_taxful_total_price": { "avg": { "field": "taxful_total_price" } } } } 返回内容 # 返回内容包含 taxful_total_price 的平均值：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/avg-bucket/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/avg-bucket/平均桶聚合 # avg_bucket 聚合是一个同级聚合，它计算上一个聚合的每个分组中的指标平均值。 指定的指标必须是数值型的，且同级聚合必须是多分组聚合。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # avg_bucket 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合存储分组的路径。请参阅存储分组路径 。 gap_policy 可选 String 要应用于缺失数据的策略。有效值为 skip 和 insert_zeros。默认值为 skip。请参阅数据差距 。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as_string 属性中的格式化输出 。 参考样例 # 以下示例创建间隔为一个月的日期直方图。sum 子聚合计算每个月的字节总和。最后，avg_bucket 聚合根据这些总和计算每月的平均字节数： POST sample_data_logs/_search { "size": 0, "aggs": { "visits_per_month": { "date_histogram": { "field": "@timestamp", "interval": "month" }, "aggs": { "sum_of_bytes": { "sum": { "field": "bytes" } } } }, "avg_monthly_bytes": { "avg_bucket": { "buckets_path": "visits_per_month>sum_of_bytes" } } } } 返回内容 # 聚合返回每月存储分组的平均字节数：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/serial-diff/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/serial-diff/序列差分聚合 # serial_diff 聚合是一个父级管道聚合，用于计算当前分组中指标值与上一个分组中指标值之间的差值。它将结果存储在当前分组中。 使用 serial_diff 聚合来计算具有指定滞后的时间段之间的变化。lag 参数（一个正整数值）指定要从中减去当前值的哪个先前分组的值。默认的 lag 值是 1，这意味着 serial_diff 从当前分组中的值减去立即前一个分组中的值。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # serial_diff 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as _string 属性中的格式化输出。 lag 可选 Integer 用于从当前数据分组中减去的历史数据分组。必须是正整数。默认为 1 。 参考样例 # 以下示例创建一个日期直方图，间隔为一个月。 sum 子聚合计算每个月的字节总和。最后， serial_diff 聚合计算这些总和之间的月度字节差异：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/extended-stats/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/extended-stats/扩展统计桶聚合 # extended_stats_bucket 聚合是 stats_bucket 同级聚合的更全面的版本。除了 stats_bucket 提供的基本统计度量外，extended_stats_bucket 还计算以下指标： 平方和 方差 总体方差 抽样方差 标准差 总体标准差 抽样标准差 标准差界限： ** 上限 ** 下限 ** 种群上限 ** 种群下限 ** 采样上限 ** 采样下限 标准差和方差是总体统计量；它们分别始终等于总体标准差和方差。 std_deviation_bounds 对象定义了一个范围，该范围在均值（默认为两个标准差）的上方和下方跨越指定的标准差数量。此对象始终包含在输出中，但仅对正态分布的数据才有意义。在解释这些值之前，请验证您的数据集是否遵循正态分布。 指定的指标必须是数值型，并且同级聚合必须是多分组聚合。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # extended_stats_bucket 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as_string 属性中的格式化输出。 sigma 可选 Double 非负） 用于计算 std_deviation_bounds 区间的均值上方和下方的标准差数量。默认值为 2 。参见 extended_stats 中定义范围。 参考样例 # 以下示例创建一个以一个月为间隔的日期直方图。 sum 子聚合计算每个月的字节总和。最后， extended_stats_bucket 聚合返回这些总和的扩展统计信息：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/extended-stats/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/extended-stats/扩展统计聚合 # extended_stats 聚合是 stats 聚合的更全面版本。除了 stats 提供的基本统计指标外，extended_stats 还计算以下内容： 相关指南（先读这些） # 聚合基础 聚合场景实践 平方和 方差 总体方差 抽样方差 标准差 总体标准差 抽样标准差 标准差界限： ** 上限 ** 下限 ** 总体上限 ** 总体下限 ** 抽样上限 ** 抽样下限 其中标准差和方差是总体统计量；它们分别始终等于总体标准差和方差。 std_deviation_bounds 对象定义了一个范围，该范围在均值（默认为两个标准差）的上方和下方跨越指定的标准差数量。此对象始终包含在输出中，但仅对正态分布的数据才有意义。在解释这些值之前，请验证您的数据集是否遵循正态分布。 参数说明 # extended_stats 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 返回扩展统计信息的字段名称。 sigma 可选 Double（非负） 计算 std_deviation_bounds 区间所使用的均值上下标准差的数量。默认值为 2 。 missing 可选 Numeric 分配给字段缺失实例的值。如果未提供，包含缺失值的文档将不会出现在扩展统计中。 参考样例 # 以下示例请求数据中 taxful_total_price 的扩展统计信息：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/rank/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/rank/Rank 字段类型 # 下表列出了 Easysearch 支持的所有 rank 字段类型。 字段数据类型 描述 rank_feature 提升或降低文档的相关性得分。 rank_features 提升或降低文档的相关性得分。用于特征列表稀疏的情况。 注意：rank_feature 和 rank_features 字段只能使用 rank_feature 查询进行查询。它们不支持聚合或排序。 相关指南（先读这些） # 映射基础 相关性：加权与调参 排序功能查询 Rank feature 字段类型 # Rank feature 字段类型使用正浮点值来提升或降低文档在 rank_feature 查询中的相关性得分。默认情况下，该值会提升相关性得分。要降低相关性得分，请将可选参数 positive_score_impact 设置为 false。 示例 # 创建一个包含 rank feature 字段的映射： PUT chessplayers { "mappings": { "properties": { "name": { "type": "text" }, "rating": { "type": "rank_feature" }, "age": { "type": "rank_feature", "positive_score_impact": false } } } } 索引三个文档，其中包含一个提升得分的 rank_feature 字段（rating）和一个降低得分的 rank_feature 字段（age）：https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/troubleshooting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/troubleshooting/故障排查 # 本文提供一条"遇到问题时可以照着走"的诊断路线，包含具体的诊断命令和解决方案。 排查总体思路 # 遇到问题时，先快速判断三个问题： ┌─────────────────────────────────────────────────────────────────────────┐ │ 1. 影响范围：单个索引/租户？还是整个集群？ │ ├─────────────────────────────────────────────────────────────────────────┤ │ 2. 症状类型：性能下降？错误增多？节点异常？数据不符合预期？ │ ├─────────────────────────────────────────────────────────────────────────┤ │ 3. 时间维度：长期慢性问题？还是某个时间点突然恶化？ │ └─────────────────────────────────────────────────────────────────────────┘ 问题 1：集群状态变红/黄 # 快速诊断 # # 1. 检查集群状态 GET _cluster/health # 2. 查看未分配分片 GET _cat/shards?v&h=index,shard,prirep,state,unassigned.reason&s=state # 3. 分析未分配原因 GET _cluster/allocation/explain 常见原因与解决方案 # 原因 1：节点离线 # 诊断： GET _cat/nodes?v 检查节点数是否符合预期，缺失的节点需要检查： 进程是否存活：ps aux | grep easysearch 系统日志：journalctl -u easysearch Easysearch 日志：logs/{cluster_name}.log 解决方案：https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/field-masking/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/field-masking/数据脱敏 # 如果您的数据里面包含一些敏感信息，除了通过 字段级权限 来进行访问控制，您还可以通过混淆字段里面的内容来进行脱敏。目前，字段数据脱敏仅适用于基于字符串的字段，支持加密哈希和正则替换字段的内容。 字段脱敏与字段级权限一起可以在相同的角色级别和索引级别上工作。您可以允许某些角色查看明文格式的敏感字段，并为其他角色脱敏这些字段。带有脱敏字段的搜索结果可能如下所示： { "_index": "movies", "_type": "_doc", "_source": { "year": 2013, "directors": ["Ron Howard"], "title": "ca998e768dd2e6cdd84c77015feb29975f9f498a472743f159bec6f1f1db109e" } } 设置盐值 # 可以在 easysearch.yml 设置一个随机字符串: security.compliance.salt: abcdefghijklmnopqrstuvqxyz1234567890 属性 说明 security.compliance.salt 生成哈希值时要使用的盐值。必须至少为 32 个字符。仅允许使用 ASCII 字符。选填。 配置脱敏字段 # role.yml # masked_movie: cluster: [] indices: - names: - movies privileges: - "read" field_mask: - "genres" - "title" REST API # 参照 创建角色.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/string-field-type/text/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/string-field-type/text/Text 字段类型 # text 字段类型包含经过分析器分析的字符串。它用于全文搜索，因为它允许部分匹配。对多个词条的搜索可以匹配其中的一部分而不是全部。根据分析器的不同，搜索结果可以是大小写不敏感的、词干化的、去除停用词的、应用同义词的等等。 提示：如果您需要进行精确值搜索，请将字段映射为 keyword 类型。 相关指南（先读这些） # 映射基础 映射模式 全文搜索 代码样例 # 创建一个带有 text 字段的映射： PUT movies { "mappings" : { "properties" : { "title" : { "type" : "text" } } } } 参数说明 # 下表列出了 text 字段类型接受的参数。所有参数都是可选的。 参数 描述 analyzer 用于此字段的分词器。默认情况下，它将在索引时和搜索时使用。要在搜索时覆盖它，请设置 search_analyzer 参数。默认是 standard 分词器，它使用基于语法的分词，并基于 Unicode 文本分段算法。 boost 浮点值，指定此字段对相关性分数的权重。大于 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/date-histogram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/date-histogram/日期直方图聚合 # date_histogram 聚合使用日期计算来为时间序列数据生成直方图。 相关指南（先读这些） # 聚合基础 聚合场景实践 时间序列建模 例如，您可以找到您的网站每月有多少次访问： GET sample_data_logs/_search { "size": 0, "aggs": { "logs_per_month": { "date_histogram": { "field": "@timestamp", "interval": "month" } } } } 返回内容 ... "aggregations" : { "logs_per_month" : { "buckets" : [ { "key_as_string" : "2020-10-01T00:00:00.000Z", "key" : 1601510400000, "doc_count" : 1635 }, { "key_as_string" : "2020-11-01T00:00:00.000Z", "key" : 1604188800000, "doc_count" : 6844 }, { "key_as_string" : "2020-12-01T00:00:00.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/date-range/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/date-range/日期范围聚合 # date_range 聚合在概念上与 range 聚合相同，只是它允许执行日期计算。例如，你可以获取过去 10 天内的所有文档。为了使日期更易读，可以使用 format 参数包含格式： 相关指南（先读这些） # 聚合基础 聚合场景实践 时间序列建模 GET sample_data_logs/_search { "size": 0, "aggs": { "number_of_bytes": { "date_range": { "field": "@timestamp", "format": "MM-yyyy", "ranges": [ { "from": "now-10d/d", "to": "now" } ] } } } } 返回内容 ... "aggregations" : { "number_of_bytes" : { "buckets" : [ { "key" : "03-2021-03-2021", "from" : 1.6145568E12, "from_as_string" : "03-2021", "to" : 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/mapping/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/mapping/Mapping 字符过滤器 # mapping 字符过滤器接受一个用于字符替换的键值对映射。每当该过滤器遇到与某个键匹配的字符串时，它就会用相应的值来替换这些字符。替换值可以是空字符串。 该过滤器采用贪婪匹配方式，这意味着会匹配最长的匹配结果。 在分词过程之前，需要进行特定文本替换的场景下，mapping 字符过滤器会很有帮助。 相关指南（先读这些） # 文本分析基础 文本分析：规范化 参考样例 # 以下请求配置了一个映射字符过滤器，该过滤器可将罗马数字（如 I、II 或 III）转换为对应的阿拉伯数字（1、2 和 3）： GET /_analyze { "tokenizer": "keyword", "char_filter": [ { "type": "mapping", "mappings": [ "I => 1", "II => 2", "III => 3", "IV => 4", "V => 5" ] } ], "text": "I have III apples and IV oranges" } 返回内容中包含一个词元，其中罗马数字已被替换为阿拉伯数字： { "tokens": [ { "token": "1 have 3 apples and 4 oranges", "start_offset": 0, "end_offset": 32, "type": "word", "position": 0 } ] } 参数说明 # 你可以使用以下任意一个参数来配置键值映射。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/significant-text/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/significant-text/显著文本聚合 # significant_text 聚合与 significant_terms 聚合类似，但它适用于原始文本字段。重要文本通过统计分析测量前景集和背景集之间流行度的变化。例如，当你搜索其股票缩写 TSLA 时，它可能会建议 Tesla。 significant_text 聚合会动态重新分析源文本，过滤掉重复段落、模板化的页眉和页脚等噪声数据，这些数据可能会扭曲结果。 重新分析高基数数据集可能是一项非常耗费 CPU 的操作。我们建议在采样聚合中使用 significant_text 聚合来将分析限制在少量最匹配文档中，例如 200。 相关指南（先读这些） # 聚合基础 聚合性能优化 聚合场景实践 您可以设置以下参数： size - 返回的最大桶数量。默认 10。 min_doc_count - 返回匹配超过配置数量的 Top Hits 结果。我们不建议将 min_doc_count 设置为 1，因为它倾向于返回拼写错误或错别字。找到一个以上的词项实例有助于加强显著性不是偶然事件的结果。默认值 3 用于提供最小证据权重。 shard_size - 设置高值会增加稳定性（和准确性），但会牺牲计算性能。 shard_min_doc_count - 如果你的文本包含许多低频词，而你又不关心这些词（例如拼写错误），那么你可以将 shard_min_doc_count 参数设置为在分片级别上过滤候选词，以合理地确保即使合并本地显著文本频率也不会达到所需的 min_doc_count 。默认值为 1，直到你显式设置它之前没有影响。我们建议将此值设置得远低于 min_doc_count 值。 filter_duplicate_text - 是否过滤掉重复的文本段落（如模板化页眉/页脚）。默认 true。设为 false 可提升性能，但可能引入噪声。 假设你在一个 Easysearch 集群中索引了莎士比亚的全部作品。你可以在 text_entry 字段中找到与“breathe”相关的显著文本：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/significant-terms/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/significant-terms/显著词项聚合 # significant_terms 聚合可以帮助你在相对于索引中其他数据的过滤子集中识别不寻常或有趣的分组出现情况。 前景集是指你进行过滤的文档集合，背景集是指索引中所有文档的集合。significant_terms 聚合会检查前景集中的所有文档，并与背景集中的文档进行对比，从而为重要出现情况找到相应的分数。 相关指南（先读这些） # 聚合基础 聚合场景实践 在示例网络日志数据中，每个文档都有一个包含访客 user-agent 的字段。此示例搜索来自 iOS 操作系统的所有请求。对这一前景集进行常规的 terms 聚合返回 Firefox，因为它在这个分组内有最多的文档数量。另一方面， significant_terms 聚合返回 Internet Explorer（IE），因为 IE 在前景集中的出现频率显著高于背景集。 GET sample_data_logs/_search { "size": 0, "query": { "terms": { "machine.os.keyword": [ "ios" ] } }, "aggs": { "significant_response_codes": { "significant_terms": { "field": "agent.keyword" } } } } 返回内容 ... "aggregations" : { "significant_response_codes" : { "doc_count" : 2737, "bg_count" : 14074, "buckets" : [ { "key" : "Mozilla/4.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/maximum/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/maximum/最大值聚合 # max 聚合是一个单值指标聚合，返回字段的最大值。 相关指南（先读这些） # 聚合基础 聚合场景实践 max 聚合使用 double （双精度）表示来比较数值字段。对于包含 long 或 unsigned_long 超过 2^53 的整数值的字段，结果应被视为近似值，因为 double 的尾数中的有效位数是 53。 参数说明 # max 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 计算最大值的字段名称。 missing 可选 Numeric 分配给字段缺失实例的值。如果未提供，则包含缺失值的文档将从聚合中排除。 参考样例 # 以下示例请求在数据中查找最昂贵的商品——即 base_unit_price 值最大的商品： GET sample_data_ecommerce/_search { "size": 0, "aggs": { "max_base_unit_price": { "max": { "field": "products.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/max-bucket/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/max-bucket/最大桶聚合 # max_bucket 聚合是一个同级聚合，用于计算先前聚合中每个分组中某个指标的最大值。 指定的指标必须是数值型，并且同级聚合必须是多分组聚合。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # max_bucket 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as_string 属性中的格式化输出。 参考样例 # 以下示例创建一个日期直方图，间隔为一个月。 sum 子聚合计算每个月的字节总和。最后， max_bucket 聚合找到最大值——这些分组中最大的那个： POST sample_data_logs/_search { "size": 0, "aggs": { "visits_per_month": { "date_histogram": { "field": "@timestamp", "interval": "month" }, "aggs": { "sum_of_bytes": { "sum": { "field": "bytes" } } } }, "max_monthly_bytes": { "max_bucket": { "buckets_path": "visits_per_month>sum_of_bytes" } } } } 返回内容 # max_bucket 聚合返回跨多个分组的指定指标的最大值。在这个示例中，它计算了 sum_of_bytes 指标在 visits_per_month 中的每月最大字节数。 value 字段显示了在所有分组中找到的最大值。 keys 数组包含观察到该最大值的分组的键。它是一个数组，因为多个分组可以具有相同最大值。在这种情况下，所有匹配的分组键都会被包含。这确保了即使多个时间段（或分组项）具有相同最大值，结果也是准确的：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/minimum/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/minimum/最小值聚合 # min 聚合是一个单值指标聚合，返回字段的最小值。 相关指南（先读这些） # 聚合基础 聚合场景实践 min 聚合使用 double （双精度）表示来比较数值字段。对于包含 long 或 unsigned_long 且绝对值大于 2 53 的字段，结果应被视为近似值，因为 double 尾数中的有效位数是 53。 参数说明 # min 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 计算最小值的字段名称。 missing 可选 Numeric 分配给字段缺失实例的值。如果未提供，则包含缺失值的文档将从聚合中排除。 参考样例 # 以下示例请求在样本数据中查找最便宜的商品——即 base_unit_price 值最小的商品： GET sample_data_ecommerce/_search { "size": 0, "aggs": { "min_base_unit_price": { "min": { "field": "products.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/min-hash/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/min-hash/Min Hash 分词过滤器 # min_hash 分词过滤器用于基于最小哈希近似算法为词元生成哈希值，这对于检测文档间的相似度很有用。min_hash 分词过滤器会为一组词元（通常来自一个经过分词的字段）生成哈希值。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # 最小哈希分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 hash_count 可选 整数 为每个词元生成的哈希值数量。增加此值通常会提高相似度估计的准确性，但会增加计算成本。默认值为 1。 bucket_count 可选 整数 要使用的哈希桶数量。这会影响哈希的粒度。更多的桶能提供更细的粒度并减少哈希冲突，但需要更多内存。默认值为 512。 hash_set_size 可选 整数 每个桶中要保留的哈希数量。这会影响哈希质量。更大的集合大小可能会带来更好的相似度检测效果，但会消耗更多内存。默认值为 1。 with_rotation 可选 布尔值 当设置为 true 时，如果 hash_set_size 为 1，过滤器会用从其右侧按环形顺序找到的第一个非空桶的值填充空桶。如果 bucket_count 参数大于 1，此设置会自动默认为 true；否则，默认为 false。 参考样例 # 以下示例请求创建了一个名为 minhash_index 的新索引，并配置了一个带有最小哈希过滤器的分词器：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/min-bucket/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/min-bucket/最小桶聚合 # min_bucket 聚合是一个同级聚合，用于计算先前聚合中每个分组中某个指标的最小值。 指定的指标必须是数值型，并且同级聚合必须是多分组聚合。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # min_bucket 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as _string 属性中的格式化输出。 参考样例 # 以下示例创建一个日期直方图，间隔为一个月。 sum 子聚合计算每个月的字节总和。最后， min_bucket 聚合找到最小值——这些分组中最小的一个： POST sample_data_logs/_search { "size": 0, "aggs": { "visits_per_month": { "date_histogram": { "field": "@timestamp", "interval": "month" }, "aggs": { "sum_of_bytes": { "sum": { "field": "bytes" } } } }, "min_monthly_bytes": { "min_bucket": { "buckets_path": "visits_per_month>sum_of_bytes" } } } } 返回内容 # min_bucket 聚合返回跨多个分组的指定指标的最小值。在这个示例中，它计算了 sum_of_bytes 指标在 visits_per_month 中的每月最小字节数。 value 字段显示了在所有分组中找到的最小值。 keys 数组包含观察到该最小值的分组的键。它是一个数组，因为多个分组可以具有相同的最小值。在这种情况下，所有匹配的分组键都会被包含。这确保了即使多个时间段（或分组项）具有相同的最小值，结果也是准确的：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/bucket-sort/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/bucket-sort/桶排序聚合 # bucket_sort 聚合是一个父聚合，它对其父多存储分组聚合生成的存储分组进行排序或截断。 在 bucket_sort 聚合中，您可以按多个字段对存储分组进行排序，每个字段都有自己的排序顺序。可以按存储分组的键、文档计数或子聚合中的值进行排序。您还可以使用 from 和 size 参数来截断结果，无论是否进行排序。 有关指定排序顺序的信息，请参阅排序结果。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # bucket_sort 聚合采用以下参数。 参数 必需/可选 数据类型 描述 gap_policy 可选 String 要应用于缺失数据的策略。有效值为 skip 和 insert_zeros。默认值为 skip。请参阅数据差距 。 sort 可选 String 要排序的字段列表。请参阅排序结果 。 from 可选 String 要返回的第一个结果的索引。必须是非负整数。默认值为 0。请参阅 from 和 size 参数 。 size 可选 String 要返回的最大结果数。必须是正整数。请参阅 from 和 size 参数 。 您必须至少提供一个 sort、from 和 size。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/bucket-script/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/bucket-script/桶脚本聚合 # bucket_script 聚合是一个父管道聚合，它执行脚本以跨一组存储分组执行每个存储分组的数字计算。使用 bucket_script 聚合对分分组聚合中的多个指标执行自定义数值计算。例如，您可以： 计算派生指标和复合指标。 使用 if/else 语句应用条件逻辑。 计算特定于业务的 KPI，例如自定义评分指标。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # bucket_script 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 Object 一个变量名称到分分组指标的映射，用于识别脚本中使用的指标。这些指标必须是数值型。参见脚本变量 。 script 必需 String 或 Object 要执行的脚本。可以是内联脚本、存储脚本或脚本文件。脚本可以访问通过 buckets_path 参数定义的变量名。必须返回一个数值。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认值为 skip 。详见 数据空缺。 format 可选 String 一个 DecimalFormat 格式化字符串。将在聚合的 value_as_string 参数中返回格式化后的输出。 脚本变量 # buckets_path 参数将脚本变量名称映射到父聚合的指标。然后可以在脚本中使用这些变量。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/bucket-selector/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/bucket-selector/桶选择器聚合 # bucket_selector 聚合是一个父管道聚合，它评估脚本以确定直方图（或 date_histogram）聚合返回的存储分组是否应包含在最终结果中。 与创建新值的管道聚合不同，bucket_selector 聚合充当筛选器，根据指定的条件保留或删除整个存储分组。使用此聚合可根据存储分组的计算指标筛选存储分组。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # bucket_selector 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 Object 变量名称到分分组指标的映射，用于标识要在脚本中使用的指标。指标必须是数字。请参阅脚本变量 。 script 必需 String 或 Object 要执行的脚本。可以是内联脚本、存储脚本或脚本文件。该脚本可以访问 buckets_path 参数中定义的变量名称。必须返回布尔值。返回 false 的存储分组将从最终输出中删除。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认值为 skip 。详见 数据空缺。 参考样例 # 以下示例创建间隔为一周的日期直方图。sum 子聚合计算每周所有销售额的总和。最后，bucket_selector 聚合会筛选生成的每周存储分组，删除所有总值不超过 75,000 美元的存储分组：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/pattern-replace/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/pattern-replace/Pattern Replace 字符过滤器 # pattern_replace 字符过滤器使你能够使用正则表达式来定义文本匹配替换的模式。对于文本转换的高阶需求场景，尤其是在处理复杂的字符串模式时，它是一种灵活的工具。 这个过滤器会用替换符合匹配模式的所有匹配项，从而可以轻松地对输入文本进行替换、删除或复杂的修改。你可以在分词之前使用它对输入内容进行规范化处理。 相关指南（先读这些） # 文本分析基础 文本分析：规范化 参考样例 # 为了规范电话号码，你可以使用正则表达式 [\\s()-]+去替换号码里的特殊格式： []：定义一个字符类，意味着它将匹配方括号内的任意一个字符。 \\s：匹配任何空白字符，如空格、制表符或换行符。 ()：匹配字面意义上的括号（( 或 )）。 -：匹配字面意义上的连字符（-）。 +：指定该模式应匹配前面字符的一次或多次出现。 模式 [\\s()-]+ 将匹配由一个或多个空白字符、括号或连字符组成的任意序列，并将其从输入文本中移除。这确保了电话号码得到规范处理，结果将仅包含数字。 以下请求通过移除空格、连字符和括号来规范电话号码： GET /_analyze { "tokenizer": "standard", "char_filter": [ { "type": "pattern_replace", "pattern": "[\\s()-]+", "replacement": "" } ], "text": "(555) 123-4567" } 返回内容中包含生成的词元： { "tokens": [ { "token": "5551234567", "start_offset": 1, "end_offset": 14, "type": "<NUM>", "position": 0 } ] } 参数说明 # pattern_replace 字符过滤器必须使用以下参数进行配置。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/sum-bucket/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/sum-bucket/求和桶聚合 # sum_bucket 聚合是一个同级聚合，用于计算先前聚合中每个分组中指标的总和。 指定的指标必须是数值型，并且同级聚合必须是多分组聚合。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # sum_bucket 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as _string 属性中的格式化输出。 参考样例 # 以下示例创建一个日期直方图，间隔为一个月。 sum 子聚合计算每个月的字节总和。最后， sum_bucket 聚合通过汇总这些总和来计算每个月的总字节数： POST sample_data_logs/_search { "size": 0, "aggs": { "visits_per_month": { "date_histogram": { "field": "@timestamp", "interval": "month" }, "aggs": { "sum_of_bytes": { "sum": { "field": "bytes" } } } }, "sum_monthly_bytes": { "sum_bucket": { "buckets_path": "visits_per_month>sum_of_bytes" } } } } 返回内容 # 该聚合返回所有月度分组中的字节总和：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/sum/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/sum/求和聚合 # sum 聚合是一种单值指标聚合，计算字段中匹配文档中提取的数值的总和。此聚合常用于计算诸如收入、数量或持续时间等指标的总计。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # sum 聚合接受以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 聚合的字段。必须是数值字段。 script 可选 Object 用于计算聚合自定义值的脚本。可以替代或与 field 结合使用。 missing 可选 Number 缺少目标字段时使用的默认值。 参考样例 # 以下示例演示了如何计算物流索引中记录的交付总重量。 创建一个索引： PUT /deliveries { "mappings": { "properties": { "shipment_id": { "type": "keyword" }, "weight_kg": { "type": "double" } } } } 添加示例文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/top-hits/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/top-hits/热门匹配聚合 # top_hits 聚合是一种多值指标聚合，它根据聚合字段的相关性评分对匹配文档进行排名。 相关指南（先读这些） # 聚合基础 聚合场景实践 您可以指定以下选项： from : 命中的起始位置。 size : 返回命中的最大数量。默认值为 3。 sort : 匹配命中的排序方式。默认情况下，命中的排序依据聚合查询的相关性得分。 以下示例返回数据中的前 5 个产品： GET sample_data_ecommerce/_search { "size": 0, "aggs": { "top_hits_products": { "top_hits": { "size": 5 } } } } 返回内容 ... "aggregations" : { "top_hits_products" : { "hits" : { "total" : { "value" : 4675, "relation" : "eq" }, "max_score" : 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/parent/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/parent/父文档聚合 # parent 聚合是一个分组聚合，根据您索引中定义的父子关系创建一个包含父级文档的分组。此聚合使您能够对具有相同匹配子级文档的父级文档执行分析，从而实现强大的层次结构数据分析。 parent 聚合与 join 字段类型一起工作，该字段类型在同一个索引中的文档内建立父子关系。 parent 聚合识别具有匹配子文档的父文档，而 children 聚合识别匹配特定子关系的子文档。这两种聚合都使用子关系名称作为输入。 相关指南（先读这些） # 聚合基础 Parent-Child 建模 聚合场景实践 参数说明 # parent 聚合具有以下参数： 参数 必需/可选 数据类型 描述 type 必填 String join 字段中的子类型名称。 参考样例 # 以下示例构建了一个包含三名员工的小公司数据库。每个员工记录都与一个父部门记录存在 join 子关系。 首先，创建一个 company 索引，其中包含一个 join 字段，该字段将部门（父级）映射到员工（子级）： PUT /company { "mappings": { "properties": { "join_field": { "type": "join", "relations": { "department": "employee" } }, "department_name": { "type": "keyword" }, "employee_name": { "type": "keyword" }, "salary": { "type": "double" }, "hire_date": { "type": "date" } } } } 接下来，用三个部门和三个员工填充数据。父子关系在以下表格中展示。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/percentile-ranks/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/percentile-ranks/百分位排名聚合 # percentile_ranks 聚合估计低于或等于给定阈值的观测值百分比。这对于了解特定值在值分布中的相对位置很有用。 例如，您可以使用百分位排名聚合来学习交易金额 45 与数据集中其他交易值相比如何。百分位排名聚合返回一个值，如 82.3，这意味着 82.3% 的交易额低于或等于 45。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # percentile_ranks 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 用于计算百分位数的数值字段。 values 必需 Array of doubles 用于计算百分位数的值。 keyed 可选 Boolean 如果设置为 false ，则将结果作为数组返回。否则将结果作为 JSON 对象返回。默认值为 true 。 tdigest.compression 可选 Double 控制 tdigest 算法的准确性和内存使用。参见使用 tdigest 进行精度调整。 hdr.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/percentile/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/percentile/百分位数聚合 # percentiles 聚合估计数值字段在给定百分位处的值。这对于理解分布边界很有用。 例如，load_time 的 95th 百分位 = 120ms 表示 95% 的值小于或等于 120 毫秒。 与 cardinality 指标类似，percentiles 指标也是近似的。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # percentiles 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 用于计算百分位数的数值字段。 percents 可选 Array of doubles 返回百分位数列表。默认为 [1, 5, 25, 50, 75, 95, 99] 。 keyed 可选 Boolean 如果设置为 false ，则将结果作为数组返回。否则将结果作为 JSON 对象返回。默认值为 true 。 tdigest.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/percentiles-bucket/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/percentiles-bucket/百分位桶聚合 # percentiles_bucket 聚合是一个同级聚合，用于计算分位数的位置。 percentiles_bucket 聚合精确计算分位数，不使用近似或插值。每个分位数都返回为目标分位数小于或等于的最近值。 percentiles_bucket 聚合需要将整个值列表临时保存在内存中，即使对于大型数据集也是如此。相比之下，percentiles 指标聚合使用更少的内存，但会近似百分比。 指定的指标必须是数值型，并且同级聚合必须是多分组聚合。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # percentiles_bucket聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as _string 属性中的格式化输出。 percents 可选 List 一个包含任意数量数值百分比值的列表，这些值将被包含在输出中。有效值为 0.0 到 100.0（含）。默认为 [1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/histogram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/histogram/直方图聚合 # histogram 聚合根据指定的间隔对文档进行分组。 使用 histogram 聚合，您可以非常轻松地可视化给定范围内文档中值的分布。 相关指南（先读这些） # 聚合基础 聚合场景实践 以下示例将 number_of_bytes 字段按 10,000 个间隔进行分组： GET sample_data_logs/_search { "size": 0, "aggs": { "number_of_bytes": { "histogram": { "field": "bytes", "interval": 10000 } } } } 返回内容 ... "aggregations" : { "number_of_bytes" : { "buckets" : [ { "key" : 0.0, "doc_count" : 13372 }, { "key" : 10000.0, "doc_count" : 702 } ] } } 参数说明 # histogram 聚合支持以下参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/matrix-stats/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/matrix-stats/矩阵统计聚合 # matrix_stats 聚合是一个多值指标聚合，以矩阵形式为两个或多个字段生成协方差统计。 注意：matrix_stats 聚合不支持脚本。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # matrix_stats 聚合采用以下参数。 参数 必需/可选 数据类型 描述 field 必需 String 用于计算矩阵统计的一组字段。 missing 可选 Object 用于替代缺失值的值。默认情况下，会忽略缺失值。参见缺失值。 mode 可选 String 用作多值或数组字段样本的值。允许的值是 avg 、 min 、 max 、 sum 和 median 。默认是 avg 。 参考样例 # 以下示例返回数据中 taxful_total_price 和 products.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/moving-function/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/moving-function/移动函数聚合 # moving_fn 聚合是一个父级管道聚合，它在滑动窗口上执行脚本。滑动窗口在从父级 histogram 或 date_histogram 聚合中提取的一系列值上移动。窗口一次向右移动一个分组；moving_fn 每次窗口移动时都会运行脚本。 使用 moving_fn 聚合在滑动窗口内的数据上执行任何数值计算。你可以使用 moving_fn 用于以下目的： 趋势分析 异常值检测 自定义时间序列分析 自定义平滑算法 数字信号处理 (DSP) 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # moving_fn 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 script 必需 String 或 Object 为每个数据窗口计算值的脚本。可以是内联脚本、存储脚本或脚本文件。该脚本可以访问在 buckets_path 参数中定义的变量名。 window 必需 Integer 滑动窗口中的分组的数量。必须是正整数。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as_string 属性中的格式化输出。 shift 可选 Integer 窗口要移动的分组的数量。可以是正数（向未来的分组右移）或负数（向过去的分组左移）。默认是 0 ，将窗口立即放置在当前分组的左侧。参见移动窗口。 移动函数的工作原理 # moving_fn 聚合操作在有序分组序列上的滑动窗口上。从父聚合中的第一个分组开始， moving_fn 执行以下操作：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/moving-avg/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/moving-avg/移动平均聚合 # moving_avg 聚合是一个父级管道聚合，它计算有序数据集中窗口（相邻子集）内指标的一系列平均值。 要创建一个 moving_avg 聚合，您首先创建一个 histogram 或 date_histogram 聚合。然后，您可以选择在直方图聚合中嵌入一个指标聚合。最后，您在直方图中嵌入 moving_avg 聚合，并将 buckets_path 参数设置为要跟踪的嵌入指标。 相关指南（先读这些） # 聚合基础 聚合场景实践 窗口的大小是窗口中连续数据值的数量。在每次迭代中，算法计算窗口中所有数据点的平均值，然后向前滑动一个数据值，排除上一个窗口的第一个值，并包含下一个窗口的第一个值。 例如，给定数据 [1, 5, 8, 23, 34, 28, 7, 23, 20, 19] ，一个窗口大小为 5 的移动平均如下： (1 + 5 + 8 + 23 + 34) / 5 = 14.2 (5 + 8 + 23 + 34 + 28) / 5 = 19.6 (8 + 23 + 34 + 28 + 7) / 5 = 20 .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/rare-terms/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/rare-terms/稀有词项聚合 # rare_terms 聚合是一个分组聚合，用于识别数据集中的不常见词项。与 terms 聚合（查找最常见的词项）不同，rare_terms 聚合查找出现频率最低的词项。rare_terms 聚合适用于异常检测、长尾分析和异常报告等应用。 相关指南（先读这些） # 聚合基础 聚合场景实践 可以使用 terms 通过按升序计数排序（ “order”: {“count”: “asc”} ）来搜索不常见的值。然而，我们强烈不建议这种做法，因为在涉及多个分片时，它可能导致不准确的结果。一个全局上不常见的词项可能不会在每个单个分片上显得不常见，或者可能完全不在某些分片返回的最不常见结果中。相反，一个在某个分片上出现频率较低的词项可能在另一个分片上很常见。在这两种情况下，分片级别的聚合可能会遗漏稀有词项，导致整体结果不正确。我们建议使用 rare_terms 聚合代替 terms 聚合，它专门设计用于更准确地处理这些情况。 近似结果 # 计算 rare_terms 聚合的精确结果需要编译所有分片上的值完整映射，这需要过多的运行时内存。因此， rare_terms 聚合结果被近似处理。 rare_terms 计算中的大多数错误是假阴性或“遗漏”的值，这些值定义了聚合检测测试的灵敏度。 rare_terms 聚合使用 CuckooFilter 算法以实现适当的灵敏度和可接受的内存使用平衡。有关 CuckooFilter 算法的描述，请参阅这篇论文。 控制灵敏度 # rare_terms 聚合算法中的灵敏度误差被衡量为被遗漏的稀有值的比例，或 false negatives/target values 。例如，如果聚合在包含 5,000 个稀有值的数据集中遗漏了 100 个稀有值，灵敏度误差为 100/5000 = 0.02 ，或 2%。 您可以调整 precision 参数在 rare_terms 聚合中来控制灵敏度和内存使用之间的权衡。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-compression/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-compression/索引压缩 # 索引编码 # 索引编码决定索引的存储字段如何被压缩和存储在磁盘上。索引编码由静态的 index.codec 设置来控制，该设置指定压缩算法。这个设置会影响索引分片的大小和索引操作的性能。 Easysearch 提供了多种基于索引编码的压缩方案，以降低索引的存储成本。 default – 该编码使用LZ4算法和预设字典，优先考虑性能而非压缩比。与best_compression相比，它提供更快的索引和搜索操作，但可能导致更大的索引/分片大小。如果在索引设置中未提供编码，则默认使用LZ4作为压缩算法。 best_compression – 该编码底层使用zlib算法进行压缩。它能实现高压缩比，从而减小索引大小。然而，这可能会增加索引操作期间的额外CPU使用，并可能随后导致较高的索引和搜索延迟。 从 Easysearch 1.1 开始，增加了基于 Zstandard 压缩算法的新编码方式。这种算法在压缩比和速度之间提供了良好的平衡。 ZSTD 与默认编解码器相比，该编解码器提供了与best_compression编解码器相当的压缩比，CPU使用合理，索引和搜索性能也有所提高。 source 复用 # source_reuse： 启用 source_reuse 配置项能够去除 _source 字段中与 doc_values 或倒排索引重复的部分，从而有效减小索引总体大小，这个功能对日志类索引效果尤其明显。 source_reuse 支持对以下数据类型进行压缩：keyword，integer，long，short，boolean，float，half_float，double，geo_point，ip， 如果是 text 类型，需要默认启用 keyword 类型的 multi-field 映射。 以上类型必须启用 doc_values 映射（默认启用）才能压缩。 使用限制 # 当索引里包含 nested 类型映射，或插件额外提供的数据类型时，不能启用 source_reuse，例如 knn 索引。 使用 source_reuse 压缩时，keyword 类型的字段最好不要设置 ignore_above 属性，设置过短的值可能会导致字段内容无法展示。 压缩效果对比 # Easysearch 压缩效果对比如下https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/cumulative-sum/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/cumulative-sum/累积和聚合 # cumulative_sum 聚合是一个父聚合，用于计算上一个聚合的存储分组的累积总和。 累积和是给定序列的部分和的序列。例如，序列 {a, b, c, ...} 的累积和为 a、a+b、a+b+c 等。您可以使用累积总和来可视化字段随时间的变化率。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # cumulative_sum 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合存储分组的路径。请参阅存储分组路径 。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as_string 属性中的格式化输出。 参考样例 # 以下示例创建间隔为一个月的日期直方图。sum 子聚合计算每个月所有字节的总和。最后，cumulative_sum 聚合计算每个月存储分组的累积字节数： GET sample_data_logs/_search { "size": 0, "aggs": { "sales_per_month": { "date_histogram": { "field": "@timestamp", "calendar_interval": "month" }, "aggs": { "no-of-bytes": { "sum": { "field": "bytes" } }, "cumulative_bytes": { "cumulative_sum": { "buckets_path": "no-of-bytes" } } } } } } 返回内容https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/classic/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/classic/Classic 分词器 # classic 分词器会解析文本，并应用英语语法规则将文本拆分为词元。它包含以下特定的逻辑来处理匹配规则： 相关指南（先读这些） # 文本分析：识别词元 文本分析基础 首字母缩写词 电子邮件地址 域名 某些类型的标点符号 这种词元生成器最适合处理英语文本。对于其他语言，尤其是那些具有不同语法结构的语言，它可能无法产生最佳效果。 经典词元生成器按如下方式解析文本： 标点符号：在大多数标点符号处拆分文本，并移除标点字符。后面不跟空格的点号会被视为词元的一部分。 连字符：在连字符处拆分单词，但当词元中存在数字时除外。当词元中存在数字时，该词元不会被拆分，而是被当作产品编号处理。 电子邮件：识别电子邮件地址和主机名，并将它们作为单个词元保留。 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个使用经典词元生成器的分词器： PUT /my_index { "settings": { "analysis": { "analyzer": { "my_classic_analyzer": { "type": "custom", "tokenizer": "classic" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "my_classic_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/stats-bucket/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/pipeline-aggregations/stats-bucket/统计桶聚合 # stats_bucket 聚合是一个同级聚合，它为先前聚合的分组返回各种统计信息（count、min、max、avg 和 sum）。 指定的指标必须是数值型，并且同级聚合必须是多分组聚合。 相关指南（先读这些） # 聚合基础 聚合场景实践 参数说明 # stats_bucket 聚合采用以下参数。 参数 必需/可选 数据类型 描述 buckets_path 必需 String 要聚合的聚合分组的路径。参见分组路径。 gap_policy 可选 String 应用于缺失数据的策略。有效值为 skip 和 insert_zeros 。默认为 skip 。参见数据间隙。 format 可选 String DecimalFormat 格式字符串。返回聚合的 value_as _string 属性中的格式化输出。 参考样例 # 以下示例创建一个以一个月为间隔的日期直方图。 sum 子聚合计算每个月所有字节的总和。最后， stats_bucket 聚合从这些总和中返回 count 、 avg 、 sum 、 min 和 max 统计信息：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/stats/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/stats/统计聚合 # stats 聚合是一个多值指标聚合，用于计算数值数据的汇总。这种聚合有助于快速了解数值字段的分布情况。它可以直接作用于字段，应用脚本来派生值，或处理缺少字段的文档。stats 聚合返回五个值： 相关指南（先读这些） # 聚合基础 聚合场景实践 count : 收集到的值的数量 min : 最低值 max : 最高值 sum : 所有值的总和 avg : 值的平均数（总和除以数量） 参数说明 # stats 聚合支持以下可选参数。 参数 必需/可选 数据类型 描述 field 必需 String 要聚合的字段。必须是数值字段。 script 可选 Object 用于计算聚合自定义值的脚本。可单独使用或与 field 一起使用。 missing 可选 Number 用于缺少目标字段的文档的默认值。 参考样例 # 以下示例计算 stats 聚合的电力使用情况。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/missing/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/missing/缺失值聚合 # 如果你的索引中的文档完全不包含聚合字段，或者聚合字段的值为 null，请使用 missing 参数指定这些文档应该放入的分组的名称。 相关指南（先读这些） # 聚合基础 聚合场景实践 以下示例将任何缺失的值添加到名为“N/A”的分组中： GET sample_data_logs/_search { "size": 0, "aggs": { "response_codes": { "terms": { "field": "response.keyword", "size": 10, "missing": "N/A" } } } } 由于 min_doc_count 参数的默认值为 1， missing 参数在其响应中不会返回任何分组。将 min_doc_count 参数设置为 0 以在响应中查看“N/A”分组： GET sample_data_logs/_search { "size": 0, "aggs": { "response_codes": { "terms": { "field": "response.keyword", "size": 10, "missing": "N/A", "min_doc_count": 0 } } } } 返回内容https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/scripted-metric/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/scripted-metric/脚本指标聚合 # scripted_metric 聚合是一个多值指标聚合，它返回根据指定脚本计算的指标。脚本有四个阶段：init、map、combine 和 reduce，每个聚合按顺序运行这些阶段，组合来自文档的结果。 相关指南（先读这些） # 聚合基础 聚合场景实践 所有四个脚本共享一个可变对象，称为 state，该对象由你定义。state 在 init、map 和 combine 阶段时对每个分片是局部的。结果被传递到 states 数组中用于 reduce 阶段。因此，每个分片的 state 在分片在 reduce 步骤中组合之前是独立的。 参数说明 # scripted_metric 聚合采用以下参数。 参数 必需/可选 数据类型 描述 init_script 可选 String 一个脚本，在每个分片上处理任何文档之前执行一次。用于设置初始 state（例如，在 state 对象中初始化计数器或列表）。如果没有提供，state 在每个分片上开始时是一个空对象。 map_script 必需 String 一个脚本，针对聚合收集的每个文档执行。此脚本根据文档的数据更新 state。例如，您可以检查字段的值，然后递增计数器或在 state 中计算运行总和。 combine_script 必需 String 一个脚本，在每个分片上处理完所有文档后由 map_script 执行一次。此脚本将分片的 state 聚合为单个结果发送回协调节点。此脚本用于完成一个分片的计算（例如，汇总存储在 state 中的计数器或总计）。脚本应返回其分片的汇总值或结构。 reduce_script 必需 String 一个脚本在接收到所有分片的合并结果后，在协调节点上执行一次。这个脚本接收一个特殊变量 states，它是一个包含每个分片从 combine_script 输出的数组。reduce_script 遍历状态并生成最终的聚合输出（例如，添加分片总和或合并计数的映射）。reduce_script 返回的值是在聚合结果中报告的值。 params 可选 Object 除 reduce_script 外，所有脚本都可以访问用户定义的参数。 可返回的类型 # 脚本可以在内部使用任何有效的操作和对象。然而，存储在 state 或从任何脚本返回的数据必须属于允许的类型之一。这个限制存在是因为中间 state 需要在节点之间发送。允许的类型如下：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/auto-interval-date-histogram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/auto-interval-date-histogram/自动间隔日期直方图聚合 # 与日期直方图聚合类似，其中你必须指定一个间隔，auto_date_histogram 是一个多分组聚合，根据你提供的分组数量和数据的时范围自动创建日期直方图分组。返回的实际分组数量总是小于或等于你指定的分组数量。当你在处理时间序列数据并希望在不同时间间隔上可视化或分析数据，而不需要手动指定间隔大小时，这种聚合特别有用。 相关指南（先读这些） # 聚合基础 聚合场景实践 时间序列建模 间隔参数 # 分组间隔是根据收集的数据选择的，以确保返回的分组数量小于或等于请求的数量。 下表列出了每个时间单位可能的返回间隔。 单位 间隔参数 Seconds 1、5、10 和 30 的倍数 Minutes 1、5、10 和 30 的倍数 Hours 1、3 和 12 的倍数 Days 1 和 7 的倍数 Months 1 和 3 的倍数 Years 1、5、10、20、50 和 100 的倍数 如果一个聚合返回的分组太多（例如，每天一个分组），Easysearch 会自动减少分组的数量以确保结果可管理。它不会返回请求的确切数量的每日分组，而是会减少大约 1/7。例如，如果你请求 70 个分组，但数据中包含太多的每日间隔，Easysearch 可能只会返回 10 个分组，将数据分组到更大的间隔（如周）中，以避免结果数量过多。这有助于优化聚合，并在数据过多时防止过多细节。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/range/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/range/范围聚合 # range 聚合允许你为每个分组定义范围。 相关指南（先读这些） # 聚合基础 聚合场景实践 例如，你可以找到在 1000 和 2000 之间、2000 和 3000 之间以及 3000 和 4000 之间的字节数。在 range 参数中，你可以将范围定义为数组对象。 GET sample_data_logs/_search { "size": 0, "aggs": { "number_of_bytes_distribution": { "range": { "field": "bytes", "ranges": [ { "from": 1000, "to": 2000 }, { "from": 2000, "to": 3000 }, { "from": 3000, "to": 4000 } ] } } } } 响应包含 from 键值，并排除 to 键值：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/normalization/Normalization 分词过滤器 # 归一化分词过滤器旨在以减少文本差异（尤其是特殊字符差异）的方式对文本进行调整和简化。它主要用于通过对特定语言中的字符进行标准化处理，来应对书写上的差异。 相关指南（先读这些） # 文本分析：规范化 文本分析基础 以下是可用的归一化分词过滤器： 阿拉伯语归一化: arabic_normalization 德语归一化: german_normalization 印地语归一化: hindi_normalization 印度语系归一化: indic_normalization 索拉尼语归一化: sorani_normalization 波斯语归一化: persian_normalization 斯堪的纳维亚语归一化: scandinavian_normalization 斯堪的纳维亚语折叠处理归一化: scandinavian_folding 塞尔维亚语归一化: serbian_normalization 参考样例 # 以下示例请求创建了一个名为 german_normalizer_example 的新索引，并配置了一个带有 german_normalization的分词器： PUT /german_normalizer_example { "settings": { "analysis": { "filter": { "german_normalizer": { "type": "german_normalization" } }, "analyzer": { "german_normalizer_analyzer": { "tokenizer": "standard", "filter": [ "lowercase", "german_normalizer" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/terms/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/terms/词项聚合 # terms 聚合会动态为字段中的每个唯一词条创建一个分组。 相关指南（先读这些） # 聚合基础 聚合场景实践 以下示例使用 terms 聚合来查找网络日志数据中每个响应代码的文档数量： GET sample_data_logs/_search { "size": 0, "aggs": { "response_codes": { "terms": { "field": "response.keyword", "size": 10 } } } } 返回内容 ... "aggregations" : { "response_codes" : { "doc_count_error_upper_bound" : 0, "sum_other_doc_count" : 0, "buckets" : [ { "key" : "200", "doc_count" : 12832 }, { "key" : "404", "doc_count" : 801 }, { "key" : "503", "doc_count" : 441 } ] } } } 值以 key 键返回。 doc_count 指定每个分组中的文档数量。默认情况下，分组按 doc-count 的降序排列。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/filter/过滤器聚合 # filter 聚合是一个查询子句，就像一个搜索查询一样 — match 或 term 或 range。您可以使用 filter 聚合在创建分组之前将整个文档集缩小到特定的文档集。 相关指南（先读这些） # 聚合基础 聚合场景实践 以下示例展示了 avg 聚合在过滤上下文中运行的情况。 avg 聚合仅聚合与 range 查询匹配的文档： GET sample_data_ecommerce/_search { "size": 0, "aggs": { "low_value": { "filter": { "range": { "taxful_total_price": { "lte": 50 } } }, "aggs": { "avg_amount": { "avg": { "field": "taxful_total_price" } } } } } } 返回内容 ... "aggregations" : { "low_value" : { "doc_count" : 1633, "avg_amount" : { "value" : 38.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/rate/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/metric-aggregations/rate/速率聚合 # rate 聚合是一个指标聚合，用于计算文档或字段值在指定时间单位内的速率。它必须嵌套在 date_histogram（或 composite 中的 date_histogram 源）内部使用。 rate 聚合特别适合将不同时间粒度的数据统一到相同的速率单位进行对比。例如，当 date_histogram 按月分桶时，你可以用 rate 聚合将每个月的值换算为"每天"或"每年"的速率。 相关指南（先读这些） # 聚合基础 日期直方图聚合 聚合场景实践 参数说明 # 参数 必需/可选 数据类型 描述 field 可选 String 要计算速率的数值字段。如果省略，则计算文档的速率（即文档数/时间单位）。 unit 可选 String 速率的时间单位。有效值：second、minute、hour、day、week、month、quarter、year。如果省略，使用 date_histogram 的 calendar_interval 作为单位。 script 可选 Object 使用脚本动态计算速率值。 missing 可选 Numeric 缺少字段值的文档所使用的替代值。 基本用法：文档速率 # 计算每月的文档数量，并将其换算为每天的速率：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/adjacency-matrix/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/adjacency-matrix/邻接矩阵聚合 # adjacency_matrix 聚合允许你定义过滤表达式，并返回一个交集矩阵，矩阵中的每个非空单元格代表一个分组。你可以找到落入任何过滤器组合中的文档数量。 使用 adjacency_matrix 聚合通过将数据可视化为图形来发现概念之间的关联。 相关指南（先读这些） # 聚合基础 聚合场景实践 例如，下面查询可以分析不同制造公司之间的关联关系： GET sample_data_ecommerce/_search { "size": 0, "aggs": { "interactions": { "adjacency_matrix": { "filters": { "grpA": { "match": { "manufacturer.keyword": "Low Tide Media" } }, "grpB": { "match": { "manufacturer.keyword": "Elitelligence" } }, "grpC": { "match": { "manufacturer.keyword": "Oceanavigations" } } } } } } } 返回内容 { ... "aggregations" : { "interactions" : { "buckets" : [ { "key" : "grpA", "doc_count" : 1553 }, { "key" : "grpA&grpB", "doc_count" : 590 }, { "key" : "grpA&grpC", "doc_count" : 329 }, { "key" : "grpB", "doc_count" : 1370 }, { "key" : "grpB&grpC", "doc_count" : 299 }, { "key" : "grpC", "doc_count" : 1218 } ] } } } 让我们更仔细地查看结果https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/sampler/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/sampler/采样聚合 # 如果你正在聚合大量文档，可以使用 sampler 聚合将范围缩小到一小部分文档，从而获得更快的响应。sampler 聚合通过选择得分最高的文档来选取样本。 结果是大致的，但能很好地反映真实数据的分布。sampler 聚合显著提高了查询性能，但估计的响应并不完全可靠。 相关指南（先读这些） # 聚合基础 聚合性能优化 聚合场景实践 基本语法是： “aggs”: { "SAMPLE": { "sampler": { "shard_size": 100 }, "aggs": {...} } } 分片大小属性 # shard_size 属性告诉 Easysearch 每个分片最多收集多少文档。 以下示例将每个分片上收集的文档数量限制为 1,000，然后使用 terms 聚合对文档进行分组： GET sample_data_logs/_search { "size": 0, "aggs": { "sample": { "sampler": { "shard_size": 1000 }, "aggs": { "terms": { "terms": { "field": "agent.keyword" } } } } } } 返回内容https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/limit/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/limit/Limit 分词过滤器 # limit 分词过滤器用于限制分词链通过的词元数量。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参数说明 # 限制分词过滤器可以使用以下参数进行配置。 参数 必填/可选 数据类型 描述 max_token_count 可选 整数 要生成的词元的最大数量。默认值为 1。 consume_all_tokens 可选 布尔值 （专家级设置）即使结果超过 max_token_count，也会使用来自词元生成器的所有词元。当设置此参数时，输出仍然只包含 max_token_count 指定数量的词元。不过，词元生成器生成的所有词元都会被处理。默认值为 false。 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个带有限制过滤器的分析器： PUT my_index { "settings": { "analysis": { "analyzer": { "three_token_limit": { "tokenizer": "standard", "filter": [ "custom_token_limit" ] } }, "filter": { "custom_token_limit": { "type": "limit", "max_token_count": 3 } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/geohash-grid/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/geohash-grid/Geohash 网格聚合 # geohash_grid 聚合将 geo_point 值按照 Geohash 编码分组到网格单元中。这对于在地图上可视化大量地理坐标点非常有用——将密集的点聚合成可管理的网格，每个网格显示该区域的统计信息。 相关指南（先读这些） # 聚合基础教程 地理位置搜索 Geohash 编码原理 参数说明 # 参数 必需/可选 类型 说明 field 必需 String 包含 geo_point 值的字段名 precision 可选 Integer/String Geohash 精度级别（1-12）或距离字符串（如 1km）。默认 5 bounds 可选 Object 限制聚合的地理边界框，只处理该范围内的点 size 可选 Integer 返回的最大 bucket 数量。默认 10000 shard_size 可选 Integer 每个分片返回的 bucket 数量，用于提高精度。默认 max(10, size) 精度级别参考 # 精度 网格尺寸 适用场景 1 ~ 5,000km 大洲级别 2 ~ 1,250km 国家级别 3 ~ 156km 大区域 4 ~ 39km 城市群 5 ~ 4.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/html-strip/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/html-strip/HTML 清理处理器 # html_strip 处理器从传入文档的字符串字段中移除 HTML 标签。当从网页或其他可能包含 HTML 标记的来源索引数据时，此处理器非常有用。HTML 标签被替换为换行符（\n）。 以下是为 html_strip 处理器提供的语法： { "html_strip": { "field": "webpage" } } 配置参数 # 下表列出了 html_strip 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 要从中移除 HTML 标签的字符串字段。 target_field 可选 接收去除 HTML 标签后的纯文本版本的字段。如果未指定，则字段将就地更新。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。默认为 false 。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/icu-normalizer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/icu-normalizer/ICU Normalizer 字符过滤器 # icu_normalizer 字符过滤器使用 ICU 库在分词之前对原始文本进行 Unicode 归一化。它可以将字符的多种编码形式统一为标准形式，确保相同的"视觉字符"在搜索时能够匹配。 需要插件：此过滤器由 analysis-icu 插件提供，Easysearch 默认已集成。 与词元过滤器版本的区别 # ICU 插件同时提供了字符过滤器和词元过滤器两个版本： 版本 类型名 处理阶段 适用场景 字符过滤器 icu_normalizer 分词前 需要在分词前统一字符形式 词元过滤器 icu_normalizer 分词后 只需对词元进行归一化 建议：大多数场景使用字符过滤器版本效果更好，因为归一化发生在分词之前，可以避免因字符形式不同导致的分词差异。 参数说明 # 参数 类型 默认值 说明 name String nfkc_cf Unicode 归一化方式，见下方选项 mode String compose 归一化模式：compose（合成）或 decompose（分解） unicode_set_filter String — 可选，ICU UnicodeSet 过滤条件，仅对匹配字符进行归一化 name 可选值 # 值 说明 nfc NFC 标准归一化（合成优先） nfkc NFKC 兼容归一化（合成优先） nfkc_cf 默认值。NFKC 归一化 + Case Folding（大小写折叠） 使用示例 # 基本用法（默认 nfkc_cf） # PUT /my-icu-index { "settings": { "analysis": { "analyzer": { "my_icu_analyzer": { "type": "custom", "tokenizer": "standard", "char_filter": ["icu_normalizer"] } } } } } 自定义归一化方式 # PUT /my-icu-index { "settings": { "analysis": { "char_filter": { "my_icu_normalizer": { "type": "icu_normalizer", "name": "nfc", "mode": "compose" } }, "analyzer": { "my_analyzer": { "type": "custom", "tokenizer": "standard", "char_filter": ["my_icu_normalizer"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "keyword", "char_filter": ["icu_normalizer"], "text": "Ⅲ fi ℃" } 归一化结果：ⅲ→iii、fi→fi、℃→°c（NFKC 兼容分解 + case folding）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/run-as/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/run-as/身份模拟 # 用户模拟允许具备特定权限的用户以另外的身份来进行集群的访问。 用户模拟可用于测试和故障排除，或允许系统服务安全地充当用户。 在 REST 接口或 TCP 传输层上都可以进行用户模拟。 REST 接口 # 要允许一个用户模拟另一个用户，请将以下内容添加到 easysearch.yml : security.authcz.rest_impersonation_user: <AUTHENTICATED_USER>: - <IMPERSONATED_USER_1> - <IMPERSONATED_USER_2> 模拟用户字段支持通配符。将其设置为 * 允许 AUTHENTICATED_USER 来模拟任意用户。 传输层配置 # 类似的配置方法如下： security.authcz.impersonation_dn: "CN=spock,OU=client,O=client,L=Test,C=DE": - worf 模拟其他用户 # 要模拟其他用户，请向系统提交请求，并将 HTTP 标头 security_run_as 设置为要模拟的用户的名称。例如： curl -XGET -u 'admin:xxxxxxxxxxxx' -k -H "security_run_as: user_1" https://localhost:9200/_security/authinfo?prettyhttps://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/geotile-grid/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/bucket-aggregations/geotile-grid/Geotile 网格聚合 # geotile_grid 聚合将 geo_point 值按照地图瓦片坐标分组。与 geohash_grid 类似，但使用的是 Web 地图标准的瓦片坐标系统（x/y/zoom），这使得它与 Google Maps、OpenStreetMap、Mapbox 等瓦片地图服务的集成更加方便。 相关指南（先读这些） # 聚合基础教程 地理位置搜索 Geohash Grid 聚合 瓦片坐标系统 # Web 地图使用 Slippy Map 瓦片坐标系统： zoom：缩放级别（0-29），级别越高网格越精细 x：水平瓦片索引（从左到右） y：垂直瓦片索引（从上到下） 瓦片标识符格式：{zoom}/{x}/{y}，如 14/8532/5765 缩放级别与覆盖范围 # Zoom 瓦片数量 每个瓦片覆盖范围 0 1 整个世界 1 4 ~ 20,000km 5 1,024 ~ 1,250km 10 ~100万 ~ 39km 15 ~10亿 ~ 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/n-gram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/n-gram/N-gram 分词过滤器 # ngram 分词过滤器是一种强大的工具，用于将文本拆分为更小的组件，即 n-gram，这有助于提升部分匹配和模糊搜索能力。它通过将一个词元拆分成指定长度的子字符串来工作。这些过滤器在搜索应用程序中很常用，可用于支持自动补全、部分匹配以及容错拼写搜索。 相关指南（先读这些） # 部分匹配 文本分析：模糊匹配 文本分析：识别词元 参数说明 # n-gram 分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 min_gram 可选 整数 n-gram 的最小长度。默认值为 1。 max_gram 可选 整数 n-gram 的最大长度。默认值为 2。 preserve_original 可选 布尔值 是否将原始词元保留为输出之一。默认值为 false。 参考样例 # 以下示例请求创建了一个名为“ngram_example_index”的新索引，并配置了一个带有 n-gram 过滤器的分词器： PUT /ngram_example_index { "settings": { "analysis": { "filter": { "ngram_filter": { "type": "ngram", "min_gram": 2, "max_gram": 3 } }, "analyzer": { "ngram_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "ngram_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/write-and-storage/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/write-and-storage/写入与存储机制 # 当你向 Easysearch 索引一个文档时，数据要经历多个阶段才能最终安全地持久化到磁盘。理解这个过程，有助于你在性能调优和故障恢复时做出正确决策。 写入的全景图 # 一个文档从写入请求到可被搜索再到持久化落盘，大致经历以下阶段： 客户端请求 ↓ 协调节点路由到主分片 ↓ 主分片写入： 1. 追加到 translog（事务日志） 2. 写入内存索引缓冲区（in-memory buffer） ↓ refresh（默认每秒）: - 缓冲区内容写入新的段（segment）到文件系统缓存 - 新段可被搜索（近实时） - 缓冲区清空，translog 保留 ↓ flush（translog 超过 512MB 阈值时触发）: - 段从文件系统缓存 fsync 到磁盘 - 写入提交点（commit point） - translog 清空 ↓ 段合并（后台持续）: - 小段合并为大段 - 清理已删除文档 - 减少段数量，提升搜索性能 下面按阶段逐一展开。 近实时搜索：为什么不是"实时" # Easysearch 被称为 近实时（Near Real-Time, NRT） 搜索引擎——文档写入后并非立刻可搜索，但通常在一秒内就能被检索到。 背后的原因在于：磁盘 I/O 是瓶颈。提交（commit）一个新的段到磁盘需要 fsync，开销非常大。如果每索引一个文档就执行一次 fsync，性能将无法接受。 Easysearch 的做法是：将新段先写入文件系统缓存（OS page cache）——这一步代价很低；稍后再 fsync 到磁盘。只要新段进入了文件系统缓存，就可以像其他文件一样被打开和读取，从而对搜索可见。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/stconvert/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/character-filters/stconvert/ST Convert 字符过滤器 # stconvert 字符过滤器在分词之前对中文文本进行简体与繁体之间的转换，使简繁体内容在搜索时可以互相匹配。 需要插件：此过滤器由 analysis-stconvert 插件提供，Easysearch 默认已集成。 转换方向 # convert_type 说明 s2t 默认值。简体 → 繁体 t2s 繁体 → 简体 使用示例 # 简体转繁体（默认） # PUT /my-chinese-index { "settings": { "analysis": { "analyzer": { "s2t_analyzer": { "type": "custom", "tokenizer": "standard", "char_filter": ["stconvert"] } } } } } 繁体转简体 # PUT /my-chinese-index { "settings": { "analysis": { "char_filter": { "t2s_filter": { "type": "stconvert", "convert_type": "t2s" } }, "analyzer": { "t2s_analyzer": { "type": "custom", "tokenizer": "standard", "char_filter": ["t2s_filter"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "keyword", "char_filter": [ { "type": "stconvert", "convert_type": "t2s" } ], "text": "國際化標準" } 结果：國際化標準 → 国际化标准https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/cross-cluster-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/cross-cluster-search/跨集群搜索权限 # 跨集群搜索允许集群中的节点对其他集群执行搜索请求。Easysearch 原生支持跨集群搜索，本页重点说明权限与配置要点。 相关指南（先读这些） # 权限控制总览 分布式搜索基础 安全与多租户最佳实践 身份验证流程 # 当跨集群搜索通过 协调集群 访问 远程集群 时： 安全模块对协调集群上的用户进行身份验证。 安全模块在协调集群上获取用户的后端角色。 请求调用（包括经过身份验证的用户）将转发到远程集群。 在远程群集上评估用户的权限。 远程群集和协调集群可以分别配置不同的身份验证和授权配置，但我们建议在两者上使用相同的设置。 权限信息 # 要查询远程集群上的索引，除了 READ 或 SEARCH 权限外，用户还需要具有以下索引权限： indices:admin/shards/search_shards role.yml 样例配置 # humanresources: cluster: - CLUSTER_COMPOSITE_OPS_RO indices: "humanresources": "*": - READ - indices:admin/shards/search_shards # needed for CCS 配置流程 # 分别启动两个集群，如下： ➜ curl -k 'https://localhost:9200/_cluster/health?pretty' -u admin:xxxxxxxxxxxx { "cluster_name" : "easysearch", "status" : "green", "timed_out" : false, "number_of_nodes" : 1, "number_of_data_nodes" : 1, "active_primary_shards" : 1, "active_shards" : 1, "relocating_shards" : 0, "initializing_shards" : 0, "unassigned_shards" : 0, "delayed_unassigned_shards" : 0, "number_of_pending_tasks" : 0, "number_of_in_flight_fetch" : 0, "task_max_waiting_in_queue_millis" : 0, "active_shards_percent_as_number" : 100.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/filter-query-processor/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/filter-query-processor/过滤查询处理器（filter query processor） # 版本引入：1.14.0 filter_query 查询重写处理器用于拦截搜索请求，并向该请求中添加一个额外的查询条件，从而对搜索结果进行过滤。当你不希望重写应用程序中已有的查询语句，但又需要对结果进行额外过滤时，此功能非常有用。 请求体字段 # 下表列出了所有可用的请求字段。 字段 数据类型 说明 query 对象 使用 Easysearch 查询领域特定语言（DSL）编写的查询语句。必填。 tag 字符串 处理器的唯一标识符。可选。 description 字符串 对该处理器的描述信息。可选。 ignore_failure 布尔值 若为 true，则当此处理器执行失败时，Easysearch 将忽略该错误并继续执行搜索管道中的其余处理器。可选，默认值为 false。 示例 # 以下示例演示如何在搜索管道中使用 filter_query 处理器。 准备工作 # 创建一个名为 my_index 的索引，并索引两个文档：一个公开，一个私有： POST /my_index/_doc/1 { "message": "This is a public message", "visibility": "public" } POST /my_index/_doc/2 { "message": "This is a private message", "visibility": "private" } 创建搜索管道 # 以下请求创建一个名为 my_pipeline 的搜索管道，其中包含一个 filter_query 查询重写处理器。该处理器使用 term 查询，仅返回可见性为“public”的文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/join/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/join/连接处理器 # join 处理器将数组中的元素连接成一个单独的字符串值，每个元素之间使用指定的分隔符。如果提供的输入不是数组，则抛出异常。 以下是为 join 处理器提供的语法： { "join": { "field": "field_name", "separator": "separator_string" } } 配置参数 # 下表列出了 join 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 应用连接操作符的字段名称。必须是数组。 separator 必填 字段值连接时使用的字符串分隔符。如果未指定，则值将无分隔符地连接。 target_field 可选 将清理后的值分配给的字段。如果未指定，则字段将就地更新。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/access-token/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/access-token/Access Token # Access Token 提供了一种面向程序调用的认证方式。客户端可以先由管理员签发 token，后续通过 HTTP 头 X-API-TOKEN 访问 Easysearch API，而不需要在每次请求中传递用户名和密码。 这一能力适合以下场景： 服务到服务的 API 调用 临时授予只读或特定动作权限 为自动化脚本、采集任务、运维工具发放独立凭据 相关指南（先读这些） # 权限控制总览 用户与角色 权限列表 安全 API 使用前提 # 在使用 Access Token 之前，请先确认： 安全模块已经启用。 你可以使用 superadmin 身份或 superuser 角色访问安全 API。 调用方已经明确需要的权限范围。 当前实现中，创建 Access Token 需要 superadmin 身份，或拥有 superuser 角色。在默认发行配置下，初始化后的 admin 用户通常会映射到 superuser；如果你修改过默认密码或角色映射，请改用实际具备相应权限的账户。 接口概览 # 操作 方法 路径 创建 token POST /_security/access_token 更新 token PUT /_security/access_token/{token_id} 删除 token DELETE /_security/access_token/{token_id} 搜索 token GET / POST /_security/access_token/search 创建 Access Token # 创建请求至少需要指定：https://docs.infinilabs.com/easysearch/v2.2.0/docs/release-notes/client/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/release-notes/client/版本发布日志 # 这里是 INFINI Easysearch-client 历史版本发布的相关说明。 2.0.2(2024-08-13) # Improvements # 升级相关依赖项至安全版本 2.0.0(2024-04-17) # Breaking changes # Features # 发布全新的 Easysearch java 客户端 2.0 版本。 客户端经过完全重构，更加轻量级，避免冗余的第三方依赖。 为常用 Easysearch API 提供强类型的请求和响应。 API 均支持阻塞和异步方式。 使用流式构建器和函数式模式，以在创建复杂嵌套结构时编写简洁易读的代码。 通过使用 Jackson 无缝集成应用程序类。 自带 Java 低级别 REST 客户端，处理所有传输级别的问题：HTTP 连接池、重试、节点发现等。 Bug fix # Improvements # 1.0.1(2023-11-14) # Breaking changes # Features # 正式发布 Easysearch Java 客户端。这一里程碑式的更新为开发人员带来了前所未有的便利性，使得与 Easysearch 集群的交互变得更加简洁和直观。现在，通过 Easysearch-client 客户端，开发者可以直接使用 Java 方法和数据结构来进行交互，而不再需要依赖于传统的 HTTP 方法和 JSON。这一变化大大简化了操作流程，使得数据管理和索引更加高效。高级客户端的功能范围包括处理数据操作，管理集群，包括查看和维护集群的健康状态，并对 Security 模块全面兼容。它提供了一系列 API，用于管理角色、用户、权限、角色映射和账户。这意味着安全性和访问控制现在可以更加细粒度地管理，确保了数据的安全性和合规性。 Bug fix # Improvements #https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/json/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/json/JSON 处理器 # json 处理器将字符串值字段序列化为一个嵌套的映射，这对于各种数据处理和丰富任务可能很有用。 以下是为 json 处理器提供的语法： { "processor": { "json": { "field": "<field_name>", "target_field": "<target_field_name>", "add_to_root": <boolean> } } } 配置参数 # 下表列出了 json 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要反序列化的 JSON 格式字符串的字段名称。 target_field 可选 字段名称，用于存储反序列化的 JSON 数据。如果未提供，数据将存储在 field 字段中。如果 target_field 存在，其现有值将被新的 JSON 数据覆盖。 add_to_root 可选 一个布尔标志，用于确定是否将反序列化的 JSON 数据添加到文档的根（ true ）或存储在目标字段（ false ）中。如果 add_to_root 是 true ，则 target-field 无效。默认值是 false 。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/edge-n-gram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/edge-n-gram/Edge N-gram 分词过滤器 # edge_ngram 分词过滤器与 ngram 分词过滤器非常相似，二者都会将特定字符串拆分成不同长度的子字符串。不过，edge_ngram 分词过滤器仅从词元的开头（边缘）生成 n 元子字符串。在自动补全或前缀匹配等场景中，它特别有用，因为在这些场景里，你希望在用户输入单词或短语时就能匹配词项的开头部分。 相关指南（先读这些） # 部分匹配 文本分析：识别词元 文本分析：规范化 参数说明 # 边缘 n 元分词过滤器可使用以下参数进行配置。 参数 必需/可选 数据类型 描述 min_gram 可选 整数 要生成的 n 元词项的最小长度。默认值为1。 max_gram 可选 整数 要生成的 n 元词项的最大长度。对于边缘 n 元分词过滤器，默认值为1；对于自定义分词过滤器，默认值为2。避免将此参数设置为较低的值。如果该值设置得过低，将只会生成非常短的 n 元词项，并且可能找不到搜索词。例如，将max_gram设置为 3，并且对单词“banana”建立索引，那么生成的最长词元将是“ban”。如果用户搜索“banana”，将不会返回任何匹配结果。你可以使用截断truncate分词过滤器作为搜索分析器来降低这种风险。 preserve_original 可选 布尔值 将原始词元包含在输出中。默认值为false。 参考样例 # 以下示例请求创建了一个名为 edge_ngram_example 的新索引，并配置了一个带有边缘 n 元过滤器的分词器：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/rename-field-processor/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/rename-field-processor/重命名字段处理器（Rename Field Processor） # 版本引入：1.14.0 rename_field 结果增强处理器用于拦截搜索响应，并对指定字段进行重命名。当你索引中的字段名称与应用程序使用的名称不一致时，该功能非常有用。例如，当索引中使用了新的字段名称，但应用程序仍期望接收旧字段名称时，可通过 rename_field 处理器在返回响应前完成字段名的映射，实现平滑过渡和向后兼容。 请求体字段 # 下表列出了该处理器支持的所有配置字段。 字段 数据类型 说明 field 字符串 要重命名的原始字段名。必填。 target_field 字符串 新的字段名称。必填。 tag 字符串 处理器的唯一标识符。可选。 description 字符串 对该处理器的描述信息。可选。 ignore_failure 布尔值 若为 true，当此处理器执行失败时，Easysearch 将忽略错误并继续执行搜索管道中的其余处理器。可选，默认值为 false。 示例 # 以下示例演示如何在搜索管道中使用 rename_field 处理器。 准备工作 # 创建一个名为 my_index 的索引，并索引一个包含 message 字段的文档： POST /my_index/_doc/1 { "message": "This is a public message", "visibility": "public" } 创建搜索管道 # 以下请求创建一个名为 my_pipeline 的搜索管道，其中包含一个 rename_field 结果增强处理器，用于将字段 message 重命名为 notification：https://docs.infinilabs.com/easysearch/v2.2.0/docs/release-notes/easysearch/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/release-notes/easysearch/版本发布日志 # 这里是 INFINI Easysearch 历史版本发布的相关说明。 Latest (In development) # Breaking changes # Features # Bug fix # Improvements # 2.2.0 (2026-05-06) # Breaking changes # repository-s3 插件底层 AWS SDK 升级至 2.x，相关依赖栈已同步更新。 Features # 新增 Agent UI，支持统一管理主机上的节点 新增模型提供商管理 UI 新增 API Token 管理 UI，支持在控制台中管理 Access Token 安全模块新增 Access Token 认证与授权能力 支持通过 X-API-TOKEN 进行程序化认证，减少脚本和服务调用中直接使用用户名密码的需求 支持 Access Token 的创建、更新、删除与检索 支持按 cluster / indices 粒度配置权限，且权限模型与角色权限保持一致 新增大模型供应商管理 API，支持通过 /_model_provider/* 统一管理模型供应商配置 支持模型供应商配置与模型参数的增删改查 api_key 支持加密存储，列表不返回，详情掩码返回，并支持独立更新 使用该 API 需配置相应权限 内置供应商配置支持写保护，避免被误修改或删除 规则引擎新增规则库管理与调试 API 支持通过 GET /_match_rules 查询规则库列表 支持通过 GET /_match_rules/{repo_id}/_references 查询规则库引用关系 支持通过 POST /_match_rules/{repo_id}/_simulate 对已编译规则库进行模拟匹配 新增规则引擎 UI 新增 Agent UI 巡检模块 Bug fix # 修复 cron 表达式表单正则校验 修复开发工具集群信息异常 修复点击服务管理页面的链接进入服务 UI 时出现 404 的中间页 修复自动生成管理员密码在有可能缺少随机特殊字条 修复节点设置中 easysearch.https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/client-api/java-client/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/client-api/java-client/Java 客户端 # Easysearch Java API Client 是 Easysearch 的官方 Java 客户端，提供了简洁、强大且类型安全的 API 接口。 相关指南（先读这些） # Java 客户端集成 客户端集成 全新重构的 2.0.x 版本，更轻量级的设计，移除冗余依赖。 兼容 Easysearch 各个版本。 为常用 Easysearch API 提供强类型的请求和响应。 API 均支持阻塞和异步方式。 使用流式构建器和函数式模式，以在创建复杂嵌套结构时编写简洁易读的代码。 通过使用 Jackson 无缝集成应用程序类。 快速开始 # 本页指导您完成Java客户端的安装过程，展示了如何实例化客户端，以及如何使用它执行基本的 Easysearch 操作。 安装 # easysearch-client 已经发布到 Maven https://mvnrepository.com/artifact/com.infinilabs/easysearch-client/2.0.2https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/kv/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/kv/KV 处理器 # kv 处理器会自动提取特定事件字段或消息，这些字段或消息以 key=value 格式存在。这种结构化格式通过将数据根据键和值分组来组织您的数据。这对于分析、可视化和使用数据非常有帮助，例如用户行为分析、性能优化或安全调查。 以下是为 kv 处理器提供的语法： { "kv": { "field": "message", "field_split": " ", "value_split": " " } } 配置参数 # 下表列出了 kv 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要解析的数据的字段名称。 field_split 必填 键值对分割的正则表达式模式。 value_split 必填 从键值对中分割键和值的正则表达式模式，例如，等号 = 或冒号 : 。 exclude_keys 可选 要排除的文档中的键。默认为 null 。 include_keys 可选 用于过滤和插入的键。默认为包含所有键。 prefix 可选 添加到提取键的前缀。默认为 null 。 strip_brackets 可选 如果设置为 true ，则从提取的值中去除括号（ () 、 <>, 或 [] ）和引号（ ' 或 " ）。默认为 false 。 trim_key 可选 从提取键中修剪的字符字符串。 trim_value 可选 从提取值中修剪的字符字符串。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。默认为 false 。 target_field 可选 要插入提取的键的字段名称。默认为 null 。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/document-model/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/document-model/文档建模 # 这一页回答两个问题：应该把什么放进一个文档？字段怎么设计才适合搜索？ 这里只讲单个文档层面的建模，跨文档关系放在“数据建模”章节。 什么是文档 # 在 Easysearch 中，一个 文档（Document） 是被序列化为 JSON 的最顶层对象，指定了唯一 ID 并存储到 Easysearch 中。例如： { "name": "John Smith", "age": 42, "confirmed": true, "join_date": "2014-06-01", "home": { "lat": 51.5, "lon": 0.1 }, "accounts": [ { "type": "facebook", "id": "johnsmith" }, { "type": "twitter", "id": "johnsmith" } ] } 文档可以包含字符串、数字、布尔、日期、嵌套对象、数组等多种类型。 文档元数据 # 每个文档都有三个核心元数据： 元数据 说明 _index 文档存放的索引，是逻辑命名空间 _id 文档的唯一标识符，可自定义或自动生成 _source 文档的原始 JSON 内容 此外，每个文档还有 _version 字段——每次对文档修改（包括删除）时版本号递增，用于并发控制。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/script-processor/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/script-processor/脚本处理器（Script Processor） # 版本引入：1.14.0 script 查询重写处理器用于拦截搜索请求，并在请求中添加一个内联的 Painless 脚本，该脚本会在接收到请求时执行。脚本仅能操作以下请求字段： from size explain version seq_no_primary_term track_scores track_total_hits min_score terminate_after profile 请求体字段 # 下表列出了该处理器支持的所有配置字段。 字段 数据类型 说明 source 内联脚本 要执行的脚本代码。必填。 lang 字符串 脚本语言。可选，默认为 painless，目前仅支持 painless。 tag 字符串 处理器的唯一标识符，用于调试或跟踪。可选。 description 字符串 对该处理器的描述信息。可选。 ignore_failure 布尔值 若为 true，当此处理器执行失败时，Easysearch 将忽略错误并继续执行后续处理器。可选，默认值为 false。 示例 # 以下请求创建一个名为 explain_one_result 的搜索管道，其中包含一个 script 查询重写处理器。该脚本的作用是：当请求返回多个结果时自动关闭 explain 功能，因为 explain 是一项开销较大的操作；仅在返回单个结果时启用。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/shingle/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/shingle/Shingle 分词过滤器 # shingle 分词过滤器用于从输入文本中生成词 n 元组（即词片）。例如，对于字符串 “slow green turtle”，词片过滤器会创建以下一元词片和二元词片：“slow”、“slow green”、“green”、“green turtle” 以及 “turtle”。 这个分词过滤器常常与其他过滤器结合使用，通过对短语而不是单个词元进行索引来提高搜索的准确性。 相关指南（先读这些） # 邻近匹配 文本分析：识别词元 文本分析：规范化 参数说明 # 词片分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 min_shingle_size 可选 整数 要连接的词元的最小数量。默认值为 2。 max_shingle_size 可选 整数 要连接的词元的最大数量。默认值为 2。 output_unigrams 可选 布尔值 是否将一元词（单个词元）包含在输出中。默认值为 true。 output_unigrams_if_no_shingles 可选 布尔值 如果未生成词片，是否输出一元词。默认值为 false。 token_separator 可选 字符串 用于将词元连接成词片的分隔符。默认值为一个空格（ ）。 filler_token 可选 字符串 插入到词元之间的空位置或间隙中的词元。默认值为下划线（_）。 如果 output_unigrams 和 output_unigrams_if_no_shingles 都设置为 true，则 output_unigrams_if_no_shingles 将被忽略。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/client-api/client-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/client-api/client-api/Easysearch Java API Client 使用文档 # 管理索引 # 使用客户端对索引进行管理 String index = "test1"; if (client.indices().exists(r -> r.index(index)).value()) { LOGGER.info("Deleting index " + index); DeleteIndexResponse deleteIndexResponse = client.indices().delete(new DeleteIndexRequest.Builder().index(index).build()); LOGGER.info(deleteIndexResponse.toString()); } LOGGER.info("Creating index " + index); CreateIndexResponse createIndexResponse = client.indices().create(req -> req.index(index)); CloseIndexResponse closeIndexResponse = client.indices().close(req -> req.index(index)); OpenResponse openResponse = client.indices().open(req -> req.index(index)); RefreshResponse refreshResponse = client.indices().refresh(req -> req.index(index)); FlushResponse flushResponse = client.indices().flush(req -> req.index(index)); ForcemergeResponse forcemergeResponse = client.https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/api/API # 通过 REST API 可以管理用户、角色、角色映射、权限集合和租户。 如果你要为程序或脚本签发并使用 X-API-TOKEN，请参见 Access Token。 API 的访问控制 # 您可以控制哪些角色可以访问安全相关的 API，在配置文件 easysearch.yml: security.restapi.roles_enabled: ["<role>", ...] 如果希望阻止访问特定的 API： security.restapi.endpoints_disabled.<role>.<endpoint>: ["<method>", ...] 参数 endpoint 可以是: PRIVILEGE ROLE ROLE_MAPPING USER CONFIG CACHE 参数 method 可以是: GET PUT POST DELETE PATCH 例如，以下配置授予三个角色对 REST API 的访问权限，但随后会阻止 test-role 发送 PUT, POST, DELETE, 或 PATCH 到 _security/role 或 _security/user : security.restapi.roles_enabled: ["superuser", "security", "test-role"] security.restapi.endpoints_disabled.test-role.ROLE: ["PUT", "POST", "DELETE", "PATCH"] security.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/cjk-bigram/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/cjk-bigram/CJK Bigram 分词过滤器 # cjk_bigram 分词过滤器是专门为处理东亚语言（如中文、日文和韩文，简称 CJK）而设计的，这些语言通常不使用空格来分隔单词。二元组是指在词元字符串中两个相邻元素的序列，这些元素可以是字符或单词。对于 CJK 语言来说，二元组有助于近似确定单词边界，并捕捉那些能够传达意义的重要字符对。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # CJK 二元分词过滤器可以通过两个参数进行配置：ignore_scripts（忽略字符集）和 output_unigrams（输出一元组）。 ignore_scripts（忽略字符集） # CJK 二元分词过滤器会忽略所有非 CJK 字符集（如拉丁字母或西里尔字母等书写系统），并且仅将 CJK 文本分词为二元组。可使用此选项指定要忽略的 CJK 字符集。该选项有以下有效值： han（汉字）：汉字字符集处理汉字。汉字是用于中国、日本和韩国书面语言的意符文字。该过滤器可帮助处理文本相关任务，例如对用中文、日文汉字或韩文汉字书写的文本进行分词、规范化或词干提取。 hangul（韩文）：韩文（谚文）字符集处理韩文字符，这些字符是韩语所特有的，不存在于其他东亚字符集中。 hiragana（平假名）：平假名字符集处理平假名，平假名是日语书写系统中使用的两种音节文字之一。平假名通常用于日语的本土词汇、语法元素以及某些形式的标点符号。 katakana（片假名）：片假名字符集处理片假名，片假名是日语的另一种音节文字。片假名主要用于外来借词、拟声词、科学名称以及某些日语词汇。 output_unigrams（输出一元组） # 当此选项设置为 true 时，会同时输出一元组（单个字符）和二元组。默认值为 false。 参考样例 # 以下示例请求创建了一个名为 devanagari_example_index 的新索引，并定义了一个分词器，该分词器使用了 cjk_bigram_filter 过滤器，且将 ignored_scripts 参数设置为 katakana（片假名）： PUT /cjk_bigram_example { "settings": { "analysis": { "analyzer": { "cjk_bigrams_no_katakana": { "tokenizer": "standard", "filter": [ "cjk_bigrams_no_katakana_filter" ] } }, "filter": { "cjk_bigrams_no_katakana_filter": { "type": "cjk_bigram", "ignored_scripts": [ "katakana" ], "output_unigrams": true } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/cjk-width/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/cjk-width/CJK Width 分词过滤器 # cjk_width 分词过滤器通过将全角 ASCII 字符转换为其标准（半角）ASCII 等效字符，并将半角片假名字符转换为全角等效字符，来对中文、日文和韩文（CJK）词元进行规范化处理。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 转换全角 ASCII 字符 # 在 CJK 文本中，ASCII 字符（如字母和数字）可能会以全角形式出现，占据两个半角字符的空间。全角 ASCII 字符在东亚排版中通常用于与 CJK 字符的宽度对齐。然而，出于索引和搜索的目的，这些全角字符需要规范化为其标准（半角）ASCII 等效字符。 以下示例说明了 ASCII 字符的规范化过程： 全角: ＡＢＣＤＥ １２３４５ 规范化 (半角): ABCDE 12345 转换半角片假名字符 # CJK 宽度分词过滤器会将半角片假名字符转换为对应的全角片假名字符，全角片假名是日语文本中使用的标准形式。如下例所示，这种规范化处理对于文本处理和搜索的一致性至关重要： 半角 katakana: ｶﾀｶﾅ 规范化 (全角) katakana: カタカナ 参考样例 # 以下示例请求创建了一个名为 cjk_width_example_index 的新索引，并定义了一个包含 cjk_width 过滤器的分词器： PUT /cjk_width_example_index { "settings": { "analysis": { "analyzer": { "cjk_width_analyzer": { "type": "custom", "tokenizer": "standard", "filter": ["cjk_width"] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/lowercase/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/lowercase/小写处理器 # lowercase 处理器将特定字段中的所有文本转换为小写字母。 语法 # 以下是为 lowercase 处理器提供的语法： { "lowercase": { "field": "field_name" } } 配置参数 # 下表列出了 lowercase 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要转换的数据的字段名称。支持模板使用。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true ，则处理器在字段不存在或为 null 时不会修改文档。默认为 false 。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 target_field 可选 要存储解析数据的字段名称。默认为 field 。默认情况下， field 将就地更新。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/semantic-query-enricher-processor/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/semantic-query-enricher-processor/语义查询增强处理器（Semantic Query Enricher Processor） # 需要 AI 插件 semantic_query_enricher 查询重写处理器用于拦截搜索请求，自动为其中的语义查询（semantic / hybrid 等基于 Embedding 模型的查询）注入模型连接信息（URL、API Key、vendor、model ID），使用户在编写查询时无需手动指定这些参数。 工作原理 # 当搜索请求到达管道时，处理器会遍历查询树，找到所有继承自 ModelBaseQueryBuilder 的查询节点（如 semantic 查询、hybrid 查询中的语义子查询），并为它们绑定 Embedding 请求参数： 从处理器配置中读取 url、vendor、api_key 根据 default_model_id 或 vector_field_model_id 为每个语义查询字段分配模型 ID 用户只需在查询中写 semantic 查询和查询文本，无需关心模型连接细节 请求体字段 # 字段 类型 是否必填 说明 url String 是 Embedding 模型服务的 URL vendor String 是 模型提供商标识（如 openai、dashscope、ollama 等） api_key String 否 模型服务的 API Key。存储时会自动加密 default_model_id String 条件必填 默认模型 ID，应用于所有未指定模型的语义查询字段。与 vector_field_model_id 至少提供一个 vector_field_model_id Object 条件必填 按向量字段指定模型 ID 的映射。格式：{"field_name": "model_id"}。与 default_model_id 至少提供一个 tag String 否 处理器标识标签 description String 否 处理器描述 ignore_failure Boolean 否 处理器失败时是否继续执行。默认 false 示例 # 使用全局默认模型 # PUT /_search/pipeline/my_semantic_pipeline { "rewrite_processors": [ { "semantic_query_enricher": { "tag": "enricher", "description": "为语义查询注入 Embedding 模型信息", "url": "https://dashscope.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/delete-by-query/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/document-operations/delete-by-query/Delete by Query # Delete by Query 删除所有匹配查询条件的文档。 适用于批量清理过期数据、删除特定条件的文档等场景。 内部流程：scroll 遍历匹配文档 → 逐批执行 bulk delete → 返回统计结果。 请求格式 # POST /<index>/_delete_by_query 路径参数 # 参数 必需 说明 <index> 是 目标索引，支持逗号分隔多索引和通配符 查询参数 # 参数 类型 默认值 说明 refresh boolean false 操作完成后是否刷新受影响的分片 timeout time 1m 超时时间 wait_for_completion boolean true 为 true 时同步等待；为 false 时立即返回 task ID wait_for_active_shards string — 操作前需要的活跃分片数量 requests_per_second float 无限制 每秒请求数限制。-1 = 不限制 slices int/string 1 并行切片数。"auto" = 按分片数自动拆分 scroll time — scroll 上下文存活时间 scroll_size int 1000 每批 scroll 获取的文档数 conflicts string abort 版本冲突处理：abort = 中止；proceed = 跳过继续 max_docs int 全部 最多删除的文档数量 search_timeout time — 搜索阶段超时 q string — 简单查询字符串 df string — q 参数的默认字段 default_operator string OR q 参数的默认运算符 analyzer string — q 参数使用的分析器 analyze_wildcard boolean false 是否分析通配符 lenient boolean — 宽松解析模式 routing string — 路由值 preference string — 查询偏好 terminate_after int 0 每分片最多处理的文档数 expand_wildcards string open 通配符展开方式 ignore_unavailable boolean false 忽略不存在的索引 allow_no_indices boolean true 允许通配符不匹配任何索引 请求体 # { "query": { .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/ik-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/ik-analyzer/IK 分析器 # IK 分析器是一款专为处理中文文本设计的分析器，高效且智能。支持 ik_smart 和 ik_max_word 两种分词模式。 相关指南（先读这些） # 文本分析基础 文本分析：识别词元 IK 分词器安装 # IK 分词插件安装命令如下： bin/easysearch-plugin install analysis-ik 同时也需要安装 ingest-common 插件： bin/easysearch-plugin install ingest-common 如果觉得比较麻烦，也可以直接使用 Easysearch 的 bundle 包安装部署。 使用样例 # 下面的命令样例展示了 IK 的使用方式。 # 1.创建索引 PUT index_ik # 2.创建映射关系 POST index_ik/_mapping { "properties": { "content": { "type": "text", "analyzer": "ik_max_word", "search_analyzer": "ik_smart" } } } # 3.写入文档 POST index_ik/_create/1 {"content":"美国留给伊拉克的是个烂摊子吗"} POST index_ik/_create/2 {"content":"公安部：各地校车将享最高路权"} POST index_ik/_create/3 {"content":"中韩渔警冲突调查：韩警平均每天扣1艘中国渔船"} POST index_ik/_create/4 {"content":"中国驻洛杉矶领事馆遭亚裔男子枪击 嫌犯已自首"} # 4.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/ip/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/ip/IP 地址字段类型 # IP 字段类型用于存储 IPv4 或 IPv6 格式的 IP 地址。 要表示 IP 地址范围，可以使用 IP 范围字段类型 参考代码 # 创建一个有 IP 地址的 mapping PUT testindex { "mappings" : { "properties" : { "ip_address" : { "type" : "ip" } } } } 索引一个有 IP 地址的文档 PUT testindex/_doc/1 { "ip_address" : "10.24.34.0" } 查询一个特定 IP 地址的索引 GET testindex/_doc/1 { "query": { "term": { "ip_address": "10.24.34.0" } } } 搜索 IP 地址及其关联的网络掩码 # 您可以使用无类别域间路由 (CIDR) 表示法查询索引中的 IP 地址。在 CIDR 表示法中，通过斜杠 / 分隔 IP 地址和前缀长度（0–32）。例如，前缀长度为 24 表示匹配所有具有相同前 24 位的 IP 地址。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/vector-search/knn_api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/vector-search/knn_api/k-NN 查询 API # 先决条件 # 要运行 k-NN 搜索，必须安装 knn 插件，参考 插件安装。 注意：从 1.11.1 版本起，创建 k-NN 索引时不再需要配置 index.knn 参数。 向量字段的映射参数、各索引模型和相似度函数的详细说明，请参阅 向量字段类型参考。 查询语法 # 所有向量搜索都通过 knn_nearest_neighbors 查询完成： GET /<index>/_search { "query": { "knn_nearest_neighbors": { "field": "<vector_field>", "vec": { ... }, "model": "<model>", "similarity": "<similarity>", "candidates": <n> } } } 查询参数 # 参数 类型 必填 说明 field String ✅ 向量字段名称 vec Object ✅ 查询向量，支持三种格式（见下方） model String ✅ 索引模型：lsh、exact、permutation_lsh、sparse_indexed similarity String ✅ 相似度函数，必须与映射中的配置一致 candidates Integer 否 近似搜索的候选数量。仅用于 lsh/permutation_lsh/sparse_indexed 模型。越大越精准但越慢，推荐 size 的 5～10 倍 probes Integer 否 仅用于 l2 相似度的 LSH 查询：探测数量 查询向量格式 # 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/langchain/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/langchain/LangChain 集成 # LangChain 是最流行的 LLM 应用开发框架。通过将 Easysearch 作为 Vector Store，可以构建 RAG（Retrieval-Augmented Generation）应用，让大模型基于企业知识库进行问答。 架构概览 # 用户提问 → LangChain ↓ 1. Embedding 模型将问题转为向量 ↓ 2. Easysearch 向量检索（kNN）找到相关文档 ↓ 3. 将相关文档 + 问题发送给 LLM ↓ 4. LLM 生成基于上下文的回答 ↓ 用户得到答案 安装 # pip install langchain langchain-community elasticsearch 连接 Easysearch # from elasticsearch import Elasticsearch es = Elasticsearch( hosts=["https://localhost:9200"], basic_auth=("admin", "your-password"), verify_certs=False # 自签名证书时使用 ) # 验证连接 print(es.info()) 作为 Vector Store 使用 # 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/scripting/expressions/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/scripting/expressions/Lucene 表达式 脚本语言 # Lucene Expressions 是一种轻量级的数学表达式脚本语言，编译为 Java 字节码，性能极高。适用于简单的数值计算场景，如自定义排序和评分。 特点 # 特性 说明 性能 极高，直接编译为字节码，无解释器开销 安全 完全沙盒，只能进行数学运算 功能范围 仅支持数值运算和比较 数据访问 只能访问 doc values（doc['field']） 返回类型 始终返回 double 语法 # 基本运算 # doc['price'].value * 0.9 doc['score'].value + doc['bonus'].value (doc['a'].value + doc['b'].value) / 2 数学函数 # 函数 说明 示例 abs(x) 绝对值 abs(doc['delta'].https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/macos/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/macos/MacOS 环境下使用 Easysearch # 目前，有多种方案可以在 MacOS 下体验 Easysearch。可以选择使用 Docker 方式安装，或者使用本地安装包进行安装。 前置要求 # macOS 10.15 (Catalina) 或更高版本 JDK 11+（推荐 JDK 17）。Bundle 包已内置 JDK，无需单独安装。 至少 4 GB 可用内存 方案一：Docker 安装（推荐） # 如果您的 MacOS 环境上有 Docker（Docker Desktop、OrbStack 等），可以用最简单的方式启动 Easysearch： docker run -d --name easysearch \ -p 9200:9200 \ -e "EASYSEARCH_INITIAL_ADMIN_PASSWORD=EasysearchP@ssw0rd!" \ -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" \ infinilabs/easysearch:latest 详细 Docker 配置请参考 Docker 环境下使用 Easysearch。 方案二：本地安装 # 使用一键安装脚本进行安装，请按照以下步骤操作：https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/nested/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/nested/Nested 建模 # Nested 解决的是这样一种典型需求：数组里是一组对象，而不是一堆无关字段的拼接，查询时既要对数组元素内部做精确匹配，又不想被"笛卡尔积假匹配"坑到。 什么时候需要 nested？ # 先看一个常见例子：订单里有多条明细 items： { "order_id": "O-1", "items": [ { "sku": "A", "price": 100, "qty": 1 }, { "sku": "B", "price": 200, "qty": 2 } ] } 如果你把 items.sku、items.price、items.qty 都当成普通多值字段： items.sku = [“A”, “B”] items.price = [100, 200] items.qty = [1, 2] 此时一个查询： items.sku = "A" 且 items.price = 200 在"扁平多值字段"模型下是会命中的（因为它只在每个字段内部看是否包含该值），但现实里并不存在 sku=A 且 price=200 这一条明细。这就是经典的"笛卡尔积假匹配"。 要避免这种问题，就需要 nested。 如何定义 nested 字段 # 在 Mapping 中，把数组元素声明为 nested 类型（示意）：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/rag-and-llm/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/rag-and-llm/RAG 与 LLM 集成 # 检索增强生成（Retrieval-Augmented Generation，RAG）是一种将搜索引擎与大语言模型（LLM）结合的架构模式。Easysearch 作为高性能检索层，可以为 LLM 提供精准的上下文信息，显著提升生成质量。 相关指南（先读这些） # Embedding 服务接入 向量工作流与 Hybrid 检索 Hybrid Search API LangChain 集成 RAG 架构概览 # 典型的 RAG 流程如下： 用户提问 ↓ 1. 查询改写（可选） ↓ 2. 检索阶段：在 Easysearch 中搜索相关文档 - 全文搜索（BM25） - 向量搜索（kNN） - 混合搜索（Hybrid） ↓ 3. 结果裁剪：选取 Top-K 段落，控制 token 数量 ↓ 4. Prompt 组装：将检索结果 + 用户问题拼接为 Prompt ↓ 5. LLM 生成：调用 LLM API 生成答案 ↓ 6.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/raid/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/raid/RAID 配置指南 # 本文讨论 Easysearch 环境中 RAID 的选型与配置建议。 RAID 与 Easysearch 的关系 # Easysearch 自身通过副本机制实现数据冗余。因此 RAID 在 Easysearch 场景中的定位与传统数据库不同： 方案 数据冗余 性能 适用场景 无 RAID + 副本 由 ES 副本保障 最高 推荐方案 RAID-0 无 高 多 SATA 盘聚合（有副本前提下） RAID-1 镜像 中 单节点无副本（不推荐） RAID-5/6 校验 较低 不推荐（写放大严重） RAID-10 镜像+条带 中高 预算充足且需要本地冗余 核心建议：优先使用 Easysearch 副本，而非 RAID 来保障数据安全。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/superset/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/clients/superset/Apache Superset 集成 # Apache Superset 是一款强大的开源数据可视化与 BI 平台。通过 Elasticsearch 连接器，Superset 可以直接查询 Easysearch 中的数据并构建交互式看板。 相关指南 # SQL 查询接口 Grafana 集成 前置条件 # 条件 说明 Superset 版本 2.0+ 推荐 Python 驱动 elasticsearch-dbapi 包 网络可达 Superset 服务器能够访问 Easysearch 端口 Easysearch SQL 功能 确保 SQL 插件已启用 安装驱动 # 在 Superset 运行环境中安装 Elasticsearch 驱动：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/binary/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/binary/二进制字段类型 # 二进制字段类型包含以 Base64 编码存储的二进制值，这些值不可被搜索。 参考代码 # 创建包含二进制字段的映射 PUT testindex { "mappings" : { "properties" : { "binary_value" : { "type" : "binary" } } } } 索引一个二进制值的文档 PUT testindex/_doc/1 { "binary_value" : "bGlkaHQtd29rfx4=" } 使用 = 作为填充字符。不允许嵌入换行符。 参数说明 # 以下参数均为可选参数 参数 数据类型 默认值 描述 doc_values Boolean false 是否存储在磁盘上，用于聚合、排序或脚本。 store Boolean false 是否单独存储字段值，使其可以独立于 _source 被检索。 使用场景 # 二进制字段适合存储小型二进制数据，例如：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ingest/jdbc-etl/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ingest/jdbc-etl/从数据库同步数据（JDBC / ETL） # 将关系型数据库（MySQL、PostgreSQL 等）中的数据同步到 Easysearch 是一个常见需求。本文介绍全量导入和增量同步的主要方案和实践。 相关指南（先读这些） # Logstash 接入 SeaTunnel 集成 Bulk API 同步方案概览 # 方案 全量 增量 实时性 复杂度 说明 Logstash JDBC Input ✅ ✅ 分钟级 低 定时轮询数据库，适合中小规模 SeaTunnel ✅ ✅ 分钟级 中 分布式 ETL，适合大数据量 Canal / Debezium (CDC) ❌ ✅ 秒级 高 基于 binlog，实时捕获变更 自研同步程序 ✅ ✅ 灵活 高 完全自定义，适合特殊需求 Logstash JDBC Input（推荐入门） # 基本配置 # # logstash-jdbc.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/position_increment_gap/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/position_increment_gap/Position Increment Gap 参数 # position_increment_gap 参数控制数组中相邻文本值之间的位置间隔。该参数影响短语查询（match_phrase）在跨数组元素时的匹配行为。 相关指南 # 全文搜索 analyzer 参数 默认值 # 默认值为 100。 为什么需要 position_increment_gap # 当一个 text 字段接受数组值时，各元素的文本会被拼接分析。例如： PUT my-index/_doc/1 { "tags": ["quick brown", "fox jumps"] } 分析后的词条位置： 词条 位置 quick 0 brown 1 fox 102 （1 + 100 + 1） jumps 103 默认间隔 100 使得 match_phrase 查询 "brown fox" 不会匹配该文档，因为 brown（位置 1）和 fox（位置 102）之间有 100 个位置的间隔，远大于短语查询允许的 slop。https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/java-client/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/java-client/Java 客户端快速入门 # 本页面帮助你快速跑通 Easysearch Java API Client 连接 Easysearch 的完整流程。更深入的用法请参阅 Java 客户端详细指南。 Easysearch Java API Client 是 Easysearch 的官方 Java 客户端，提供了强类型、流式构建器风格的 API 接口： 全新 2.0.x 版本，更轻量，移除冗余依赖 兼容 Easysearch 各版本 支持阻塞和异步两种调用方式 使用 Jackson 无缝集成应用类 添加依赖 # Maven： <dependency> <groupId>com.infinilabs</groupId> <artifactId>easysearch-client</artifactId> <version>2.0.2</version> </dependency> Gradle： implementation 'com.infinilabs:easysearch-client:2.0.2' 💡 已发布到 Maven 中央仓库： mvnrepository.com/artifact/com.infinilabs/easysearch-client，需要 JDK 8 或以上版本。 建立连接 # import com.infinilabs.clients.easysearch.EasysearchClient; import com.infinilabs.clients.json.jackson.JacksonJsonpMapper; import com.infinilabs.clients.transport.rest_client.RestClientTransport; import com.infinilabs.clients.transport.EasysearchTransport; import org.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/meta/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/meta/_meta 元数据字段 # _meta 字段是一个映射属性，允许您为索引映射附加自定义元数据。您的应用程序可以使用这些元数据来存储与您的用例相关的信息，如版本控制、所有权、分类或审计。 相关指南（先读这些） # 映射基础 元数据字段 用法 # 您可以在创建新索引或更新现有索引的映射时定义 _meta 字段，如以下示例所示： PUT my-index { "mappings": { "_meta": { "application": "MyApp", "version": "1.2.3", "author": "John Doe" }, "properties": { "title": { "type": "text" }, "description": { "type": "text" } } } } 在此示例中，添加了三个自定义元数据字段：application、version 和 author。您的应用程序可以使用这些字段来存储有关索引的任何相关信息，例如它所属的应用程序、应用程序版本或索引的作者。 您可以使用 Put Mapping API 操作更新 _meta 字段，如以下示例所示： PUT my-index/_mapping { "_meta": { "application": "MyApp", "version": "1.3.0", "author": "Jane Smith" } } 检索元数据信息 # 您可以使用 Get Mapping API 操作检索索引的 _meta 信息，如以下示例所示：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/meta/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/meta/Meta 参数 # meta 参数允许为字段附加自定义元数据。这些元数据不影响搜索或索引行为，仅用于记录字段的业务含义或管理信息。 相关指南 # 映射基础 示例 # PUT my-index { "mappings": { "properties": { "latency": { "type": "long", "meta": { "unit": "ms", "description": "接口响应延迟" } }, "cpu_usage": { "type": "float", "meta": { "unit": "percent", "metric_type": "gauge" } } } } } 典型用途 # 场景 示例 meta 键值 标注计量单位 "unit": "ms", "unit": "bytes" 标记指标类型 "metric_type": "counter", "metric_type": "gauge" 记录字段用途 "description": "用户最后登录时间" 标记数据来源 "source": "nginx_access_log" 团队归属信息 "owner": "data-team" 通过 API 查看 # 字段元数据会在 Get Mapping API 的响应中返回：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/fulltext-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/fulltext-search/全文检索 # 全文检索的核心特点是：对 text 字段做分词与评分，用“相关性”来排序结果。本页只关注最常用的几类查询及常见坑。 前提：字段必须是可分析（text）类型 # 全文查询（match/match_phrase/multi_match 等）应该作用在 text 字段 上： 写入时会通过 analyzer 做分词、归一化（大小写、同义词等） 查询时会用同一个 analyzer 处理查询词，再去匹配倒排索引 如果字段是 keyword/数值/日期，更适合使用 Term 级别查询。 match：最常用的全文查询 # match 会： 对查询字符串分词 按字段的 analyzer 处理 把多个词项组合成一个全文查询，并参与 _score 计算 示例： { "query": { "match": { "title": "分布式 搜索 引擎" } } } 常见参数： operator：or（默认）或 and minimum_should_match：要求最少命中多少词 一个直觉对比： operator: "and"：所有词都必须出现，召回会明显变少，但结果通常更“干净” minimum_should_match: "75%"：允许部分词缺失，在“可搜到”和“不要太多噪声”之间找折中 示例（用户搜索“分布式 搜索 引擎 调优”）：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/analyzer/Analyzer 参数 # analyzer 映射参数用于定义在索引和搜索期间应用于文本字段的文本分析过程。 相关指南（先读这些） # 映射基础 文本分析基础 代码样例 # 以下示例配置定义了一个名为 my_custom_analyzer 的自定义分词器： PUT my_index { "settings": { "analysis": { "analyzer": { "my_custom_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "my_stop_filter", "my_stemmer" ] } }, "filter": { "my_stop_filter": { "type": "stop", "stopwords": ["the", "a", "and", "or"] }, "my_stemmer": { "type": "stemmer", "language": "english" } } } }, "mappings": { "properties": { "my_text_field": { "type": "text", "analyzer": "my_custom_analyzer", "search_analyzer": "standard", "search_quote_analyzer": "my_custom_analyzer" } } } } 在此示例中，my_custom_analyzer 使用标准分词器，将所有标记转换为小写，应用自定义停用词过滤器，并应用英语词干提取器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/create-prod-cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/create-prod-cluster/创建生产模式集群 # 操作步骤 # 进入服务管理页面：登录 Agent UI 后，在服务管理页面，点击「安装 Easysearch」区域的「创建集群」按钮。 完成系统环境检测：进入安装向导，系统会自动检测操作系统、内存、JDK 等安装前置条件，确认所有项均通过后，点击「开始安装」。 选择集群模式：在安装模式选择页，点击「生产模式 | 新集群」卡片，进入生产模式配置流程。 配置基础环境信息： 选择 Easysearch 版本、JDK 版本。 填写网络配置：监听地址、HTTP 端口、Transport 端口，点击「检测端口」确保端口可用。 设置管理员密码，可使用「生成密码并复制」快速生成强密码。 完成高级配置项： 配置安全模式，可选择自动生成 CA 和节点证书或上传现有证书。 - 设置 JVM 内存，建议根据系统可用内存分配。 - 填写集群名称、节点名称，可按需开启自定义数据目录、日志目录。 - 勾选需要安装的插件（如 ai、analysis-ik 等）。 启动集群创建流程：配置完成后，点击页面底部的「开始安装」，系统将自动执行下载、解压、配置证书、启动服务等步骤。 确认集群创建结果：等待安装进度完成，页面提示「集群创建成功」后，可查看集群状态、节点信息，点击「打开 Easysearch」进入集群管理界面。 注意事项 # 生产模式集群对系统资源要求较高，建议在安装前确保系统内存、CPU 等资源满足推荐配置，避免因资源不足导致集群性能异常。 端口配置需确保未被其他进程占用，HTTP 端口默认 9200、Transport 端口默认 9300，如已被占用需手动修改。 管理员密码需妥善保存，若使用自动生成密码，需提前复制保存，避免后续无法登录集群。 插件安装需根据业务需求选择，安装过多不必要的插件可能影响集群启动速度和运行性能。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/alias/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/alias/Alias 别名字段类型 # 别名字段类型为现有字段创建另一个名称。您可以在搜索和字段功能的 API 操作中使用别名字段，但存在一些例外情况。要设置别名，必须在 path 参数中指定原始字段名称。 参考代码 # PUT movies { "mappings" : { "properties" : { "year" : { "type" : "date" }, "release_date" : { "type" : "alias", "path" : "year" } } } } 参数说明 # path：指向原始字段的完整路径，包括所有父对象。例如，parent.child.field_name。此参数为必填项。 别名（Alias）字段 # 别名（Alias）字段必须遵循以下规则： 一个别名字段只能引用一个原始字段。 在嵌套对象中，别名必须与原始字段位于相同的嵌套层级。 要更改别名引用的字段，需要更新映射配置。但请注意，之前存储的 Percolator 查询中的别名仍会继续引用原始字段，不会自动更新为新的字段引用。 原始字段 # 别名的原始字段必须遵守以下规则： 原始字段必须在别名字段创建之前定义。 原始字段不能是对象类型，也不能是另一个别名字段。 可以使用别名字段的搜索 API # 您可以在以下搜索 API 的只读操作中使用别名：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/boost/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/boost/Boost 参数 # ⚠️ 已弃用：映射级别的 boost 参数已被弃用，将在未来版本中移除。请改为在查询时通过 boost 参数控制字段权重。 boost 映射参数用于在搜索查询期间增加或减少字段的相关性分数。它允许你在计算文档的整体相关性分数时，对特定字段应用更多或更少的权重。默认值为 1.0。 boost 参数作为字段分数的乘数应用。例如，如果一个字段的 boost 值为 2，则该字段的分数的权重将翻倍。相反，boost 值为 0.5 将使该字段的分数的权重减半。 相关指南（先读这些） # 映射基础 相关性：加权与调参 代码样例 # 以下是在 Easysearch 映射中使用 boost 参数的示例： PUT my-index1 { "mappings": { "properties": { "title": { "type": "text", "boost": 2 }, "description": { "type": "text", "boost": 1 }, "tags": { "type": "keyword", "boost": 1.5 } } } } 在此示例中，title 字段的提升值为 2，这意味着它对整体相关性分数的权重是描述字段（提升值为 1）的两倍。tags 字段的提升值为 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/dynamic/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/dynamic/Dynamic 参数 # dynamic 参数指定是否可以动态地将新检测到的字段添加到映射中。它接受下表中列出的参数。 参数 描述 true 指定可以动态地将新字段添加到映射中。默认值为 true。 false 指定不能动态地将新字段添加到映射中。如果检测到新字段，则不会对其进行索引或搜索，但可以从 _source 字段中检索。 strict 当检测到文档中有新字段时，索引操作失败，抛出异常。 相关指南（先读这些） # 映射基础 映射模式 示例：创建 dynamic 设置为 true 的索引 # 通过以下命令创建一个 dynamic 设置为 true 的索引： PUT testindex1 { "mappings": { "dynamic": true } } 通过以下命令，索引一个包含两个字符串字段的对象字段 patient 的文档： PUT testindex1/_doc/1 { "patient": { "name" : "John Doe", "id" : "123456" } } 通过以下命令确认映射按预期工作：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/word-delimiter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/word-delimiter/Word Delimiter 分词过滤器 # word_delimiter 分词过滤器用于根据预定义的字符拆分词元，还能根据可定制规则对词元进行可选的规范化处理。 注意：我们建议尽可能使用 word_delimiter_graph 过滤器而非 word_delimiter 过滤器，因为 word_delimiter 过滤器有时会生成无效的词元图。 提示：word_delimiter 过滤器可用于从零件编号或产品 ID 等复杂标识符中去除标点符号。在这种情况下，它最好与 keyword 分词器配合使用。对于带连字符的单词，建议使用 synonym_graph 分词过滤器而非 word_delimiter 过滤器，因为用户搜索这些词项时，常常既会搜索带连字符的形式，也会搜索不带连字符的形式。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 默认情况下，该过滤器应用以下规则： 描述 输入 输出 将非字母数字字符视为分隔符 ultra-fast ultra, fast 去除词元开头或结尾的分隔符 Z99++'Decoder' Z99, Decoder 当字母大小写发生转换时拆分词元 Easysearch Easy, search 当字母和数字之间发生转换时拆分词元 T1000 T, 1000 去除词元末尾的所有格形式（‘s） John's John 重要提示：不要将该过滤器与会去除标点符号的分词器（如标准分词器）一起使用。这样做可能会导致词元无法正确拆分，并影响诸如 catenate_all 或 preserve_original 等选项的效果。我们建议将此过滤器与关键(keyword)字分词器或空白(whitespace)分词器配合使用。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/knn/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/knn/K-NN 向量字段类型 # 相关指南（先读这些） # 向量搜索 向量字段建模 映射基础 关于向量 # 在索引文档和运行查询时都需要指定向量类型。在这两种情况下，您都使用相同的 JSON 结构来定义向量类型。每个向量类型还有一个简写形式，这在使用不支持嵌套文档的工具时会很方便。以下示例展示了如何在索引向量时指定它们。 knn_dense_float_vector 密集向量类型 # 假设您已经定义了一个映射，其中 my_vec 的类型为 knn_dense_float_vector。 POST /my-index/_doc { "my_vec": { "values": [0.1, 0.2, 0.3, ...] # 1 } } POST /my-index/_doc { "my_vec": [0.1, 0.2, 0.3, ...] # 2 } 说明 # 1 向量中所有浮点值的 JSON 列表。长度应与映射中的dims匹配。 2 #1 的简写形式。 knn_sparse_bool_vector 稀疏向量类型 # 假设您已经定义了一个映射，其中 my_vec 的类型为 knn_sparse_bool_vector。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/enabled/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/enabled/Enabled 参数 # enabled 参数允许您控制 Easysearch 是否解析字段的内容。此参数可以应用于顶级映射定义和对象字段。 enabled 参数接受以下值： 参数 描述 true 字段被解析和索引。默认值为 true。 false 字段不被解析或索引，但仍可从 _source 字段中检索。当 enabled 设置为 false 时，Easysearch 将字段的值存储在 _source 字段中，但不索引或解析其内容。这对于您想要存储但不需要搜索、排序或聚合的字段很有用。 相关指南（先读这些） # 映射基础 映射模式 示例：使用 enabled 参数 # 在以下示例请求中，session_data 字段被禁用。Easysearch 将其内容存储在 _source 字段中，但不对其进行索引或解析： PUT my-index-002 { "mappings": { "properties": { "user_id": { "type": "keyword" }, "last_updated": { "type": "date" }, "session_data": { "type": "object", "enabled": false } } } } 使用场景 # 存储原始 JSON 但不索引 # enabled: false 非常适合那些需要随文档一起返回但不需要被搜索的数据：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/geo-field-type/geo-point/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/geo-field-type/geo-point/地理坐标点字段类型（Geo Point） # geo_point 字段类型包含由纬度（latitude）和经度（longitude）指定的地理点。地理坐标点可以用来计算两个坐标间的距离，判断一个坐标是否在一个区域中，或在聚合中。 代码示例 # 创建一个带有 Geopoint 地理点字段类型的映射： PUT testindex1 { "mappings": { "properties": { "point": { "type": "geo_point" } } } } 地理坐标点不能被动态映射自动检测，必须显式声明字段类型为 geo_point。 地理点格式 # Geopoint 地理点可以用以下格式索引： 包含纬度和经度的对象 PUT testindex1/_doc/1 { "point": { "lat": 40.71, "lon": 74.00 } } 写入包含纬度,经度 的文档 PUT testindex1/_doc/2 { "point": "40.71,74.00" } geohash 格式的文档 PUT testindex1/_doc/3 { "point": "txhxegj0uyp3" } [经度, 纬度] 格式的数组 PUT testindex1/_doc/4 { "point": [74.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/geo-field-type/geo-shape/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/geo-field-type/geo-shape/地理形状字段类型（Geo Shape） # geo_shape 字段类型包含地理形状，例如多边形或地理点的集合。为了索引地理形状，Easysearch 会将形状分割成三角形网格，并将每个三角形存储在 BKD 树中。这提供了 10^-7 度的精度，代表了接近完美的空间分辨率。这个过程的性能主要受到您正在索引的多边形顶点数量多少的影响。 Geo-shapes 可以用来判断查询的形状与索引的形状的关系： intersects：查询的形状与索引的形状有重叠（默认） disjoint：查询的形状与索引的形状完全不重叠 within：索引的形状完全被包含在查询的形状中 contains：索引的形状完全包含查询的形状 注意：Geo-shapes 不能用于计算距离、排序、打分以及聚合。如需距离排序，请使用 geo_point 字段。 代码样例 # 创建一个带有地理形状字段类型的映射： PUT testindex { "mappings": { "properties": { "location": { "type": "geo_shape" } } } } 格式说明 # 地理形状可以用以下格式索引： GeoJSON Well-Known Text (WKT) 在 GeoJSON 和 WKT 中，坐标必须在坐标数组中按照 经度, 纬度 的顺序指定。注意在这种格式中经度是在前面的。 地理形状类型 # 下表描述了可能的地理形状类型以及它们与 GeoJSON 和 WKT 类型的关系。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/copy_to/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/copy_to/Copy To 参数 # copy_to 参数允许您将多个字段的值复制到单个字段中。如果您经常跨多个字段搜索，此参数会很有用，因为这样可以达到搜索一组字段的效果。 只有字段值被复制，而不是分析器产生的词项。原始的 _source 字段保持不变，并且可以使用 copy_to 参数将相同的值复制到多个字段。但是，字段间不支持递归复制；相反，应该直接使用 copy_to 从源字段复制到多个目标字段。 相关指南（先读这些） # 映射基础 多字段搜索 代码样例 # 以下示例使用 copy_to 参数通过产品的名称和描述进行搜索，并将这些值复制到单个字段中： PUT my-products-index { "mappings": { "properties": { "name": { "type": "text", "copy_to": "product_info" }, "description": { "type": "text", "copy_to": "product_info" }, "product_info": { "type": "text" }, "price": { "type": "float" } } } } PUT my-products-index/_doc/1 { "name": "Wireless Headphones", "description": "High-quality wireless headphones with noise cancellation", "price": 99.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/complex/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/complex/复杂查询 # 本章介绍子查询、JOIN 连接和条件表达式等进阶 SQL 功能。 子查询（Subquery） # 子查询是嵌套在另一个 SQL 语句中的完整 SELECT 语句，用括号括起来。Easysearch SQL 支持两种形式的子查询。 WHERE IN 子查询 # 在 WHERE 子句中使用 IN 加子查询来过滤符合条件的文档。底层会被转换为等效的 JOIN 查询执行。 POST /_sql { "query": """ SELECT a1.firstname, a1.lastname, a1.balance FROM accounts a1 WHERE a1.account_number IN ( SELECT a2.account_number FROM accounts a2 WHERE a2.balance > 10000 ) """ } 结果： a1.firstname a1.lastname a1.balance Amber Duke 39225 Nanette Bates 32838 FROM 子查询 # 在 FROM 子句中使用子查询作为派生表，子查询必须指定别名。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/fields/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/fields/Fields 参数（Multi-fields） # fields 参数允许你对同一个字段以多种方式进行索引。这是 Easysearch 中最常用的映射技巧之一，典型场景是：一个字段同时需要全文搜索（text）和精确匹配/排序/聚合（keyword）。 相关指南（先读这些） # 映射基础 映射模式与最佳实践 基本语法 # PUT my-index { "mappings": { "properties": { "title": { "type": "text", "fields": { "raw": { "type": "keyword" } } } } } } 上面的映射中，title 字段被索引为 text（用于全文搜索），同时通过 fields.raw 创建了一个 keyword 子字段（用于精确匹配、排序和聚合）。 查询时使用方式： 全文搜索："match": { "title": "搜索引擎" } 精确匹配："term": { "title.raw": "Easysearch 分布式搜索引擎" } 排序："sort": [{ "title.raw": "asc" }] 聚合："aggs": { "titles": { "terms": { "field": "title.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/field-names/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/field-names/_field_names 元数据字段 # _field_names 字段索引包含非空值的字段名称。可以使用 exists 查询来识别指定字段是否具有非空值的文档。 但是，只有当 doc_values 和 norms 都被禁用时，_field_names 才会索引字段名称。如果启用了 doc_values 或 norms 中的任何一个，则 exists 查询仍然可以工作，但不会依赖 _field_names 字段。 相关指南（先读这些） # 映射基础 元数据字段 映射示例 # PUT testindex { "mappings": { "_field_names": { "enabled": true }, "properties": { "title": { "type": "text", "norms": false }, "description": { "type": "text" }, "price": { "type": "float", "doc_values": false } } } }https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/fielddata/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/fielddata/Fielddata 参数 # fielddata 参数控制 text 字段是否可以用于排序、聚合和脚本。 默认情况下，text 字段不支持排序和聚合——因为 text 字段使用倒排索引，按词项而非完整值存储，无法高效地做正排查找。fielddata 通过将整个倒排索引加载到 JVM 堆内存来实现这一功能，但这 非常消耗内存，通常不推荐使用。 相关指南（先读这些） # 映射基础 映射模式与最佳实践 Doc Values 参数 参数选项 # 值 说明 false 禁用 fielddata。对 text 字段执行排序/聚合会报错。默认值。 true 启用 fielddata。允许对 text 字段排序和聚合，但会大量消耗堆内存。 示例 # PUT my-index { "mappings": { "properties": { "content": { "type": "text", "fielddata": true } } } } ⚠️ 警告：在生产环境中启用 fielddata 可能导致大量内存消耗，甚至触发断路器（circuit breaker）或 OOM。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/store/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/store/Store 参数 # store 参数指定字段值是否应被独立存储，以便可以脱离 _source 单独检索。 默认情况下，字段值在 _source 中存储，但不会被独立存储。当你需要检索某个字段的值时，Easysearch 会加载整个 _source 文档并提取该字段。如果一个文档非常大，而你只需要获取其中一两个小字段的值，使用 store: true 可能更高效。 相关指南（先读这些） # _source 与字段存储 映射基础 参数选项 # 值 说明 true 字段值被独立存储，可通过 stored_fields 参数单独检索。 false 字段值不独立存储。默认值。 示例 # PUT my-index { "mappings": { "properties": { "title": { "type": "text", "store": true }, "content": { "type": "text" }, "created_at": { "type": "date", "store": true } } } } 检索独立存储的字段：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/object/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/object/Object 字段类型 # object 字段类型包含一个 JSON 对象（一组名称/值对）。JSON 对象中的值可以是另一个 JSON 对象。在映射对象字段时不需要指定 object 作为类型，因为 object 是默认类型。 相关指南（先读这些） # 映射基础 映射模式 代码示例 # 创建一个带有对象字段的映射： PUT testindex1/_mappings { "properties": { "patient": { "properties" : { "name" : { "type" : "text" }, "id" : { "type" : "keyword" } } } } } 索引一个包含对象字段的文档： PUT testindex1/_doc/1 { "patient": { "name" : "John Doe", "id" : "123456" } } 嵌套对象在内部存储为扁平的键/值对。要引用嵌套对象中的字段，使用 parent field.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/properties/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/properties/Properties 参数 # properties 参数用于定义对象（object）和嵌套（nested）类型字段的子字段映射。它是构建层级文档结构的核心参数。 相关指南 # 映射基础 dynamic 参数 使用位置 # properties 出现在三个层级： 层级 说明 mappings.properties 顶层字段定义 mappings.properties.<object>.properties 对象字段的子字段 mappings.properties.<nested>.properties 嵌套字段的子字段 示例 # 基本层级结构 # PUT my-index { "mappings": { "properties": { "name": { "type": "text" }, "address": { "type": "object", "properties": { "city": { "type": "keyword" }, "zip": { "type": "keyword" } } } } } } 嵌套类型 # PUT my-index { "mappings": { "properties": { "comments": { "type": "nested", "properties": { "author": { "type": "keyword" }, "content": { "type": "text" }, "date": { "type": "date" } } } } } } 多层嵌套 # PUT my-index { "mappings": { "properties": { "department": { "properties": { "name": { "type": "keyword" }, "manager": { "properties": { "name": { "type": "text" }, "email": { "type": "keyword" } } } } } } } } 对应的文档字段以 .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/nested/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/nested/Nested 字段类型 # nested 字段类型是一种特殊的 对象字段类型，用于将数组中的对象作为独立文档索引，避免扁平化导致的"笛卡尔积假匹配"问题。 相关指南（先读这些） # Nested 建模 映射模式 扁平化 vs Nested # 任何对象字段都可以包含一个对象数组。默认情况下，数组中的每个对象都会被动态映射为对象字段类型并以扁平化形式存储。这意味着数组中的对象会被分解成单独的字段，每个字段在所有对象中的值会被存储在一起。有时需要使用 Nested 嵌套类型来将嵌套对象作为一个整体保存，以便您可以对其关联性执行搜索。 扁平化形式 # 默认情况下，每个嵌套对象都被动态映射为对象字段类型。任何对象字段都可以包含一个对象数组。 PUT testindex1/_doc/100 { "patients": [ {"name": "John Doe", "age": 56, "smoker": true}, {"name": "Mary Major", "age": 85, "smoker": false} ] } 当这些对象被存储时，它们会被扁平化，因此它们的内部表示形式具有每个字段的所有值的数组： { "patients.name": ["John Doe", "Mary Major"], "patients.age": [56, 85], "patients.smoker": [true, false] } 一些查询会在这种表示形式中正确工作。如果您搜索年龄大于 75 或者 吸烟的病人 "patients.smoker": true，文档 id 100 应该匹配。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/boolean/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/boolean/布尔字段类型 # 布尔字段类型接受 true 或 false 值，也支持字符串形式的 “true” 或 “false”。此外，还可以使用空字符串 "" 表示 false 值。 参考代码 # 创建一个由 a,b,c 三个布尔字段组成的 mapping PUT testindex { "mappings" : { "properties" : { "a" : { "type" : "boolean" }, "b" : { "type" : "boolean" }, "c" : { "type" : "boolean" } } } } 索引由布尔值组成的文档 PUT testindex/_doc/1 { "a" : true, "b" : "true", "c" : "" } 因此，字段 a 和 b 将被设置为 true，而字段 c 将被设置为 false。https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/concurrency-and-versioning/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/concurrency-and-versioning/并发控制与版本 # 当有多个客户端同时写入同一份文档时，如果不做任何并发控制，很容易出现"旧值覆盖新值"的问题。本页介绍如何用版本与乐观锁避免这类隐性数据错误。 为什么需要并发控制？ # 考虑这样一个场景： 客户端 A 读取文档，准备把字段 count 从 1 改到 2 客户端 B 也读取了同一文档，把 count 从 1 改到 3 如果没有并发控制： A 先写入，文档变成 count=2 B 后写入，文档被覆盖为 count=3（A 的更新"丢了"） 很多时候这种问题不会立刻暴露，但会在数据对账或业务逻辑中造成难以解释的异常。 乐观并发控制（Optimistic Concurrency Control） # Easysearch 使用 _seq_no（序列号） 和 _primary_term（主分片任期） 实现乐观并发控制： _seq_no：每次对分片的写操作递增，全局唯一标识该分片上的操作顺序 _primary_term：当主分片发生切换（故障转移）时递增，用于区分不同"任期"的写入 每次读取文档时，响应中都会包含这两个值： GET /products/_doc/1 // 响应 { "_index": "products", "_type": "_doc", "_id": "1", "_version": 3, "_seq_no": 5, "_primary_term": 1, "found": true, "_source": { "name": "iPhone", "count": 10, "price": 5999 } } 安全更新：if_seq_no + if_primary_term # 使用 if_seq_no 和 if_primary_term 参数，只有当前版本与预期一致时才允许更新：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/coerce/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/coerce/Coerce 参数 # coerce 映射参数控制数据在索引期间如何将其值转换为预期的字段数据类型。此参数让您可以验证数据是否按照预期的字段类型正确格式化和索引。这提高了搜索结果的准确性。 相关指南（先读这些） # 映射基础 映射模式 代码样例 # 以下示例演示如何使用 coerce 映射参数。 启用 coerce 去索引文档 # PUT products { "mappings": { "properties": { "price": { "type": "integer", "coerce": true } } } } PUT products/_doc/1 { "name": "Product A", "price": "19.99" } 在此示例中，price 字段被定义为 integer 类型，且 coerce 设置为 true。在索引文档时，字符串值 19.99 被强制转换为整数 19。 禁用 coerce 的文档索引 # PUT orders { "mappings": { "properties": { "quantity": { "type": "integer", "coerce": false } } } } PUT orders/_doc/1 { "item": "Widget", "quantity": "10" } 在此示例中，quantity 字段被定义为 integer 类型，且 coerce 设置为 false。在索引文档时，字符串值 10 不会被强制转换，由于类型不匹配，文档写入会被拒绝。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/ignored/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/ignored/_ignored 元数据字段 # _ignored 字段帮助您管理文档中与格式错误数据相关的问题。由于在 索引映射中启用了 ignore_malformed 设置，此字段用于存储在数据索引过程中被忽略的字段名称。 _ignored 字段允许您搜索和识别包含被忽略字段的文档，以及被忽略的具体字段名称。这对于故障排除很有用。 您可以使用 term、terms 和 exists 查询来查询 _ignored 字段。 注意：只有当索引映射中启用了 ignore_malformed 设置时，才会填充 _ignored 字段。如果 ignore_malformed 设置为 false（默认值），则格式错误的字段将导致整个文档被拒绝，并且不会填写 _ignored 字段。 相关指南（先读这些） # 映射基础 元数据字段 以下示例展示了如何使用 _ignored 字段： GET _search { "query": { "exists": { "field": "_ignored" } } } 使用 _ignored 字段的索引请求示例 # 以下示例向 test-ignored 索引添加一个新文档，其中 ignore_malformed 设置为 true，这样在数据索引时不会抛出错误： PUT test-ignored { "mappings": { "properties": { "title": { "type": "text" }, "length": { "type": "long", "ignore_malformed": true } } } } POST test-ignored/_doc { "title": "correct text", "length": "not a number" } GET test-ignored/_search { "query": { "exists": { "field": "_ignored" } } } 示例返回内容 # { "took": 42, "timed_out": false, "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 }, "hits": { "total": { "value": 1, "relation": "eq" }, "max_score": 1, "hits": [ { "_index": "test-ignored", "_id": "qcf0wZABpEYH7Rw9OT7F", "_score": 1, "_ignored": [ "length" ], "_source": { "title": "correct text", "length": "not a number" } } ] } } 忽略指定字段 # 您可以使用 term 查询来查找特定字段被忽略的文档，如以下示例请求所示：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/ignore_malformed/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/ignore_malformed/Ignore Malformed 参数 # ignore_malformed 参数控制在写入格式错误的数据时，是否忽略该值而不是拒绝整个文档。 默认情况下，写入一个类型不匹配的值（如向数值字段写入字符串）会导致整个文档被拒绝。启用 ignore_malformed 后，格式错误的值会被静默忽略，文档的其他字段仍然正常索引。 相关指南（先读这些） # 映射基础 Index API 参数选项 # 值 说明 false 格式错误的值导致整个文档被拒绝。默认值。 true 格式错误的值被忽略，文档其余部分正常索引。 字段级示例 # PUT my-index { "mappings": { "properties": { "price": { "type": "integer", "ignore_malformed": true }, "name": { "type": "keyword" } } } } PUT my-index/_doc/1 { "price": "not_a_number", "name": "测试产品" } 文档 1 会被成功写入：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/ignore_above/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/ignore_above/Ignore Above 参数 # ignore_above 参数指定字符串的最大长度限制。超过此长度的字符串不会被索引或存储在 doc_values 中，但仍会出现在 _source 中。 该参数主要用于 keyword 字段类型，防止超长字符串占用过多索引空间。 相关指南（先读这些） # 映射基础 Keyword 字段类型 参数选项 # 值 说明 正整数 超过此字符数的值不被索引。 默认值 2147483647（几乎不限制）。动态映射创建的 keyword 子字段默认为 256。 示例 # PUT my-index { "mappings": { "properties": { "tag": { "type": "keyword", "ignore_above": 100 } } } } 写入测试： PUT my-index/_doc/1 { "tag": "short_tag" } PUT my-index/_doc/2 { "tag": "this_is_a_very_long_tag_value_that_exceeds_one_hundred_characters_and_therefore_should_not_be_indexed_at_all_in_the_inverted_index" } 文档 1 的 tag 会被正常索引，可以搜索和聚合 文档 2 的 tag 不会被索引，无法通过 term 查询找到，也不会出现在聚合结果中，但仍然存在于 _source 中 动态映射的默认行为 # 当 Easysearch 动态检测到字符串字段时，会自动创建如下映射：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/flattened/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/flattened/Flattened 字段类型 # 在 Easysearch 中，您不需要在索引文档之前指定映射。如果您不指定映射，Easysearch 会使用动态映射自动映射文档中的每个字段及其子字段。当您摄取诸如日志之类的文档时，您可能事先不知道每个字段的子字段名称和类型。在这种情况下，动态映射所有新的子字段可能会快速导致"映射爆炸"，其中不断增长的字段数量可能会降低集群的性能。 flattened 字段类型通过将整个 JSON 对象视为字符串来解决这个问题。可以使用标准的点路径表示法访问 JSON 对象中的子字段，但它们不会被索引成单独的字段以供快速查找。 注意：点表示法（a.b）中的字段名最大长度为 2^24 − 1。 相关指南（先读这些） # 映射基础 映射模式 Flat 对象字段类型提供以下优势： 高效读取：获取性能类似于关键字字段。 内存效率：将整个复杂的 JSON 对象存储在一个字段中而不索引其所有子字段，可以减少索引中的字段数量。 空间效率：Easysearch 不会为 flat 对象中的子字段创建倒排索引，从而节省空间。 迁移兼容性：您可以将数据从支持类似 flat 字段的数据库系统迁移到 Easysearch。 当字段及其子字段主要用于读取而不是用作搜索条件时，应将字段映射为 flat 对象，因为子字段不会被索引。当对象具有大量字段或您事先不知道内容时，flat 对象非常有用。 Flat 对象支持带有和不带有点路径表示法的精确匹配查询。有关支持的查询类型的完整列表，请参见支持的查询。 在文档中搜索特定嵌套字段的值可能效率低下，因为它可能需要对索引进行完整扫描，这可能是一个昂贵的操作。 Flat 对象不支持： 特定类型的解析。 数值运算，如数值比较或数值排序。 文本分析。 高亮显示。 使用点表示法(a.b)的子字段聚合。 按子字段过滤。 支持的查询 # Flat 对象字段类型支持以下查询： Term Terms Terms set Prefix Range Match Multi-match Query string Simple query string Exists Wildcard 限制 # 以下限制适用于 Easysearch 中的 flat 对象：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/flattened_text/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/flattened_text/Flattened Text 字段类型 # flattened_text 类型是一种特殊的数据结构，适用于存储和查询嵌套层次的数据，同时保留类似于 text 类型的灵活搜索特性，例如分词和全文匹配。它在处理结构化或者半结构化数据时非常有用，例如 JSON 对象或动态键值对映射。 相关指南（先读这些） # 映射基础 映射模式 全文搜索 定义映射 # { "properties": { "my_field": { "type": "flattened_text" } } } 特性 # 扁平化存储 将嵌套的 JSON 对象转换为扁平结构 保留完整的路径信息 支持点号访问内部字段 文本分析 支持标准分词器 支持短语查询 支持全文搜索功能 内部索引结构 每个 flattened_text 字段在 lucene 层面会创建多个子字段: {field} - 存储所有键 {field}._value - 存储所有值 {field}.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/open-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/open-index/打开索引 # 对已关闭的索引执行打开操作，使其重新可读写。 操作步骤 # 进入索引列表：在「索引」页面，找到状态为 Close（已关闭）的目标索引（如 testing_index_creation）。 打开操作菜单：点击该索引行「操作」列的更多按钮（...），在下拉菜单中选择「打开索引」。 确认打开操作：在弹出的确认提示框中，点击「确定」，系统将执行索引打开操作。 查看操作结果：操作完成后，索引列表中该索引的「索引状态」将更新为 Open，代表索引已成功打开，恢复正常读写服务。 补充说明 # 打开索引时，系统需要重新加载索引数据并恢复分片分配，大索引的恢复过程可能需要一定时间，期间索引健康状态可能暂时显示为 Yellow 或 Red，属于正常现象。 打开索引后会重新占用内存和其他计算资源，请确保集群有足够的资源容量。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/sort/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/sort/排序 # 默认情况下，全文查询按相关性 _score 排序。你也可以按任意字段值升序/降序排序，或使用地理距离、脚本等高级排序方式。 相关指南 # 分页与排序 基础字段排序 # 通过 sort 参数指定排序字段和顺序： GET shakespeare/_search { "query": { "term": { "play_name": { "value": "Henry IV" } } }, "sort": [ { "line_id": { "order": "desc" } } ] } 排序参数 # 参数 说明 可选值 order 排序方向 asc（升序）、desc（降序） mode 多值字段的聚合模式 min、max、avg、sum、median missing 缺失值的处理方式 _first（排最前）、_last（排最后）、自定义值 unmapped_type 未映射字段的假设类型 字段类型名（如 long、date） 多级排序 # sort 是数组，可以配置多级排序。当主排序键相同时，使用次排序键：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/search_analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/search_analyzer/Search Analyzer 参数 # search_analyzer 参数指定查询时使用的分析器，可以与索引时的 analyzer 不同。这允许在写入和查询时使用不同的文本分析策略。 相关指南（先读这些） # Analyzer 参数 文本分析 映射基础 分析器选择优先级 # Easysearch 按以下优先级选择查询时分析器： 查询中指定的 analyzer 参数（如 match 查询的 analyzer 字段） 映射中字段的 search_analyzer 索引设置 analysis.analyzer.default_search 映射中字段的 analyzer standard 分析器 示例 # 写入时最大化召回，查询时精确匹配 # PUT my-index { "settings": { "analysis": { "analyzer": { "ik_smart_search": { "type": "custom", "tokenizer": "ik_smart" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "ik_max_word", "search_analyzer": "ik_smart" } } } } 阶段 分析器 策略 索引时 ik_max_word 最细粒度分词，生成更多词项，最大化召回 查询时 ik_smart 智能分词，生成更少词项，提高精确度 同义词扩展只在查询时生效 # "title": { "type": "text", "analyzer": "standard", "search_analyzer": "synonym_analyzer" } 这样索引时不扩展同义词（节省空间），查询时通过同义词分析器扩展查询词。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/numeric-field/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/numeric-field/Numeric 字段类型 # 下表列出了 Easysearch 支持的所有数字字段类型。 字段数据类型 描述 byte 有符号的 8 位整数。最小值为 -128，最大值为 127。 double 双精度 64 位 IEEE 754 浮点数。最小值为 2^−1074，最大值为 (2 − 2^−52) · 2^1023。有效位数为 53，有效数字位为 15.95。 float 单精度 32 位 IEEE 754 浮点数。最小值为 2^−149，最大值为 (2 − 2^−23) · 2^127。有效位数为 24，有效数字位为 7.22。 half_float 半精度 16 位 IEEE 754 浮点数。最小值为 2^−24，最大值为 65504。有效位数为 11，有效数字位为 3.31。 integer 有符号的 32 位整数。最小值为 -2^31，最大值为 2^31 - 1。 long 有符号的 64 位整数。最小值为 -2^63，最大值为 2^63 - 1。 short 有符号的 16 位整数。最小值为 -2^15，最大值为 2^15 - 1。 scaled_float 一个浮点值，它会被乘以双精度缩放因子并存储为长整型值。 Integer、long、float 和 double 字段类型都有对应的 范围字段类型。https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-lifecycle/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-lifecycle/数据生命周期与保留策略 # 这篇从“业务数据要活多久”的角度出发，帮你把几块能力串在一起： 时间序列索引设计（按时间切分索引） 热/温/冷 分层与硬件资源规划 自动化的保留与归档流程（ILM/SLM 思路） data-retention 里讲到的删除/关闭/快照等具体动作 如果你只想记住一句话：先画清楚数据时间轴，再用索引 + 模板 + 生命周期策略把它搬进 Easysearch。 1. 先画一条“数据时间轴” # 通常可以按“价值 + 访问频率”粗分为几段： 实时区（Hot）：最近几小时～几天，写入密集、查询频繁，对延迟和可用性要求最高。 近线/历史区（Warm/Cold）：最近几周～几个月，主要用于排查与报表，对延迟容忍度更高。 归档区（Archive）：为了合规或审计留存多年，几乎不查，只要“能找回来”。 每一段都需要明确三件事： 保留多久（例如：实时 7 天、近线 90 天、归档 3 年） 大致容量（每天多少文档/多少 GB） 访问模式（实时 OLTP vs 批量统计/偶尔查询） 有了这条时间轴，后面的索引结构、硬件资源和自动化策略才有落点。 2. 把时间轴映射到索引与模板 # 2.1 按时间切索引：一天/一周/一月？ # 结合业务特征和容量估算，选择合适的时间粒度： 高流量日志：通常是按天建索引：logs-2026.02.04 中等流量：可以按周：metrics-2026.w05 低流量：甚至可以按月：audit-2026.02 核心目标： 单个分片不要过大（影响恢复和迁移） 单个索引不要包含“过长时间跨度”的数据（否则删除/归档粒度太粗） 2.2 用索引模板固化生命周期相关设置 # 为一类时间序列业务准备一个模板，例如 logs-*：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/id/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/id/_id 元数据字段 # Easysearch 中的每个文档都有一个唯一的 _id 字段。此字段已被索引，允许你使用 GET API 或 ids 查询 检索文档。 注意：如果您未提供 _id 值，则 Easysearch 会自动为文档生成一个。 相关指南（先读这些） # 映射基础 元数据字段 以下示例请求创建一个名为 test-index1 的索引，并添加两个具有不同 _id 值的文档： PUT test-index1/_doc/1 { "text": "Document with ID 1" } PUT test-index1/_doc/2?refresh=true { "text": "Document with ID 2" } 您可以使用 _id 字段查询文档，如以下示例请求所示： GET test-index1/_search { "query": { "terms": { "_id": ["1", "2"] } } } 返回 _id 值为 1 和 2 的两个文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/doc_values/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/doc_values/Doc Values 参数 # 默认情况下，Easysearch 会为搜索目的索引大多数字段的字段值。doc_values 参数启用文档到词项的正排查找，用于排序、聚合和脚本等操作。 doc_values 参数接受以下选项： 选项 描述 true 启用字段的 doc_values。默认值为 true。 false 禁用字段的 doc_values。 相关指南（先读这些） # 映射基础 映射模式 示例：创建启用和禁用 doc_values 的索引 # 以下示例请求创建一个索引，其中一个字段启用 doc_values，另一个字段禁用： PUT my-index-001 { "mappings": { "properties": { "status_code": { "type": "keyword" }, "session_id": { "type": "keyword", "doc_values": false } } } } 工作原理 # doc_values 是一种列式存储结构，与倒排索引互补：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/templates/create-index-template/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/templates/create-index-template/新增索引模板 # 索引模板用于在创建索引时自动应用预定义的设置和映射。 操作步骤 # 进入模板页面：在左侧导航栏点击「模板」，切换至「索引模板」标签页。 打开新增模板弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增模板」配置窗口。 配置模板基础信息： 填写必填项「名称」，自定义模板标识（如示例中的 test_template）。 填写必填项「索引模式」，设置模板匹配的索引规则（如示例中的 test_template-*）。 按需开启「启用数据流」开关，开启后可配置「时间戳字段」（默认值为 @timestamp）。 完成创建：配置完成后，点击「确定」按钮，系统将自动创建索引模板。 查看创建结果：模板创建成功后，将在索引模板列表中展示该模板的完整信息，包括名称、索引模式、数据流状态等。 注意事项 # 模板名称不可与已有模板重复，否则创建将失败。 索引模式支持通配符（如 *），用于匹配符合规则的索引名称。 模板仅对新创建的索引生效，不会影响已存在的索引。 开启「启用数据流」后，匹配的索引将作为数据流的后备索引创建，请确认业务场景是否需要数据流功能。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/security/create-role/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/security/create-role/新增角色 # 角色定义了一组权限集合，可授予用户对集群、索引或文档级别的操作权限。 操作步骤 # 进入角色管理页：在左侧导航栏点击「安全管理」，切换到「角色」标签页，查看现有角色列表。 打开新增弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增角色」配置窗口。 配置角色信息： 名称：填写自定义的角色名称（如示例中的 test_role）。 集群权限：配置该角色的集群级操作权限（如 cluster:* 代表全集群权限）。 索引权限：配置索引访问权限，可指定索引范围、操作权限，还可按需开启「特定文档访问权限」「字段访问权限控制」。 描述：（可选）填写角色的功能说明，方便后续管理。 完成创建：信息配置无误后，点击「确定」，系统将创建该角色。 查看结果：角色创建成功后，将在角色列表中展示，代表操作完成。 注意事项 # 配置权限时建议遵循最小权限原则，避免使用 * 通配符授予过多权限，降低误操作和安全风险。 集群权限与索引权限是独立配置的，集群权限控制集群级操作（如查看集群健康状态），索引权限控制对具体索引的读写访问。 角色创建后可随时编辑调整权限配置，无需删除重建。 内置角色（如 admin、readonly 等）不可修改或删除。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/date-field-type/date/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/date-field-type/date/Date 字段类型 # 在 Easysearch 中，日期可以表示为以下几种形式： 一个长整型值，对应自纪元以来的毫秒数（必须为非负数）。日期在内部以此形式存储。 一个格式化的字符串。 一个整数值，对应自纪元以来的秒数（必须为非负数）。 要表示日期范围，可以使用 date range 字段类型。 代码样例 # 创建一个有两种日期格式的 date 字段 PUT testindex { "mappings" : { "properties" : { "release_date" : { "type" : "date", "format" : "strict_date_optional_time||epoch_millis" } } } } 参数说明 # 下表列出了日期字段类型支持的参数，所有参数均为可选项。 参数 描述 默认值 boost 浮点值，指定字段对相关性评分的权重。值大于 1.0 增加相关性，0.0 到 1.0 降低相关性。 1.0 doc_values 布尔值，指定是否将字段存储到磁盘，以便用于聚合、排序或 script 脚本操作。 true format 用于解析日期的格式。 strict_date_time_no_millis || strict_date_optional_time || epoch_millis ignore_malformed 布尔值，指定是否忽略格式错误的值而不抛出异常。 false index 布尔值，指定字段是否可搜索。 true locale 指定基于区域和语言的日期表示格式。 ROOT（区域和语言中立的本地设置） meta 接受字段的元数据。 null_value 指定替代 null 的值，必须与字段类型一致。如果未指定，字段值为 null 时会被视为缺失值。 null store 布尔值，指定字段值是否单独存储并可从 _source 字段外检索。 false 格式 # Easysearch 提供内置的日期格式，但您也可以自定义日期格式。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/format/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/format/Format 参数 # format 参数指定日期字段的解析格式。Easysearch 内置了多种日期格式，也支持自定义格式字符串。 相关指南（先读这些） # 映射基础 Date 字段类型 基本用法 # PUT my-index { "mappings": { "properties": { "created_at": { "type": "date", "format": "yyyy-MM-dd HH:mm:ss" } } } } 多格式支持 # 使用 || 分隔符可以指定多个格式，Easysearch 会依次尝试每种格式进行解析： "created_at": { "type": "date", "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis" } 内置日期格式 # 格式 说明 示例 epoch_millis 毫秒时间戳 1618000000000 epoch_second 秒时间戳 1618000000 date_optional_time / strict_date_optional_time ISO 8601 日期，时间部分可选 2021-04-10T08:00:00Z basic_date yyyyMMdd 20210410 basic_date_time yyyyMMdd’T’HHmmss.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/thai/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/thai/Thai 分词器 # thai 分词器使用 Java 内置的泰语分词算法（BreakIterator）对泰语文本进行分词。对于非泰语文本，其行为与 standard 分词器相同。 示例 # POST _analyze { "tokenizer": "thai", "text": "การทดสอบ" } 相关指南 # Standard 分词器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/hybrid-ranker-processor/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/hybrid-ranker-processor/混合搜索排序处理器（Hybrid Ranker Processor） # 需要 AI 插件 hybrid_ranker_processor 是一种搜索阶段结果处理器（search phase results processor），运行于 Query 阶段和 Fetch 阶段之间，用于对混合搜索（hybrid 查询）返回的多路子查询得分进行归一化和融合，生成统一的最终得分排序。 工作原理 # 在混合搜索中，多个子查询（如 BM25 关键词查询 + KNN 向量查询）各自返回独立的得分。这些得分的量纲和分布可能完全不同，无法直接比较。hybrid_ranker_processor 通过以下步骤解决这个问题： 得分归一化：将各子查询的得分归一化到可比较的范围 得分融合：使用融合算法（如 RRF）将多路归一化后的得分合并为统一的最终得分 根据最终得分重新排序搜索结果 RRF 算法 # 默认使用 Reciprocal Rank Fusion (RRF) 算法，其核心思想是基于排名而非原始分数进行融合： $$\text{RRF}(d) = \sum_{i=1}^{n} \frac{1}{k + r_i(d)}$$ 其中 $k$ 为常数（默认 60），$r_i(d)$ 为文档 $d$ 在第 $i$ 个子查询结果中的排名。 请求体字段 # 字段 类型 是否必填 说明 combination Object 否 得分融合配置 combination.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/percolator/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/percolator/Percolator 字段类型 # percolator 字段类型将该字段视为查询处理。任何 JSON 对象字段都可以标记为 percolator 字段。通常，文档被索引并用于搜索，而 percolator 字段存储搜索条件，稍后通过 Percolate 查询将匹配文档到该条件。 相关指南（先读这些） # 映射基础 渗透查询 参考代码 # 客户正在搜索价格在 400 美元或以下的桌子，并希望为此搜索创建警报。 创建一个映射，为查询字段分配一个 percolator 字段类型： PUT testindex1 { "mappings": { "properties": { "search": { "properties": { "query": { "type": "percolator" } } }, "price": { "type": "float" }, "item": { "type": "text" } } } } 索引一个查询 PUT testindex1/_doc/1 { "search": { "query": { "bool": { "filter": [ { "match": { "item": { "query": "table" } } }, { "range": { "price": { "lte": 400.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/source/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/source/_source 元数据字段 # _source 字段包含已索引的原始 JSON 文档主体。虽然此字段不可搜索，但它会被存储，以便在执行获取请求（如 get 和 search）时可以返回完整文档。 禁用 _source # 您可以通过将 enabled 参数设置为 false 来禁用 _source 字段，如以下示例所示： PUT sample-index1 { "mappings": { "_source": { "enabled": false } } } 注意：禁用 _source 字段可能会影响某些功能的可用性，例如 update、update_by_query 和 reindex API，以及使用原始索引文档查询或聚合的能力。 相关指南（先读这些） # 映射基础 元数据字段 包含或排除某些字段 # 您可以使用 includes 和 excludes 参数选择 _source 字段的内容。如以下示例： PUT logs { "mappings": { "_source": { "includes": [ "*.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/join/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/object-field-type/join/Join 字段类型 # join 字段类型用于在同一索引中的文档之间建立父/子关系。 相关指南（先读这些） # Parent-Child 建模 映射模式 代码样例 # 模拟创建一个映射来建立一个产品和其品牌之间的父/子关系： PUT testindex1 { "mappings": { "properties": { "product_to_brand": { "type": "join", "relations": { "brand": "product" } } } } } 索引一个父文档： PUT testindex1/_doc/1 { "name": "Brand 1", "product_to_brand": { "name": "brand" } } 您也可以使用更简单的格式： PUT testindex1/_doc/1 { "name": "Brand 1", "product_to_brand": "brand" } 路由要求：在索引子文档时，您需要指定 routing 查询参数，因为同一父/子层级中的父文档和子文档必须索引在同一分片上。每个子文档在 parent 字段中引用其父文档的 ID。更多路由与性能考虑，请参考 Parent-Child 建模章节。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/similarity/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/similarity/Similarity 参数 # similarity 参数指定字段使用的相关性评分算法。不同的算法适合不同类型的数据和搜索场景。 相关指南（先读这些） # 评分基础 映射基础 内置算法 # 值 算法 说明 BM25 Okapi BM25 默认值。适合大多数全文搜索场景。 boolean 布尔模型 不计算相关性分数，匹配的文档得分为查询的 boost 值。适合不需要相关性排序的过滤场景。 DFR Divergence from Randomness 基于随机性散度模型的评分算法。 DFI Divergence from Independence 基于独立性散度模型的评分算法。 IB Information Based 基于信息论的评分算法。 LMDirichlet Dirichlet 语言模型 使用 Dirichlet 先验的语言模型平滑方法。 LMJelinekMercer Jelinek-Mercer 语言模型 使用线性插值的语言模型平滑方法。 自定义名称 自定义相似度 在索引 settings 中定义的自定义评分算法。 示例 # PUT my-index { "mappings": { "properties": { "content": { "type": "text", "similarity": "BM25" }, "status": { "type": "text", "similarity": "boolean" } } } } BM25 参数调优 # BM25 的行为可以通过索引 settings 自定义：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/null_value/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/null_value/Null Value 参数 # null_value 参数指定一个替代值，用于在字段值为 null 或缺失时代替索引。这使得 null 值可以被搜索和聚合。 相关指南（先读这些） # 映射基础 结构化搜索 基本用法 # PUT my-index { "mappings": { "properties": { "status": { "type": "keyword", "null_value": "UNKNOWN" } } } } 写入和查询： PUT my-index/_doc/1 { "status": null } PUT my-index/_doc/2 { "status": "active" } # 搜索 null 值的文档 GET my-index/_search { "query": { "term": { "status": "UNKNOWN" } } } 文档 1 会被上面的查询找到，因为 null 被替换为 "UNKNOWN" 进行索引。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/pipeline/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/pipeline/管道处理器 # pipeline 处理器允许管道引用和包含另一个预定义的管道。当您有一组需要在多个管道之间共享的常见处理器时，这非常有用。您不必在每个管道中重新定义这些常见处理器，而是可以创建一个包含共享处理器的单独基础管道，然后使用管道处理器从其他管道中引用该基础管道。 以下是为 pipeline 处理器提供的语法： { "pipeline": { "name": "general-pipeline" } } 配置参数 # 下表列出了 pipeline 处理器所需的和可选参数。 参数 是否必填 描述 name 必填 要执行的管道的名称。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 步骤 1：创建一个管道 # 以下查询创建了一个名为 general-pipeline 的一般管道，然后创建了一个名为 outer-pipeline 的新管道，该管道引用了 general-pipeline :https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/Index 参数 # index 参数控制字段值是否被索引（写入倒排索引）。未被索引的字段无法被搜索，但仍然会存储在 _source 中，且如果启用了 doc_values，仍可用于排序和聚合。 相关指南（先读这些） # 映射基础 映射模式与最佳实践 参数选项 # 值 说明 true 字段被索引，可搜索。默认值。 false 字段不被索引，无法搜索。减少磁盘空间和索引时间。 示例 # PUT my-index { "mappings": { "properties": { "title": { "type": "text" }, "internal_code": { "type": "keyword", "index": false } } } } 上面的映射中，internal_code 字段不被索引，无法用于搜索查询，但： 仍然出现在 _source 中（可被返回） 如果 doc_values 为 true（keyword 默认），仍可用于排序和聚合 适用场景 # 场景 建议 字段仅用于展示，不需要搜索 "index": false 字段用于排序/聚合，不需要搜索 "index": false（保持 doc_values: true） 字段需要搜索 "index": true（默认） 仅存储原始值，不搜索不聚合 "index": false, "doc_values": false 注意事项 # index 参数在索引创建后无法修改，需要重建索引 对 index: false 的字段执行搜索查询会返回错误 与 enabled: false 不同：enabled: false 会完全跳过字段的解析，而 index: false 仍然会解析和存储字段值https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/index-field/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/index-field/_index 元数据字段 # 当跨多个索引进行查询时，您可能需要根据文档所在的索引来过滤结果。_index 字段根据文档的索引来匹配文档。 相关指南（先读这些） # 映射基础 元数据字段 以下示例创建两个索引，products 和 customers，并向每个索引添加一个文档： PUT products/_doc/1 { "name": "Widget X" } PUT customers/_doc/2 { "name": "John Doe" } 然后，您可以查询这两个索引，并使用 _index 属性过滤结果，如以下示例请求所示： GET products,customers/_search { "query": { "terms": { "_index": ["products", "customers"] } }, "aggs": { "index_groups": { "terms": { "field": "_index", "size": 10 } } }, "sort": [ { "_index": { "order": "desc" } } ], "script_fields": { "index_name": { "script": { "lang": "painless", "source": "doc['_index'].https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/ilm/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/ilm/索引生命周期管理 # 索引生命周期管理（Index Lifecycle Management, ILM）为您提供了一种集成化、自动化的方式来高效管理时序数据。 通过配置 ILM 策略，您可以根据性能、可用性与数据保留需求，自动执行索引的滚动、归档和清理等操作。 从 1.15.2 版本开始，index-management 已经成为 modules 的一部分，不需要单独安装插件。 典型应用场景 # 自动滚动生成新索引：当现有索引达到指定大小或文档数量时，自动创建新索引。 周期性轮换索引：按天、周或月创建新索引，并将历史索引归档。 强制数据保留策略：自动删除过期索引，确保合规与存储成本可控。 分层存储：将热数据分配到高性能节点，冷数据迁移到廉价存储节点。 策略管理 API # 创建策略 # 创建一个新的生命周期策略。 请求 # PUT _ilm/policy/{policyID} 参数 描述 类型 是否必需 policyID 策略 ID。 string 是 查询参数 # 参数 描述 类型 默认值 if_seq_no 仅当匹配此序列号时更新。 long — if_primary_term 仅当匹配此主分片任期时更新。 long — 请求体 # 策略支持 ES 兼容的 phases 格式。系统内部会将其转换为 Easysearch 原生的 managed-index / states / actions 执行模型。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/match_only_text/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/match_only_text/match_only_text 字段类型 # Introduced 1.10.0 简介 # match_only_text 是一个为全文搜索优化的字段类型，是 text 类型的变体。它通过省略词条位置、词频和规范化信息来减少存储需求,适合对存储成本敏感但仍需要基本全文搜索功能的场景。 主要特点 # 存储优化: 不存储位置信息 不存储词频信息 不存储规范化信息 显著减少索引大小 评分机制: 禁用评分计算 所有匹配文档得分统一为 1.0 查询支持: 支持大多数查询类型 不支持 interval 查询 不支持 span 查询 支持但不优化短语查询 使用场景 # 适合用于: 需要快速查找包含特定词条的文档 对存储成本敏感的大数据集 不需要复杂相关性排序的场景 不适合用于: 需要基于相关性排序的查询 依赖词条位置或顺序的查询 需要精确短语匹配的场景 映射示例 # PUT my_index { "mappings": { "properties": { "title": { "type": "match_only_text" } } } } 参数配置 # 参数 说明 默认值 analyzer 分析器设置 standard boost 评分提升因子 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/date-field-type/date-nanos/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/date-field-type/date-nanos/Date nanoseconds 字段类型 # 日期纳秒字段类型与 日期 字段类型类似，它存储一个日期。然而，date 以毫秒分辨率存储日期，而 date_nanos 以纳秒分辨率存储日期。日期以 long 值的形式存储，表示自纪元以来的纳秒数。因此，支持的日期范围大约是 1970-2262 年。 对 date_nanos 字段的查询被转换为对字段值的 long 表示形式的范围查询。然后使用字段上设置的格式将存储的字段和聚合结果转换为字符串。 date_nano 字段支持 date 支持的所有格式和参数。你可以使用 || 分隔的多种格式。 对于 date_nanos 字段，你可以使用 strict_date_optional_time_nanos 格式来保留纳秒值。如果你在将字段映射为 date_nanos 时没有指定格式，默认格式是 strict_date_optional_time||epoch_millis，它允许你以 strict_date_optional_time 或 epoch_millis 格式传递值。strict_date_optional_time 格式支持纳秒的日期，但 epoch_millis 格式仅支持毫秒的日期。 示例 # 创建一个具有 strict_date_optional_time_nanos 格式的 date_nanos 类型的 date 字段的映射： PUT testindex/_mapping { "properties": { "date": { "type": "date_nanos", "format" : "strict_date_optional_time_nanos" } } } 将两个文档写入到索引中： PUT testindex/_doc/1 { "date": "2022-06-15T10:12:52.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/edit-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/edit-filter/编辑过滤条件 # 可以对已添加的过滤条件进行修改，以调整数据筛选规则。 操作步骤 # 唤起操作菜单：在数据探索页面，找到已生效的过滤条件标签（如 _id:LJAUJ0BlYzaDM3kYDbw），点击该标签，弹出操作菜单。 进入编辑页面：在菜单中选择「编辑过滤条件」，打开过滤条件配置窗口。 修改过滤参数： 可按需调整「字段」「运算」的选择项； 在「值」输入框中，修改目标过滤值（示例中修改为 nYsUlJ0Bc_MPNLBvYYQh）。 （可选）高级编辑：如需自定义复杂查询，可点击窗口右上角的「编辑 Query DSL」，直接编写 Elasticsearch 查询语句。 保存并生效：配置完成后，点击「保存」按钮，系统将自动更新过滤条件。 查看结果：更新生效后，搜索栏的过滤标签会同步更新，右侧数据列表将展示符合新条件的文档记录。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/network/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/network/网络配置 # 本页介绍 easysearch.yml 中与网络绑定、端口和 HTTP 行为相关的配置项。这些都是静态设置，修改后需要重启节点生效。 核心网络参数 # network.host # network.host: 0.0.0.0 项目 说明 参数 network.host 默认值 _local_（仅本机 127.0.0.1） 属性 静态 说明 节点绑定的主机名或 IP 地址。同时设置 network.bind_host 和 network.publish_host。这是最常修改的网络配置 特殊值： 值 含义 _local_ 回环地址（127.0.0.1），仅本机可访问 _site_ 内网地址（如 192.168.x.x / 10.x.x.x） _global_ 公网地址 0.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/auto-indent/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/auto-indent/自动缩进 # 操作步骤 # 进入开发工具页面：在左侧导航栏点击「开发工具」，进入开发工具编辑页。 输入请求内容：在左侧编辑区输入未格式化的请求语句。 执行自动缩进：点击编辑区右上角的「自动缩进」按钮，系统将自动对编辑区的请求内容进行格式化缩进。 查看格式化结果：操作完成后，编辑区的请求语句将自动调整为规范的缩进格式，提升可读性。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/autocomplete-field-type/completion/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/autocomplete-field-type/completion/Completion 自动补全字段类型 # 自动补全字段类型通过补全建议器提供自动补全功能。补全建议器是一个前缀建议器，所以它只匹配文本的开头部分。补全建议器会创建一个内存中的数据结构，这提供了更快的查找速度，但会导致内存使用增加。在使用此功能之前，你需要将所有可能的补全项上传到索引中。 代码样例 # 创建一个包含补全字段的映射： PUT chess_store { "mappings": { "properties": { "suggestions": { "type": "completion" }, "product": { "type": "keyword" } } } } 将建议内容索引到 Easysearch 中： PUT chess_store/_doc/1 { "suggestions": { "input": ["Books on openings", "Books on endgames"], "weight" : 10 } } 参数 # 下表列出了补全字段接受的参数。 参数 描述 input 可能的补全项列表，可以是字符串或字符串数组。不能包含 \u0000 (null),\u001f (信息分隔符一) 或 \u001e (信息分隔符二)。必需。 weight 用于对建议进行排序的正整数或正整数字符串。可选。 可以按以下方式索引多个建议：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/range-field-type/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/range-field-type/Range 字段类型 # 以下表格列出了 Easysearch 支持的所有范围字段类型。 字段数据类型 描述 integer_range 整数值范围。 long_range 长整型值范围。 double_range 双精度浮点值范围。 float_range 浮点值范围。 ip_range IPv4 或 IPv6 地址范围，起始和结束地址可使用不同格式。 date_range 日期值范围，起始和结束日期可采用不同格式。内部以 64 位无符号整数存储，自纪元以来的毫秒数表示。 相关指南（先读这些） # 映射基础 结构化搜索 参考代码 # 创建一个有双精度浮点数范围字段和日期范围字段的映射 PUT testindex { "mappings" : { "properties" : { "gpa" : { "type" : "double_range" }, "graduation_date" : { "type" : "date_range", "format" : "strict_year_month||strict_year_month_day" } } } } 索引一个包含这两个字段的文档https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/normalizer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/normalizer/Normalizer 参数 # normalizer 参数用于 keyword 字段，在索引和查询之前对值进行标准化处理（如转换为小写）。与 analyzer 不同，normalizer 不会对字符串进行分词，只做字符级别的变换。 完整指南 → 归一化与规范化器，包含概念介绍、自定义配置、兼容过滤器列表和最佳实践。 参数选项 # 值 说明 null 不使用 normalizer，值按原样索引。默认值。 自定义名称 使用在索引 settings 中定义的 normalizer。 使用示例 # keyword 字段默认区分大小写。使用内置的 lowercase normalizer 可忽略大小写： "status": { "type": "keyword", "normalizer": "lowercase" } 或自定义 normalizer： PUT my-index { "settings": { "analysis": { "normalizer": { "lowercase_normalizer": { "type": "custom", "filter": ["lowercase"] } } } }, "mappings": { "properties": { "status": { "type": "keyword", "normalizer": "lowercase_normalizer" } } } } 写入 "OK" 后，使用 "ok" 可以查到，因为两者在索引时都被标准化为 "ok"。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/remove-follower-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/remove-follower-index/解除跟随者索引 # 解除跟随者索引后，该索引将不再从主索引同步数据，变为独立索引。 操作步骤 # 进入管理页面：登录 Easysearch UI，左侧导航栏点击「主从复制」，默认进入「跟随者索引」标签页。 触发解除：找到目标跟随者索引（如 cloud_resource_usage_billing），点击「操作」列的更多按钮，选择「解除」。 确认执行：在弹出的提示框中核对索引名称，点击「确定」。 查看结果：操作完成后，目标索引从列表中移除，同步关系终止。 注意事项 # 解除仅断开同步，不会删除本地索引和远端主导索引的数据。 解除前请停止依赖该索引的业务，避免数据访问异常。 恢复同步需重新执行「新增跟随者索引」配置。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/norms/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/norms/Norms 参数 # norms 参数控制是否存储字段长度归一化因子，用于相关性评分计算。 在 BM25 评分算法中，字段长度是一个重要因素：短字段中的匹配通常比长字段中的匹配更相关。norms 存储的就是这个字段长度信息。 相关指南（先读这些） # 映射基础 评分基础 参数选项 # 字段类型 默认值 说明 text true 默认启用，用于全文搜索评分 keyword false 默认禁用，keyword 通常用于过滤/聚合 示例 # 禁用 text 字段的 norms： PUT my-index { "mappings": { "properties": { "tags": { "type": "text", "norms": false } } } } 何时禁用 norms # 场景 建议 字段用于全文搜索，需要相关性排序 保持启用 字段仅用于过滤（filter context） 可禁用，节省空间 字段是日志/标签等，不关心评分 可禁用 多个字段的评分权重由 boost 控制 保持启用 注意事项 # 禁用 norms 可以节省磁盘空间（每个文档每个字段约 1 byte） norms 一旦禁用后无法重新启用，需要重建索引 对于不需要评分的字段（如纯过滤用途），禁用 norms 是安全的优化https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/term_vector/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/term_vector/Term Vector 参数 # term_vector 参数控制是否为字段存储词条向量（Term Vector）信息。词条向量包含词条及其位置、偏移量等信息，供高亮和 More Like This 查询使用。 相关指南 # 全文搜索 analyzer 参数 可选值 # 值 说明 no 默认值。不存储词条向量。 yes 仅存储词条，不含位置和偏移量。 with_positions 存储词条和位置信息。 with_offsets 存储词条和字符偏移量。 with_positions_offsets 存储词条、位置和偏移量。推荐用于快速高亮。 with_positions_payloads 存储词条、位置和有效载荷。 with_positions_offsets_payloads 存储所有信息。 示例 # 为高亮优化 # PUT my-index { "mappings": { "properties": { "content": { "type": "text", "term_vector": "with_positions_offsets" } } } } 使用 with_positions_offsets 可以让 fast vector highlighter（FVH）高亮器直接从词条向量中提取数据，而无需重新分析文档，显著提高高亮性能。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/stemming/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/stemming/词干提取配置参考 # 本页提供词干提取（Stemming）相关组件的技术配置参考。关于词干提取的概念、策略选择和最佳实践，请先阅读指南。 相关指南（概念与策略） # 文本分析：词干提取 - 词干提取的收益、风险与控制方式 文本分析基础 - 分析器原理 概述 # 词干提取是将单词还原为其词根或基本形式（即词干）的过程。这项技术可确保在搜索操作中，单词的不同变体都能匹配到相应结果。例如，单词 “running”（跑步，现在分词形式）、“runner”（跑步者，名词形式）和 “ran”（跑步，过去式）都可以还原为词干 “run”（跑步，原形），这样一来，搜索这些词中的任何一个都能返回相关结果。 在自然语言中，由于动词变位、名词复数变化或词的派生等原因，单词常常以各种形式出现。词干提取在以下方面提升了搜索操作的效果： 提高搜索召回率：通过将不同的单词形式匹配到同一个词干，词干提取增加了检索到的相关文档的数量 减小索引大小：仅存储单词的词干形式可以减少搜索索引的总体大小 词干提取是通过在分析器中使用词元过滤器来配置的。一个分析器包含以下组件： 字符过滤器：在分词之前修改字符流 分词器：将文本拆分为词元（通常是单词） 词元过滤器：在分词之后修改词元，例如，应用词干提取操作 使用内置词元过滤器进行词干提取的示例 # 要实现词干提取，你可以配置一个内置的词元过滤器，比如 porter_stem 或 kstem 过滤器。 波特词干提取算法（ Porter stemming algorithm）是一种常用于英语的词干提取算法。 创建带有自定义分词器的索引 # 以下示例请求创建了一个名为 my_stemming_index 的新索引，并配置了一个使用 porter_stem 词元过滤器的分词器： PUT /my_stemming_index { "settings": { "analysis": { "analyzer": { "my_stemmer_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "porter_stem" ] } } } } } 此配置包含以下内容：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/relevance/debug-and-explain/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/relevance/debug-and-explain/调试与 Explain # 当你觉得"这条结果不该排这么前/这么后"时，就需要用调试工具把 _score 拆开来看。本页给出一个通用的排查流程。 典型症状 # 明显相关的文档排在很后面 噪声文档排在前几条 修改 Mapping 或查询结构后，排序结果变得难以解释 这些问题往往源于：字段类型/分析器不匹配、查询结构不合理、boost 失衡等。 理解评分标准 # 当调试一条复杂的查询语句时，想要理解 _score 究竟是如何计算是比较困难的。Easysearch 在每个查询语句中都有一个 explain 参数，将 explain 设为 true 就可以得到更详细的信息。 GET /_search?explain { "query" : { "match" : { "tweet" : "honeymoon" }} } explain 参数可以让返回结果添加一个 _score 评分的得来依据。 注意：增加一个 explain 参数会为每个匹配到的文档产生一大堆额外内容，但是花时间去理解它是很有意义的。如果现在看不明白也没关系——等你需要的时候再来回顾这一节就行。 首先，我们看一下普通查询返回的元数据： { "_index" : "us", "_id" : "12", "_score" : 0.076713204, "_source" : { ... trimmed .https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/resource_manager/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/resource_manager/资源扩容 # Easysearch Operator 支持对集群的 CPU、内存和磁盘资源进行在线扩容，扩容过程采用滚动更新方式，不影响集群可用性。 查看当前资源 # kubectl get sts/threenodes-masters -o yaml 示例输出（关键部分）： resources: requests: cpu: "1" memory: 3Gi limits: cpu: "1" memory: 5Gi # 存储 resources: requests: storage: 30Gi 修改资源配置 # 编辑 Operator YAML 文件，调整资源限制： resources: requests: cpu: "1" memory: 4Gi limits: cpu: "2" memory: 6Gi # 磁盘扩容 resources: requests: storage: 50Gi 应用修改： kubectl apply -f easysearch-cluster.yaml 注意：磁盘扩容依赖于 StorageClass 是否支持在线扩容（allowVolumeExpansion: true）。 滚动更新流程 # Operator 会按顺序逐个更新节点：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/routing/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/routing/_routing 元数据字段 # Easysearch 使用哈希算法将文档路由到索引中的特定分片。默认情况下，文档的 _id 字段用作路由值，但您也可以为每个文档指定自定义路由值。 默认路由 # 以下是 Easysearch 的默认路由公式。_routing 值是文档的 _id。 相关指南（先读这些） # 映射基础 元数据字段 shard_num = hash(_routing) % num_primary_shards 自定义路由 # 您可以在索引文档时指定自定义路由值，如以下示例所示： PUT sample-index1/_doc/1?routing=JohnDoe1 { "title": "This is a document" } 在此示例中，文档使用的路由值是 JohnDoe1 而不是默认的 _id 。 在检索、删除或更新文档时，您必须提供相同的路由值，如以下示例所示： GET sample-index1/_doc/1?routing=JohnDoe1 通过路由查询 # 您可以使用 _routing 字段根据文档的路由值进行查询，如以下示例所示。此查询仅搜索与 JohnDoe1 路由值关联的分片： GET sample-index1/_search { "query": { "terms": { "_routing": [ "JohnDoe1" ] } } } 设置路由为必需项 # 您可以使索引上的所有 CRUD 操作都必需提供路由值，如以下示例。如果您尝试在不提供路由值的情况下索引文档，Easysearch 将抛出异常。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/autocomplete-field-type/search-as-you-type/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/autocomplete-field-type/search-as-you-type/Search-as-you-type 字段类型 # search-as-you-type 字段类型通过前缀和中缀补全提供边输入边搜索的功能。 代码样例 # 将字段映射为 search-as-you-type 类型时，会为该字段创建 n-gram 子字段，其中 n 的范围为 [2, max_shingle_size]。此外，还会创建一个索引前缀子字段。 创建一个 search-as-you-type 的映射字段 PUT books { "mappings": { "properties": { "suggestions": { "type": "search_as_you_type" } } } } 除了创建 suggestions 字段外，还会生成 suggestions._2gram、suggestions._3gram 和 suggestions._index_prefix 字段。 以下是使用 search-as-you-type 字段索引文档的示例： PUT books/_doc/1 { "suggestions": "one two three four" } 要匹配任意顺序的词项，可以使用 bool_prefix 或 multi-match 查询。 这些查询会将搜索词项按顺序匹配的文档排名提高，而将词项顺序不一致的文档排名降低。 GET books/_search { "query": { "multi_match": { "query": "tw one", "type": "bool_prefix", "fields": [ "suggestions", "suggestions.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/restore-backup/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/restore-backup/还原备份 # 可以从已有的快照备份中还原索引数据。 操作步骤 # 进入备份管理页面：登录 Easysearch UI，在左侧导航栏点击「备份管理」，切换至「备份」标签页。 触发还原操作：在备份列表中，找到目标快照，点击「操作」列的更多按钮，选择「还原」选项。 配置还原参数：在弹出的「还原索引」窗口中，按需配置以下选项： 开启/关闭「所有索引」开关，选择还原快照中的全部或部分索引。 按需开启「重命名索引」，设置还原后的索引名称。 按需开启「忽略不可用索引」「允许部分快照」等开关。 确认还原操作：配置完成后，点击「确定」按钮，系统将开始执行快照还原。 查看还原进度：可切换至「还原」标签页查看还原任务的执行状态，还原完成后索引数据将恢复至快照创建时的状态。 注意事项 # 还原操作会覆盖集群中已存在的同名索引，执行前请确认数据已备份或无需保留。 还原过程中请勿中断操作，避免索引状态异常。 若需还原部分索引，可关闭「所有索引」开关，单独指定需要还原的索引列表。 开启「忽略不可用索引」可跳过快照中无法还原的索引，避免整体还原任务失败。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/other-settings/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/cluster-settings/other-settings/集群其它配置 # 操作步骤 # 进入其它配置页：在左侧导航栏点击「集群设置」，切换到「其它配置」标签页。 修改配置参数：根据业务需求，调整分片均衡、并发控制、日志设置、主节点选举、查询与缓存等对应配置项的参数值。 生效配置：确认所有配置修改无误后，点击「更新」按钮，配置立即生效。 注意事项 # 此页面涉及的配置项对集群行为影响较大，修改前请充分了解各参数含义，建议在测试环境验证后再应用到生产集群。 分片均衡相关参数会影响集群的分片分配策略，不当设置可能导致分片分布不均或频繁迁移。 并发控制参数会限制索引和搜索的并发数量，设置过低可能影响吞吐量，设置过高可能导致资源耗尽。 所有配置修改同样为临时配置，集群重启后将恢复为默认值或配置文件中的持久设置。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/eager_global_ordinals/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/eager_global_ordinals/Eager Global Ordinals 参数 # eager_global_ordinals 参数控制是否在索引刷新时提前构建全局序数（Global Ordinals）。全局序数是 keyword、ip 等字段执行聚合和排序时使用的内部数据结构。 相关指南 # doc_values 参数 fielddata 参数 参数选项 # 值 说明 false 默认值。全局序数在首次查询（聚合/排序）时惰性构建。 true 在索引刷新（refresh）时立即构建全局序数。 默认行为 # 默认情况下，全局序数采用惰性加载策略：第一次聚合或排序请求会触发构建，后续请求直接使用缓存。当索引发生变更并刷新后，缓存失效，下次查询时重新构建。 示例 # PUT my-index { "mappings": { "properties": { "category": { "type": "keyword", "eager_global_ordinals": true } } } } 何时启用 # 场景 建议 高频聚合字段，要求低延迟 设为 true，将构建开销转移到索引阶段 普通聚合字段 保持默认 false，惰性构建已足够 很少聚合的字段 保持默认 false，避免浪费资源 写入量远大于查询量 保持默认 false，频繁刷新会导致频繁重建 注意事项 # 启用后会增加索引刷新时间，因为每次 refresh 都需要重新构建全局序数 全局序数存储在堆内存中，高基数字段会占用较多内存 可通过 _stats API 查看全局序数占用的内存大小 对于时序数据等写入密集场景，建议保持默认值以避免刷新延迟增加https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/icu-tokenizer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/icu-tokenizer/ICU Tokenizer # icu_tokenizer 分词器使用 ICU 的 Unicode 文本分割算法，对多语言文本（尤其是亚洲语言混合文本）提供比 standard 分词器更好的分词效果。 需要安装 analysis-icu 插件。 示例 # PUT my_index { "settings": { "analysis": { "tokenizer": { "my_icu": { "type": "icu_tokenizer" } } } } } 参数 # 参数 说明 默认值 rule_files 自定义 ICU 分词规则文件路径 无 相关指南 # ICU 分析器 Standard 分词器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/ik-smart-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/ik-smart-analyzer/IK Smart 分析器 # ik_smart 分析器是为中文智能分词的分析器，使用 IK 分词器的智能模式，会尽量将文本切分为最少的词语。 需要安装 analysis-ik 插件。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： ik_smart 分词器：使用 IK 智能分词模式，倾向于切分出较长的词语 lowercase 分词过滤器：转换为小写 示例 # POST _analyze { "analyzer": "ik_smart", "text": "中华人民共和国国歌" } 相关指南 # 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-template/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-template/Search Template API # 您可以将全文查询转换为查询模板，以接受用户输入并将其动态插入到查询中。 例如，如果您使用 Easysearch 作为应用程序或网站的后端搜索引擎，则可以从搜索栏或表单字段接收用户查询，并将其作为参数传递到查询模板中。这样，创建 Easysearch 查询的语法就从最终用户那里抽象出来了。 当您编写代码将用户输入转换为 Easysearch 查询时，可以使用查询模板简化代码。如果需要将字段添加到搜索查询中，只需修改模板即可，而无需更改代码。 查询模板使用 Mustache 语言。有关所有语法选项的列表，请参阅 Mustache 手册。 相关指南（先读这些） # 查询 DSL 基础 全文搜索 创建查询模版 # 查询模版有两个组件：查询和参数。参数是放置在变量中的用户输入值。在 Mustache 符号中，变量用双括号表示。当在查询中遇到类似 {% raw %}{{var}}{% endraw %} 的变量时，Easysearch 会转到 params 部分，查找名为 var 的参数，并用指定的值替换它。 您可以编写应用程序代码，询问用户要搜索什么，然后在运行时将该值插入 params 对象中。 此命令定义了一个查询模版，用于按名称查找播放。查询中的 {% raw %}{{play_name}}{% endraw %} 被值 Henry IV 替换： GET _search/template { "source": { "query": { "match": { "play_name": "{% raw %}{{play_name}}{% endraw %}" } } }, "params": { "play_name": "Henry IV" } } 此模板在整个集群上运行搜索。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/word-delimiter-graph/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/word-delimiter-graph/Word Delimiter Graph 分词过滤器 # word_delimiter_graph 分词过滤器用于依据预定义的字符对词元进行拆分，还能基于可定制的规则对词元进行可选的规范化处理。 提示：word_delimiter_graph 分词过滤器可用于去除零件编号或产品 ID 这类复杂标识符中的标点符号。在这种情况下，它最好与 keyword 分词器搭配使用。对于带有连字符的单词，建议使用 synonym_graph 分词过滤器而非 word_delimiter_graph 分词过滤器，因为用户在搜索这些词时，往往既会搜索带连字符的形式，也会搜索不带连字符的形式。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 默认情况下，该过滤器会应用以下规则： 描述 输入 输出 将非字母数字字符视为分隔符 ultra-fast ultra, fast 去除词元开头或结尾的分隔符 Z99++'Decoder' Z99, Decoder 当字母大小写发生转换时拆分词元 Easysearch Easy, search 当字母和数字之间发生转换时拆分词元 T1000 T, 1000 去除词元末尾的所有格形式（‘s） John's John 重要的是，不要将此过滤器与会去除标点符号的分词器（如标准分词器）一起使用。这样做可能会导致词元无法正确拆分，并且会影响诸如 catenate_all 或 preserve_original 之类的选项。我们建议将此过滤器与关键字(keyword)分词器或空白(whitespace)分词器搭配使用。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/hybrid-score-explanation-processor/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/search-pipelines/hybrid-score-explanation-processor/混合评分解释处理器（Hybrid Score Explanation Processor） # 需要 AI 插件 hybrid_score_explanation 响应处理器用于为混合搜索结果添加评分解释信息。当与 hybrid_ranker_processor 配合使用时，该处理器将归一化和得分融合的详细过程附加到每个搜索命中结果中，帮助用户理解最终得分的来源。 工作原理 # 在混合搜索管道中，hybrid_ranker_processor 在得分融合过程中会将详细的计算信息（各子查询的原始得分、归一化方式、融合方式）记录到管道处理上下文中。hybrid_score_explanation 处理器在响应阶段读取这些信息，并将其合并到每个搜索命中结果的 _explanation 字段中。 解释信息包括： 归一化详情：使用的归一化技术及每个子查询得分的归一化结果 得分融合详情：使用的融合算法（如 RRF）及各路得分的融合过程 请求体字段 # 字段 类型 是否必填 说明 tag String 否 处理器标识标签 description String 否 处理器描述 ignore_failure Boolean 否 处理器失败时是否继续执行。默认 false 示例 # 基本用法 # PUT /_search/pipeline/my_explain_pipeline { "phase_results_processors": [ { "hybrid_ranker_processor": { "tag": "ranker", "description": "RRF 混合排序" } } ], "response_processors": [ { "hybrid_score_explanation": { "tag": "explanation", "description": "添加混合评分解释" } } ] } 返回结果示例 # 使用上述管道执行混合搜索后，每个命中结果的 _explanation 中会包含类似以下的评分解释：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-identifying-words/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-identifying-words/词汇识别 # 词汇识别是文本分析的第一步：将文本拆分为可搜索的词项。不同语言的词汇识别方式差异很大，需要选择合适的分析器和分词器。 不同语言的挑战 # 英语 # 英语单词相对容易识别：单词之间通常以空格或标点分隔。但也有一些边界情况： you're 是一个单词还是两个？ o'clock、cooperate、half-baked、eyewitness 等复合词如何处理？ 德语和荷兰语 # 这些语言会将独立的单词合并成长复合词，例如： Weißkopfseeadler（white-headed sea eagle） 为了在查询 Adler（eagle）时也能匹配到 Weißkopfseeadler，需要将复合词拆分成词组。 亚洲语言 # 亚洲语言更复杂： 很多语言在单词、句子甚至段落之间没有空格 有些词可以用一个字表达，但同样的字在另一个字旁边时就是不同意思的长词的一部分 标准分析器 # 任何全文检索的 text 字段默认使用 standard 分析器。标准分析器包括： 分词器：standard 分词器 词元过滤器：lowercase（小写转换）和 stop（停用词，默认关闭） 标准分析器可以这样重新实现： { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "stop"] } 标准分词器 # standard 分词器基于 Unicode 文本分割算法，能够： 识别单词边界（空格、标点） 处理大多数欧洲语言 处理亚洲语言（虽然可能不够精确） 示例：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/wildcard/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/wildcard/Wildcard 字段类型 # wildcard 字段是 keyword 字段的一种变体，专为任意子字符串和正则表达式匹配而设计。 当您的内容由"字符串"而非"文本"组成时，应使用 wildcard 字段。示例包括非结构化日志行和计算机代码。 wildcard 字段类型的索引方式与 keyword 字段类型不同。keyword 字段将原始字段值写入索引，而 wildcard 字段类型则将字段值拆分为长度小于或等于 3 的子字符串，并将这些子字符串写入索引。例如，字符串 test 被拆分为 t、te、tes、e、es 和 est 这些子字符串。 在搜索时，将查询模式中所需的子字符串与索引进行匹配以生成候选文档，然后根据查询中的模式对这些文档进行过滤。例如，对于搜索词 test，Easysearch 执行索引搜索 tes AND est。如果搜索词包含少于三个字符，Easysearch 会使用长度为一或二的字符子字符串。对于每个匹配的文档，如果源值为 test，则该文档将出现在结果中。这样可以排除误报值，如 nikola tesla felt alternating current was best。 通常，精确匹配查询（如 term 或 terms 查询）在 wildcard 字段上的表现不如在 keyword 字段上有效，而 wildcard、 prefix 和 regexp 查询在 wildcard 字段上表现更好。 相关指南（先读这些） # 映射基础 部分匹配 结构化搜索 示例 # 创建带有 wildcard 字段的映射：https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/source-and-stored-fields/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/source-and-stored-fields/_source 与字段存储 # _source 是文档写入时的原始 JSON，而字段的存储和检索有多种方式。本页讨论如何在"读取灵活性、存储成本与性能"之间做权衡。 _source：默认的真相来源 # _source 保存了写入时的完整 JSON 文档。在 _source 开启的情况下： GET 请求可以直接返回原始文档 update 操作可以在服务端基于 _source 进行部分更新 需要重建索引时，可以直接从 _source 读取数据（参见 重建索引） 大多数场景下，建议保持 _source 开启，除非有非常严格的存储或合规要求。 _source 字段过滤 # 在查询时，可以通过 _source_includes 和 _source_excludes 只返回需要的字段，减少网络传输： // GET 请求中过滤 _source GET /my-index/_doc/1?_source_includes=title,date // Search 请求中过滤 _source POST /my-index/_search { "_source": { "includes": ["title", "date"], "excludes": ["description"] }, "query": { "match_all": {} } } // 完全不返回 _source GET /my-index/_doc/1?https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/flatten-graph/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/flatten-graph/Flatten Graph 分词过滤器 # flatten_graph 分词过滤器用于处理在图结构中同一位置生成多个词元时出现的复杂词元关系。一些分词过滤器，比如 synonym_graph 和 word_delimiter_graph，会生成多位置词元——即相互重叠或跨越多个位置的词元。这些词元图对于搜索查询很有用，但在索引过程中却不被直接支持。flatten_graph 分词过滤器会将多位置词元解析为一个线性的词元序列。对图进行扁平化处理可确保与索引过程兼容。 注意：词元图的扁平化是一个有损耗的过程。只要有可能，就应避免使用 flatten_graph 过滤器。相反，应仅在搜索分词器中应用图分词过滤器，这样就无需使用 flatten_graph 分词过滤器了。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参考样例 # 以下示例请求创建了一个名为 test_index 的新索引，并配置了一个带有平图化分词过滤器的分词器： PUT /test_index { "settings": { "analysis": { "analyzer": { "my_index_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "my_custom_filter", "flatten_graph" ] } }, "filter": { "my_custom_filter": { "type": "word_delimiter_graph", "catenate_all": true } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-normalization/归一化与规范化器 # 词元归一化是将不同形式的词项统一为标准形式的过程，这对于提高搜索的召回率非常重要。例如，搜索 rôle 时也应该能匹配到 role。 为什么需要归一化？ # 在搜索中，我们经常遇到这样的情况： 同一个词的不同大小写形式：The、the、THE 带变音符号和不带变音符号的词：rôle、role Unicode 的不同表示形式：é 可能以不同方式编码 如果不进行归一化，这些不同的形式会被视为不同的词项，导致搜索时无法匹配。 小写转换（Lowercasing） # 小写转换是最常见的归一化操作。大多数分析器默认都会进行小写转换。 使用 lowercase 过滤器 # PUT /my_index { "settings": { "analysis": { "analyzer": { "my_lowercase_analyzer": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase"] } } } } } 测试效果： GET /my_index/_analyze { "analyzer": "my_lowercase_analyzer", "text": "The Quick Brown Fox" } 输出：[the, quick, brown, fox] 何时需要保留大小写？ # 某些场景下可能需要保留大小写：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/pinyin-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/pinyin-analyzer/Pinyin 分析器 # pinyin 分析器能够在索引阶段将中文字符实时转写为拼音，并在检索阶段对拼音、汉字及混输查询进行统一匹配。借助该插件，你可以轻松实现： 相关指南（先读这些） # 文本分析基础 文本分析：识别词元 支持 全拼、首字母、全拼拼接 等多种检索方式； 保留非中文字符，实现「中英混输」搜索； 借助 token filter 在分词链中灵活组合不同策略； 在联想输入、排序、聚合等场景下提升中文用户体验。 适用于人名、地名、品牌、歌曲、商品等多种中文文本检索场景。 参数说明 # 下表整理了 pinyin 分词器 / 过滤器支持的全部可选参数及默认值。 参数 说明 默认值 keep_first_letter 仅保留每个汉字的拼音首字母。例如 刘德华 → ldh true keep_separate_first_letter 将首字母分开存储，提高命中率。例如 刘德华 → l, d, h，注意：这可能会由于词频增加而增加查询模糊性。 false limit_first_letter_length 首字母结果最长长度 16 keep_full_pinyin 保留每个汉字的全拼。如 刘德华 → liu, de, hua true keep_joined_full_pinyin 将全拼连接在一起。如 刘德华 → liudehua false keep_none_chinese 保留非中文字符（数字/字母等） true keep_none_chinese_together 将连续非中文字符作为整体保留。例如， DJ 音乐家 变成 DJ 、 yin 、 yue 、 jia 。当设置为 false 时， DJ 音乐家 变成 D 、 J 、 yin 、 yue 、 jia 。注意： keep_none_chinese 应该先启用。 true keep_none_chinese_in_first_letter 在首字母结果中保留非中文字。例如， 刘德华 AT2016 变成 ldhat2016 。符 true keep_none_chinese_in_joined_full_pinyin 在拼接全部拼音时保留非中文字。例如， 刘德华 2016 变成 liudehua2016 。符 false none_chinese_pinyin_tokenize 将非中文字符中可能的拼音继续拆分例如， liudehuaalibaba13zhuanghan 变成 liu 、 de 、 hua 、 a 、 li 、 ba 、 ba 、 13 、 zhuang 、 han 。注意： keep_none_chinese 和 keep_none_chinese_together 应该先启用。 true keep_original 同时保留原始文本 false lowercase 对非中文字符强制小写 true trim_whitespace 去除首尾空格 true remove_duplicated_term 开启时，移除重复术语以节省索引空间。例如， de 的 变为 de 。注意：位置相关的查询可能会受影响。积 false ignore_pinyin_offset 忽略 offset 以允许重叠 token。在 6.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/remove/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/remove/移除处理器 # remove 处理器用于从文档中移除一个字段。 语法 # 以下是为 remove 处理器提供的语法： { "remove": { "field": "field_name" } } 配置参数 # 下表列出了 remove 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要移除的数据的字段名称。支持模板片段。 _index 、 _version 、 _version_type 和 _id 元数据字段不能被移除。如果指定了 version ，则不能从摄取文档中移除 _id 。 exclude_field 必填 要保留的字段名称。除元数据字段外，所有其他字段都将被删除。 exclude_field 和 field 选项互斥。支持模板片段。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/unique/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/unique/Unique 分词过滤器 # unique 分词过滤器可确保在分词过程中仅保留唯一的词元，它会去除在单个字段或文本块中出现的重复词元。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参数说明 # 唯一分词过滤器可以使用以下参数进行配置： 参数 必需/可选 数据类型 描述 only_on_same_position 可选 布尔值 如果设置为 true，该分词过滤器将充当去重分词过滤器，仅移除位于相同位置的词元。默认值为 false。 参考样例 # 以下示例请求创建了一个名为 unique_example 的新索引，并配置了一个带有唯一过滤器的分词器。 PUT /unique_example { "settings": { "analysis": { "filter": { "unique_filter": { "type": "unique", "only_on_same_position": false } }, "analyzer": { "unique_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "unique_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/stconvert-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/stconvert-analyzer/STConvert 分析器 # stconvert 分析器可在索引与查询阶段将简体中文与繁体中文之间进行双向转换，解决两种文字体系混合检索的问题。 相关指南（先读这些） # 文本分析基础 文本分析：规范化 参数说明 # 参数 说明 默认值 convert_type 转换方向，可选：s2t（简 → 繁），t2s（繁 → 简） s2t keep_both 是否同时保留转换前后两种 token false delimiter 当 keep_both=true 时，两种 token 之间的分隔符 , 使用介绍 # 映射创建 PUT /stconvert/ { "settings" : { "analysis" : { "analyzer" : { "tsconvert" : { "tokenizer" : "tsconvert" } }, "tokenizer" : { "tsconvert" : { "type" : "stconvert", "delimiter" : "#", "keep_both" : false, "convert_type" : "t2s" } }, "filter": { "tsconvert" : { "type" : "stconvert", "delimiter" : "#", "keep_both" : false, "convert_type" : "t2s" } }, "char_filter" : { "tsconvert" : { "type" : "stconvert", "convert_type" : "t2s" } } } } } 分词测试https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-stemming/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-stemming/词干提取 # 很多语言的单词都存在“词形变化”（inflection）：同一个概念会换着马甲出现： 单复数：fox / foxes 时态：pay / paid / paying 性别：waiter / waitress 人称变化：hear / hears 如果只做精确词项匹配，用户搜索 fox 时不会命中只包含 foxes 的文档。词干提取（Stemming） 的目标就是把这些“形式差异”抹平：让相关词项尽量归并到同一个词根上，从而提升召回率。 词干提取会遇到的两类问题 # 词干提取不是“精确科学”，它更像“有原则的近似”。常见两类风险： 弱提取（Understemming）：相关词没有收敛到同一词干 例如：jumped、jumps → jump，但 jumping → jumpi，导致漏召回。 过度提取（Overstemming）：本应区分的词被合并到同一词干 例如：general 与 generate 都被提取为 gener，导致误召回、降低精度。 这也是为什么“哪个词干器最好”没有统一答案：你的语料、你的用户、你的容错边界都不一样。 词干提取 vs 词形还原（Lemmatization） # 词干提取：规则化“裁剪”词形，得到的词根未必是真实单词（如 jumpi）。 重点是：索引与查询两端一致即可。 词形还原：尝试按“词义/词典形态”归类（如 is/was/am/being → be），通常更复杂、成本更高，需要更多语言知识与上下文。 在多数搜索系统里，词干提取更常作为默认选择：成本低、收益稳。词形还原则更像“精装修”，做得好很香，做不好也可能很贵。 算法词干器（Algorithmic stemmers） # Easysearch 常用的是算法型词干器：通过一系列规则把词映射到词根，不依赖大词典。你可以把它理解为“规则派”：不查字典，按套路办事。 优点： 速度快、内存占用小 对“规律变化”的词效果稳定 缺点：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/rename/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/rename/重命名处理器 # rename 处理器用于重命名现有字段，也可以用来将字段从一个对象移动到另一个对象或根级别。 语法 # 以下是为 rename 处理器提供的语法： { "rename": { "field": "field_name", "target_field" : "target_field_name" } } 配置参数 # 下表列出了 rename 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要重命名的数据的字段名称。支持模板使用。 target_field 必填 字段的新名称。支持模板使用。 ignore_missing 可选 指定处理器是否应忽略不包含指定 field 的文档。如果设置为 true ，则处理器在 field 不存在时不会修改文档。默认为 false 。 override_target 可选 确定当 target_field 存在于文档中时会发生什么。如果设置为 true ，则处理器将现有的 target_field 值覆盖为新值。如果设置为 false ，则现有值保持不变，处理器不会覆盖它。默认为 false 。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hanlp-crf-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hanlp-crf-analyzer/HanLP CRF 分析器 # hanlp_crf 分析器是为中文 CRF 分词的分析器，使用 HanLP CRF（条件随机场）模型进行分词，适合学术研究场景。 需要安装 analysis-hanlp 插件。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： hanlp_crf 分词器：使用 HanLP CRF 条件随机场模型进行分词 lowercase 分词过滤器：转换为小写 示例 # POST _analyze { "analyzer": "hanlp_crf", "text": "中国科学院计算技术研究所" } 相关指南 # 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hanlp-nlp-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hanlp-nlp-analyzer/HanLP NLP 分析器 # hanlp_nlp 分析器是为中文 NLP 分词的分析器，使用 HanLP NLP 模式，支持命名实体识别，适合需要高精度语义分析的场景。 需要安装 analysis-hanlp 插件。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： hanlp_nlp 分词器：使用 HanLP NLP 模式，支持命名实体识别 lowercase 分词过滤器：转换为小写 示例 # POST _analyze { "analyzer": "hanlp_nlp", "text": "刘德华和张学友是好朋友" } 相关指南 # 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hanlp-standard-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hanlp-standard-analyzer/HanLP Standard 分析器 # hanlp_standard 分析器是为中文标准分词的分析器，使用 HanLP 标准分词模式，适合大多数通用中文搜索场景。 需要安装 analysis-hanlp 插件。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： hanlp_standard 分词器：使用 HanLP 标准分词模式 lowercase 分词过滤器：转换为小写 示例 # POST _analyze { "analyzer": "hanlp_standard", "text": "中华人民共和国国歌" } 相关指南 # 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hanlp-index-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/hanlp-index-analyzer/HanLP Index 分析器 # hanlp_index 分析器是为中文索引分词的分析器，使用 HanLP 索引分词模式，会对文本进行更细粒度的切分。 需要安装 analysis-hanlp 插件。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： hanlp_index 分词器：使用 HanLP 索引分词模式，对文本进行细粒度切分 lowercase 分词过滤器：转换为小写 示例 # POST _analyze { "analyzer": "hanlp_index", "text": "中华人民共和国国歌" } 相关指南 # 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/pit-api/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/pit-api/Point In Time (PIT) API # Point In Time（PIT）搜索具有与常规搜索相同的功能，不同之处在于 PIT 搜索作用于较旧的数据集，而常规搜索作用于实时数据集。PIT 搜索不绑定于特定查询，因此您可以在同一个冻结在时间点上的数据集上运行不同的查询。 您可以使用创建 PIT API 来创建 PIT。当您为一组索引创建 PIT 时，Easysearch 会锁定这些索引的一组段，使它们在时间上冻结。在底层，此 PIT 所需的资源不会被修改或删除。如果作为 PIT 一部分的段被合并，Easysearch 会在 PIT 创建时通过 keep_alive 参数指定的时间段内保留这些段的副本。 创建 PIT 操作会返回一个 PIT ID，您可以使用该 ID 在冻结的数据集上运行多个查询。即使索引继续摄取数据并修改或删除文档，PIT 引用的数据自 PIT 创建以来不会发生变化。当您的查询包含 PIT ID 时，您不需要将索引传递给搜索，因为它将使用该 PIT。使用 PIT ID 的搜索在多次运行时将产生完全相同的结果。 相关指南（先读这些） # 分页与排序 查询 DSL 基础 创建 PIT # 创建一个 PIT。查询参数 keep_alive 是必需的；它指定了保持 PIT 的时间长度。 端点 # POST /<target_indexes>/_pit?https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-stopwords/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-stopwords/停用词 # 停用词（Stopwords）是指在大多数文本中非常常见、对区分文档贡献很小的词，例如 the、and、is。早期信息检索系统会大量使用停用词来减少索引体积；在今天，更需要从 性能与表达力 两方面权衡。 高频词与低频词 # 从词项频率的角度，我们可以把词项粗略分为两类： 低频词（更重要）：在文档集合中出现较少，通常信息量更大，区分能力更强 高频词（次重要）：在大量文档中都出现，对区分能力弱，但会显著影响性能 哪些词是“高频”，强依赖你的语料：在英文语料里 the 极常见；在中文语料里它反而不会出现。 停用词的优缺点 # 优点：性能 # 假设一个索引有 100 万文档，词 fox 只出现在 20 个文档中： 查询 fox：只需要对很少的候选文档计算 _score 查询 the OR fox：由于 the 几乎在所有文档里都出现，系统可能需要对大量文档计算 _score，代价骤增 因此，减少极高频词对候选集合的“污染”，有助于控制查询成本。 缺点：表达力下降 # 把常见词一律移除会让一些真实需求变得难以表达： 区分 happy 与 not happy 搜索乐队名 The The 搜索名句 “to be, or not to be” 某些短词在特定语料里可能很关键（例如国家代码、产品型号） 在现代硬件条件下，“省空间”往往不再是使用停用词的主理由；更重要的是避免让搜索变得“说不清、搜不准”。 如何配置停用词 # 停用词由 stop 过滤器处理，也可以通过分析器参数直接配置。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/remove-duplicates/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/remove-duplicates/Remove Duplicates 分词过滤器 # remove_duplicates 分词过滤器用于去除在分词过程中在相同位置生成的重复词元。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参考样例 # 以下示例请求创建了一个带有 keyword_repeat（关键词重复）分词过滤器的索引。该过滤器会在每个词元自身所在的相同位置添加该词元的关键词版本，然后使用 kstem（K 词干提取）过滤器来创建该词元的词干形式。 PUT /example-index { "settings": { "analysis": { "analyzer": { "custom_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "keyword_repeat", "kstem" ] } } } } } 使用以下请求来分析字符串 “Slower turtle”。 GET /example-index/_analyze { "analyzer": "custom_analyzer", "text": "Slower turtle" } 返回内容中在同一位置包含了两次词元 “turtle”。 { "tokens": [ { "token": "slower", "start_offset": 0, "end_offset": 6, "type": "<ALPHANUM>", "position": 0 }, { "token": "slow", "start_offset": 0, "end_offset": 6, "type": "<ALPHANUM>", "position": 0 }, { "token": "turtle", "start_offset": 7, "end_offset": 13, "type": "<ALPHANUM>", "position": 1 }, { "token": "turtle", "start_offset": 7, "end_offset": 13, "type": "<ALPHANUM>", "position": 1 } ] } 可以通过在索引设置中添加一个去重分词过滤器来移除重复的词元。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/script/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/script/脚本处理器 # script 处理器执行内联和存储的脚本，可以在数据导入过程中修改或转换 Easysearch 文档中的数据。由于脚本可能按文档重新编译，处理器使用脚本缓存以提高性能。有关在 Easysearch 中使用脚本的信息，请参阅脚本 API。 以下是为 script 处理器提供的语法： { "processor": { "script": { "source": "<script_source>", "lang": "<script_language>", "params": { "<param_name>": "<param_value>" } } } } 配置参数 # 下表列出了 script 处理器所需的和可选参数。 参数 是否必填 描述 source 可选 要执行的 Painless 脚本。必须指定 id 或 source ，但不能同时指定两者。如果指定了 source ，则使用提供的源代码执行脚本。 id 可选 存储脚本的 ID，之前使用 Create Stored Script API 创建的。必须指定 id 或 source ，但不能同时指定两者。如果指定了 id ，则从具有指定 ID 的存储脚本中检索脚本源。 lang 可选 脚本的编程语言。默认为 painless 。 params 可选 可以传递给脚本的参数。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/geo-field-type/geohash/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/geo-field-type/geohash/Geohash 编码 # Geohash 是一种将经纬度坐标（lat/lon）编码成字符串的方式。这么做的初衷只是为了让地理位置在 URL 上呈现的形式更加友好，但现在 Geohash 已经变成一种在数据库中高效索引地理坐标点和地理形状的方式。 工作原理 # Geohash 把整个世界分为 32 个单元的格子——4 行 8 列——每一个格子都用一个字母或者数字标识。比如 g 这个单元覆盖了半个格林兰、冰岛的全部和大不列颠的大部分。 每一个单元还可以进一步被分解成新的 32 个单元，这些单元又可以继续被分解成 32 个更小的单元，不断重复下去： gc 覆盖了爱尔兰和英格兰 gcp 覆盖了伦敦的大部分和部分南英格兰 gcpuuz94k 是白金汉宫的入口，精确到约 5 米 核心特性：Geohash 的长度越长，精度就越高。如果两个 Geohash 有一个共同的前缀（如 gcpuuz），就表示它们挨得很近。共同的前缀越长，距离就越近。 精度级别 # 下表展示了不同长度 Geohash 对应的近似尺寸： Geohash 级别 近似尺寸 g 1 ~ 5,004km × 5,004km gc 2 ~ 1,251km × 625km gcp 3 ~ 156km × 156km gcpu 4 ~ 39km × 19.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/icu-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/icu-analyzer/ICU 分析器 # icu 分析器是为多语言文本分析的分析器，基于 ICU（International Components for Unicode）实现，对亚洲语言混合文本提供比标准分析器更好的分词效果。 需要安装 analysis-icu 插件。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： icu_tokenizer 分词器：使用 ICU Unicode 文本分割算法 icu_normalizer 分词过滤器：Unicode 归一化（NFC 模式） 示例 # POST _analyze { "analyzer": "icu", "text": "Elasticsearch の全文検索エンジン" } 相关指南 # 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/ik-smart/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/ik-smart/IK Smart 分词器 # ik_smart 是 IK 分词器插件提供的智能分词模式，是最常用的中文分词方式。 ##分词方式 智能分词（Smart）模式倾向于将文本分成"人类可读"的粗粒度词项，适合大多数应用场景。 示例 # POST _analyze { "tokenizer": "ik_smart", "text": "北京市朝阳区建国路1号" } 分析结果 # [ "北京市", "朝阳区", "建国路", "1", "号" ] 相关指南 # IK分词器文档 文本分析基础 依赖插件 # analysis-ik 插件 配置 # PUT my_index { "settings": { "analysis": { "tokenizer": { "my_ik_smart": { "type": "ik_smart" } } } } }https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/mapping-analysis-intro/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/mapping-analysis-intro/Mapping 与文本分析 # Easysearch 中不同字段类型的索引和搜索行为截然不同。理解映射（Mapping）和分析（Analysis）是用好全文搜索的关键。 精确值 VS 全文 # Easysearch 中的数据可以概括为两类： 精确值（Exact Values） 例如日期 2024-09-15、用户 ID user_123、状态码 published Foo 和 foo 是不同的，2024 和 2024-09-15 也是不同的 查询是二进制的：要么匹配，要么不匹配 全文（Full Text） 例如文章内容、商品描述、邮件正文 查询不是"是否匹配"，而是"匹配程度有多大" 期望搜索 jump 能匹配 jumped、jumps、jumping 期望搜索 UK 能返回包含 United Kingdom 的文档 为了支持全文搜索，Easysearch 在索引之前会先对文本进行分析，生成标准化的词条后写入倒排索引。 分析器：三步处理 # 分析（Analysis） 是将文本转换为适合倒排索引的词条的过程。一个分析器由三个部分组成： 组件 作用 示例 字符过滤器 在分词前整理字符串 去掉 HTML 标签、& → and 分词器 将字符串拆分为单独的词条 按空格/标点拆分 Token 过滤器 对词条做变换 小写化、词干提取、同义词扩展、停用词删除 内置分析器对比 # 以文本 "Set the shape to semi-transparent by calling set_trans(5)" 为例：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/trim/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/trim/Trim 分词过滤器 # trim 分词过滤器会从词元中去除前导和尾随的空白字符。 注意：许多常用的分词器，例如 standard 分词器、keyword 分词器和 whitespace 分词器，在分词过程中会自动去除前导和尾随的空白字符。当使用这些分词器时，无需额外配置 trim 分词过滤器。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参考样例 # 以下示例请求创建了一个名为 my_pattern_trim_index 的新索引，并配置了一个带有修剪过滤器和匹配词元生成器的分词器。其中，匹配词元生成器不会去除词元的前导和尾随空白字符。 PUT /my_pattern_trim_index { "settings": { "analysis": { "filter": { "my_trim_filter": { "type": "trim" } }, "tokenizer": { "my_pattern_tokenizer": { "type": "pattern", "pattern": "," } }, "analyzer": { "my_pattern_trim_analyzer": { "type": "custom", "tokenizer": "my_pattern_tokenizer", "filter": [ "lowercase", "my_trim_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/reverse/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/reverse/Reverse 分词过滤器 # reverse 分词过滤器会反转每个词元中字符的顺序，这样在分析过程中，后缀信息就会位于反转后词元的开头。 相关指南（先读这些） # 文本分析：识别词元 部分匹配 文本分析基础 这对于基于后缀的搜索很有用： 反转分词过滤器在你需要进行基于后缀的搜索时很有帮助，例如以下场景： 后缀匹配：根据单词的后缀来搜索单词，比如识别以特定后缀结尾的单词（例如 -tion 或 -ing）。 文件扩展名搜索：通过文件的扩展名来搜索文件，例如 .txt 或 .jpg。 自定义排序或排名：通过反转词元，你可以基于后缀实现独特的排序或排名逻辑。 后缀自动补全：实现基于后缀而非前缀的自动补全建议。 参考说明 # 以下示例请求创建了一个名为 my-reverse-index 的新索引，并配置了一个带有反转过滤器的分词器。 PUT /my-reverse-index { "settings": { "analysis": { "filter": { "reverse_filter": { "type": "reverse" } }, "analyzer": { "my_reverse_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "reverse_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-synonyms/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-synonyms/同义词 # 词干提取通过归并词形变化扩大搜索范围；同义词（Synonyms） 则通过归并“意义接近的不同表达”扩大搜索范围。 例如，查询“英国女王”时，你可能也希望命中包含“英国君主”的文档；用户搜索“美国”时，可能也期望命中包含“美利坚合众国”“USA”等表达的文档。 同义词看起来很简单，但“用对”并不容易：如果把语义跨度过大的词强行绑定，会让结果变得像“随机返回”。经验上，同义词应当 少而精，服务于明确的高价值场景。 基本用法：synonym 过滤器 # 同义词通过 synonym 词元过滤器实现，它会在分析过程中把词项替换或扩展为多个词项： PUT /my_index { "settings": { "analysis": { "filter": { "my_synonym_filter": { "type": "synonym", "synonyms": [ "british,english", "queen,monarch" ] } }, "analyzer": { "my_synonyms": { "tokenizer": "standard", "filter": [ "lowercase", "my_synonym_filter" ] } } } } } 同义词通常与原词项处于同一 position，因此短语查询仍能成立（前提是规则与分析链设置得当）。 同义词规则格式 # 权威指南里给出了两种常用格式： 1）等价同义词（逗号分隔） # jump,leap,hop 含义：遇到其中任意一个词项时，扩展为这一组同义词（等价看待）。 2）定向映射（=>） # u s a,united states,united states of america => usa g b,gb,great britain => britain,england,scotland,wales 含义：把左侧的一组表达统一映射为右侧一个或多个词项。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/slm/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/slm/快照生命周期管理 # 快照生命周期管理（Snapshot Lifecycle Management, SLM）提供自动化的快照创建与清理能力。 通过配置 SLM 策略，您可以按照预定计划自动创建快照，并根据保留条件自动删除过期快照。 策略配置参考 # 策略结构 # { "description": "策略描述", "creation": { ... }, "deletion": { ... }, "snapshot_config": { ... }, "notification": { ... } } creation — 快照创建配置 # 参数 描述 类型 是否必需 schedule 创建快照的时间计划。 object 是 time_limit 创建快照的最大等待时间。 string 否 schedule — 时间计划 # 支持 cron 表达式或固定间隔两种格式：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/truncate/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/truncate/Truncate 分词过滤器 # truncate 分词过滤器用于缩短超过指定长度的词元。它会将词元修剪至最大字符数，确保超过该限制的词元被截断。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参数说明 # 截断分词过滤器可以使用以下参数进行配置： 参数 必需/可选 数据类型 描述 length 可选 整数 指定生成的词元的最大长度。默认值为 10。 参考样例 # 以下示例请求创建了一个名为 truncate_example 的新索引，并配置了一个带有截断过滤器的分词器。 PUT /truncate_example { "settings": { "analysis": { "filter": { "truncate_filter": { "type": "truncate", "length": 5 } }, "analyzer": { "truncate_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "truncate_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/apostrophe/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/apostrophe/Apostrophe 分词过滤器 # apostrophe 分词过滤器的主要功能是移除所有格形式的撇号以及跟在撇号后面的所有内容。这在分析那些大量使用撇号的语言的文本时非常有用，比如土耳其语。在土耳其语中，撇号用于将词根与后缀分隔开来，这些后缀包括所有格后缀、格标记以及其他语法词尾。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参考样例 # 以下示例请求创建了一个名为 custom_text_index 的新索引，在索引设置中配置了一个自定义分词器，并在映射中使用该分词器： PUT /custom_text_index { "settings": { "analysis": { "analyzer": { "custom_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "apostrophe" ] } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "custom_analyzer" } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /custom_text_index/_analyze { "analyzer": "custom_analyzer", "text": "John's car is faster than Peter's bike" } 返回内容包含产生的词元https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/elision/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/elision/Elision 分词过滤器 # elision 分词过滤器用于从某些语言的单词中去除省略的字符。省略现象通常出现在像法语这样的语言中，在这些语言里，单词常常会发生缩合，并与后面的单词结合，常见的方式是省略一个元音字母，并用一个撇号来替代。 注意：elision 分词过滤器已经在以下语言分词器中预先配置好了：加泰罗尼亚语（catalan）、法语（french）、爱尔兰语（irish）和意大利语（italian）。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参数说明 # 自定义省略词分词过滤器可使用以下参数进行配置。 参数 必需/可选 数据类型 描述 articles 若未配置 articles_path 则为必需 字符串数组 定义当某些冠词或短词作为省略形式的一部分出现时，哪些应该被移除。 articles_path 若未配置 articles 则为必需 字符串 指定在分析过程中应被移除的自定义冠词列表的路径。 articles_case 可选 布尔值 指定在匹配省略形式时，该过滤器是否区分大小写。默认值为 false。 参考样例 # 法语中默认的省略形式集合包括 l'、m'、t'、qu'、n'、s'、j'、d'、c'、jusqu'、quoiqu'、lorsqu' 和 puisqu'。你可以通过配置 french_elision 分词过滤器来更新这个集合。以下示例请求创建了一个名为 french_texts 的新索引，并配置了一个带有 french_elision 过滤器的分词器：https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-templates/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-templates/索引模板 # 日志、指标、审计事件这类数据，常见模式是"按天/按月一个新索引"。如果每次新索引都要手动 PUT /index 配 settings + mappings，很快就会变成运维噩梦。 索引模板（Index Template） 就是为了解决这个问题：当新索引（手动或自动）被创建时，只要名字命中规则，就自动套用一组预配置——索引设置、映射和别名。 先了解： 索引管理：创建、删除与重建索引 | 时间序列建模 Easysearch 支持三类模板： 类型 API 路径 说明 可组合索引模板 _index_template 推荐使用，支持组件模板组合 组件模板 _component_template 可复用的模板构建块，被可组合模板引用 遗留索引模板 _template 旧版 API，建议迁移到可组合模板 注意：可组合索引模板（_index_template）优先级高于遗留模板（_template）。如果同时存在匹配的可组合模板和遗留模板，将使用可组合模板。 可组合索引模板 # 可组合索引模板是推荐的模板方式，支持通过 composed_of 引用组件模板，实现模板的模块化组合。 创建模板 # PUT _index_template/daily_logs { "index_patterns": ["logs-2024-01-*"], "priority": 100, "template": { "aliases": { "my_logs": {} }, "settings": { "number_of_shards": 2, "number_of_replicas": 1 }, "mappings": { "properties": { "timestamp": { "type": "date", "format": "yyyy-MM-dd HH:mm:ss||yyyy-MM-dd||epoch_millis" }, "value": { "type": "double" } } } } } 请求参数 # 参数 类型 描述 默认值 create boolean 为 true 时，仅在模板不存在时创建，不会覆盖已有模板 false cause string 创建/更新模板的原因（记录到日志） — master_timeout time 连接主节点的超时时间 30s 请求体参数 # 参数 类型 描述 必填 index_patterns array 索引名称匹配模式列表 是 template object 包含 aliases、settings、mappings 的模板定义 否 composed_of array 引用的组件模板名称列表，按顺序合并 否 priority number 模板优先级，值越大优先级越高 0 version number 模板版本号（用户自定义，仅供管理使用） — _meta object 模板的元数据信息 — data_stream object 设置后匹配的索引将作为数据流创建 — 查看模板 # # 获取指定模板 GET _index_template/daily_logs # 获取所有可组合模板 GET _index_template # 通配符匹配 GET _index_template/daily* 查询参数 # 参数 类型 描述 默认值 flat_settings boolean 以扁平格式返回 Settings false local boolean 从本地节点返回信息，不查询主节点 false master_timeout time 连接主节点的超时时间 30s 检查模板是否存在 # HEAD _index_template/daily_logs 返回 200 表示存在，404 表示不存在。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/set/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/set/设置处理器 # set 处理器向文档中添加或更新字段。它设置一个字段并将其与指定的值关联。如果该字段已存在，则其值将被提供的值替换，除非设置了 override 参数为 false。当 override 为 false 且指定的字段存在时，该字段的值保持不变。 以下是为 set 处理器提供的语法： { "description": "...", "processors": [ { "set": { "field": "new_field", "value": "some_value" } } ] } 配置参数 # 下表列出了 set 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 要设置或更新的字段的名称。支持模板使用。 value 必填 字段分配的值。支持模板使用。 override 可选 一个布尔标志，用于确定处理器是否应覆盖字段的现有值。 ignore_empty_value 可选 一个布尔标志，用于确定处理器是否应忽略 null 值或空字符串。默认为 false 。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/partial-matching/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/partial-matching/部分匹配 # 部分匹配允许用户输入“词的一部分”，并找出包含该片段的词项。全文检索很多时候并不需要它（分析器已经做了词干/同义词等处理），但在权威指南总结的几类场景中，部分匹配非常有价值： 精确值字段：邮编、产品序列号等以固定前缀/模式出现的值 输入即搜索（search-as-you-type）：用户还没输完就给出候选结果 复合词语言：德语/荷兰语等将多个词组合成长词 本页按“查询时方案 → 索引时优化”的顺序展开，并重点强调性能与可控性。 查询时方案 1：prefix 前缀查询 # 查找所有以 W1 开头的邮编： GET /my_index/_search { "query": { "prefix": { "postcode": "W1" } } } prefix 是词项级查询，不会分析输入，它做的事情近似于： 扫描倒排词典（有序词列表），找到第一个以 W1 开头的词 收集该词对应的文档 ID 向后移动，继续收集所有以 W1 开头的词，直到遇到不再匹配的词 重要的性能结论（权威指南强调）：前缀越短，扫描的词越多；当唯一词很多时，前缀查询的伸缩性并不好。尽量使用更长的前缀，或者转向索引时优化方案（见下文）。 查询时方案 2：wildcard / regexp（更灵活，也更危险） # 通配符查询（? 匹配一个字符，* 匹配 0 或多个字符）： GET /my_index/_search { "query": { "wildcard": { "postcode": "W?F*HW" } } } 正则表达式查询： GET /my_index/_search { "query": { "regexp": { "postcode": "W[0-9].https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/length/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/length/Length 分词过滤器 # length 分词过滤器用于从词元流中移除那些不符合指定长度标准（最小和最大长度值）的词元。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参数说明 # 长度分词过滤器可以使用以下参数进行配置。 参数 必填/可选 数据类型 描述 min 可选 整数 词元的最小长度。默认值为 0。 max 可选 整数 词元的最大长度。默认值为整数类型的最大值（2147483647）。 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个带有长度过滤器的分词器： PUT my_index { "settings": { "analysis": { "analyzer": { "only_keep_4_to_10_characters": { "tokenizer": "whitespace", "filter": [ "length_4_to_10" ] } }, "filter": { "length_4_to_10": { "type": "length", "min": 4, "max": 10 } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/ik-max-word/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/ik-max-word/IK Max Word 分词器 # ik_max_word 是 IK 分词器插件提供的细粒度分词模式。 分词方式 # 最大词模式（Max Word）倾向于将文本分成最细粒度的词项，适合对召回率要求高的场景。 示例 # POST _analyze { "tokenizer": "ik_max_word", "text": "北京市朝阳区建国路1号" } 分析结果 # [ "北京市", "北京", "市", "朝阳区", "朝阳", "区", "建国路", "建国", "路", "1", "号" ] 相关指南 # IK分词器文档 文本分析基础 依赖插件 # analysis-ik 插件 配置 # PUT my_index { "settings": { "analysis": { "tokenizer": { "my_ik_max_word": { "type": "ik_max_word" } } } } }https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/jieba-search-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/jieba-search-analyzer/Jieba Search 分析器 # jieba_search 分析器是为中文搜索分词的分析器，使用 Jieba 分词器的搜索模式，在精确模式的基础上对长词再次切分。 需要安装 analysis-jieba 插件。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： jieba_search 分词器：使用 Jieba 搜索模式，对长词进行二次切分以提高召回率 lowercase 分词过滤器：转换为小写 示例 # POST _analyze { "analyzer": "jieba_search", "text": "小明硕士毕业于中国科学院计算所" } 相关指南 # 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/jieba-index-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/jieba-index-analyzer/Jieba Index 分析器 # jieba_index 分析器是为中文索引分词的分析器，使用 Jieba 分词器的索引模式。 需要安装 analysis-jieba 插件。 分析器组成 # 该分析器由以下分词器和分词过滤器组成： jieba_index 分词器：使用 Jieba 索引模式，适合索引时的细粒度分词 lowercase 分词过滤器：转换为小写 示例 # POST _analyze { "analyzer": "jieba_index", "text": "小明硕士毕业于中国科学院计算所" } 相关指南 # 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/sort/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/sort/Sort 处理器 # sort 处理器可以按升序或降序对项目数组进行排序。数值数组按数值排序，而字符串或混合数组（字符串和数字）按字典顺序排序。如果输入不是数组，处理器将抛出错误。 以下是为 sort 处理器提供的语法： { "description": "Sort an array of items", "processors": [ { "sort": { "field": "my_array_field", "order": "desc" } } ] } 配置参数 # 下表列出了 sort 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 要排序的字段。必须是数组。 order 可选 应用排序顺序。接受 asc 用于升序或 desc 用于降序。默认是 asc 。 target_field 可选 存储排序数组字段的名称。如果未指定，则排序数组将存储在原始数组（ field 变量）相同的字段中。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/searchable-snapshot/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/searchable-snapshot/可搜索快照（Searchable Snapshots） # Easysearch 快照搜索允许系统直接在对象存储（如 S3、MinIO、OSS）上挂载快照索引，让归档数据瞬间具备检索能力——无需将快照恢复为完整索引，即使是 PB 级快照数据也能在数分钟内完成挂载并开放搜索。 核心优势 # 分钟级上线，零恢复等待 # 传统快照恢复需要将全量数据拷贝到本地磁盘，耗时可能达数小时。快照搜索消除了这一步骤，仅挂载元数据，数据按需从对象存储拉取。 极低的存储成本 # 核心数据保留在低成本的对象存储中，仅在查询时按需调用，大幅节省高性能磁盘（SSD）的占用空间。 统一的搜索体验 # 快照搜索与在线集群共享统一的 API 和查询语法，业务人员无需学习新接口即可调取历史记录。 前置条件 # 配置 search 角色节点 # 只有角色为 search 的节点才能执行快照搜索。在 easysearch.yml 中配置： node.name: search-node node.roles: [search] Docker 环境： - node.roles: [search] 集群中至少需要一个 search 角色节点才能使用可搜索快照功能。 注册快照仓库 # 以 MinIO（S3 兼容）为例： PUT _snapshot/my-repo { "type": "s3", "settings": { "access_key": "minioadmin", "secret_key": "minioadmin", "bucket": "es-bucket", "endpoint": "http://127.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/rescore/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/rescore/查询重打分 # 查询重打分（Rescore）允许你在初始查询返回 Top-N 结果后，用更复杂、更精细的查询对这些结果重新打分。这是一种二阶段打分策略：第一阶段用快速查询（如 match）粗筛，第二阶段用代价更高的查询（如 match_phrase、function_score）精排。 使用场景 # 短语精排：先用 match 召回，再用 match_phrase 提升短语完全匹配的文档 复杂评分：初始召回后，对 Top 结果做 function_score 或 script_score 精细计算 向量混排：用 BM25 召回后，对 Top-N 用 kNN 重打分 基础用法 # GET shakespeare/_search { "query": { "match": { "text_entry": "to be or not to be" } }, "rescore": { "window_size": 100, "query": { "rescore_query": { "match_phrase": { "text_entry": { "query": "to be or not to be", "slop": 2 } } }, "query_weight": 0.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-fuzzy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis-fuzzy/模糊匹配 # 结构化数据通常追求精确匹配，但好的全文检索往往需要一定的“容错”：用户可能会拼错名字、记不清准确写法，或者输入了常见变体。 模糊匹配（Fuzzy matching）允许你在查询时匹配拼写接近的词项，并把“更接近”的结果排在前面或作为兜底补充。 编辑距离与 fuzziness # 模糊匹配常以“编辑距离”定义两个词的相似度：把一个词变成另一个词需要的最少单字符编辑次数。 一次编辑可能是： 替换：fox → box 插入：sic → sick 删除：black → back 相邻换位：star → tsar fuzziness 参数用来限制允许的最大编辑距离： 0：不允许编辑（精确） 1：允许一次编辑（多数拼写错误属于这一档） 2：更宽松，但更容易引入噪声、性能也更差 AUTO：根据词长自动选择（短词更严格，长词更宽松） 实践上，若你发现 AUTO 返回的结果“太松”，把 fuzziness 设为 1 往往能得到更好的质量与性能平衡。 fuzzy 查询：term 级别的模糊等价 # fuzzy 查询可以看作是 term 查询的模糊版本。它不会对输入做分析（不分词、不归一化），而是直接在词典上找“编辑距离足够近”的候选词项： GET /my_index/_search { "query": { "fuzzy": { "text": { "value": "surprize", "fuzziness": 1 } } } } 性能保护：prefix_length 与 max_expansions # 模糊查询本质上要在词典里做扩展，候选词项越多，越可能拖垮性能。权威指南给出的两个重要“刹车”：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/pattern-capture/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/pattern-capture/Pattern Capture 分词过滤器 # pattern_capture 分词过滤器是一种功能强大的过滤器，它使用正则表达式根据特定模式来捕获和提取文本的部分内容。当你想要提取词元的特定部分，例如电子邮件域名、话题标签或数字，并将其重新用于进一步的分析或索引编制时，这个过滤器会非常有用。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # 捕获匹配分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 patterns 必需 字符串数组 用于捕获文本部分的正则表达式数组。 preserve_original 必需 布尔值 是否在输出中保留原始词元。默认值为 true。 参考样例 # 以下示例请求创建了一个名为 email_index 的新索引，并配置了一个带有捕获匹配过滤器的分词器，以便从电子邮件地址中提取本地部分和域名。 PUT /email_index { "settings": { "analysis": { "filter": { "email_pattern_capture": { "type": "pattern_capture", "preserve_original": true, "patterns": [ "^([^@]+)", "@(.+)$" ] } }, "analyzer": { "email_analyzer": { "tokenizer": "uax_url_email", "filter": [ "email_pattern_capture", "lowercase" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/pattern-replace/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/pattern-replace/Pattern Replace 分词过滤器 # pattern_replace 分词过滤器允许您使用正则表达式来修改词元。此过滤器会将词元中的模式替换为指定的值，这使您在对词元进行索引之前，能够灵活地转换或规范化词元。当您在分析过程中需要清理或规范文本时，该过滤器尤其有用。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参数说明 # 匹配替换分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 pattern 必需 字符串 一个正则表达式模式，用于匹配需要被替换的文本。 all 可选 布尔值 是否替换所有匹配的模式。如果为 false，则仅替换第一个匹配项。默认值为 true。 replacement 可选 字符串 用于替换匹配模式的字符串。默认值为空字符串。 参考样例 # 以下示例请求创建了一个名为 text_index 的新索引，并配置了一个带有匹配替换过滤器的分词器，用于将包含数字的词元替换为字符串 [NUM]： PUT /text_index { "settings": { "analysis": { "filter": { "number_replace_filter": { "type": "pattern_replace", "pattern": "\\d+", "replacement": "[NUM]" } }, "analyzer": { "number_analyzer": { "tokenizer": "standard", "filter": [ "lowercase", "number_replace_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/proximity-matching/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/proximity-matching/邻近匹配 # 标准全文检索可以把字段视为“一袋词”（bag of words）：match 能告诉你这些词是否存在，但无法表达词与词之间的顺序与距离。这会导致一些明显不合理的匹配： Sue ate the alligator. The alligator ate Sue. Sue never goes anywhere without her alligator-skin purse. 搜索 sue alligator 时，上面三句都会被 match 命中，但它们的语义完全不同。邻近匹配（proximity matching）并不能“理解语义”，但它能利用位置信息来判断词项是否相邻、是否接近，从而让结果更符合直觉。 match_phrase：短语匹配 # match_phrase 是最常用的位置敏感查询：要求词项按顺序出现，并且位置相邻。 GET /my_index/_search { "query": { "match_phrase": { "title": "quick brown fox" } } } 它的核心逻辑是：查询字符串先被分析为词项列表，然后只保留那些同时包含全部词项，且词项位置关系一致的文档。 词项位置（position）从哪来？ # 分词不仅会产出 tokens，还会产出 position。你可以用 _analyze 观察： GET /_analyze { "analyzer": "standard", "text": "Quick brown fox" } 典型输出会包含 position（示意）：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/jieba-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/jieba-search/Jieba Search 分词器 # jieba_search 分词器是 analysis-jieba 插件 提供的搜索模式分词器。它在精确分词的基础上对长词不做额外切分，适合搜索时使用。 前提条件 # bin/easysearch-plugin install analysis-jieba 与 jieba_index 的对比 # 分词器 模式 以"中华人民共和国"为例 适用场景 jieba_search 精确模式 中华人民共和国 搜索时 jieba_index 索引模式 中华、华人、人民、共和、共和国、中华人民共和国 索引时 使用示例 # 索引/搜索搭配 # PUT my-jieba-index { "settings": { "analysis": { "analyzer": { "jieba_idx": { "type": "custom", "tokenizer": "jieba_index" }, "jieba_srch": { "type": "custom", "tokenizer": "jieba_search" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "jieba_idx", "search_analyzer": "jieba_srch" } } } } 测试分词 # GET /_analyze { "tokenizer": "jieba_search", "text": "中华人民共和国国歌" } 相关链接 # Jieba Index 分词器 — 索引模式 文本分析https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/split/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/split/分割处理器 # split 处理器用于根据指定的分隔符将字符串字段拆分为一个子字符串数组。 以下是为 split 处理器提供的语法： { "split": { "field": "field_to_split", "separator": "<delimiter>", "target_field": "split_field" } } 配置参数 # 下表列出了 split 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要拆分的字符串的字段。 separator 必填 字符串分割时使用的分隔符。这可以是一个正则表达式模式。 preserve_trailing 可选 如果设置为 true ，则保留结果数组中的空尾字段（例如， '' ）。如果设置为 false ，则从结果数组中删除空尾字段。默认为 false 。 target_field 可选 存储子字符串数组的字段。如果没有指定，则字段将就地更新。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true ，则处理器忽略字段中的缺失值，并保持 target_field 不变。默认为 false 。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/multi-field-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/multi-field-search/多字段搜索 # 真实的搜索很少是单个字段的 match。更常见的是： 同一条查询要在多个字段上执行（标题/正文/标签） 不同的查询片段要映射到不同字段（标题 vs 作者） 多个字段共同组成一个“实体”（姓名、地址），每个词可能落在不同字段里 难点在于：匹配结果怎么合并、相关性怎么计算。这一页会按权威指南的三种典型场景，给出可直接落地的查询结构。 场景 1：多字符串、多字段（你知道每个词该搜哪个字段） # 例如你要找作者 Leo Tolstoy 写的《War and Peace》： GET /_search { "query": { "bool": { "should": [ { "match": { "title": "War and Peace" } }, { "match": { "author": "Leo Tolstoy" } } ] } } } bool 查询采用“匹配越多越好”的策略：匹配到更多 should 子句的文档会得到更高 _score。 语句优先级：用 boost 做权重分配 # 当有些子句更重要（例如标题、作者比译者更重要），可以给关键子句加 boost： GET /_search { "query": { "bool": { "should": [ { "match": { "title": { "query": "War and Peace", "boost": 2 } } }, { "match": { "author": { "query": "Leo Tolstoy", "boost": 2 } } }, { "bool": { "should": [ { "match": { "translator": "Constance Garnett" } }, { "match": { "translator": "Louise Maude" } } ] } } ] } } } 经验：boost 往往不需要非常大。通常从 1~10 试起，配合真实样本不断调试更可靠。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/dictionary-decompounder/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/dictionary-decompounder/Dictionary Decompounder 分词过滤器 # dictionary_decompounder 分词过滤器用于根据预定义的词典将复合词拆分为其组成部分。该过滤器对于德语、荷兰语或芬兰语等复合词较为常见的语言特别有用，因为将复合词拆分可以提高搜索的相关性。dictionary_decompounder 分词过滤器会根据已知词列表判断每个词元（单词）是否可以拆分为更小的词元。如果该词元可以拆分为已知单词，过滤器就会为该词元生成子词元。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # 词典复合词分词过滤器具有以下参数： 参数 必需/可选 数据类型 描述 word_list 除非配置了 word_list_path，否则为必需 字符串数组 过滤器用于拆分复合词的单词词典。 word_list_path 除非配置了 word_list，否则为必需 字符串 包含词典单词的文本文件的文件路径。可以接受绝对路径或相对于配置(config)目录的相对路径。词典文件必须采用 UTF-8 编码，且每个单词必须单独占一行。 min_word_size 可选 整数 会被考虑进行拆分的整个复合词的最小长度。如果复合词短于该值，则不会进行拆分。默认值为 5。 min_subword_size 可选 整数 任何子词的最小长度。如果子词短于该值，则不会包含在输出中。默认值为 2。 max_subword_size 可选 整数 任何子词的最大长度。如果子词长于该值，则不会包含在输出中。默认值为 15。 only_longest_match 可选 布尔值 如果设置为 true，则仅返回最长匹配的子词。默认值为 false。 参考样例 # 以下示例请求创建了一个名为 decompound_example 的新索引，并配置了一个带有词典复合词过滤器的分词器：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/rollup/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/rollup/数据汇总 # 先读概述：如果您尚未了解 Rollup 的优势与应用场景，建议先阅读 数据生命周期 中的 Rollup 部分。 数据汇总或上卷（Rollup），对于时序场景类的数据，往往会有大量的非常详细的聚合指标，随着时间的图推移，存储将持续增长。汇总功能可以将旧的、细粒度的数据汇总为粗粒度格式以进行长期存储。通过将数据汇总到一个单一的文档中，可以大大降低历史数据的存储成本。 Easysearch 的 rollup 具备一些独特的优势，可以自动对 rollup 索引进行滚动而不用依赖其他 API 去单独设置，并且在进行聚合查询时支持直接搜索原始索引，做到了对业务端的搜索代码完全兼容，从而对用户无感知。 支持的聚合类型 # 对数值类型字段支持的聚合 avg sum max min value_count percentiles 对 keyword 类型字段提供 terms 聚合。 对 date 类型字段 除了 date_histogram 聚合，还支持 date_range 聚合。(v1.10.0) 查询 rollup 数据时，增加支持 Filter aggregation，某些场景可以用来替代 query 过滤数据。(v1.10.1) 增加针对个别字段自定义 special_metrics 指标的配置项。 (v1.10.1) 增加支持 Bucket sort aggregation。 (v1.10.1) 混合查询原始索引和 rollup 索引时，返回的 response 里增加了 origin 参数，表示包含 rollup 数据。(v1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/permissions/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/security/access-control/permissions/权限列表 # 此页面是可用权限的完整列表。每个权限控制对数据类型或 API 的访问。 集群权限 # 核心集群权限 # cluster:admin/component_template/delete cluster:admin/component_template/get cluster:admin/component_template/put cluster:admin/indices/dangling/delete cluster:admin/indices/dangling/find cluster:admin/indices/dangling/import cluster:admin/indices/dangling/list cluster:admin/ingest/pipeline/delete cluster:admin/ingest/pipeline/get cluster:admin/ingest/pipeline/put cluster:admin/ingest/pipeline/simulate cluster:admin/ingest/processor/grok/get cluster:admin/nodes/reload_secure_settings cluster:admin/reindex/rethrottle cluster:admin/repository/_cleanup cluster:admin/repository/delete cluster:admin/repository/get cluster:admin/repository/put cluster:admin/repository/verify cluster:admin/reroute cluster:admin/script/delete cluster:admin/script/get cluster:admin/script/put cluster:admin/script_context/get cluster:admin/script_language/get cluster:admin/scripts/painless/context cluster:admin/scripts/painless/execute cluster:admin/search/pipeline/delete cluster:admin/search/pipeline/get cluster:admin/search/pipeline/put cluster:admin/settings/update cluster:admin/snapshot/clone cluster:admin/snapshot/create cluster:admin/snapshot/delete cluster:admin/snapshot/get cluster:admin/snapshot/restore cluster:admin/snapshot/status cluster:admin/snapshot/status* cluster:admin/tasks/cancel cluster:admin/tasks/test cluster:admin/tasks/testunblock cluster:admin/voting_config/add_exclusions cluster:admin/voting_config/clear_exclusions cluster:monitor/allocation/explain cluster:monitor/health cluster:monitor/main cluster:monitor/nodes/hot_threads cluster:monitor/nodes/info cluster:monitor/nodes/liveness cluster:monitor/nodes/stats cluster:monitor/nodes/usage cluster:monitor/remote/info cluster:monitor/state cluster:monitor/stats cluster:monitor/task cluster:monitor/task/get cluster:monitor/tasks/lists 异步搜索权限 # cluster:admin/async_search/delete cluster:admin/async_search/get cluster:admin/async_search/stats cluster:admin/async_search/submit 安全管理权限 # cluster:admin/security/config/update cluster:admin/security/whoami ILM 索引生命周期管理权限 # cluster:admin/ilm/managedindex/add cluster:admin/ilm/managedindex/change cluster:admin/ilm/managedindex/explain cluster:admin/ilm/managedindex/remove cluster:admin/ilm/managedindex/retry cluster:admin/ilm/policy/delete cluster:admin/ilm/policy/get cluster:admin/ilm/policy/search cluster:admin/ilm/policy/write cluster:admin/ilm/update/managedindexmetadata Rollup 权限 # cluster:admin/rollup/delete cluster:admin/rollup/explain cluster:admin/rollup/get cluster:admin/rollup/index cluster:admin/rollup/mapping/update cluster:admin/rollup/search cluster:admin/rollup/start cluster:admin/rollup/stop cluster:admin/rollup/update Transform 权限 # cluster:admin/transform/delete cluster:admin/transform/explain cluster:admin/transform/get cluster:admin/transform/get_transforms cluster:admin/transform/index cluster:admin/transform/preview cluster:admin/transform/start cluster:admin/transform/stop 快照管理权限 # cluster:admin/snapshot_management/policy/delete cluster:admin/snapshot_management/policy/explain cluster:admin/snapshot_management/policy/get cluster:admin/snapshot_management/policy/search cluster:admin/snapshot_management/policy/start cluster:admin/snapshot_management/policy/stop cluster:admin/snapshot_management/policy/write 通知权限 # cluster:admin/easysearch/notifications/channels/get cluster:admin/easysearch/notifications/configs/create cluster:admin/easysearch/notifications/configs/delete cluster:admin/easysearch/notifications/configs/get cluster:admin/easysearch/notifications/configs/update cluster:admin/easysearch/notifications/feature/publish cluster:admin/easysearch/notifications/feature/send cluster:admin/easysearch/notifications/features 跨集群复制权限 # cluster:admin/plugins/replication/autofollow cluster:admin/plugins/replication/autofollow/update cluster:indices/admin/replication cluster:indices/shards/replication 插件权限 # cluster:admin/ai/embed cluster:admin/ik/dictionary/reload cluster:admin/model_provider/get cluster:admin/model_provider/search cluster:admin/model_provider/write cluster:admin/model_provider/update cluster:admin/model_provider/delete cluster:admin/rules/get cluster:admin/rules/list cluster:admin/rules/import cluster:admin/rules/references cluster:admin/rules/compile cluster:admin/rules/simulate cluster:admin/rules/delete cluster:admin/rules/compile/internal cluster:admin/rules/delete/internal cluster:admin/rules/sync/block 索引权限 # 核心索引管理权限 # indices:admin/aliases indices:admin/aliases/exists indices:admin/aliases/get indices:admin/analyze indices:admin/analyze_space_usage indices:admin/auto_create indices:admin/block/add indices:admin/cache/clear indices:admin/close indices:admin/create indices:admin/data_stream/create indices:admin/data_stream/delete indices:admin/data_stream/get indices:admin/delete indices:admin/exists indices:admin/flush indices:admin/flush* indices:admin/forcemerge indices:admin/get indices:admin/index_template/delete indices:admin/index_template/get indices:admin/index_template/put indices:admin/index_template/simulate indices:admin/index_template/simulate_index indices:admin/mapping/auto_put indices:admin/mapping/put indices:admin/mappings/fields/get indices:admin/mappings/fields/get* indices:admin/mappings/get indices:admin/open indices:admin/refresh indices:admin/refresh* indices:admin/refresh_search_analyzers indices:admin/reload indices:admin/resize indices:admin/resolve/index indices:admin/rollover indices:admin/seq_no/global_checkpoint_sync indices:admin/settings/update indices:admin/shards/search_shards indices:admin/shrink indices:admin/synced_flush indices:admin/template/delete indices:admin/template/get indices:admin/template/put indices:admin/types/exists indices:admin/upgrade indices:admin/validate/query 索引数据读取权限 # indices:data/read/async_search indices:data/read/explain indices:data/read/field_caps indices:data/read/field_caps* indices:data/read/get indices:data/read/mget indices:data/read/mget* indices:data/read/msearch indices:data/read/msearch/template indices:data/read/mtv indices:data/read/mtv* indices:data/read/point_in_time/create indices:data/read/point_in_time/delete indices:data/read/point_in_time/readall indices:data/read/rank_eval indices:data/read/rollup/search indices:data/read/scroll indices:data/read/scroll/clear indices:data/read/search indices:data/read/search* indices:data/read/search/template indices:data/read/tv 索引数据写入权限 # indices:data/write/bulk indices:data/write/bulk* indices:data/write/delete indices:data/write/delete/byquery indices:data/write/index indices:data/write/reindex indices:data/write/update indices:data/write/update/byquery 索引监控权限 # indices:monitor/data_stream/stats indices:monitor/field_usage_stats indices:monitor/recovery indices:monitor/segments indices:monitor/settings/get indices:monitor/shard_stores indices:monitor/stats indices:monitor/upgrade ILM 索引级别权限 # indices:admin/ilm/managedindex 跨集群复制索引权限 # indices:admin/plugins/replication/autofollow/stats indices:admin/plugins/replication/follower/stats indices:admin/plugins/replication/index/all-shards indices:admin/plugins/replication/index/pause indices:admin/plugins/replication/index/resume indices:admin/plugins/replication/index/setup/validate indices:admin/plugins/replication/index/start indices:admin/plugins/replication/index/stats indices:admin/plugins/replication/index/status_check indices:admin/plugins/replication/index/stop indices:admin/plugins/replication/index/update indices:admin/plugins/replication/index/update_metadata indices:admin/plugins/replication/resources/release indices:admin/replication/index/all_status indices:data/read/plugins/replication/changes indices:data/read/plugins/replication/file_chunk indices:data/read/plugins/replication/file_metadata indices:data/write/plugins/replication/changes 权限集合 # 为了提高权限设置的效率，我们对系统权限进行自定义管理，从而快速批量选择一组相关的权限，而不是分别选择单个权限，为了方便，系统内置了若干权限集合。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/collapse/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/collapse/结果折叠 # 结果折叠（Field Collapsing）允许你按某个字段的值对搜索结果进行分组去重，每组只返回最相关的一条（或通过 inner_hits 展开多条）。常用于： 商品搜索：同一品牌/店铺只展示最相关的一个商品 新闻搜索：同一来源的新闻只展示一条 日志分析：按主机名折叠，每台机器只显示最新的一条 基础用法 # GET products/_search { "query": { "match": { "title": "手机" } }, "collapse": { "field": "brand.keyword" }, "sort": [{ "_score": "desc" }] } 每个 brand.keyword 值只返回分数最高的一条文档。 字段要求：collapse 字段必须是 keyword 或数值类型，且必须启用 doc_values。 参数说明 # 参数 类型 默认值 说明 field String 必填 用于折叠的字段名（keyword 或数值类型，需有 doc_values） inner_hits Object 或 Array 空 展开折叠组，返回组内的多条文档 max_concurrent_group_searches Integer 0（不限制） 内部 inner_hits 请求的最大并发数 使用 inner_hits 展开 # 默认每组只返回一条文档。通过 inner_hits 可以展开每组，返回组内的 Top-N 文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/jieba-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/jieba-index/Jieba Index 分词器 # jieba_index 分词器是 analysis-jieba 插件 提供的索引模式分词器。它在精确分词的基础上对长词进行二次切分，生成更多子词项，适合索引时使用以最大化召回率。 前提条件 # bin/easysearch-plugin install analysis-jieba 分词效果 # 以"中华人民共和国国歌"为例： 分词器 输出 jieba_search 中华人民共和国、国歌 jieba_index 中华、华人、人民、共和、共和国、中华人民共和国、国歌 使用示例 # 基本用法 # PUT my-jieba-index { "settings": { "analysis": { "analyzer": { "jieba_idx": { "type": "custom", "tokenizer": "jieba_index" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "jieba_idx", "search_analyzer": "jieba_srch" } } } } 测试分词 # GET /_analyze { "tokenizer": "jieba_index", "text": "中华人民共和国国歌" } 最佳实践 # 场景 分词器 索引时 jieba_index（最大化召回） 搜索时 jieba_search（精确匹配） 相关链接 # Jieba Search 分词器 — 搜索模式 文本分析https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/restful-query-dsl/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/restful-query-dsl/RESTful 与 Query DSL # Easysearch 通过 RESTful API 提供所有功能，使用 JSON 格式的 Query DSL 描述查询逻辑。理解这两个基础概念，是使用 Easysearch 的第一步。 RESTful API 约定 # Easysearch 的所有操作都通过 HTTP 请求完成，遵循 RESTful 风格： HTTP 方法 含义 示例 GET 读取 GET /my-index/_search PUT 创建或全量更新 PUT /my-index POST 创建或部分更新 POST /my-index/_doc DELETE 删除 DELETE /my-index 请求结构 # 一个典型的 Easysearch 请求由三部分组成：https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/vector-fields/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/vector-fields/向量字段建模 # 概述 # 向量字段是实现语义搜索（向量/kNN 搜索）的基础设施。本指南覆盖 Easysearch 中向量字段的设计原则、存储优化、性能权衡，帮助你做出合理的架构决策。 核心出发点： 向量字段的设计直接影响三个维度——存储成本、索引性能、查询效率。在业务约束下找到最优平衡是关键。 1. 文档模型设计 # 1.1 基本模式：混合字段设计 # 在支持语义搜索的系统中，典型文档包含三类字段： { "_id": "doc-001", "metadata": { "title": "Easysearch 向量搜索最佳实践", "created_at": "2026-02-13", "category": "AI搜索" }, "content": "完整的正文内容……", "embedding": [0.124, -0.031, 0.092, ...], "snippet": "用于快速展示的摘要" } 字段分工： 字段类型 典型字段名 数据类型 用途 存储开销 文本字段 title, content text BM25 全文搜索、分面过滤 低 元数据字段 created_at, category keyword, date 精确过滤、排序、聚合 低 向量字段 embedding, vector dense_vector kNN 语义相似度查询 高 展示字段 snippet, summary text（不分词） 快速返回、避免重查询 中 设计要点：https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/vector-fields/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/vector-fields/向量字段建模指南 # 概述 # 向量字段是实现语义搜索（向量/kNN 搜索）的基础设施。本指南覆盖 Easysearch 中向量字段的设计原则、存储优化、性能权衡，帮助你做出合理的架构决策。 核心出发点： 向量字段的设计直接影响三个维度——存储成本、索引性能、查询效率。在业务约束下找到最优平衡是关键。 1. 文档模型设计 # 1.1 基本模式：混合字段设计 # 在支持语义搜索的系统中，典型文档包含三类字段： { "_id": "doc-001", "metadata": { "title": "Easysearch 向量搜索最佳实践", "created_at": "2026-02-13", "category": "AI搜索" }, "content": "完整的正文内容……", "embedding": [0.124, -0.031, 0.092, ...], "snippet": "用于快速展示的摘要" } 字段分工： 字段类型 典型字段名 数据类型 用途 存储开销 文本字段 title, content text BM25 全文搜索、分面过滤 低 元数据字段 created_at, category keyword, date 精确过滤、排序、聚合 低 向量字段 embedding, vector dense_vector kNN 语义相似度查询 高 展示字段 snippet, summary text（不分词） 快速返回、避免重查询 中 设计要点：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/multiplexer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/multiplexer/Multiplexer 分词过滤器 # multiplexer 分词过滤器允许你通过应用不同的过滤器来创建同一词元的多个版本。当你想要以多种方式分析同一个词元时，这非常有用。例如，你可能希望使用不同的词干提取、同义词或 n-gram 过滤器来分析一个词元，并将所有生成的词元一起使用。这个分词过滤器的工作方式是复制分词流，并对每个副本应用不同的过滤器。 注意：multiplexer 分词过滤器会从分词流中移除重复的词元。 限制：multiplexer 分词过滤器不支持 synonym 过滤器、synonym_graph 分词过滤器或 shingle 分词过滤器，因为这些过滤器不仅需要分析当前词元，还需要分析后续的词元，以便正确确定如何转换输入内容。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # 多路复用分词过滤器可以使用以下参数进行配置。 参数 必需/可选 数据类型 描述 filters 可选 字符串列表 要应用于分词流每个副本的分词过滤器的逗号分隔列表。默认值为空列表。 preserve_original 可选 布尔值 是否将原始词元保留为输出之一。默认值为 true。 参考样例 # 以下示例请求创建了一个名为 multiplexer_index 的新索引，并配置了一个带有多路复用过滤器的分词器： PUT /multiplexer_index { "settings": { "analysis": { "filter": { "english_stemmer": { "type": "stemmer", "name": "english" }, "synonym_filter": { "type": "synonym", "synonyms": [ "quick,fast" ] }, "multiplexer_filter": { "type": "multiplexer", "filters": ["english_stemmer", "synonym_filter"], "preserve_original": true } }, "analyzer": { "multiplexer_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "multiplexer_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/common-grams/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/common-grams/Common Grams 分词过滤器 # common_grams 分词过滤器通过保留文本中常见的短语（常用词组）来提高搜索的相关性。当处理某些语言或数据集时，特定的单词组合经常作为一个整体出现，如果将它们当作单独的词元处理，可能会影响搜索的相关性，此时该过滤器就非常有用。如果输入字符串中常用词，这个分词过滤器会同时生成它们的一元词组（单个词）和二元词组（两个词的组合）。 使用这个分词过滤器可以保持常用短语的完整性，从而提高搜索的相关性。这有助于更准确地匹配查询内容，尤其是对于频繁出现的单词组合。它还能通过减少不相关的匹配结果来提高搜索的精度。 相关指南（先读这些） # 文本分析：停用词 邻近匹配 文本分析：规范化 使用此过滤器时，你必须谨慎选择并维护常用词(common_words)列表。 参数说明 # 常用词组分词过滤器可通过以下参数进行配置： 参数 必需/可选 数据类型 描述 common_words 必需 字符串列表 一个应被视为常用词词组的单词列表。如果 common_words 参数是一个空列表，common_grams 分词过滤器将成为一个无操作过滤器，即它根本不会修改输入的词元。 ignore_case 可选 布尔值 指示过滤器在匹配常用词时是否应忽略大小写差异。默认值为 false。 query_mode 可选 布尔值 当设置为 true 时，应用以下规则： - 从 common_words 生成的一元词组（单个词）不包含在输出中。 - 非常用词后跟常用词形成的二元词组会保留在输出中。 - 如果非常用词的一元词组后面紧接着一个常用词，则该一元词组会被排除。 - 如果非常用词出现在文本末尾且前面是一个常用词，其一元词组不包含在输出中。 参考样例 # 以下示例请求创建了一个名为 my_common_grams_index 的新索引，并配置了一个使用常用词组（common_grams）过滤器的分析器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/fingerprint/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/fingerprint/Fingerprint 分词过滤器 # fingerprint 分词过滤器用于对文本进行标准化和去重处理。当文本处理的唯一性或者一致性至关重要时，这个过滤器特别有用。fingerprint 分词过滤器通过以下步骤处理文本以实现这一目的： 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 小写转换：将所有文本转换为小写。 分词：把文本拆分成词元。 排序：按字母顺序排列这些词元。 去重：消除重复的词元。 合并词元：将这些词元合并成一个字符串，通常使用空格或其他指定的分隔符进行连接。 参数说明 # 指纹分词过滤器可以使用以下两个参数进行配置。 参数 必需/可选 数据类型 描述 max_output_size 可选 整数 限制生成的指纹字符串的长度。如果拼接后的字符串超过了 max_output_size，过滤器将不会产生任何输出，从而得到一个空词元。默认值是 255 separator 可选 字符串 定义在词元排序和去重后，用于将词元连接成单个字符串。默认是空格（" "）。 参考样例 # 以下示例请求创建了一个名为 my_index 的新索引，并配置了一个带有指纹分词过滤器的分词器： PUT /my_index { "settings": { "analysis": { "filter": { "my_fingerprint": { "type": "fingerprint", "max_output_size": 200, "separator": "-" } }, "analyzer": { "my_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "my_fingerprint" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/condition/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/condition/Condition 分词过滤器 # condition 分词过滤器是一种特殊类型的过滤器，它允许你根据特定标准有条件地应用其他分词过滤器。这使得在文本分析过程中，你能更精准地控制何时应用特定的分词过滤器。你可以配置多个过滤器，并且只有当满足你定义的条件时，这些过滤器才会被应用。该分词过滤器在进行特定语言处理和特殊字符处理时非常有用。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参数说明 # 要使用条件分词过滤器，必须配置两个参数，具体如下： 参数 必需/可选 数据类型 描述 filter 必需 数组 当满足由 script 参数定义的指定条件时，指定应对词元应用哪个分词过滤器。 script 必需 对象 配置一个内联脚本，该脚本定义了要应用 filter 参数中指定的过滤器所需满足的条件（仅接受内联脚本）。 参考样例 # 以下示例请求创建了一个名为 my_conditional_index 的新索引，并配置了一个带有条件过滤器的分词器。该过滤器会对任何包含字符序列 “um” 的词元应用小写（lowercase）字母过滤器。 PUT /my_conditional_index { "settings": { "analysis": { "filter": { "my_conditional_filter": { "type": "condition", "filter": ["lowercase"], "script": { "source": "token.https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-management/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-management/索引的增删改查 # 索引（Index）是 Easysearch 的"逻辑命名空间"，但它背后是不可变段（segment）与固定主分片数等一系列硬约束。结果就是：很多你以为"改一下就行"的变更，最后都会走到"建新索引 + 迁移数据"的路上。 本页涵盖索引的完整生命周期操作：创建、查看、修改设置/映射、删除，以及重建索引的常见套路。 创建索引：把关键设置提前定好 # 你当然可以“先写一条文档让索引自动出现”，但在生产环境，更推荐显式创建索引，把关键设置、映射、分析器在写入前一次性确定： PUT /my_index { "settings": { "number_of_shards": 3, "number_of_replicas": 1 }, "mappings": { "properties": { "title": { "type": "text" }, "tags": { "type": "keyword" } } } } 你需要提前考虑的常见项： 分片与副本：见 索引设置 映射与字段类型：见 Mapping 基础 分析器：见 Mapping 与文本分析 索引命名限制 # Easysearch 索引命名规则： 所有字母必须小写 索引名称不能以 _（下划线）或 -（连字符）开头 索引名称不能包含空格、逗号或以下字符：: " * + / \ | ? # > < 是否允许“自动创建索引”？ # 对日志类场景，“按天/按月写到新索引”很常见，此时自动创建索引会很省事；但对强管控业务，自动创建索引可能变成“拼写错误导致创建一堆垃圾索引”的事故源头。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/classic/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/classic/Classic 分词过滤器 # classic 分词过滤器的主要功能是与 classic 分词器配合使用。它通过应用以下常见的转换操作来处理词元，这些操作有助于文本分析和搜索： 移除所有格词尾，例如 “’s”。比如，“John’s” 会变为 “John”。 从首字母缩略词中移除句点。例如，“D.A.R.P.A.” 会变为 “DARPA”。 相关指南（先读这些） # 文本分析：规范化 文本分析：识别词元 参考样例 # 以下示例请求创建了一个名为 custom_classic_filter 的新索引，并配置了一个使用经典分词过滤器的分词器。 PUT /custom_classic_filter { "settings": { "analysis": { "analyzer": { "custom_classic": { "type": "custom", "tokenizer": "classic", "filter": ["classic"] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元： POST /custom_classic_filter/_analyze { "analyzer": "custom_classic", "text": "John's co-operate was excellent." } 返回内容包含产生的词元https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/trim/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/trim/裁剪处理器 # trim 处理器用于从指定的字段中删除前导和尾随空白字符。 以下是为 trim 处理器提供的语法： { "trim": { "field": "field_to_trim", "target_field": "trimmed_field" } } 配置参数 # 下表列出了 trim 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要修剪文本的字段。 target_field 必填 存储被截断文本的字段。如果未指定，则字段将就地更新。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true ，则处理器忽略字段中的缺失值，并保持 target_field 不变。默认为 false 。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/predicate-token-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/predicate-token-filter/Predicate Token Filter 分词过滤器 # predicate_token_filter 分词过滤器会根据自定义脚本中定义的条件来评估词元是应该保留还是丢弃。词元的评估是在分析谓词上下文中进行的。此过滤器仅支持内联 Painless 脚本。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # 谓词分词过滤器有一个必需参数：script。该参数提供一个条件，用于评估词元是否应被保留。 参考样例 # 以下示例请求创建了一个名为 predicate_index 的新索引，并配置了一个带有谓词分词过滤器的分词器。该过滤器指定仅输出长度超过 7 个字符的词元。 PUT /predicate_index { "settings": { "analysis": { "filter": { "my_predicate_filter": { "type": "predicate_token_filter", "script": { "source": "token.term.length() > 7" } } }, "analyzer": { "predicate_analyzer": { "tokenizer": "standard", "filter": [ "lowercase", "my_predicate_filter" ] } } } } } 产生的词元 # 使用以下请求来检查使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/uppercase/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/uppercase/大写处理器 # uppercase 处理器将特定字段中的所有文本转换为大写字母。 语法 # 以下是为 uppercase 处理器提供的语法： { "uppercase": { "field": "field_name" } } 配置参数 # 下表列出了 uppercase 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要附加数据的字段名称。支持模板使用。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 ignore_missing 可选 指定处理器是否应忽略不包含指定字段的文档。如果设置为 true ，则处理器在字段不存在或为 null 时不会修改文档。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 target_field 可选 要存储解析数据的字段名称。默认为 field 。默认情况下， field 将就地更新。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/pinyin/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/pinyin/Pinyin 分词器 # pinyin 分词器来自 analysis-pinyin 插件，将中文文本直接转换为拼音词元。与 pinyin 词元过滤器不同，分词器在分词阶段就完成拼音转换。 前提条件 # bin/easysearch-plugin install analysis-pinyin 分词器 vs 过滤器 # 组件 说明 适用场景 pinyin 分词器 直接将整段文本转拼音并分词 纯拼音索引 pinyin 词元过滤器 在已有分词结果上转拼音 需要保留原始中文词元 使用示例 # 基本用法 # PUT my-pinyin-index { "settings": { "analysis": { "analyzer": { "pinyin_analyzer": { "type": "custom", "tokenizer": "pinyin", "filter": ["lowercase"] } } } }, "mappings": { "properties": { "name": { "type": "text", "analyzer": "pinyin_analyzer" } } } } 测试分词 # GET /_analyze { "tokenizer": "pinyin", "text": "中华人民共和国" } 参数 # 分词器支持与 pinyin 词元过滤器相同的参数：https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/ai-search-architecture/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/ai-search-architecture/AI 搜索与向量检索架构实践 # 本页从整体架构的角度，讨论 Easysearch 在 AI/语义搜索系统中的位置： 如何规划“全文 + 向量”的多路召回 如何利用 Easysearch 做向量检索与文档存储 如何与上游模型服务、下游应用/LLM 集成 详细的向量字段与 kNN API 参数，请参考 Mapping 与 Reference 中的相关章节，本页重点放在“怎么搭这条链路”。 1. 一条典型的 AI 搜索链路长什么样？ # 可以把 AI 搜索拆成几段： 向量生产：由模型服务（自研或第三方）把文本/图片等转换成向量 向量与文档存储：在 Easysearch 里存放文档及其 Embedding 多路召回： 全文召回：BM25 等传统检索 向量召回：基于 kNN 的相似度检索 重排与融合： 按业务需要对多路召回结果做打分融合或模型重排 应用消费： 直接给用户展示 作为上下文提供给问答系统或大模型 Easysearch 重点负责第 2～4 段中的“存储 + 检索”能力。 2. 全文 + 向量：多路召回的常见拆法 # 结合 Easysearch，比较常见的做法有：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/api-suggestions/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/api-suggestions/API 智能提示 # 操作步骤 # 进入开发工具页面：在左侧导航栏点击「开发工具」，进入开发工具编辑页。 触发智能补全：在左侧编辑区输入请求语句时，系统将自动弹出 API 提示列表，展示匹配的接口端点、索引等选项。 选择并补全语句：在提示列表中点击目标接口（示例为 _alias），自动补全完整的请求语句。 发送请求并查看结果：补全完成后，点击运行按钮发送请求，在右侧「Result」标签页查看接口响应结果。https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/parent-child/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/parent-child/Parent-Child 建模 # Parent-Child 用来表达"两个文档属于不同类型/生命周期，但又需要建立关联"的场景。相比 nested，它更适合父文档频繁变化 / 子文档数量较多 / 生命周期不同步的情况。 什么时候考虑 Parent-Child？ # 典型场景： 主资源 + 活动记录：例如用户（父）+ 多条行为日志/评论（子） 订单 + 物流/状态变更记录：订单比较稳定，状态记录会持续追加 文档 + 标签/评分：标签或评分变化频率远高于主体文档 这类关系有几个共同特点： 父/子文档生命周期不同步（子可以频繁新增/删除，父相对稳定） 子文档数量可能很多，如果全部嵌入父文档会让父文档变得非常庞大 查询时既可能只查子文档，也可能需要"从父找子"或"从子找父" Parent-Child 与 Nested 的对比 # 可以用下面的方式做一个快速选择： 更适合 Nested 的情况： 子元素数量有限，整体更新成本可接受 查询几乎总是"连带父文档一起看" 不需要单独对"子"做大规模搜索或独立生命周期管理 更适合 Parent-Child 的情况： 子元素数量较多，且经常新增/删除 子文档需要独立参与搜索与统计 父/子有不同的更新/存储策略 Nested 更像"文档内部的结构"， Parent-Child 更像"两个文档集合之间的引用关系"。 建模要点（概念级） # 底层上，父文档与子文档都存储在同一个索引中，通过一个"连接字段"来描述父/子的关系：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/seatunnel/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/seatunnel/SeaTunnel 集成 # Apache SeaTunnel 是一款高性能分布式数据集成平台，支持海量数据的实时和离线同步。 SeaTunnel 从 2.3.4 版本开始内置了原生的 INFINI Easysearch Connector，同时支持 Source（读取）和 Sink（写入），使用 easysearch-client 专用客户端，无需依赖 Elasticsearch 兼容层。 Sink 关键特性：Exactly-Once 语义、CDC（INSERT / UPDATE / DELETE）、HTTPS/TLS。 Source 关键特性：Batch / Stream 模式、Exactly-Once、列投影、并行读取、自定义分片。 典型场景 # 场景 Source → Sink MySQL 全量/增量同步 MySQL → Easysearch 日志接入 Kafka → Easysearch 数据仓库导出 Hive / ClickHouse → Easysearch 跨集群迁移 Elasticsearch → Easysearch Easysearch 数据导出 Easysearch → ClickHouse / Kafka / 文件 CDC 实时同步 MySQL CDC → Easysearch 安装 SeaTunnel # # 下载（建议使用 2.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/urldecode/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/urldecode/URL 解码处理器 # urldecode 处理器在解码日志数据或其他文本字段中的 URL 编码字符串时非常有用。这可以使数据更易于阅读和分析，尤其是在处理包含特殊字符或空格的 URL 或查询参数时。 以下是为 urldecode 处理器提供的语法： { "urldecode": { "field": "field_to_decode", "target_field": "decoded_field" } } 配置参数 # 下表列出了 urldecode 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含要解码的 URL 编码字符串的字段。 target_field 可选 存储解码字符串的字段。如果未指定，则解码字符串将存储在原始编码字符串相同的字段中。 ignore_missing 可选 指定处理器是否应忽略不包含指定 field 的文档。如果设置为 true ，则处理器忽略 field 中的缺失值并保持 target_field 不变。默认为 false 。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/windows/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/windows/Windows 环境下使用 Easysearch # 目前，有多种方案可以在 Windows 下体验 Easysearch。 前置要求 # Windows 10 / Windows Server 2016 或更高版本 至少 4 GB 可用内存 JDK 11+（推荐 JDK 17+，2.0.3 及以上版本要求 JDK 21+）。Bundle 包已内置 JDK，无需单独安装。 方案一：Docker 安装（推荐） # 如果您的 Windows 环境上有 Docker Desktop，可以用最简单的方式启动： docker run -d --name easysearch ` -p 9200:9200 ` -e "EASYSEARCH_INITIAL_ADMIN_PASSWORD=EasysearchP@ssw0rd" ` -e "ES_JAVA_OPTS=-Xms512m -Xmx512m" ` infinilabs/easysearch:latest 详细 Docker 配置请参考 Docker 环境下使用 Easysearch。 方案二：手工安装（无 HTTPS） # 由于 Windows 环境下默认没有 OpenSSL，生成证书不太方便。如果仅用于开发测试，可以先关闭安全模块快速体验。生产环境请务必启用安全功能（参见方案三）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/python-client/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/quick-start/connect/python-client/Python 客户端快速入门 # 本页面帮助你快速跑通 Python 客户端连接 Easysearch 的完整流程。更深入的生产配置请参阅 Python 客户端详细指南。 推荐：Easysearch 官方 Python 客户端 # Easysearch 提供了官方 Python 客户端 easysearch-py，基于 Apache 2.0 协议开源。 安装 # # 从 GitHub Releases 安装（推荐） pip install https://github.com/infinilabs/easysearch-py/releases/download/v0.1.0/easysearch-0.1.0-py2.py3-none-any.whl # 如需 async/await 支持 pip install "easysearch[async] @ https://github.com/infinilabs/easysearch-py/releases/download/v0.1.0/easysearch-0.1.0-py2.py3-none-any.whl" 建立连接 # from easysearch import Easysearch es = Easysearch( ["https://localhost:9200"], http_auth=("admin", "your_password"), verify_certs=False, # 开发环境；生产环境请配置 CA 证书 timeout=30, ) # 验证连接 print(es.info()) 生产环境（使用 CA 证书） # from ssl import create_default_context context = create_default_context(cafile="/path/to/root-ca.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/russian-morphology-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/russian-morphology-analyzer/Russian Morphology 分析器 # russian_morphology 分析器专为处理俄语文本而设计。与 standard 分析器不同，它能够识别俄语词汇的形态变化，将单词还原为其词干或原型（Lemmatization）。这使得用户在搜索某个单词的特定形式（如单复数、格的变化）时，能够匹配到该单词的其他形态。 该分析器由以下分词器和分词过滤器组成： standard 分词器：去除大部分标点符号，并依据空格和其他常见分隔符对文本进行分割。 lowercase 分词过滤器：将所有词元转换为小写，以确保匹配时不区分大小写。 russian_morphology 分词过滤器：执行俄语词汇的形态分析，将不同格、性、数的单词映射到统一原型。 相关指南（先读这些） # 文本分析：词干提取 文本分析基础 安装 # 俄语形态分词器包含在Morphological Analysis插件中。此插件已包含在Easysearch的bundle包中。 analysis-morphology插件安装命令如下： bin/easysearch-plugin install analysis-morphology 参考样例 # 以下命令创建一个名为 my_morphology_index 的索引，并为 my_field 字段配置俄语形态分词器的索引： PUT /my_morphology_index { "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "russian_morphology" } } } } 配置自定义分词器 # 在生产环境中，为了兼顾性能和准确度，建议定义一个包含小写化、形态还原和停用词过滤的自定义分析器： PUT /my_custom_morphology_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "russian_morphology", "english_morphology", "my_stopwords" ] } }, "filter": { "my_stopwords": { "type": "stop", "stopwords": "_russian_" } } } } } 产生的词元 # 通过形态分析，不同的词形会被索引为相同的词元。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/clone-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/clone-index/克隆索引 # 克隆操作会将源索引的所有数据和 Mapping 完整复制到一个新索引中。 操作步骤 # 进入索引列表：在「索引」页面，找到目标索引（如 testing_index_creation）。 打开操作菜单：点击该索引行「操作」列的更多按钮（...），在下拉菜单中选择「克隆索引」。 配置克隆参数： 设置只读：弹窗提示需将源索引设为只读，点击「设为只读」完成前置操作。 填写新索引名：系统自动生成默认名（如 testing_index_creation-clone），可自定义修改。 配置副本数：按需设置副本数（默认 1）。 设置别名：可选开启，为新索引配置别名。 执行克隆：点击「确定」，系统开始克隆操作。 恢复源索引：克隆成功后，勾选「恢复源索引读写」，点击「确定」将源索引恢复为正常读写状态。 查看结果：操作完成后，索引列表中将出现新克隆的索引（如 testing_index_creation-clone），即代表克隆成功。 注意事项 # 克隆操作要求源索引处于只读状态，系统会在操作流程中自动引导设置；克隆完成后，请记得恢复源索引的读写状态，否则源索引将无法写入新数据。 克隆后的新索引与源索引具有相同的分片数和 Mapping，但它们是完全独立的索引，互不影响。 请确保集群有足够的磁盘空间容纳克隆后的新索引数据。 克隆操作的耗时与索引大小成正比，对于大索引建议在业务低峰期执行。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/delimited-payload/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/delimited-payload/Delimited Payload 分词过滤器 # delimited_payload 分词过滤器用于在分词过程中解析包含负载的词元。例如，字符串 red|1.5 fast|2.0 car|1.0 会被解析为词元 red（负载为 1.5）、fast（负载为 2.0）和 car（负载为 1.0）。当你的词元包含额外的关联数据（如权重、分数或其他数值），且你打算将这些数据用于评分或自定义查询逻辑时，这个过滤器就特别有用。该过滤器可以处理不同类型的负载，包括整数、浮点数和字符串，并将负载（额外的元数据）附加到词元上。 在文本分词时，delimited_payload 分词过滤器会解析每个词元，提取负载并将其附加到词元上。后续在查询中可以使用这个负载来影响评分、提升权重或实现其他自定义行为。 负载以 Base64 编码的字符串形式存储。默认情况下，负载不会随词元一起在查询响应中返回。若要返回负载，你必须配置额外的参数。 相关指南（先读这些） # 文本分析：识别词元 文本分析：规范化 参数说明 # 分隔式负载分词过滤器有两个参数： 参数 必需/可选 数据类型 描述 encoding 可选 字符串 指定附加到词元的负载的数据类型。这决定了在分析和查询期间如何解释负载数据。 有效值为： - float：使用 IEEE 754 格式将负载解释为 32 位浮点数（例如，car\|2.5 中的 2.5）。 - identity：将负载解释为字符序列（例如，在 user\|admin 中，admin 被解释为字符串）。 - int：将负载解释为 32 位整数（例如，priority \| 1中的1）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/pagination-and-sorting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/pagination-and-sorting/分页与排序 # 分页与排序看似简单，但在分布式搜索里细节很多。本页聚焦几种常见分页方式的适用场景，以及排序字段选择上的坑。 from/size：小页场景的首选 # from + size 适合： 页码较小（例如前几十页以内）的分页 结果集总量不特别大 特点： 使用简单，语义直观（类似 SQL 的 OFFSET/LIMIT） 页码越大，开销越大（需要跳过前面的结果） 参数说明： size：显示应该返回的结果数量，默认是 10 from：显示应该跳过的初始结果数量，默认是 0 如果每页展示 5 条结果，可以用下面方式请求得到 1 到 3 页的结果： GET /_search?size=5 GET /_search?size=5&from=5 GET /_search?size=5&from=10 深度分页的问题 # 理解为什么深度分页是有问题的，我们可以假设在一个有 5 个主分片的索引中搜索。 当我们请求结果的第一页（结果从 1 到 10），每一个分片产生前 10 的结果，并且返回给协调节点，协调节点对 50 个结果排序得到全部结果的前 10 个。 现在假设我们请求第 1000 页——结果从 10001 到 10010。所有都以相同的方式工作，除了每个分片不得不产生前 10010 个结果以外。然后协调节点对全部 50050 个结果排序，最后丢弃掉这些结果中的 50040 个结果。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/delete-backup/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/delete-backup/删除备份 # 可以删除不再需要的快照备份以释放存储空间。 操作步骤 # 进入备份管理页面：登录 Easysearch UI，在左侧导航栏点击「备份管理」，切换至「备份」标签页。 触发删除操作：在备份列表中，找到目标快照，点击「操作」列的更多按钮，选择「删除」选项。 确认删除操作：在弹出的提示窗口中，点击「确定」按钮。 验证删除结果：删除完成后，目标快照将从备份列表中移除，列表记录总数更新。 注意事项 # 删除快照前，请确认已不再需要该备份数据，删除后无法恢复。 若该快照被其他依赖（如跨集群复制）引用，删除前需确认无业务依赖，避免影响相关功能。 删除操作仅移除快照元数据，不会影响存储库中已备份的物理文件（需根据存储库配置手动清理）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/templates/delete-index-template/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/templates/delete-index-template/删除索引模板 # 当索引模板不再需要时，可以通过 UI 进行删除操作。 操作步骤 # 进入模板页面：在左侧导航栏点击「模板」，切换至「索引模板」标签页。 打开操作菜单：找到需要删除的模板，点击「操作」列的更多按钮，展开操作菜单。 选择删除操作：在菜单中点击「删除」选项，弹出删除确认提示框。 确认删除：在提示框中点击「确定」按钮，完成模板删除。 验证删除结果：删除成功后，该模板将从列表中消失，代表删除操作完成。 注意事项 # 删除模板不会影响已通过该模板创建的索引，已有索引的设置和映射保持不变。 删除操作不可撤销，如需恢复请重新创建模板。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/security/delete-role/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/security/delete-role/删除角色 # 操作步骤 # 进入角色管理页：在左侧导航栏点击「安全管理」，切换到「角色」标签页，查看现有角色列表。 打开操作菜单：找到需要删除的目标角色（如 test_role），点击该行「操作」列的更多按钮（...），在弹出菜单中选择「删除」。 确认删除操作：在弹出的确认提示框中，点击「确定」，系统将执行角色删除。 查看操作结果：操作成功后，该角色将从角色列表中移除，列表中不再显示该角色，代表删除完成。 注意事项 # 删除角色前，请确认该角色未被任何用户引用，否则相关用户将失去该角色所赋予的权限，可能导致业务访问异常。 内置系统角色不可删除，仅自定义角色支持删除操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/join-cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/join-cluster/加入已有集群 # 可以将当前节点加入到一个已有的 Easysearch 集群中。注意，已有集群的 security 设置需是打开状态，才可以被加入。 操作步骤 # 获取已有集群的准入凭证 见 如何获取集群准入凭证 进入服务管理页面：在 Agent UI 中进入「服务管理」页面，点击「加入现有集群」按钮，进入安装向导。 完成系统环境检测：系统会自动进行环境兼容性检测，确认所有检测项均通过后，点击「开始安装」。 配置集群连接信息： 输入「准入凭证」，点击「验证连接」。 验证通过后，系统将自动获取并展示集群信息。 配置节点信息： 填写节点名称、监听地址、HTTP 端口、Transport 端口，并选择节点角色。 配置 JVM 内存、数据/日志目录等参数，完成后点击「开始安装」。 等待下载与同步：系统将自动下载 Easysearch、JDK 并同步集群配置，等待进度条完成。 完成集群加入：安装完成后，页面将显示节点已成功加入集群，点击「打开 Easysearch」即可访问服务。 如何获取集群准入凭证 # 注意，已有集群的 security 设置需是打开状态，才可以获取集群准入凭证。 在服务管理页面，点击已有集群的「集群名称」进入集群概览页面 在集群概览页面，点击集群名称下方的「获取集群准入凭证」 在弹窗中，点击「复制」按钮进行复制 注意事项 # 加入集群前，请确保目标集群处于正常运行状态，且节点间网络互通。 节点的 HTTP 端口和 Transport 端口需为空闲端口，可通过「检测端口」功能进行校验。 节点角色配置需与集群规划一致，避免角色冲突影响集群可用性。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/vector-search/vector-and-semantic-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/vector-search/vector-and-semantic-search/向量搜索与语义搜索 # 向量搜索和语义搜索经常被混用，但它们面向的层次不同。理解它们的区别有助于选择正确的方案。 概念区分 # 概念 本质 Easysearch 中的对应 向量搜索 在高维空间中查找最近邻 knn_nearest_neighbors 查询 语义搜索 按"含义"而非"关键词"检索 文本 → Embedding → 向量搜索 Hybrid 检索 关键词 + 语义多路召回融合 bool（knn + match） 全文搜索 基于 BM25 的词频匹配 match、multi_match 等 关系：语义搜索 = Embedding 模型 + 向量搜索。向量搜索是底层能力，语义搜索是应用层方案。 什么时候用什么 # 场景 推荐方案 理由 用户查询关键词明确 全文搜索 BM25 对精确关键词匹配效果最好 用户用自然语言提问 语义搜索 Embedding 能捕获同义词和意图 既要关键词又要语义 Hybrid 检索 两路召回互补，综合效果最好 以图搜图、跨模态 向量搜索 不同模态映射到同一向量空间 RAG / 知识库问答 语义搜索 或 Hybrid 为 LLM 提供高质量上下文 推荐系统 向量搜索 用户/商品特征向量的近邻查找 端到端语义搜索流程 # ┌──────────────┐ 用户查询 ──────▶ │ Embedding 模型│ ──────▶ 查询向量 └──────────────┘ │ ▼ ┌─────────────────┐ │ knn_nearest_ │ │ neighbors 查询 │ └─────────────────┘ │ ▼ 按语义相似度排序的结果 写入阶段：将文本通过 Embedding 模型转为向量，连同原始字段一起写入索引 查询阶段：将用户查询通过同一模型转为向量，使用 knn_nearest_neighbors 检索 融合阶段（可选）：将向量相似度得分与 BM25 得分加权融合 Embedding 模型的接入方式参见 Embedding 服务集成。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/pinyin-first-letter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/pinyin-first-letter/Pinyin First Letter 分词器 # pinyin_first_letter 分词器将中文字符转换为拼音首字母缩写，例如 “中华人民共和国” → “zhrmghg”。适用于拼音首字母搜索场景。 需要安装 analysis-pinyin 插件。 示例 # PUT my_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "tokenizer": "pinyin_first_letter" } } } } } 相关指南 # Pinyin 分词器 Pinyin 分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/exclude-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/exclude-filter/排除过滤条件 # 排除过滤条件可以将指定条件取反，从结果中排除匹配的数据。 操作步骤 # 唤起操作菜单：在数据探索页面，找到已生效的过滤条件标签（如 _id:nYsUlJ0Bc_MPNLBvYYQh），点击该标签，弹出操作菜单。 执行排除操作：在菜单中选择「排除结果」，系统将自动反转该过滤条件的匹配逻辑。 查看生效结果： 过滤标签将同步更新为 'NOT'_id:nYsUlJ0Bc_MPNLBvYYQh，标识当前为排除逻辑； 右侧数据列表将展示不满足该条件的所有文档记录，完成排除过滤。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/create-auto-follow/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/create-auto-follow/新增自动跟随模式 # 自动跟随模式可以自动为匹配规则的新索引创建跟随者索引。 操作步骤 # 进入自动跟随模式配置页面：登录 Easysearch UI，在左侧导航栏点击「主从复制」，切换至「自动跟随模式」标签页。 打开新增自动跟随弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增自动跟随」配置窗口。 配置自动跟随信息： 填写必填项「名称」，自定义自动跟随规则标识（如示例中的 test_auto_follow）。 选择「远端集群」，从下拉框中选取已配置的远程集群（如 leader）。 填写「索引模式」，输入需要自动同步的索引匹配规则（如 product*，表示匹配所有以 product 开头的索引）。 按需填写「排除索引模式」，指定不需要同步的索引规则。 完成创建：确认配置无误后，点击「确定」按钮。 验证自动跟随效果：配置成功后，新规则将出现在自动跟随模式列表中，远端集群中匹配索引模式的新索引将自动在本地集群创建对应的跟随者索引，并开始同步数据。可在「跟随者索引」标签页查看新增的同步任务。 注意事项 # 索引模式支持通配符匹配（如 product*），可批量同步远端集群中符合规则的所有索引。 新增自动跟随规则前，需确保远端集群已完成配置，且本地集群具备 remote_cluster_client 角色权限。 自动跟随模式仅对新增的远端索引生效，已存在的索引需手动添加跟随者索引进行同步。 可通过「排除索引模式」过滤不需要同步的索引，避免无效同步操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/plugins/testing-and-validation/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/plugins/testing-and-validation/测试与验证 # 本文档聚焦 Easysearch 插件的测试与验证，包括测试基类的选择、Gradle 任务、运行态验证以及常见问题排查。插件初始化、打包安装和本地开发闭环请参考： 插件开发入门。 引入 test-framework 依赖 # Easysearch 官方提供了 test-framework 包，内置随机化测试、嵌入式节点、Hamcrest 断言等工具，所有测试基类均来自这个包。 在插件项目中添加依赖 # 若你的插件项目与 Easysearch 源码在同一 Gradle 多项目构建中，使用项目引用： dependencies { testImplementation project(':test:framework') } 若你的插件是独立项目（如从官方模板克隆），使用 Maven 坐标： dependencies { testImplementation "com.infinilabs.easysearch.test:framework:${easysearch_version}" } 同时确保 repositories 中包含 Easysearch 制品库，或将 test-framework 的 jar 发布到本地 Maven（./gradlew publishToMavenLocal）。 测试基类与选择指南 # Easysearch 提供了多个测试基类，适用于不同的测试场景。 测试基类概览 # 基类 适用场景 常见任务 启动开销 EasySearchTestCase 纯单元测试，无需启动节点 test 最低 ESSingleNodeTestCase 单节点节点内测试，验证插件加载和组件交互 通常是 test 中等 ESIntegTestCase 多节点集群级测试，验证分布式行为 通常是 internalClusterTest / icTest 较高 EasySearchRestTestCase 通过 REST API 测试 HTTP 行为 integTest / yamlRestTest 较高 如何选择测试类型？ # 单元测试是首选：大多数情况下，单元测试更易于理解、更容易复现，且不易受到与被测功能无关的代码变更影响。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/relevance/relevance-recipes/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/relevance/relevance-recipes/相关性常用策略 # 本页以"配方"的形式给出几个常见场景下的相关性策略，帮助你在默认评分的基础上做业务级调优。 通用配方：标题 + 正文 + 标签 # 适用：大多数文档检索（文章、博客、知识库等）。 思路： 使用 multi_match 将多个字段一起搜索 提高标题权重，其次是标签，再是正文 示意： { "query": { "multi_match": { "query": "搜索 引擎", "fields": [ "title^3", "tags^2", "content" ] } } } 要点： 确保字段类型合理（title/content 为 text，tags 可为 keyword 或 text+keyword） 对排序特别重要的字段，优先在 Mapping 里设计好 multi-fields 电商配方：匹配 + 业务信号 # 适用：商品搜索。 核心元素： 文本相关性：标题、品牌、类目、卖点等字段 业务信号：销量、点击率、转化率、上下架状态、库存 常见做法： 先通过 bool + multi_match 保证文本相关性 再通过字段 boost 或 function_score 将业务信号以"加分项"的形式叠加进来 注意：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/disk-encryption/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/disk-encryption/磁盘加密配置指南 # 在合规要求较高的场景（金融、政务、医疗），可能需要对 Easysearch 数据所在磁盘进行静态加密（Encryption at Rest）。 加密方案对比 # 方案 透明性 性能影响 适用场景 LUKS (dm-crypt) 完全透明 5~15% Linux 原生，推荐 eCryptfs 文件级 15~30% 不推荐（性能差） 硬件自加密 (SED) 完全透明 ~0% 硬件支持时首选 云盘加密 完全透明 ~0% 云环境推荐 LUKS 全盘加密（Linux） # 配置步骤 # # 1. 安装 cryptsetup yum install -y cryptsetup # CentOS/RHEL apt install -y cryptsetup # Ubuntu/Debian # 2.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/settings/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/settings/系统调优 # 芯片及操作系统兼容性 # 目前已在国产主流芯片及操作系统上进行了验证，分别为 openEuler、统信 UOS、麒麟、龙芯、申威、兆芯。同样也兼容 Windows、 MacOS、 CentOS、 Ubuntu、 RedHat 等常用操作系统。 Java 兼容性 # 默认情况下 Easysearch 并不包含 JDK, 推荐使用 Java 15.0.1+9 或 Java 17.0.6+10, 最低版本要求为 Java 11, 要使用不同的 Java 安装，请将 JAVA_HOME 环境变量设置为 Java 安装位置或将 JDK 软链接到 Easysearch 安装目录下取名为 jdk。 例如： #设置 JAVA_HOME 环境变量，可放入 ~/.bashrc 或 /etc/profile export JAVA_HOME=/usr/local/jdk #软链接 sudo ln -s /usr/local/jdk /data/easysearch/jdk 网络要求 # Easysearch 需要打开以下端口: 端口 模块说明 9200 REST API 9300 节点间通信 系统参数 # 要保证 Easysearch 运行在最佳状态，其所在服务器的操作系统也需要进行相应的调优，以 Linux 为例。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-settings/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-settings/索引设置（Index Settings） # 索引级别的设置直接影响写入、查询性能以及资源利用率。本页按功能分类列出关键设置及其默认值，帮助你在建索引或调优时有一个清单。 查看与修改索引设置 # // 查看索引的所有设置 GET /my-index/_settings // 查看特定设置 GET /my-index/_settings/index.refresh_interval // 动态修改设置（仅限 Dynamic 类型的设置） PUT /my-index/_settings { "index.refresh_interval": "30s" } Static vs Dynamic：Static 设置只能在索引创建时指定或在关闭索引后修改；Dynamic 设置可以在运行时通过 _settings API 随时修改。 分片与副本 # 设置 默认值 类型 说明 index.number_of_shards 1 Static 主分片数量。创建后不可更改（上限由 es.index.max_number_of_shards 控制，默认 1024） index.number_of_replicas 1 Dynamic 每个主分片的副本数量。最小值 0 index.number_of_routing_shards 等于主分片数 Static 用于 _split 操作的路由分片数，必须 ≥ number_of_shards index.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/aggregations/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/aggregations/聚合查询 # 聚合函数对一组文档进行计算并返回单个值。通常与 GROUP BY 子句组合使用，对数据进行分组后计算汇总统计量。 聚合函数 # 基本聚合函数 # 函数 说明 示例 COUNT(*) 计算所有行数 SELECT COUNT(*) FROM accounts COUNT(field) 计算非 NULL 值行数 SELECT COUNT(age) FROM accounts COUNT(DISTINCT field) 计算字段不同值数量 SELECT COUNT(DISTINCT gender) FROM accounts SUM(expr) 求和 SELECT SUM(balance) FROM accounts AVG(expr) 算术平均值 SELECT AVG(age) FROM accounts MAX(expr) 最大值 SELECT MAX(balance) FROM accounts MIN(expr) 最小值 SELECT MIN(balance) FROM accounts 统计聚合函数 # 函数 同义函数 说明 VAR_POP(expr) VARIANCE(expr) 总体方差 VAR_SAMP(expr) — 样本方差 STDDEV_POP(expr) STD(expr)、STDDEV(expr) 总体标准差 STDDEV_SAMP(expr) — 样本标准差 使用示例 # -- 基本聚合 SELECT COUNT(*), SUM(balance), AVG(age), MAX(balance), MIN(balance) FROM accounts -- 分组聚合 SELECT gender, COUNT(*) AS cnt, AVG(age) AS avg_age FROM accounts GROUP BY gender -- 聚合表达式 SELECT gender, SUM(age) * 2 AS double_sum FROM accounts GROUP BY gender -- 表达式作为聚合参数 SELECT gender, SUM(age * 2) AS sum_double FROM accounts GROUP BY gender COUNT 的特殊形式 # 形式 行为 COUNT(field) 仅计数字段值非 NULL 的行 COUNT(*) 计数所有输入行（包含 NULL） COUNT(1) 等同于 COUNT(*)，任何非 NULL 字面量均可 COUNT(DISTINCT field) 计数字段的不重复值 SELECT COUNT(DISTINCT gender), COUNT(gender) FROM accounts COUNT(DISTINCT gender) COUNT(gender) 2 4 GROUP BY # GROUP BY 按表达式对结果分组。支持三种写法：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/node_scale/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/node_scale/节点扩容 # Easysearch Operator 支持通过修改 YAML 配置实现快速水平扩容。 操作步骤 # 修改 Operator YAML 文件中的 replicas 字段值。例如，将集群从 3 节点扩容到 5 节点： # 修改前 replicas: 3 # 修改后 replicas: 5 应用修改： kubectl apply -f easysearch-cluster.yaml Operator 会并发创建新的节点（如 threenodes-masters-3、threenodes-masters-4），新节点启动后自动加入集群并参与分片分配。 注意：扩容前请确保 Kubernetes 集群有足够的计算和存储资源。缩容操作需要谨慎，建议先手动迁移分片后再减少副本数。 操作演示 #https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/english-morphology-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/english-morphology-analyzer/English Morphology 分析器 # english_morphology 分析器专为处理复杂的英语文本而设计。与仅执行简单算法剪裁的常规分析器不同，它基于词形还原（Lemmatization）技术，能够精准识别英语词汇的形态变化，并将其还原为词典中的标准原型。 这确保了用户在搜索单词的不同形态（如动词时态 ran/running、名词单复数 foxes/fox、或不规则变化 feet/foot）时，能够实现精准的跨形态匹配。 该分析器由以下分词器和分词过滤器组成： standard 分词器：去除大部分标点符号，并依据空格和其他常见分隔符对文本进行分割。 lowercase 分词过滤器：将所有词元转换为小写，以确保匹配时不区分大小写。 english_morphology 分词过滤器：执行英语词汇的形态分析，将动词的时态、形容词的比较级以及名词的复数形式映射到其唯一的语义原型。 相关指南（先读这些） # 文本分析：词干提取 文本分析基础 安装 # 英语形态分词器包含在Morphological Analysis插件中。此插件已包含在Easysearch的bundle包中。 analysis-morphology插件安装命令如下： bin/easysearch-plugin install analysis-morphology 参考样例 # 以下命令创建一个名为 my_morphology_index 的索引，并为 my_field 字段配置俄语形态分词器的索引： PUT /my_morphology_index { "mappings": { "properties": { "my_field": { "type": "text", "analyzer": "english_morphology" } } } } 配置自定义分词器 # 在生产环境中，为了兼顾性能和准确度，建议定义一个包含小写化、形态还原和停用词过滤的自定义分析器： PUT /my_custom_morphology_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "type": "custom", "tokenizer": "standard", "filter": [ "lowercase", "english_morphology", "stop" ] } } } } } 产生的词元 # 通过形态分析，不同的词形会被索引为相同的词元。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/discovery/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/discovery/集群发现配置 # 本页介绍 easysearch.yml 中与节点发现、主节点选举和故障检测相关的配置项。这些都是静态设置，修改后需要重启节点生效。 discovery.seed_hosts # discovery.seed_hosts: - 192.168.1.10:9300 - 192.168.1.11:9300 - 192.168.1.12:9300 项目 说明 参数 discovery.seed_hosts 默认值 未设置（自动使用 ["127.0.0.1", "[::1]"]） 属性 静态 说明 提供集群中候选主节点的地址列表，用于新节点加入时的发现。这是组建多节点集群最关键的配置。未配置时默认连接本地 IPv4 和 IPv6 环回地址 格式说明 # 每个地址格式为 host:port 或 host（省略端口时使用 transport.port 的值，默认 9300） 支持 IP 地址、主机名或域名 只需列出具有 master 角色的节点地址 多种写法： # YAML 列表 discovery.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/highlight/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/highlight/高亮 # 高亮用于在返回结果中突出显示命中的查询词，方便用户快速定位关键信息。 相关指南 # 高亮 基础用法 # 在查询体中添加 highlight 段即可启用： GET shakespeare/_search { "query": { "match": { "text_entry": "life" } }, "highlight": { "fields": { "text_entry": {} } } } 响应中每条命中文档会带一个 highlight 对象，默认使用 <em> 标签包裹： "highlight": { "text_entry": [ "my <em>life</em>, except my <em>life</em>." ] } 自定义标签 # 通过 pre_tags / post_tags 自定义包裹标签： GET shakespeare/_search { "query": { "match": { "play_name": "Henry IV" } }, "highlight": { "pre_tags": ["<strong>"], "post_tags": ["</strong>"], "fields": { "play_name": {} } } } 也可以使用 "tags_schema": "styled" 启用内置的多级标签样式（<em class="hlt1">、<em class="hlt2"> 等）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp/HanLP 分词器 # HanLP 是一个功能强大的中文自然语言处理库，通过 analysis-hanlp 插件 集成到 Easysearch 中。该插件提供了 7 种分词模式，覆盖从高速到高精度的各种需求。 前提条件 # bin/easysearch-plugin install analysis-hanlp 分词模式一览 # 分词器名称 模式 速度 精度 适用场景 hanlp_standard 标准分词 ★★★ ★★★★ 通用中文分词 hanlp_index 索引分词 ★★★ ★★★ 索引时最大化召回 hanlp_nlp NLP 分词 ★★ ★★★★★ 命名实体识别 hanlp_crf CRF 分词 ★★ ★★★★★ 新词发现 hanlp_n_short N-最短路径 ★★ ★★★★ 歧义消解 hanlp_dijkstra 最短路径 ★★★ ★★★ 快速精确分词 hanlp_speed 极速分词 ★★★★★ ★★ 大数据量高吞吐 索引/搜索推荐搭配 # PUT my-hanlp-index { "settings": { "analysis": { "analyzer": { "hanlp_index_analyzer": { "type": "custom", "tokenizer": "hanlp_index" }, "hanlp_search_analyzer": { "type": "custom", "tokenizer": "hanlp_standard" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "hanlp_index_analyzer", "search_analyzer": "hanlp_search_analyzer" } } } } 测试分词 # GET /_analyze { "tokenizer": "hanlp_standard", "text": "中华人民共和国国歌" } 模式选择建议 # 需求 推荐模式 通用场景 hanlp_standard 索引时最大召回 hanlp_index 人名/地名/机构名识别 hanlp_nlp 识别新词（训练语料外的词） hanlp_crf 追求最大吞吐量 hanlp_speed 相关链接 # 文本分析https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/open-close-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/open-close-index/开关索引与索引限制 # 关闭索引 # 关闭的索引不消耗集群资源（CPU、内存、文件句柄），但索引数据仍保留在磁盘上。关闭后索引不能读写，但可以随时重新打开。 典型场景： 历史索引暂时不需要查询，但不想删除 修改 Static 类型的索引设置（必须先关闭索引） 降低集群负载 POST /my-index/_close 响应： { "acknowledged": true, "shards_acknowledged": true, "indices": { "my-index": { "closed": true } } } 批量关闭： POST /logs-2024-01,logs-2024-02/_close POST /logs-2024-*/_close 查询参数 # 参数 类型 默认值 说明 timeout Time 30s 操作超时时间 master_timeout Time 30s 连接主节点的超时时间 wait_for_active_shards String — 等待的活跃分片数（数字、all 或 index-setting） expand_wildcards String open 通配符展开策略：open、closed、hidden、none、all ignore_unavailable Boolean false 是否忽略不存在的索引 allow_no_indices Boolean true 通配符未匹配到索引时是否报错 打开索引 # POST /my-index/_open 打开后索引会进入恢复流程（重建分片、分配副本），需要等待分片就绪后才能正常读写。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/user-agent/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/user-agent/用户代理处理器 # user_agent 处理器用于从用户代理字符串中提取信息，例如客户端使用的浏览器、设备和操作系统。user_agent 处理器特别适用于分析用户行为，并根据用户设备、操作系统和浏览器识别趋势。它还可以帮助解决特定用户代理配置的问题。 以下是为 user_agent 处理器提供的语法： { "processor": { "user_agent": { "field": "user_agent", "target_field": "user_agent_info" } } } 配置参数 # 下表列出了 user_agent 处理器所需的和可选参数。 参数 是否必填 描述 field 必填 包含用户代理字符串的字段。 target_field 可选 存储提取的用户代理信息的字段。如果未指定，则信息存储在 user_agent 字段中。 ignore_missing 可选 指定处理器是否应忽略不包含指定 field 的文档。如果设置为 true ，则处理器在 field 不存在时不会修改文档。默认为 false 。 regex_file 可选 包含用于解析用户代理字符串的正则表达式模式的文件。此文件应位于 Easysearch 包中的 config/ingest-user-agent 目录下。如果未指定，则使用默认文件 regexes.yaml。 properties 可选 要从用户代理字符串中提取并添加到 target_field 的属性列表。如果未指定，则使用默认属性 name 、 major 、 minor 、 patch 、 build 、 os 、 os_name 、 os_major 、 os_minor 和 device 。 description 可选 处理器的一个简要描述。 if 可选 处理器运行的条件。 ignore_failure 可选 指定处理器是否在遇到错误时继续执行。如果设置为 true ，则忽略失败。默认为 false 。 on_failure 可选 在处理器失败时运行的处理器列表。 tag 可选 处理器的标识标签。在调试中区分同一类型的处理器很有用。 如何使用 # 按照以下步骤在管道中使用处理器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/cluster/搭建集群 # 在深入研究 Easysearch 以及搜索和聚合数据之前，你首先需要创建一个 Easysearch 集群。 Easysearch 可以作为一个单节点或多节点集群运行。一般来说，配置两者的步骤是非常相似的。本页演示了如何创建和配置一个多节点集群，但只需做一些小的调整，你可以按照同样的步骤创建一个单节点集群。 要根据你的要求创建和部署一个 Easysearch 集群，重要的是要了解节点发现和集群形成是如何工作的，以及哪些设置对它们有影响。 有许多方法可以设计一个集群。下面的插图显示了一个基本架构。 这是一个四节点的集群，有一个专用的主节点，一个专用的协调节点，还有两个数据节点，这两个节点是主节点，也是用来摄取数据的。 下表提供了节点类型的简要描述。 节点类型 描述 最佳实践 Master 管理集群的整体运作并跟踪集群的状态。这包括创建和删除索引，跟踪加入和离开集群的节点，检查集群中每个节点的健康状况（通过运行 ping 请求），并将分片分配给节点。 在三个不同区域的三个专用主节点是几乎所有生产用例的正确方法。这可以确保你的集群永远不会失去法定人数。两个节点在大部分时间都是空闲的，除非一个节点宕机或需要一些维护。 Data 存储和搜索数据。在本地分片上执行所有与数据有关的操作（索引、搜索、聚合）。这些是你的集群的工作节点，需要比其他任何节点类型更多的磁盘空间。 当你添加数据节点时，保持它们在各区之间的平衡。例如，如果你有三个区，以三的倍数添加数据节点，每个区一个。我们建议使用存储和内存重的节点。 默认情况下，每个节点是一个主节点和数据节点。决定节点的数量，分配节点类型，并为每个节点类型选择硬件，取决于你的使用情况。你必须考虑到一些因素，如你想保留数据的时间，你的文件的平均大小，你的典型工作负载（索引、搜索、聚合），你的预期性价比，你的风险容忍度，等等。 在你评估所有这些要求之后，我们建议你使用一个管理工具。要开始使用 INFINI Console，请参阅 INFINI Console 文档。 本页演示了如何处理不同的节点类型。它假设你有一个类似于前面插图的四节点集群。 前提条件 # 在你开始之前，你必须在你的所有节点上安装和配置 Easysearch。有关可用选项的信息，请参见 安装和配置。 完成后，使用 SSH 连接到每个节点，然后打开 config/easysearch.yml 文件。 你可以在这个文件中为你的集群设置所有的配置。 Step 1: 命名集群 # 为集群指定一个唯一的名字。如果你不指定集群名称，它将被默认设置为 easysearch。设置一个描述性的集群名称很重要，特别是如果你想在一个网络内运行多个集群。 要指定集群名称，请修改下面一行。 #cluster.name: my-application tohttps://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/geoip/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/geoip/GeoIP 处理器 # 需要 ingest-geoip 插件 geoip 处理器根据 IP 地址查询 MaxMind GeoLite2 数据库，为文档添加地理位置信息，包括国家、城市、经纬度、时区和 ASN 等。该处理器非常适合日志分析、流量审计和用户来源可视化等场景。 语法 # { "geoip": { "field": "ip" } } 配置参数 # 参数 是否必填 描述 field 必填 包含 IP 地址的源字段名。支持 IPv4 和 IPv6 target_field 可选 存储地理位置信息的目标字段。默认为 geoip database_file 可选 使用的 MaxMind 数据库文件名。默认为 GeoLite2-City.mmdb properties 可选 要提取的属性列表。未指定时根据数据库类型使用默认属性集（见下表） ignore_missing 可选 为 true 时，如果源字段缺失或为 null，则跳过处理不报错。默认为 false first_only 可选 当源字段为数组时，为 true 仅返回第一个匹配结果；为 false 返回所有匹配结果的列表。默认为 true description 可选 处理器的简要描述 if 可选 处理器运行的条件 ignore_failure 可选 为 true 时，处理器出错后忽略继续执行。默认为 false on_failure 可选 处理器失败时运行的处理器列表 tag 可选 处理器的标识标签 支持的数据库 # 处理器根据数据库类型后缀自动识别数据库格式：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-standard/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-standard/HanLP Standard 分词器 # hanlp_standard 分词器使用 HanLP 标准分词模式对中文文本进行分词，适合大多数中文搜索场景。 需要安装 analysis-hanlp 插件。 示例 # PUT my_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "tokenizer": "hanlp_standard" } } } } } 相关指南 # HanLP 分词器 HanLP 标准分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/clone-shrink-split/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/clone-shrink-split/克隆、缩小与拆分索引 # 这三个操作都是"把一个现有索引复制到一个新索引"，区别在于目标索引的主分片数： 操作 API 目标主分片数 典型场景 Clone _clone 与源索引相同 复制索引用于测试/实验 Shrink _shrink 源分片数的因子（如 6→3、6→2、6→1） 合并小分片、降低开销 Split _split 源分片数的倍数（如 2→4、2→6） 扩展分片以提高写入并发 前置条件：源索引必须是只读状态。所有操作都会创建一个全新的索引，源索引保持不变。 公共前置步骤 # 在执行 Clone / Shrink / Split 之前，源索引必须标记为只读： PUT /source-index/_settings { "index.blocks.write": true } 对于 Shrink 操作，还需要将所有分片的副本迁移到同一个节点： PUT /source-index/_settings { "index.routing.allocation.require._name": "node-1", "index.blocks.write": true } 等待所有分片完成迁移： GET _cat/shards/source-index?v 确认所有分片都在目标节点上后再执行 Shrink。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/common/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/common/其它常用 API # 此页面包含 Easysearch 常用 API 的示例请求。 使用非默认设置创建索引 # PUT my-logs { "settings": { "number_of_shards": 4, "number_of_replicas": 2 }, "mappings": { "properties": { "title": { "type": "text" }, "year": { "type": "integer" } } } } 索引单个文档并自动生成随机 ID # POST my-logs/_doc { "title": "Your Name", "year": "2016" } 索引单个文档并指定 ID # PUT my-logs/_doc/1 { "title": "Weathering with You", "year": "2019" } 一次索引多个文档 # 请求正文末尾的空白行是必填的。如果省略 _id 字段， Easysearch 将生成一个随机 id 。https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/relevance-and-sorting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/relevance-and-sorting/相关性与排序 # 在 Easysearch 中，搜索结果默认按**相关性（relevance）**降序排列。理解相关性如何计算、如何自定义排序，是用好全文搜索的关键。 什么是相关性？ # 每个文档都有一个 _score 字段，表示它与查询的匹配程度。评分越高，相关性越高。 _score 的计算基于 BM25 算法（Okapi BM25），它是经典 TF/IDF 的改进版本。BM25 使用三个核心因素来衡量相关性： 词频（Term Frequency, TF） # 检索词在文档字段中出现的频率。出现 5 次比出现 1 次的权重更高。BM25 对词频做了饱和处理——频率增长到一定程度后增益递减，不像经典 TF/IDF 会无限增长： $$tf_{BM25} = \frac{freq \cdot (k_1 + 1)}{freq + k_1 \cdot (1 - b + b \cdot \frac{dl}{avgdl})}$$ 逆向文档频率（Inverse Document Frequency, IDF） # 检索词在所有文档中出现的频率。越常见的词（如"的"“和”），权重越低；越罕见的词权重越高。 $$idf(t) = \ln\left(1 + \frac{N - df + 0.5}{df + 0.5}\right)$$ 其中 $N$ 是文档总数，$df$ 是包含该词的文档数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/cat/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/cat/cat API # 您可以使用紧凑且对齐的文本 （CAT） API 以易于理解的表格格式获取有关集群的基本统计信息。cat API 是一个人类可读的接口，它返回纯文本而不是传统的 JSON。 使用 cat API，您可以回答诸如哪个节点是选定的主节点、集群处于什么状态、每个索引中有多少文档等问题。 要查看 cat API 中的可用操作，请使用以下命令： GET _cat 还可以在查询中使用以下字符串参数。 参数 描述 ?v 通过向列添加标题使输出更详细。它还添加了一些格式，以帮助将每列对齐在一起。此页面上的所有示例都包含 v 参数。 ?help 列出给定操作的默认标头和其他可用标头。 ?h 将输出限制为特定标头。 ?format 以 JSON、YAML 或 CBOR 格式输出结果。 ?sort 按指定列对输出进行排序。 要查看每列表示的内容，请使用 ?v 参数： GET _cat/<operation_name>?v 要查看所有可用的标头，请使用 ?help 参数： GET _cat/<operation_name>?help 要将输出限制为标头的子集，请使用 ?h 参数：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-index/HanLP Index 分词器 # hanlp_index 分词器是 analysis-hanlp 插件 提供的索引模式分词器。它在标准分词的基础上对长词进行二次切分，生成更多子词项，适合索引时使用以提高召回率。 前提条件 # 需要安装 analysis-hanlp 插件： bin/easysearch-plugin install analysis-hanlp 分词效果对比 # 以"中华人民共和国国歌"为例： 分词器 输出词项 hanlp_standard 中华人民共和国、国歌 hanlp_index 中华、华人、人民、共和、共和国、中华人民共和国、国歌 hanlp_index 输出更细粒度的子词，确保无论用户搜索"中华"、“人民"还是"共和国"都能命中。 使用示例 # 在映射中指定 # PUT my-index { "settings": { "analysis": { "analyzer": { "hanlp_index_analyzer": { "type": "custom", "tokenizer": "hanlp_index" } } } }, "mappings": { "properties": { "content": { "type": "text", "analyzer": "hanlp_index_analyzer", "search_analyzer": "hanlp_standard" } } } } 测试分词效果 # GET /_analyze { "tokenizer": "hanlp_index", "text": "中华人民共和国国歌" } 最佳实践 # 场景 推荐 索引时 使用 hanlp_index（最大化召回） 搜索时 使用 hanlp_standard 或 hanlp_nlp（精确匹配） 相关链接 # HanLP Standard 分词器 — 标准分词模式 HanLP NLP 分词器 — 命名实体识别模式 HanLP 通用 — HanLP 分词器概述 文本分析https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-rollover/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-rollover/索引滚动（Rollover） # Rollover API 用于在满足特定条件时，将一个别名或数据流（Data Stream）滚动到一个新的索引。这是管理时间序列数据的核心操作——让你的索引保持合理大小，避免单个索引无限膨胀。 基本用法 # 前置条件 # Rollover 只能在以下两种目标上执行： 写入别名（Write Alias）：别名必须标记了 is_write_index: true 数据流（Data Stream）：天然支持 Rollover 对别名执行 Rollover # 先创建索引和写入别名： PUT /logs-000001 { "aliases": { "logs-write": { "is_write_index": true } } } 当条件满足时执行 Rollover： POST /logs-write/_rollover { "conditions": { "max_age": "7d", "max_docs": 10000000, "max_size": "50gb", "max_primary_shard_size": "25gb" } } 响应： { "acknowledged": true, "shards_acknowledged": true, "old_index": "logs-000001", "new_index": "logs-000002", "rolled_over": true, "dry_run": false, "conditions": { "[max_age: 7d]": false, "[max_docs: 10000000]": true, "[max_size: 50gb]": false, "[max_primary_shard_size: 25gb]": false } } 任一条件满足即触发滚动。响应中会列出每个条件的评估结果。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/check-match-rules/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/check-match-rules/规则匹配处理器 # 需要 Rules 插件、有效 License，以及已成功编译的规则库 check_match_rules 处理器将 规则引擎接入 Ingest Pipeline，在文档写入阶段执行规则匹配并自动打标。 语法 # { "check_match_rules": { "id": "my_ruleset" } } 配置参数 # 参数 是否必填 描述 id 必填 规则库 ID（对应已编译的 repo_id） target_field 可选 匹配结果写入字段，默认 tags fields 可选 文档字段白名单；指定后仅这些字段按原字段名参与匹配，其余字段内容不会丢弃，而是汇总到 default_match_field default_match_field 可选 当配置了 fields 时，未包含字段会汇总到该字段名参与匹配，默认 content regex_start_at_word 可选 控制底层正则匹配是否从词边界起算，默认 true，通常保持默认即可 ignore_missing 可选 为 true 时，处理阶段发生异常会直接返回原文档并继续后续处理；默认 false，避免掩盖 License、规则库或配置问题 description 可选 处理器描述 if 可选 处理器执行条件 ignore_failure 可选 为 true 时，处理器失败后忽略并继续执行，默认 false on_failure 可选 处理器失败时执行的处理器列表 tag 可选 处理器标识 工作原理 # 提取文档字段： 未配置 fields：提取所有非 _ 前缀字段（含嵌套展平） 配置 fields：白名单字段保留原名，其余字段值拼接到 default_match_field 执行规则匹配：传入底层规则匹配引擎 写入结果：命中后将标签数组写入 target_field 使用步骤 # 前置条件 # 在创建 Pipeline 前，请先完成以下检查：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-nlp/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-nlp/HanLP NLP 分词器 # hanlp_nlp 分词器使用 HanLP NLP 分词模式，支持命名实体识别，适合需要高精度语义分析的场景。 需要安装 analysis-hanlp 插件，并确保 perceptron CWS 模型可用。 示例 # PUT my_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "tokenizer": "hanlp_nlp" } } } } } 相关指南 # HanLP 分词器 HanLP NLP 分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/refresh-flush-forcemerge/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/refresh-flush-forcemerge/Refresh、Flush 与 Force Merge # 这些是索引的日常维护操作，用于控制数据可见性、持久性和段文件结构。 Refresh：让新写入的文档可搜索 # 写入的文档不会立刻出现在搜索结果中——需要经过一次 refresh 操作，在内存中创建新的 Lucene 段（segment），文档才能被 _search 检索到。 详见 写入与存储机制 了解 refresh 的工作原理。 默认情况下，Easysearch 每 1 秒 自动执行一次 refresh（由 index.refresh_interval 控制）。但你也可以手动触发： // 刷新特定索引 POST /my-index/_refresh // 刷新多个索引 POST /index-1,index-2/_refresh // 刷新所有索引 POST /_refresh 响应： { "_shards": { "total": 10, "successful": 5, "failed": 0 } } 查询参数 # 参数 类型 默认值 说明 expand_wildcards String open 通配符展开策略 ignore_unavailable Boolean false 忽略不存在的索引 allow_no_indices Boolean true 通配符未匹配时是否报错 常见场景 # 批量写入后立即搜索：导入数据后手动 refresh 确保数据可见 测试/CI 环境：写入后立即 refresh 以验证结果 生产环境注意：频繁手动 refresh 会增加小段数量，影响搜索性能。大批量写入时建议临时关闭自动 refresh（设为 "-1"），导入完成后再恢复。https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/ingest-text-embedding/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/ingest-text-embedding/写入数据文本向量化 # Easysearch 使用 Ingest 管道中的一系列处理器，可以对写入的数据进行处理，并且支持对文本进行向量化。本文档介绍如何在 Easysearch 中使用 text_embedding 处理器对写入数据进行向量化。 相关指南（先读这些） # 向量搜索 向量字段建模 AI 集成 先决条件 # 支持与 OpenAI API 兼容的 embedding 接口，支持 Ollama embedding 接口。 需要安装 Easysearch 的 knn 和 ai 插件。 在生产环境中使用数据采集时，您的集群应至少包含一个节点，且该节点的节点角色权限设置为 ingest 。 创建带有向量字段的索引 # 首先，需要创建一个包含 knn mapping 的索引，text_vector 是存储向量的字段，向量维度是 768。 PUT /my-index { "mappings": { "properties": { "text_vector": { "type": "knn_dense_float_vector", "knn": { "dims": 768, "model": "lsh", "similarity": "cosine", "L": 99, "k": 1 } } } } } 创建或更新 text_embedding 处理器 # 请求路径：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/text-embedding/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/ingest-pipelines/index-processors/text-embedding/文本向量化处理器 # 需要 AI 插件和 KNN 插件 text_embedding 处理器在文档写入时自动调用外部 Embedding 模型服务，将文本字段转换为向量并存储到指定的向量字段中，实现"写入即向量化"。该处理器是构建语义搜索和混合搜索的基础组件。 语法 # { "text_embedding": { "text_field": "content", "vector_field": "content_vector", "url": "https://api.openai.com/v1/embeddings", "vendor": "openai", "model_id": "text-embedding-3-small", "api_key": "sk-xxxxxxxx" } } 配置参数 # 参数 是否必填 描述 text_field 必填 包含待向量化文本的源字段 vector_field 必填 存储生成的向量的目标字段。该字段应映射为 knn_vector 类型 url 必填 Embedding 模型服务的 API 端点 URL vendor 必填 模型提供商标识。openai 表示 OpenAI 兼容接口，其他值（如 ollama）使用 Ollama 兼容接口 model_id 必填 使用的 Embedding 模型 ID api_key 可选 API 密钥（使用 OpenAI 兼容接口时通常必填）。存储时会自动加密 dimensions 可选 期望的向量维度。未指定时使用模型默认维度 ignore_missing 可选 为 true 时，源字段缺失则跳过处理。默认为 false batch_size 可选 批量处理时每次 API 调用包含的文档数。默认为 1 description 可选 处理器的简要描述 if 可选 处理器运行的条件 ignore_failure 可选 为 true 时，处理器出错后忽略继续执行。默认为 false on_failure 可选 处理器失败时运行的处理器列表 tag 可选 处理器的标识标签 支持的模型服务 # 接口类型 vendor 值 认证方式 典型服务 OpenAI 兼容 openai Authorization: Bearer <api_key> 请求头 OpenAI、阿里云 DashScope、Azure OpenAI、DeepSeek 等 Ollama 兼容 其他任意值（如 ollama） 无认证 Ollama 本地部署 如何使用 # 步骤 1：创建向量索引 # 首先创建包含 KNN 向量字段的索引：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-crf/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-crf/HanLP CRF 分词器 # hanlp_crf 分词器使用 HanLP CRF（条件随机场）分词模式，适合需要高精度分词的学术研究场景。 需要安装 analysis-hanlp 插件，并确保 CRF CWS 模型可用。 示例 # PUT my_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "tokenizer": "hanlp_crf" } } } } } 相关指南 # HanLP 分词器 HanLP CRF 分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/functions/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/functions/内置函数 # Easysearch SQL 提供 80 多个内置函数，涵盖数学运算、字符串处理、日期时间、条件判断和类型转换等类别。 数学函数 # 函数 说明 示例 ABS(expr) 绝对值 ABS(-5) → 5 CEIL(expr) / CEILING(expr) 向上取整 CEIL(2.3) → 3 FLOOR(expr) 向下取整 FLOOR(2.7) → 2 ROUND(expr [, d]) 四舍五入到 d 位小数 ROUND(3.1415, 2) → 3.14 TRUNCATE(expr, d) 截断到 d 位小数 TRUNCATE(3.1415, 2) → 3.14 SQRT(expr) 平方根 SQRT(16) → 4.https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/search-text-embedding/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/search-text-embedding/搜索请求文本向量化 # Easysearch 使用搜索管道的 semantic_query_enricher 处理器，协助 semantic query，将文本转为向量。 相关指南（先读这些） # 向量搜索 搜索管道 AI 集成 先决条件 # 服务兼容性 需满足以下任一条件： 支持与 OpenAI API 兼容的 embedding 接口 支持 Ollama embedding 接口 插件要求 必须安装 Easysearch 的以下插件： knn ai 数据准备 需预先完成： 创建向量索引 写入向量数据 参考 写入数据文本向量化 创建或更新 semantic_query_enricher 处理器 # PUT /_search/pipeline/default_model_pipeline { "rewrite_processors": [ { "semantic_query_enricher" : { "tag": "tag1", "description": "Sets the default embedding model", "url": "https://api.https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/data-streams/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/data-streams/数据流（Data streams） # 如果你正在将连续生成的时间序列数据（如日志、事件和指标）摄入 Easysearch，那么你很可能处于这样一种场景：文档数量快速增长，且你无需更新旧文档。 管理时间序列数据的典型工作流程包含多个步骤，例如创建滚动索引别名、定义写入索引，以及为底层索引定义通用的映射和设置。 数据流简化了这一过程，并强制采用最适合时间序列数据的配置方式，例如主要为仅追加（append-only）数据设计，并确保每个文档都包含一个时间戳字段。 数据流在内部由多个底层索引组成。搜索请求会被路由到所有底层索引，而写入请求则被路由到最新的写入索引。通过 索引生命周期管理（ILM） 策略，你可以自动处理索引滚动（rollover）或删除操作。 数据流使用说明 # 步骤 1：创建索引模板 # 要创建数据流，首先需要创建一个索引模板，用于将一组索引配置为数据流。data_stream 对象表明这是一个数据流，而非普通索引模板。索引模式需与数据流的名称匹配： PUT _index_template/logs-template-nginx { "index_patterns": "logs-nginx", "data_stream": { }, "priority": 200, "template": { "settings": { "number_of_shards": 1, "number_of_replicas": 0 } } } 在此情况下，每个摄入的文档都必须包含一个 @timestamp 字段。 你也可以在 data_stream 对象中自定义时间戳字段名称。此外，你还可以在此处定义索引映射和其他设置，就像为普通索引模板所做的那样。 PUT _index_template/logs-template-nginx { "index_patterns": "logs-nginx", "data_stream": { "timestamp_field": { "name": "request_time" } }, "priority": 200, "template": { "settings": { "number_of_shards": 1, "number_of_replicas": 0 } } } 在此示例中，logs-nginx 索引会匹配 logs-template-nginx 模板。当存在多个匹配时，Easysearch 会选择优先级更高的模板。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/hardware/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/hardware/生产环境硬件配置推荐 # 在生产环境部署 Easysearch 时，高可用性（HA）是必须满足的核心要求。为实现完整的 HA 保障，您至少需要部署 3 个节点组成 Easysearch 集群。为获得最佳运维体验，建议配合使用 INFINI Console 和 Gateway，它们提供集群监控、告警和运维管理等完整功能，可大幅提升日常运维效率。 推荐配置 # 产品 CPU 内存 JVM 堆 磁盘 高可用实例数 Easysearch 16 核+ 64 GB+ 31 GB SSD ≥ 3 INFINI Console 8 核 16 GB — ≥ 50 GB (HDD/SSD) 1 INFINI Gateway 8 核 16 GB — ≥ 50 GB (HDD/SSD) ≥ 2 对于低负载集群或测试环境，可适当降低配置标准，但需确保满足基础性能需求。测试环境最低配置参见 测试环境部署。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/aggs-performance/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/aggs-performance/聚合性能与内存 # 聚合的性能和内存使用是生产环境中需要重点关注的问题。本页介绍聚合背后的数据结构（doc_values 和 fielddata）、内存限制机制（断路器），以及如何优化聚合查询。 Doc Values # 聚合使用一个叫 doc values 的数据结构。Doc values 可以使聚合更快、更高效并且内存友好。 Doc values 的存在是因为倒排索引只对某些操作是高效的。倒排索引的优势在于查找包含某个项的文档，而对于从另外一个方向的相反操作并不高效，即：确定哪些项是否存在单个文档里，聚合需要这种次级的访问模式。 倒排索引 vs Doc Values # 对于以下倒排索引： Term Doc_1 Doc_2 Doc_3 ------------------------------------ brown | X | X | dog | X | | X dogs | | X | X fox | X | | X ... 如果我们想要获得所有包含 brown 的文档的词的完整列表，查询部分简单又高效。倒排索引是根据项来排序的，所以我们首先在词项列表中找到 brown，然后扫描所有列，找到包含 brown 的文档。 然后，对于聚合部分，我们需要找到 Doc_1 和 Doc_2 里所有唯一的词项。用倒排索引做这件事情代价很高：我们会迭代索引里的每个词项并收集 Doc_1 和 Doc_2 列里面 token。这很慢而且难以扩展：随着词项和文档的数量增加，执行时间也会增加。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-n-short/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-n-short/HanLP N-Short 分词器 # hanlp_n_short 分词器使用 HanLP N 最短路径分词算法，能找到全局 N 条最短路径，适合需要高精度分词的场景。 需要安装 analysis-hanlp 插件。 示例 # PUT my_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "tokenizer": "hanlp_n_short" } } } } } 相关指南 # HanLP 分词器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/nlp/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/nlp/NLP 自然语言处理 # 搜索引擎的核心挑战是理解人类语言。本文介绍 NLP（Natural Language Processing）在 Easysearch 中的应用，从基础的分词到高级的向量语义搜索。 NLP 在搜索中的角色 # 用户输入: "我想买一台便宜的笔记本电脑" ↓ NLP 处理层（分词、去停用词、同义词、向量化） ↓ Easysearch 查询执行 ↓ 返回相关结果（包括 "laptop"、"notebook"、"手提电脑" 等） Easysearch 中 NLP 的应用可以分为三个层次： 层次 技术 实现方式 词级处理 分词、词干提取、停用词 内置分析器 语言规则 同义词、拼音、模糊匹配 分析器插件 语义理解 向量检索、文本嵌入 AI 集成 / kNN 第一层：分词与文本分析 # 分词是 NLP 的基础——将连续文本切分为独立的词项（Token）。 中文分词 # 中文没有空格分隔，需要专用分词器： PUT /my-index { "settings": { "analysis": { "analyzer": { "ik_smart_analyzer": { "type": "custom", "tokenizer": "ik_smart" } } } } } 测试分词效果：https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/reindex/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/reindex/重新索引数据 # 相关指南 # 索引管理：创建、删除与重建索引 别名（Aliases） 创建索引后，如果您需要进行广泛的更改，例如为每个文档添加一个新字段或合并多个索引以形成一个新的索引，而不是删除索引，使更改脱机，然后重新索引数据，则可以使用 reindex 操作。 使用 reindex 操作，可以将通过查询选择的所有文档或文档子集复制到另一个索引。重新索引是一个 POST 操作。在最基本的形式中，指定源索引和目标索引。 重新编制索引可能是一项昂贵的操作，具体取决于源索引的大小。我们建议您通过将 number_of_replicas 设置为 0 来禁用目标索引中的副本，并在重新索引过程完成后重新启用它们。 重新索引所有文档 # 您可以将所有文档从一个索引复制到另一个索引。 首先需要使用所需的字段映射和设置创建目标索引，或者可以从源索引中复制这些映射和设置： PUT destination { "mappings":{ "Add in your desired mappings" }, "settings":{ "Add in your desired settings" } } reindex 命令将所有文档从源索引复制到目标索引： POST _reindex { "source":{ "index":"source" }, "dest":{ "index":"destination" } } 如果尚未创建目标索引，则 reindex 操作将使用默认配置创建新的目标索引。 从远程群集 reindex # 您可以从远程集群中的索引复制文档。使用 remote 选项指定远程主机名和所需的登录凭据。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-dijkstra/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-dijkstra/HanLP Dijkstra 分词器 # hanlp_dijkstra 分词器使用 HanLP Dijkstra 最短路径分词算法，基于词典的全切分方式。 需要安装 analysis-hanlp 插件。 示例 # PUT my_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "tokenizer": "hanlp_dijkstra" } } } } } 相关指南 # HanLP 分词器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/hybrid-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/ai/hybrid-search/混合搜索 # 混合搜索结合了关键词搜索和语义搜索，以提升搜索相关性。要实现混合搜索，您需要建立一个在搜索时运行的搜索管道。该管道会在中间阶段拦截搜索结果，并通过处理流程对文档分数进行归一化和组合处理。 要使用混合搜索，您需要配置搜索管道，添加混合排序处理器。 相关指南（先读这些） # 向量搜索 搜索管道 混合排序处理器 # 混合排序处理器 hybrid_ranker_processor 是一种重排序处理器，运行在搜索执行的查询阶段和获取阶段之间。它会拦截查询阶段的结果，然后使用 倒数排序融合算法（RRF，Reciprocal Rank Fusion） 来合并不同查询子句，最终生成排序后的搜索结果列表。 适用场景： 需要融合不同搜索技术（如关键词和语义搜索）的结果 子查询的原始分数不可直接比较（如 BM25 和 KNN） 算法原理 # RRF 是一种多查询融合方法，其核心计算逻辑为： 对每个文档在不同子结果集给出的排名取倒数（如排名第 k 则得分为 1/(k+60)） 将各子结果集的倒数得分相加，生成统一排序分数 按最终分数降序输出结果集 RRF 的通用计算公式如下（其中 k 为平滑常数，默认 60，query_j_rank 表示混合查询中某文档在第 j 种查询方法返回结果中的排名）： rankScore(document_i) = sum(1/(k + query_1_rank), 1/(k + query_2_rank), ..., 1/(k + query_j_rank)) 请求体字段 # 下表列出了所有可用的请求字段。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-stats/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/index-stats/索引统计与监控 # Easysearch 提供了一组 API，用于查看索引的运行状态、性能指标和存储详情。这些信息是性能调优和故障排查的基础。 索引统计（Index Stats） # 获取索引级别的统计信息，包括文档数、存储大小、写入/查询/合并等操作的计数和耗时。 // 获取特定索引的所有统计 GET /my-index/_stats // 获取所有索引的统计 GET /_stats // 只获取特定指标 GET /my-index/_stats/docs,store // 多索引 GET /index-1,index-2/_stats/indexing,search 可用指标 # 指标 说明 docs 文档数和已删除文档数 store 索引存储大小 indexing 写入操作统计（总数、耗时、当前进行中等） get Get 操作统计 search 搜索操作统计（query、fetch 阶段） merge 段合并统计（次数、耗时、大小） refresh Refresh 统计 flush Flush 统计 query_cache 查询缓存命中率和大小 fielddata Fielddata 内存使用 completion Completion Suggester 内存使用 segments 段数量、内存占用 translog Translog 大小和操作数 request_cache 请求缓存命中率 recovery 恢复操作统计 warmer Warmer 统计 _all 所有指标（默认） 查询参数 # 参数 类型 默认值 说明 level String indices 聚合级别：cluster、indices、shards fields String — 逗号分隔的字段名（用于 completion 和 fielddata 指标） completion_fields String — Completion 字段名 fielddata_fields String — Fielddata 字段名 include_segment_file_sizes Boolean false 在 segments 指标中包含文件大小详情 include_unloaded_segments Boolean false 包含未加载的段信息 forbid_closed_indices Boolean true 禁止查询已关闭索引的统计 expand_wildcards String open 通配符展开策略 ignore_unavailable Boolean false 忽略不存在的索引 响应示例（节选） # { "_all": { "primaries": { "docs": { "count": 1500000, "deleted": 2500 }, "store": { "size_in_bytes": 1073741824 }, "indexing": { "index_total": 1500000, "index_time_in_millis": 45000, "index_current": 0 }, "search": { "query_total": 350000, "query_time_in_millis": 12000, "query_current": 2 }, "segments": { "count": 42, "memory_in_bytes": 52428800 } } } } 常见用法 # // 查看段数量（判断是否需要 force merge） GET /my-index/_stats/segments // 查看写入速率 GET /my-index/_stats/indexing // 查看查询缓存命中率 GET /my-index/_stats/query_cache,request_cache // 按分片级别查看统计 GET /my-index/_stats?https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-speed/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/hanlp-speed/HanLP Speed 分词器 # hanlp_speed 分词器使用 HanLP 极速分词模式，牺牲一定精度换取更快的分词速度，适合对延迟敏感的在线搜索场景。 需要安装 analysis-hanlp 插件。 示例 # PUT my_index { "settings": { "analysis": { "analyzer": { "my_analyzer": { "tokenizer": "hanlp_speed" } } } } } 相关指南 # HanLP 分词器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/stconvert/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/tokenizers/stconvert/ST Convert 分词器 # stconvert 分词器用于中文简繁体转换，可将简体中文转换为繁体中文，或将繁体中文转换为简体中文。 需要安装 analysis-stconvert 插件。 参数 # 参数 说明 默认值 convert_type 转换类型：s2t（简→繁）或 t2s（繁→简） s2t keep_both 是否同时保留转换前后的词元 false delimiter 用于分隔转换结果的分隔符 , 示例 # PUT my_index { "settings": { "analysis": { "tokenizer": { "my_stconvert": { "type": "stconvert", "convert_type": "s2t" } }, "analyzer": { "my_analyzer": { "tokenizer": "my_stconvert" } } } } } 相关指南 # ST Convert 分析器 文本分析基础https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/docker/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/docker/Docker 环境下使用 Easysearch # 在使用 Docker 运行 Easysearch 之前，请确保已进行 系统调优并安装好 Docker 服务，且 Docker 服务正常运行。 最快方式：启动临时的 docker 容器，可以从前台查看到 admin 随机生成的初始密码 注： Docker 环境一般用于临时验证，如需要长期使用请务必进行数据持久化 # 直接运行镜像使用随机密码（数据及配置未持久化） docker run --name easysearch --ulimit memlock=-1:-1 -p 9200:9200 infinilabs/easysearch: # 使用自定义密码，可以使用环境变量配置 （需要 1.8.2 及以后的版本才支持） echo "EASYSEARCH_INITIAL_ADMIN_PASSWORD=$(printf "%s%s%s@%s" "$(tr -dc a-z</dev/urandom|head -c4)" "$(tr -dc A-Z</dev/urandom|head -c3)" "$(tr -dc 0-9</dev/urandom|head -c2)" "$(tr -dc a-z0-9</dev/urandom|head -c3)")" | tee .env # 通过从环境变量文件设置初始密码（数据及配置未持久化） docker run --name easysearch --env-file .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-bounding-box/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-bounding-box/Geo Bounding Box 查询 # 地理边界框查询返回 geo_point 字段值位于指定矩形边界框内的文档。如果一个文档包含多个地理坐标点，只要至少有一个点位于边界框内，该文档就匹配。 参考样例 # 您可以使用地理边界框查询来搜索包含地理点的文档。 创建一个映射，将 point 字段映射为 geo_point ： PUT testindex1 { "mappings": { "properties": { "point": { "type": "geo_point" } } } } 以经纬度作为对象索引三个地理点： PUT testindex1/_doc/1 { "point": { "lat": 74.00, "lon": 40.71 } } PUT testindex1/_doc/2 { "point": { "lat": 72.64, "lon": 22.62 } } PUT testindex1/_doc/3 { "point": { "lat": 75.00, "lon": 28.00 } } 搜索所有文档，并筛选出查询中定义的矩形内的点所在的文档： GET testindex1/_search { "query": { "bool": { "must": { "match_all": {} }, "filter": { "geo_bounding_box": { "point": { "top_left": { "lat": 75, "lon": 28 }, "bottom_right": { "lat": 73, "lon": 41 } } } } } } } 返回内容包含匹配的文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/grafana/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/third-party/grafana/Grafana 集成 # Grafana 是主流的开源可观测平台，通过内置的 Elasticsearch 数据源插件可以直接连接 Easysearch，构建实时监控看板和数据分析面板。 相关指南 # Superset 集成 监控告警 前置条件 # 条件 说明 Grafana 版本 8.0+ 推荐（内置 Elasticsearch 数据源） 网络可达 Grafana 服务器能够访问 Easysearch 的 9200 端口 认证信息 Easysearch 用户名和密码 配置步骤 # 1. 添加数据源 # 进入 Grafana → Configuration → Data Sources → Add data source 搜索并选择 Elasticsearch 填写连接信息： 配置项 值 URL https://easysearch-host:9200 Access Server（推荐） Basic Auth 开启 User / Password Easysearch 用户名 / 密码 Skip TLS Verify 开发环境可开启；生产环境配置 CA 证书 Version 选择 7.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/sql-jdbc/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/sql/sql-jdbc/SQL-JDBC 驱动 # Easysearch SQL JDBC 驱动程序是一个独立的纯 Java 驱动，可将 JDBC 调用转换为 Easysearch SQL REST API 请求，适用于 BI 工具集成、报表生成和应用程序数据访问等场景。 驱动信息 # 属性 值 Driver 类名 com.easysearch.jdbc.EasysearchDriver JDBC URL 前缀 jdbc:easysearch:// JAR 包 sql-jdbc-1.7.1.jar 最低 Java 版本 Java 8 安装 # 下载 # 从官网下载 JDBC 驱动 JAR： https://release.infinilabs.com/easysearch/archive/plugins/sql-jdbc-1.7.1.jar Maven 项目 # 将 JAR 安装到本地仓库后引用：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/tls-secure/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/tls-secure/TLS 安全配置指南 # Easysearch 默认启用安全功能，包括 TLS 加密。本文介绍如何配置和管理 TLS 证书，以保障集群通信安全。 TLS 的两层保护 # 层级 配置项 保护范围 HTTP 层 security.ssl.http.* 客户端 ↔ Easysearch REST API Transport 层 security.ssl.transport.* Easysearch 节点 ↔ 节点 生产环境两层都必须启用。 使用自签名证书（快速启动） # bin/initialize.sh -s 会自动生成自签名证书，适合测试和快速验证： bin/initialize.sh -s # 生成的证书位于 config/ 目录 使用企业 CA 证书（生产推荐） # 1. 准备证书文件 # 需要以下文件： 文件 说明 ca.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/creating-a-custom-analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/creating-a-custom-analyzer/创建一个自定义分词器 # 要创建一个自定义分词器，需要指定以下组成内容： 字符过滤器（零个或多个） 词元生成器（一个） 词元过滤器（零个或多个） 相关配置 # 以下参数可用于配置自定义分词器。 参数 必填/可选 描述 type 可选 分词器类型。默认值为custom。你也可以给这个参数指定一个预构建的分词器。 tokenizer 必填 每个分词器必须要有一个词元生成器。 char_filter 可选 要包含在分词器中的字符过滤器列表。 filter 可选 要包含在分词器中的分词过滤器列表。 position_increment_gap 可选 在对包含多个词项内容的文本字段建立索引时，应用于各词项之间的额外间隔。有关更多信息，请参阅位置间隔增量。默认值为 100。 参考样例 # 以下示例展示了各种自定义分词器的配置。 自定义分词器用于去除 HTML 格式标签 # 以下示例中的分词器在分词之前会从文本中移除 HTML 格式标签： PUT simple_html_strip_analyzer_index { "settings": { "analysis": { "analyzer": { "html_strip_analyzer": { "type": "custom", "char_filter": ["html_strip"], "tokenizer": "whitespace", "filter": ["lowercase"] } } } } } 使用以下请求来查看使用该分词器生成的词元：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/delete-auto-follow/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/delete-auto-follow/删除自动跟随模式 # 删除自动跟随模式后，将不再自动为匹配的新索引创建跟随者索引。 操作步骤 # 进入自动跟随模式页面：登录 Easysearch UI，在左侧导航栏点击「主从复制」，切换至「自动跟随模式」标签页。 触发删除操作：在列表中找到目标自动跟随模式规则，点击「操作」列的更多按钮，选择「删除」选项。 确认删除操作：在弹出的提示窗口中，核对规则名称，点击「确定」按钮。 验证删除结果：删除完成后，目标规则将从自动跟随模式列表中移除，不再对远端集群的匹配索引执行自动跟随。 注意事项 # 删除自动跟随模式仅停止新索引的自动同步，已创建的跟随者索引不会被删除，需单独手动解除。 删除前请确认业务已不再依赖该规则自动创建的同步索引，避免后续新增数据无法同步。 删除后若需恢复自动同步，需重新执行「新增自动跟随模式」配置。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/aliases/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/aliases/别名（Aliases） # 别名（Alias）是指向一个或多个索引的"虚拟名称"，常用于实现无感迁移、蓝绿切换、按条件路由等功能。合理使用别名，可以让上游客户端几乎不感知底层索引的重建与演进。 最常用的场景：无感重建索引 # 典型需求：你想调整 mapping/设置，只能重建一个新索引，但又不希望业务代码改来改去。 做法示意： 当前索引为 logs_v1，别名为 logs，所有读写都通过 logs 创建新索引 logs_v2，并将数据迁移过去 将别名 logs 从 logs_v1 原子性切换到 logs_v2 业务只需始终访问 logs，不关心具体版本 好处： 切换时可以做到"近乎无停机" 可以在后台验证新索引的可用性与正确性，再切换别名 多索引聚合访问 # 别名还可以指向多个索引，例如： 别名 logs_all → 指向 logs_2024_01、logs_2024_02、logs_2024_03 等 查询 logs_all 即可同时访问多个时间分片索引 这种方式对时间序列/多分片索引的统一查询非常有用。 按条件路由的读写别名 # 别名还可以带有过滤条件或路由信息，例如： 为某个租户创建只读别名，只能看见自己的数据 为某些写入创建"写别名"，将写入路由到特定索引/分片 这类高级用法可以在多租户、数据分层等场景中减少上游逻辑复杂度，但也需要更严格的管理与规范。 API 操作 # 创建索引别名 # 使用 actions 方法指定要执行的操作列表：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/hindi-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/hindi-normalization/印地语归一化过滤器 # hindi_normalization 词元过滤器对印地语（हिन्दी）文本进行正字法归一化，统一 Devanagari 脚本中的字符变体。 归一化规则 # 处理 说明 Nukta 移除 移除 nukta 标记（用于外来词音译的点） 视觉归一 统一视觉上相同但编码不同的字符变体 末尾 Chandra 移除 移除词尾的 chandra 符号 搭配 indic_normalization 建议先应用 indic_normalization 过滤器 使用示例 # PUT my-hindi-index { "settings": { "analysis": { "filter": { "hindi_norm": { "type": "hindi_normalization" } }, "analyzer": { "my_hindi": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "indic_normalization", "hindi_norm"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["indic_normalization", "hindi_normalization"], "text": "हिन्दी भाषा" } 参数 # 此过滤器不接受任何参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/indic-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/indic-normalization/印度语系归一化过滤器 # indic_normalization 词元过滤器对印度语系（Indic）文本进行 Unicode 归一化，统一各印度语系脚本中字符的多种表示形式。它是孟加拉语、印地语等语言归一化的基础层。 归一化规则 # 处理 说明 Unicode 分解与合成 将组合字符序列转为标准的预组合形式（NFC 归一化） 零宽字符清理 移除零宽连接符（ZWJ）和零宽非连接符（ZWNJ） Nukta 统一 将 base + nukta 两码点序列合并为等价的单码点字符 变体编码统一 统一不同 Unicode 编码表示的相同字符 使用示例 # PUT my-indic-index { "settings": { "analysis": { "filter": { "indic_norm": { "type": "indic_normalization" } }, "analyzer": { "my_indic": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "indic_norm"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["indic_normalization"], "text": "हिन्दी" } 参数 # 此过滤器不接受任何参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/turkish-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/turkish-stem/土耳其语词干过滤器 # turkish_stemmer 词元过滤器使用 Snowball 算法对土耳其语文本进行词干提取。 功能说明 # 土耳其语是黏着语，一个词可以有多层后缀。此词干提取器移除常见的名词格后缀、所有格后缀和动词变位后缀。 注意：土耳其语有特殊的大小写规则（İ↔i、I↔ı），需要搭配 turkish_lowercase 过滤器。 使用示例 # PUT my-turkish-index { "settings": { "analysis": { "filter": { "tr_stem": { "type": "stemmer", "language": "turkish" } }, "analyzer": { "my_turkish": { "type": "custom", "tokenizer": "standard", "filter": ["apostrophe", "turkish_lowercase", "tr_stem"] } } } } } 测试效果 # GET /_analyze { "analyzer": "turkish", "text": "programcıların programlama" } 参数 # 参数 值 说明 type stemmer 过滤器类型 language turkish 指定土耳其语 Snowball 词干算法 在语言分析器中的位置 # 土耳其语分析器 内置了此过滤器，搭配 apostrophe 和 turkish_lowercase。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/serbian-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/serbian-normalization/塞尔维亚语归一化过滤器 # serbian_normalization 词元过滤器将塞尔维亚语西里尔字母转写为对应的拉丁字母形式，使两种书写系统的文本在搜索时可以互相匹配。 归一化规则 # 塞尔维亚语同时使用西里尔字母和拉丁字母，此过滤器将西里尔形式统一为拉丁形式： 西里尔字母 拉丁字母 西里尔字母 拉丁字母 а a п p б b р r в v с s г g т t д d ћ ć ђ đ у u е e ф f ж ž х h з z ц c и i ч č ј j џ dž к k ш š л l љ lj м m њ nj н n о o 使用示例 # PUT my-serbian-index { "settings": { "analysis": { "filter": { "serbian_norm": { "type": "serbian_normalization" } }, "analyzer": { "my_serbian": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "serbian_norm"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["serbian_normalization"], "text": "Београд" } 响应中 Београд（西里尔）→ Beograd（拉丁）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/backup-restore/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/backup-restore/备份与恢复 # 副本提供了高可用性，但无法防御灾难性故障（如误删除、数据损坏、机房级故障）。快照（Snapshot） 是 Easysearch 的备份机制，提供完整的数据保护能力。 快照机制概述 # 核心特点 # 增量备份：首次快照是全量备份，后续快照只保存变化的数据 不阻塞写入：快照过程不会阻止正常的索引和搜索操作 支持多种存储：共享文件系统、S3、HDFS、Azure Blob 等 灵活恢复：可恢复到同一集群或不同集群，支持重命名 工作流程 # ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ 创建仓库 │───▶│ 执行快照 │───▶│ 恢复数据 │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ ▼ ▼ ▼ 配置存储位置 选择索引范围 选择目标索引 设置访问权限 等待快照完成 可重命名恢复 创建快照仓库 # 快照需要先配置一个仓库（Repository），仓库定义了快照的存储位置。 共享文件系统仓库 # 前提条件： 所有节点都能访问同一个共享目录（NFS、GlusterFS 等） 在 easysearch.yml 中配置允许的路径： path.repo: ["/mount/backups", "/mount/snapshots"] 创建仓库：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/bengali-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/bengali-normalization/孟加拉语归一化过滤器 # bengali_normalization 词元过滤器对孟加拉语（বাংলা）文本进行 Unicode 归一化，统一字符的多种表示形式。 归一化规则 # 处理 说明 Nukta 合成 将 base + nukta 组合转为对应的预组合字符 变体统一 统一视觉上相同但编码不同的字符 印度语系通用归一化 在 indic_normalization 基础上进一步处理 使用示例 # PUT my-bengali-index { "settings": { "analysis": { "filter": { "bengali_norm": { "type": "bengali_normalization" } }, "analyzer": { "my_bengali": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "indic_normalization", "bengali_norm"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["bengali_normalization"], "text": "বাংলাদেশ" } 参数 # 此过滤器不接受任何参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/security-and-multi-tenancy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/security-and-multi-tenancy/安全与多租户最佳实践 # 这页不讲具体配置字段，而是从“安全架构设计”的角度，回答几个问题： Easysearch 集群应该如何接入现有身份体系（认证）？ 权限应该怎么分层：集群、索引、文档、字段？ 多租户与业务隔离应该选什么模式？ 审计与运维流程里，Easysearch 扮演什么角色？ 具体配置与 API 细节，请以参考手册中的安全模块文档为准。 1. 认证：尽量接到现有身份系统上 # 推荐优先考虑的几种接入方式： 企业已有的 SSO / LDAP / AD / OIDC 等身份源 统一网关/反向代理（如 API Gateway / Ingress）前置认证，Easysearch 侧主要做鉴权 在 Easysearch 安全模块中： 通过配置后端（backend）连接外部身份源 使用角色映射将“后端角色”转换为 Easysearch 内部的“安全角色” 实践建议： 尽量避免在 Easysearch 里维护大量“本地用户”，而是以少量系统账号 + 外部身份源为主 为自动任务（备份、同步、监控等）单独准备技术账号与角色，避免用人类账号跑程序 2. 授权：从粗到细分层设计 # 可以从外到内分三层思考权限模型： 集群级：谁能做集群管理操作（如创建索引、调整设置、管理快照） 索引级：谁能读/写哪些索引（按业务域、租户、环境划分） 文档/字段级：在同一索引内，不同用户/角色是否看到不同的数据/字段 结合 Easysearch 的安全功能： 使用 角色 来封装一组权限（cluster + indices + document/field level） 对于跨多个索引的权限，可以用索引模式（如 logs-*, orders-*）来归并 实践建议：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/update_password/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/update_password/密码修改 # Easysearch Operator 将集群密码保存在 Kubernetes Secret 中。修改密码只需更新 Secret，Operator 会自动检测变更并应用。 操作步骤 # 查看现有 Secret kubectl get secret threenodes-admin-password -o yaml 创建或修改密码 Secret 文件 apiVersion: v1 kind: Secret metadata: name: threenodes-admin-password type: Opaque data: # admin（base64 编码） username: YWRtaW4= # admin123（base64 编码） password: YWRtaW4xMjM= 提示：使用 echo -n "your_password" | base64 生成 base64 编码值。 应用修改 kubectl apply -f admin-credentials-secret.yaml 自动生效流程 # Operator 感知到 threenodes-admin-password Secret 变更后：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/brazilian-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/brazilian-stem/巴西葡萄牙语词干过滤器 # brazilian_stemmer 词元过滤器对巴西葡萄牙语文本进行词干提取，使用 Lucene 的 BrazilianStemmer 算法。 功能说明 # 与通用葡萄牙语词干提取不同，此过滤器专门针对巴西葡萄牙语的特点进行优化： 处理巴西特有的动词变位形式 移除名词/形容词的阴阳性和单复数后缀 处理副词后缀 -mente 使用示例 # PUT my-brazilian-index { "settings": { "analysis": { "filter": { "br_stem": { "type": "stemmer", "language": "brazilian" } }, "analyzer": { "my_brazilian": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "br_stem"] } } } } } 测试效果 # GET /_analyze { "analyzer": "brazilian", "text": "brasileiros programação" } 参数 # 参数 值 说明 type stemmer 过滤器类型 language brazilian 指定巴西葡萄牙语词干算法 在语言分析器中的位置 # 巴西葡萄牙语分析器 内置了此过滤器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/german-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/german-normalization/德语归一化过滤器 # german_normalization 词元过滤器将德语特有的元音变音和 ß 归一化为 ASCII 等价形式。 归一化规则 # 原始 归一化 说明 ä a 元音变音归一化 ö o 元音变音归一化 ü u 元音变音归一化 Ä A 大写变音归一化 Ö O 大写变音归一化 Ü U 大写变音归一化 ß ss 双 s 替换 注意：这与 ae → a 不同。此过滤器只处理变音符号字符本身，不处理 ae/oe/ue 的拼写变体。 使用示例 # PUT my-german-index { "settings": { "analysis": { "filter": { "german_norm": { "type": "german_normalization" } }, "analyzer": { "my_german": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "german_norm", "german_stemmer"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["german_normalization"], "text": "Straße Übung Ärger" } 响应中 Straße → strasse、Übung → ubung、Ärger → arger。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/german-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/german-stem/德语词干过滤器 # german_light_stem 词元过滤器使用轻量级算法对德语文本进行词干提取。 功能说明 # Easysearch 提供多种德语词干算法： 算法 language 值 说明 轻量级 light_german 默认，最保守 最小化 minimal_german 只处理复数 Snowball german 标准 Snowball 算法 Snowball2 german2 改进的 Snowball 使用示例 # PUT my-german-index { "settings": { "analysis": { "filter": { "de_stem": { "type": "stemmer", "language": "light_german" } }, "analyzer": { "my_german": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "german_normalization", "de_stem"] } } } } } 测试效果 # GET /_analyze { "analyzer": "german", "text": "Programmierung Programmierer Programme" } 参数 # 参数 值 说明 type stemmer 过滤器类型 language light_german / minimal_german / german / german2 选择词干算法 在语言分析器中的位置 # 德语分析器 内置了 light_german 词干提取器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/split-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/split-index/拆分索引 # 拆分操作将一个索引的分片数增加为原来的整数倍，适用于需要扩展写入吞吐量的场景。 操作步骤 # 进入索引列表：在「索引」页面，找到需要拆分的源索引（如 testing_index_creation）。 打开操作菜单：点击该索引行「操作」列的更多按钮（...），在下拉菜单中选择「拆分索引」。 完成前置只读设置：在弹出的「拆分索引」窗口中，点击「设为只读」，将源索引切换为只读状态，确保拆分过程数据一致。 配置拆分参数： 新索引名：填写拆分后新索引的名称（系统默认生成后缀为 -split 的名称，可自定义修改）。 目标分片数：设置新索引的分片数（必须为源索引分片数的整数倍，可通过滑块或方向键调整）。 副本数：按需设置新索引的副本数（默认值为 1）。 设置别名：可选开启，为新索引配置别名。 执行拆分操作：参数配置完成后，点击「确定」，系统开始执行索引拆分。 恢复源索引读写：拆分成功后，在提示窗口中勾选「恢复源索引读写」，点击「确定」，将源索引恢复为正常读写状态。 查看操作结果：操作完成后，索引列表中将新增拆分后的新索引（如 testing_index_creation-split），代表拆分操作成功。 注意事项 # 目标分片数必须是源索引分片数的整数倍（例如源索引有 1 个分片，可拆分为 2、4、8 等），否则操作将失败。 拆分操作同样要求源索引处于只读状态，完成后请及时恢复源索引的读写。 拆分后的新索引是一个独立的索引，与源索引互不影响。 拆分操作的耗时和资源消耗与索引大小成正比，建议在业务低峰期执行。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/czech-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/czech-stem/捷克语词干过滤器 # czech_stemmer 词元过滤器使用 Lucene 的轻量级捷克语词干算法，移除捷克语常见的形态后缀。 功能说明 # 此过滤器使用轻量级算法，适度移除名词格变化和动词变位后缀，在词干精度和召回率之间取得平衡。 使用示例 # PUT my-czech-index { "settings": { "analysis": { "filter": { "czech_stem": { "type": "stemmer", "language": "czech" } }, "analyzer": { "my_czech": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "czech_stem"] } } } } } 测试效果 # GET /_analyze { "analyzer": "czech", "text": "programátorů programování" } 参数 # 参数 值 说明 type stemmer 过滤器类型 language czech 指定捷克语词干算法 在语言分析器中的位置 # 捷克语分析器 内置了此过滤器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/scandinavian-folding/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/scandinavian-folding/斯堪的纳维亚字符折叠过滤器 # scandinavian_folding 词元过滤器将斯堪的纳维亚语言中互换使用的字符统一归一化。 折叠规则 # 原始字符 折叠为 涉及语言 å a 瑞典语、丹麦语、挪威语 ä, æ a 瑞典语(ä) / 丹麦语、挪威语(æ) ö, ø o 瑞典语(ö) / 丹麦语、挪威语(ø) 与 scandinavian_normalization 的区别：scandinavian_normalization 只折叠互换字符对（如 ä↔æ），而 scandinavian_folding 还会进一步折叠到 ASCII 基础字符（如 å→a）。 使用示例 # PUT my-scandi-index { "settings": { "analysis": { "filter": { "scandi_fold": { "type": "scandinavian_folding" } }, "analyzer": { "my_scandi": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "scandi_fold"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["scandinavian_folding"], "text": "räksmörgås" } 响应中 räksmörgås → raksmørgas 或 raksmorgas（取决于折叠层级）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/scandinavian-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/scandinavian-normalization/斯堪的纳维亚归一化过滤器 # scandinavian_normalization 词元过滤器将斯堪的纳维亚语言中互换使用的字符对统一为一种形式，使跨语言搜索更一致。 归一化规则 # 原始字符 归一化为 说明 ä æ 瑞典语 ä → 丹麦语/挪威语 æ ö ø 瑞典语 ö → 丹麦语/挪威语 ø Ä Æ 大写同理 Ö Ø 大写同理 与 scandinavian_folding 的区别：scandinavian_normalization 只统一互换字符对（ä↔æ, ö↔ø），不会折叠到 ASCII 基础字符。而 scandinavian_folding 会进一步折叠为 a、o 等 ASCII 字符。 使用示例 # PUT my-scandi-index { "settings": { "analysis": { "filter": { "scandi_norm": { "type": "scandinavian_normalization" } }, "analyzer": { "my_scandi": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "scandi_norm"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["scandinavian_normalization"], "text": "räksmörgås" } 响应中 räksmörgås → pair ræksmørgås（ä→æ, ö→ø，但 å 保持不变）。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/create-policy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/create-policy/新增策略 # 通过新增备份策略，可以按计划自动执行备份任务。 操作步骤 # 进入备份策略页面：登录 Easysearch UI，在左侧导航栏点击「备份管理」，切换至「策略」标签页。 打开新增策略弹窗：点击页面右上角的「+ 新增」按钮，弹出「新增策略」配置窗口。 配置备份策略信息： 填写必填项「名称」，自定义策略标识（如 test_strategy）。 选择「存储库」，指定备份数据的存储位置（如 test_repository）。 配置「快照设置」：可选择是否备份所有索引，设置包含/排除的索引模式，按需开启「包含集群状态」「忽略不可用索引」「允许部分快照」等开关。 - 配置「备份计划」：选择时区，填写 Cron 表达式，设置备份执行周期（如在整点后的第30分钟执行）。 - 配置「备份删除规则」：设置备份的保留时长（如7天后删除）、最多/最少保留份数。 确认创建：所有配置完成后，点击「确定」按钮。 查看新增结果：配置成功后，新的备份策略将出现在策略列表中，可查看其名称、存储库、备份计划、下次运行时间和状态等信息。 注意事项 # 备份策略依赖已配置的存储库，创建前请确保存储库已正常配置并可访问。 Cron 表达式需正确配置，避免备份周期不符合预期。 备份删除规则会自动清理过期备份，需根据业务需求合理设置保留份数和时长，防止数据丢失。 策略创建后默认启用，如需暂停可在列表中关闭状态开关。https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/time-series/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/time-series/时间序列建模 # 时间序列数据（如日志、指标、事件流）是 Easysearch 的常见用例。这类数据有几个特点：文档数量快速增长、基本不更新、主要查询最近的数据。本页介绍如何为时间序列数据设计索引结构。 时间序列数据的特点 # 与传统的搜索场景不同，时间序列数据有以下特点： 文档数量快速增长：日志、指标等数据持续写入，不会停顿 文档基本不更新：写入后很少修改，主要是追加 查询集中在最近数据：大多数查询关注最近几小时、几天或几周的数据 旧数据逐渐失去价值：随着时间推移，旧数据的查询频率降低 按时间范围索引 # 如果我们为此种类型的文档建立一个超大索引，我们可能会很快耗尽存储空间。日志事件会不断的进来，不会停顿也不会中断。 我们可以使用 scroll 查询和批量删除来删除旧的事件。但这种方法非常低效。当你删除一个文档，它只会被标记为被删除。在包含它的段被合并之前不会被物理删除。 替代方案是，我们使用一个时间范围索引。你可以着手于一个按年的索引 (logs_2014) 或按月的索引 (logs_2014-10)。也许当你的数据变得十分繁忙时，你需要切换到一个按天的索引 (logs_2014-10-24)。删除旧数据十分简单：只需要删除旧的索引。 这种方法有这样的优点，允许你在需要的时候进行扩容。你不需要预先做任何艰难的决定。每天都是一个新的机会来调整你的索引时间范围来适应当前需求。 应用相同的逻辑到决定每个索引的大小上。起初也许你需要的仅仅是每周一个主分片。过一阵子，也许你需要每天五个主分片。这都不重要——任何时间你都可以调整到新的环境。 使用别名管理时间序列索引 # 别名可以帮助我们更加透明地在索引间切换。当创建索引时，你可以将 logs_current 指向当前索引来接收新的日志事件，当检索时，更新 last_3_months 来指向所有最近三个月的索引： POST /_aliases { "actions": [ { "add": { "alias": "logs_current", "index": "logs_2014-10" }}, { "remove": { "alias": "logs_current", "index": "logs_2014-09" }}, { "add": { "alias": "last_3_months", "index": "logs_2014-10" }}, { "remove": { "alias": "last_3_months", "index": "logs_2014-07" }} ] } 这样，写入操作始终使用 logs_current 别名，查询操作可以使用 last_3_months 别名来查询最近三个月的数据。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/time-series/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/data-retention/time-series/时间序列索引优化 # 最低版本：1.12.1 概述 # 在处理时序数据（如日志、监控指标、事件流）时，数据通常具有明显的时间先后顺序。Easysearch 底层的 Lucene Segment 合并是保证搜索性能和资源效率的关键操作。 然而，默认的合并策略（TieredMergePolicy）主要基于 Segment 的大小和删除文档比例来决定合并哪些 Segment，它并不感知数据的时间属性。 对于时序场景，默认策略可能导致： 冷热数据混合合并：较旧的（冷）数据 Segment 可能与较新的（热）数据 Segment 合并，导致不必要的 I/O 和 CPU 开销。 查询性能下降：跨时间范围的大 Segment 可能降低按时间范围过滤的查询效率。 为此，Easysearch 引入了基于时间范围的合并策略（TimeRangeMergePolicy），专为时序索引优化 Segment 合并行为。 核心原理 # TimeRangeMergePolicy 在选择要合并的 Segment 时，除了考虑大小、删除比例等因素外，优先考虑 Segment 所覆盖的时间范围： 时间优先：倾向于合并时间上相邻的 Segment，保持数据的"时间局部性"。 保留时间分区：避免将时间跨度很大的 Segment 合并在一起。 优先合并新数据：新写入的数据变化更频繁，优先合并较新的 Segment 有助于更快回收空间和优化查询性能。 工作流程 # 每个 Segment 在创建时记录 min_timestamp 和 max_timestamp。 合并候选按最新时间倒序排列（同一时间的按大小排列）。 候选合并组的评分以时间跨度为主要因子 — 时间跨度越小评分越优。 单次合并限制在 max_merge_at_once 个 Segment 以内，合并后大小不超过 max_merged_segment。 如何启用 # 设置索引的 index.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/pause-cluster-creation/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/pause-cluster-creation/暂停创建进群 # 在集群创建过程中，可以暂停当前的创建流程。 操作步骤 # 进入服务管理页面：在 Agent UI 的「服务管理」页面中，找到状态为「创建中」的目标集群。 打开暂停操作菜单：点击目标集群操作列的「…」按钮，在下拉菜单中选择「暂停」选项。 确认暂停操作：在弹出的确认窗口中，点击「确定」按钮，暂停该创建任务。 验证暂停结果：操作完成后，服务列表中该集群的状态将更新为「创建暂停」，代表暂停成功。 注意事项 # 暂停操作仅对「创建中」状态的集群生效，已创建完成的集群无法执行此操作。 暂停后可随时通过操作菜单恢复创建任务，暂停期间不会影响其他已运行的集群服务。 暂停状态下的创建任务不会自动继续，需手动恢复操作才能完成集群部署。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/disable-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/disable-filter/暂时停用过滤条件 # 暂时停用过滤条件可以在不删除条件的情况下临时取消其过滤效果。 操作步骤 # 唤起操作菜单：在数据探索页面，找到已生效的过滤条件标签（如 _id:nYsUlJ0Bc_MPNLBvYYQh），点击该标签，弹出操作菜单。 执行停用操作：在菜单中选择「暂时停用」，系统将临时关闭该过滤条件的生效逻辑。 查看生效结果： 过滤标签将变为灰色（示例中标签样式弱化显示），标识当前为停用状态； 右侧数据列表将恢复展示该索引下的全部文档记录，过滤条件仅保留配置，未实际生效。 恢复过滤（可选）：如需重新启用，可再次点击该停用标签，选择「重新启用」即可恢复过滤逻辑。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/french-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/french-stem/法语词干过滤器 # french_light_stem 词元过滤器使用 Lucene 的轻量级法语词干算法，移除法语常见的形态后缀。 功能说明 # 法语分析器默认使用轻量级词干提取（light_french），而非 Snowball 算法。轻量级算法更保守： 算法 说明 适用场景 light_french 轻量级，只移除明显后缀 默认推荐 french Snowball 完整词干 更激进的归约 minimal_french 最小化词干 最保守 使用示例 # PUT my-french-index { "settings": { "analysis": { "filter": { "fr_stem": { "type": "stemmer", "language": "light_french" } }, "analyzer": { "my_french": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "elision", "fr_stem"] } } } } } 测试效果 # GET /_analyze { "analyzer": "french", "text": "programmation programmeurs programmes" } 参数 # 参数 值 说明 type stemmer 过滤器类型 language light_french / french / minimal_french 选择词干算法 在语言分析器中的位置 # 法语分析器 内置了 light_french 词干提取器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/persian-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/persian-normalization/波斯语归一化过滤器 # persian_normalization 词元过滤器对波斯语（فارسی）文本进行字符归一化，统一阿拉伯语和波斯语书写变体。 归一化规则 # 处理 说明 阿拉伯语 Yaa → 波斯语 Yaa 统一 ي → ی 阿拉伯语 Kaf → 波斯语 Kaf 统一 ك → ک 变音符号移除 移除阿拉伯语 harakat 标记 搭配 arabic_normalization 建议与 arabic_normalization 一起使用 使用示例 # PUT my-persian-index { "settings": { "analysis": { "filter": { "persian_norm": { "type": "persian_normalization" } }, "analyzer": { "my_persian": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "arabic_normalization", "persian_norm"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["arabic_normalization", "persian_normalization"], "text": "فارسی" } 参数 # 此过滤器不接受任何参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/swedish-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/swedish-stem/瑞典语词干过滤器 # swedish_stemmer 词元过滤器使用 Snowball 算法对瑞典语文本进行词干提取。 功能说明 # Easysearch 提供两种瑞典语词干算法： 算法 language 值 说明 Snowball swedish 标准 Snowball 算法 轻量级 light_swedish 更保守的词干提取 使用示例 # PUT my-swedish-index { "settings": { "analysis": { "filter": { "sv_stem": { "type": "stemmer", "language": "swedish" } }, "analyzer": { "my_swedish": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "sv_stem"] } } } } } 测试效果 # GET /_analyze { "analyzer": "swedish", "text": "programmering programmerare" } 参数 # 参数 值 说明 type stemmer 过滤器类型 language swedish / light_swedish 选择词干算法 在语言分析器中的位置 # 瑞典语分析器 内置了 Snowball 词干提取器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/manage-request-tabs/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/manage-request-tabs/管理请求标签页 # 操作步骤 # 进入开发工具页面：在左侧导航栏点击「开发工具」，进入开发工具编辑页。 新增请求标签页：点击当前标签页右侧的「+」按钮，系统将自动新增一个空白的请求编辑标签页。 切换/关闭标签页：点击对应标签页可在不同请求间切换；点击标签页右侧的「×」按钮，可关闭当前标签页。 补充说明 # 每个标签页独立维护各自的请求语句和响应结果，切换标签页时内容不会丢失。 适合在调试多个接口或对比不同查询结果时使用多标签页并行操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/sorani-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/sorani-normalization/索拉尼语归一化过滤器 # sorani_normalization 词元过滤器对索拉尼库尔德语（سۆرانی）文本进行字符归一化。索拉尼语使用修改后的阿拉伯字母书写。 归一化规则 # 处理 说明 Yaa 归一化 统一 ي/ی 变体 Kaf 归一化 统一 ك/ک 变体 Haa 归一化 统一 haa 变体 变音符号移除 移除可选的变音标记 使用示例 # PUT my-sorani-index { "settings": { "analysis": { "filter": { "sorani_norm": { "type": "sorani_normalization" } }, "analyzer": { "my_sorani": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "sorani_norm", "sorani_stemmer"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["sorani_normalization"], "text": "کوردی" } 参数 # 此过滤器不接受任何参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/gateway/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/gateway/网关与恢复配置 # 本页介绍 easysearch.yml 中与集群完全重启后分片恢复行为相关的配置项。这些都是静态设置，修改后需要重启节点生效。 分片恢复的限流参数（如 indices.recovery.max_bytes_per_sec）属于动态配置，通过 集群配置 API 修改。 为什么需要网关恢复设置？ # 当整个集群重启时，各节点可能以不同的速度启动。如果集群在只有部分节点加入时就立即开始分片恢复，会导致： 不必要的数据搬运：节点 A 先启动，集群把本该在节点 B 上的分片副本重新分配给 A；等 B 启动后又要搬回去。 大量网络 I/O：分片数据在节点间来回传输。 恢复时间变长：所有数据都要重新复制一遍。 网关设置让集群等到足够数量的节点加入后再开始恢复，避免上述问题。 gateway.recover_after_nodes # gateway.recover_after_nodes: 2 项目 说明 参数 gateway.recover_after_nodes 默认值 -1 (禁用) 属性 静态 说明 集群中至少有多少个节点加入后才开始恢复分片。已弃用：建议改用 recover_after_data_nodes 和 recover_after_master_nodes 以获得更精确的控制 推荐值 # 三节点集群：设为 2 一般规则：设为集群总节点数的大多数（$\lceil N/2 \rceil + 1$ 或更大） gateway.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/romanian-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/romanian-stem/罗马尼亚语词干过滤器 # romanian_stemmer 词元过滤器使用 Snowball 算法对罗马尼亚语文本进行词干提取。 功能说明 # 此过滤器移除罗马尼亚语名词的格变化和定冠词后缀，以及动词变位后缀。 使用示例 # PUT my-romanian-index { "settings": { "analysis": { "filter": { "ro_stem": { "type": "stemmer", "language": "romanian" } }, "analyzer": { "my_romanian": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "ro_stem"] } } } } } 测试效果 # GET /_analyze { "analyzer": "romanian", "text": "programarea programatori" } 参数 # 参数 值 说明 type stemmer 过滤器类型 language romanian 指定罗马尼亚语 Snowball 词干算法 在语言分析器中的位置 # 罗马尼亚语分析器 内置了此过滤器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/aggregations-data-analysis/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/fundamentals/aggregations-data-analysis/聚合与数据分析 # 聚合（Aggregations）是 Easysearch 用于做统计与分析的核心能力，可以在一次请求中同时完成"搜索 + 统计"。本页介绍聚合的概念、类型与用法。 聚合可以解决什么问题？ # 典型场景： 统计：总数、平均值、最大/最小值、百分位数 分布：按字段分桶（如按状态、地区、时间段统计数量） 下钻分析：先按大维度分组，再在组内做更细粒度分析 和传统数据库的类比： 可以粗略类比为 GROUP BY + 聚合函数，但聚合可以与全文搜索、过滤等能力组合，且天然适应分布式环境。 聚合请求的基本结构 # 一个最小的"搜索 + 聚合"请求大致长这样： { "query": { "term": { "status": "success" } }, "aggs": { "by_host": { "terms": { "field": "host" } } } } 结构说明： query：决定哪些文档参与统计（可为空，表示全量） aggs：定义一个或多个聚合，每个聚合都有一个名字（如 by_host） 聚合的结果会出现在响应体的 aggregations 区域，与 hits（命中的文档）并列。 桶（Bucket）与指标（Metric） # 大多数聚合可以拆成两类： 桶聚合（Bucket Aggregations）：把文档分到不同"桶"里 例如：按字段值分桶（terms）、按数值区间分桶（range）、按时间间隔分桶（date_histogram）等。 指标聚合（Metric Aggregations）：对某个字段在桶内做统计https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/dutch-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/dutch-stem/荷兰语词干过滤器 # dutch_stemmer 词元过滤器使用 Snowball 算法对荷兰语文本进行词干提取。 功能说明 # 荷兰语词干提取使用 Snowball 算法，结合词干覆盖字典处理不规则变形： 移除常见名词/动词后缀 荷兰语分析器额外使用 stemmer_override 字典处理不规则形式 适合荷兰语和佛兰德语文本 使用示例 # PUT my-dutch-index { "settings": { "analysis": { "filter": { "dutch_stem": { "type": "stemmer", "language": "dutch" } }, "analyzer": { "my_dutch": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "dutch_stem"] } } } } } 测试效果 # GET /_analyze { "analyzer": "dutch", "text": "programma's programmering" } 参数 # 参数 值 说明 type stemmer 过滤器类型 language dutch 指定荷兰语 Snowball 词干算法 可选的 dutch_kp 变体使用 Krovetz-Porter 混合算法。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/ccr/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/ccr/跨集群复制（CCR） # Easysearch 跨集群复制（Cross-Cluster Replication, CCR）支持将数据从源集群（Leader）实时同步到一个或多个目标集群（Follower）。 使用跨集群复制 API 管理跨集群复制。 在跨集群复制中，可以将数据索引到一个领导者索引，然后 Easysearch 将这些数据复制到一个或多个只读的跟随者索引。所有在领导者上进行的后续操作都会在跟随者上复制，例如创建、更新或删除文档。 先决条件 # 1.11.1 版本之前，leader 和 follower 集群都必须安装 cross-cluster-replication 插件和 index-management 插件，1.11.1 版本开始，已经内置了 cross-cluster-replication 模块。 从1.15.2版本开始，cross-cluster-replication 和 index-management 都已经内置到 modules，不再需要安装。 如果 follower 集群的 easysearch.yml 文件中覆盖了 node.roles，确保它也包括 remote_cluster_client 角色，默认启用。 node.roles: [<other_roles>, remote_cluster_client] 权限 # 确保安全功能在两个集群上都启用或都禁用。如果启用了安全功能，确保非管理员用户被映射到适当的权限，以便他们可以执行复制操作。 部署示例集群 # 在本地起 2 个单节点的 easysearch 测试集群，分别是 follower-application (9201 端口) 和 leader-application (9200 端口) 在 easysearch.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/arabic-normalization/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/arabic-normalization/阿拉伯语归一化过滤器 # arabic_normalization 词元过滤器对阿拉伯语文本进行正字法归一化，将各种书写变体统一为标准形式，提高搜索的召回率。 归一化规则 # 原始形式 归一化结果 说明 \u0623 \u0625 \u0622 (带 hamza 的 alef) \u0627 (bare alef) 统一 alef 变体 \u0629 (taa marbuta) \u0647 (haa) 统一词尾形式 \u064e \u064f \u0650 \u064b \u064c \u064d (harakat) 删除 移除变音符号 \u0640 (tatweel/kashida) 删除 移除装饰性延长符 使用示例 # PUT my-arabic-index { "settings": { "analysis": { "filter": { "arabic_norm": { "type": "arabic_normalization" } }, "analyzer": { "my_arabic": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "arabic_norm"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["arabic_normalization"], "text": "\u0625\u0628\u0631\u0627\u0647\u064a\u0645" } 参数 # 此过滤器不接受任何参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/arabic-stem/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/arabic-stem/阿拉伯语词干过滤器 # arabic_stemmer 词元过滤器使用 Lucene 的 ArabicStemmer 对阿拉伯语词元进行词干提取，去除常见的前缀和后缀。 词干规则 # 此词干提取器基于 Shereen Khoja 的轻量级方法，处理以下词缀： 类型 示例 定冠词前缀 ال (al-) 介词前缀 و (wa-), ب (bi-), ك (ka-) 代词后缀 ها, هم, هن 等 阴性/双数/复数后缀 ة, ات, ين 等 使用示例 # PUT my-arabic-index { "settings": { "analysis": { "filter": { "arabic_stem": { "type": "stemmer", "language": "arabic" } }, "analyzer": { "my_arabic": { "type": "custom", "tokenizer": "standard", "filter": ["lowercase", "arabic_normalization", "arabic_stem"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": ["arabic_normalization", "stemmer"], "text": "الكتابات" } 参数 # 通过 stemmer 过滤器使用时：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/configuration/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/configuration/集群配置 # 本文介绍通过集群设置 API 管理 Easysearch 集群级别配置的方式，包括动态设置的查看、修改、重置，以及可通过 API 调整的全部动态配置项参考。 节点级别的静态配置（需要写在 easysearch.yml 中、重启后生效的配置）请参见 节点配置。 集群设置 API # 大多数集群级调优参数都可以通过集群设置 API 在运行时更改，无需重启节点。 查看设置 # # 查看所有设置（包含默认值） GET _cluster/settings?include_defaults=true # 仅查看用户自定义设置 GET _cluster/settings 设置优先级 # 集群设置 API 中存在三类设置：持久（Persistent）、临时（Transient）和默认（Default）。 优先级从高到低： Transient 设置 — 临时，集群重启后丢失 Persistent 设置 — 持久，跨重启保留 配置文件 easysearch.yml 默认值 推荐做法：节点相关配置放 easysearch.yml，集群范围的调优通过 API 以 persistent 方式修改，避免每个节点单独改配置文件。 修改设置 # // 持久化修改（推荐用于集群调优） PUT /_cluster/settings { "persistent": { "action.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/highlighting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/highlighting/高亮 # 高亮用于在返回结果中标记命中的文本片段，提升可读性。Easysearch 在搜索阶段记录哪些文本片段匹配了查询，在返回阶段根据这些信息对原文做截取与包裹（例如 <em>...</em> 标签）。 基本用法 # GET /articles/_search { "query": { "match": { "content": "搜索 引擎" } }, "highlight": { "fields": { "content": {} } } } 返回结果中每条命中文档会包含 highlight 字段： { "hits": { "hits": [ { "_source": { "content": "Easysearch 是一款高性能的搜索引擎..." }, "highlight": { "content": [ "Easysearch 是一款高性能的<em>搜索</em><em>引擎</em>..." ] } } ] } } 三种高亮器类型 # Easysearch 支持三种高亮器，通过 type 参数指定： 类型 说明 优缺点 unified（默认） 基于 Lucene Unified Highlighter，使用 BM25 对片段评分 推荐首选。支持所有字段类型，性能与准确性平衡最佳 plain 基于标准 Lucene Highlighter，逐词高亮 小文本场景尚可，大文本或复杂查询时性能较差 fvh Fast Vector Highlighter，需要 term_vector 设置为 with_positions_offsets 大文本高亮最快，但需要额外索引存储 使用 FVH 高亮器 # PUT /articles { "mappings": { "properties": { "content": { "type": "text", "term_vector": "with_positions_offsets" } } } } GET /articles/_search { "query": { "match": { "content": "搜索 引擎" } }, "highlight": { "type": "fvh", "fields": { "content": {} } } } 常用参数 # GET /articles/_search { "query": { "match": { "content": "搜索 引擎" } }, "highlight": { "pre_tags": ["<strong>"], "post_tags": ["</strong>"], "fields": { "content": { "fragment_size": 150, "number_of_fragments": 3, "no_match_size": 100 }, "title": { "number_of_fragments": 0 } } } } 参数速查 # 参数 类型 默认值 说明 pre_tags String[] ["<em>"] 高亮前标签 post_tags String[] ["</em>"] 高亮后标签 fragment_size Integer 100 每个片段的字符数 number_of_fragments Integer 5 每字段返回的最大片段数。设为 0 返回整个字段 no_match_size Integer 0 无匹配时从字段开头返回的字符数 type String "unified" 高亮器类型：unified、plain、fvh order String - 设为 "score" 按相关性排序片段 require_field_match Boolean true 只高亮查询匹配到的字段 encoder String "default" "default" 或 "html"（对 HTML 特殊字符编码） highlight_query Object - 使用不同于搜索查询的查询来做高亮 boundary_scanner String "sentence"（unified）/ "chars"（plain/fvh） 边界扫描器：chars、word、sentence boundary_chars String ".https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/loongson/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/loongson/龙芯平台安装 # 龙芯平台介绍 # 龙芯平台基于自主指令集架构（LoongArch），完全自主研发，不依赖国外技术，广泛应用于信创桌面、服务器及工控领域，强调安全可控与生态自主。 龙芯平台安装参考 # 目前，Easysearch 已支持在龙芯芯片的国产操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.infini.cloud | bash -s -- -p easysearch -d /opt/easysearch # 进入 Easysearch 目录 cd /opt/easysearch # 初始化 Easysearch bin/initialize.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-distance/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-distance/Geo Distance 查询 # 地理距离查询返回 geo_point 字段值位于指定中心点给定距离范围内的文档。如果一个文档包含多个地理坐标点，只要至少有一个点在距离范围内，该文档就匹配。 参考样例 # 创建一个映射，将 point 字段映射为 geo_point ： PUT testindex1 { "mappings": { "properties": { "point": { "type": "geo_point" } } } } 索引一个地理点，指定其纬度和经度： PUT testindex1/_doc/1 { "point": { "lat": 74.00, "lon": 40.71 } } 搜索距离指定的 point 内包含指定 distance 对象的文档： GET /testindex1/_search { "query": { "bool": { "must": { "match_all": {} }, "filter": { "geo_distance": { "distance": "50mi", "point": { "lat": 73.5, "lon": 40.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/index-analyzers/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/index-analyzers/索引分词器 # 索引分词器是在索引创建时指定的，在文档写入时对文本字段进行分词。 写入索引分词器的生效流程 # 为了确定在对文档建立索引时对某个字段使用哪种分词器，Easysearch 会按以下顺序检查以下参数： 字段的分词器映射参数，即analyzer analysis.analyzer.default 索引设置 standard标准分词器（默认分词器） 在指定索引分词器时，请记住，在大多数情况下，为索引中的每个文本字段指定一个分词器效果最佳。使用相同的分词器在文本字段（在建立索引时）和查询字符串（在查询时），可确保搜索所使用的词项与存储在索引中的词项相同。 为字段指定索引分词器 # 在创建索引映射时，可以为每个文本字段提供 analyzer（分词器）参数。例如，以下请求为 text_entry 字段指定了 simple 简单分词器： PUT testindex { "mappings": { "properties": { "text_entry": { "type": "text", "analyzer": "simple" } } } } 为索引指定默认索引分词器 # 如果想对索引中的所有文本字段使用相同的分词器，则可以在索引设置中按如下方式进行指定analysis.analyzer.default： PUT testindex { "settings": { "analysis": { "analyzer": { "default": { "type": "simple" } } } } } 如果您未指定默认分词器，那么将使用standard标准分词器。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-polygon/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-polygon/Geo Polygon 查询 # 地理多边形查询返回 geo_point 字段值位于指定多边形内的文档。如果一个文档包含多个地理坐标点，只要至少有一个点在多边形内，该文档就匹配。 多边形通过坐标顶点列表指定，不需要闭合（首尾相同不是必须的），但建议按顺时针或逆时针顺序列出。 参考样例 # 创建一个映射，将 point 字段映射为 geo_point ： PUT /testindex1 { "mappings": { "properties": { "point": { "type": "geo_point" } } } } 索引一个地理点，指定其纬度和经度： PUT testindex1/_doc/1 { "point": { "lat": 73.71, "lon": 41.32 } } 搜索包含指定 geo_polygon 的 point 对象的文档： GET /testindex1/_search { "query": { "bool": { "must": { "match_all": {} }, "filter": { "geo_polygon": { "point": { "points": [ { "lat": 74.https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/dangling-indices/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/data-management/dangling-indices/悬挂索引（Dangling Indices） # 什么是悬挂索引 # 悬挂索引是指存在于节点本地磁盘上，但不属于当前集群状态的索引。这种情况通常发生在： 节点离线期间，集群中其他节点删除了某个索引 节点从一个集群迁移到另一个集群 快照恢复失败或中断 集群状态丢失后重建 当节点重新加入集群时，它本地存储的这些"孤立"索引分片就成为悬挂索引。 自动导入 # 可以通过集群设置控制是否自动导入悬挂索引： # easysearch.yml gateway.auto_import_dangling_indices: false # 默认值：false 注意：自动导入默认关闭。在生产环境中，建议保持关闭，手动检查并决定是否导入，以避免意外引入过期或不需要的数据。 API 操作 # 列出悬挂索引 # GET /_dangling 响应示例： { "dangling_indices": [ { "index_name": "my_old_index", "index_uuid": "r1eSJ3MoTheHQ2CvFoVrOg", "creation_date_millis": 1609459200000, "node_ids": ["node-1"] } ] } 导入悬挂索引 # 使用索引 UUID 将悬挂索引导入到集群中： POST /_dangling/r1eSJ3MoTheHQ2CvFoVrOg?accept_data_loss=true accept_data_loss=true 参数是必须的，表示您已了解导入可能存在数据不一致的风险。 删除悬挂索引 # 不需要的悬挂索引可以直接删除： DELETE /_dangling/r1eSJ3MoTheHQ2CvFoVrOg?accept_data_loss=true 操作建议 # 场景 建议操作 节点短暂离线后重新加入 检查索引内容后决定是否导入 集群迁移残留数据 确认数据已在新集群中恢复后删除 集群状态丢失重建 列出所有悬挂索引，逐一导入恢复 来源不明的悬挂索引 谨慎处理，建议先备份再决定 注意事项 # 导入悬挂索引不会自动恢复副本分片，需要等待集群自行分配 如果集群中已存在同名索引（但 UUID 不同），导入会失败 悬挂索引的映射和设置保持离线前的状态，可能与当前集群配置不兼容 建议在导入前通过 _dangling API 检查索引的创建时间，确认是否是期望的数据https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/search-analyzers/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/analyzers/search-analyzers/搜索分词器 # 搜索分词器是在查询时指定的，当你对text字段进行全文匹配查询时，它会被用于分析被查询字符串。 搜索分词器的生效流程 # 在查询时确定对查询字符串使用哪种分词器，Easysearch 会按以下顺序检查以下参数： 查询的 analyzer 参数 字段的 search_analyzer 映射参数 索引设置 analysis.analyzer.default_search 字段的 analyzer 映射参数 standard 分词器（默认分词器） 在大多数情况下，没有必要指定与索引分词器不同的搜索分词器，而且这样做可能会对搜索结果的相关性产生负面影响，或者导致出现意想不到的搜索结果。 为查询内容指定搜索分词器 # 在查询时，你可以在 analyzer 字段中指定想要使用的分词器： GET shakespeare/_search { "query": { "match": { "text_entry": { "query": "speak the truth", "analyzer": "english" } } } } 为字段指定搜索分词器 # 在创建索引映射时，你可以为每个文本字段提供 search_analyzer 参数。在提供 search_analyzer 时，你还必须提供 analyzer 参数，该参数指定在索引创建时的写入索引分词器内应用。 例如，以下请求将 simple 分词器指定为 text_entry 字段的索引分词器，将 whitespace 分词器指定为该字段的搜索分词器： PUT testindex { "mappings": { "properties": { "text_entry": { "type": "text", "analyzer": "simple", "search_analyzer": "whitespace" } } } } 为索引指定默认的搜索分词器 # 如果你希望在搜索时使用同一个分词器来解析所有的查询，你可以在 analysis.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-shape-query/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-shape-query/Geo Shape 查询 # 地理形状查询用于搜索 geo_point 或 geo_shape 字段的文档。可以使用查询中内联定义的形状，或引用预索引的形状来过滤文档。 空间关系 # 当您向地理形状查询提供地理形状时，文档中的地理点和地理形状字段将使用以下空间关系与提供的形状进行匹配。 关系 描述 支持地理字段类型 INTERSECTS （默认）匹配与查询中提供的形状相交的 geopoint 或 geoshape 的文档。 geo_point, geo_shape DISJOINT 匹配与查询中提供的形状不相交的 geoshape 的文档。 geo_shape WITHIN 匹配完全位于查询中提供的形状内的 geoshape 的文档。 geo_shape CONTAINS 匹配完全包含查询中提供的形状的文档。 geo_shape 在 geoshape 查询中定义形状 # 您可以在 geoshape 查询中通过在查询时提供新的形状定义或引用另一个索引中预先索引的形状名称来定义形状以过滤文档。 使用新的形状定义 # 为了向地理形状查询提供新的形状，请在 geo_shape 字段中定义它。您必须以 GeoJSON 格式定义地理形状。https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/tasks/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/tasks/任务管理 # 任务是在集群中运行的任何操作。例如，搜索图书数据集以查找标题或作者姓名是一项任务。将自动创建任务以监视集群的运行状况和性能。有关集群中当前执行的所有任务的详细信息，可以使用 tasks API 操作。 以下请求返回有关所有任务的信息： GET _tasks 通过包含任务 ID，您可以获得特定任务的信息。请注意，任务 ID 由节点的标识字符串和任务的数字 ID 组成。例如，如果节点的标识串是 nodestring ，任务的数字标识是 1234 ，则任务 ID 是 nodestring:1234 。您可以通过运行 tasks 操作来查找此信息。 GET _tasks/<task_id> 请注意，如果任务完成运行，它将不会作为请求的一部分返回。对于一个需要稍长时间才能完成的任务的示例，可以在较大的文档上运行 _reindex API 操作，然后运行 tasks 。 响应示例 { "nodes": { "Mgqdm0f9SEGClWxp_RdnaQ": { "name": "easy-node1", "transport_address": "30.18.0.3:9300", "host": "30.18.0.3", "ip": "30.18.0.3:9300", "roles": ["data", "ingest", "master", "remote_cluster_client"], "tasks": { "Mgqdm0f9SEGClWxp_RdnaQ:17416": { "node": "Mgqdm0f9SEGClWxp_RdnaQ", "id": 17416, "type": "transport", "action": "cluster:monitor/tasks/lists", "start_time_in_millis": 1613599752458, "running_time_in_nanos": 994000, "cancellable": false, "headers": {} }, "Mgqdm0f9SEGClWxp_RdnaQ:17413": { "node": "Mgqdm0f9SEGClWxp_RdnaQ", "id": 17413, "type": "transport", "action": "indices:data/write/bulk", "start_time_in_millis": 1613599752286, "running_time_in_nanos": 30846500, "cancellable": false, "parent_task_id": "Mgqdm0f9SEGClWxp_RdnaQ:17366", "headers": {} }, "Mgqdm0f9SEGClWxp_RdnaQ:17366": { "node": "Mgqdm0f9SEGClWxp_RdnaQ", "id": 17366, "type": "transport", "action": "indices:data/write/reindex", "start_time_in_millis": 1613599750929, "running_time_in_nanos": 1529733100, "cancellable": true, "headers": {} } } } } } 您还可以在查询中使用以下参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/icu-collation/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/icu-collation/ICU 排序过滤器 # icu_collation_keyword 词元过滤器使用 ICU 排序规则将词元转换为排序键（collation key），实现语言感知的排序和范围查询。 前提条件 # 需要安装 analysis-icu 插件： bin/easysearch-plugin install analysis-icu 功能说明 # 此过滤器将文本词元转换为 ICU CollationKey 的字节表示。转换后的词元可用于： 语言感知排序：按特定语言的排序规则排列结果 范围查询：在 keyword 字段上执行符合语言习惯的范围过滤 重音/大小写不敏感匹配：通过调整排序强度控制匹配精度 使用示例 # 基本用法 — 德语排序 # PUT my-german-sort { "settings": { "analysis": { "filter": { "german_collation": { "type": "icu_collation_keyword", "language": "de", "country": "DE" } }, "analyzer": { "german_sort": { "type": "custom", "tokenizer": "keyword", "filter": ["german_collation"] } } } }, "mappings": { "properties": { "name": { "type": "text", "fields": { "sort": { "type": "keyword", "analyzer": "german_sort" } } } } } } 忽略重音的匹配 # PUT my-accent-insensitive { "settings": { "analysis": { "filter": { "collation_primary": { "type": "icu_collation_keyword", "language": "en", "strength": "primary" } } } } } 参数 # 参数 类型 说明 language string ICU 语言代码（如 de, fr, zh） country string ICU 国家代码（如 DE, FR） strength string 排序强度：primary（忽略重音+大小写）、secondary（区分重音）、tertiary（区分大小写）、quaternary、identical decomposition string Unicode 分解模式：no、canonical alternate string 空白/标点处理：shifted（忽略）、non-ignorable caseLevel boolean 是否在 primary 强度下区分大小写 caseFirst string 大小写优先：lower、upper numeric boolean 是否按数字值排序（true 使 “2” < “10”） rules string 自定义 ICU 排序规则字符串 相关链接 # ICU 分析器 ICU Transform 过滤器 文本分析https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/icu-transform/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/icu-transform/ICU 脚本转换过滤器 # icu_transform 词元过滤器使用 ICU 的 Transliterator 引擎将文本从一种脚本转写为另一种脚本。 前提条件 # 需要安装 analysis-icu 插件： bin/easysearch-plugin install analysis-icu 功能说明 # 此过滤器可以实现： 脚本转写：中文→拉丁、西里尔→拉丁、阿拉伯→拉丁等 大小写转换：Upper、Lower、Title Unicode 归一化：NFC、NFD、NFKC、NFKD 自定义转换规则 使用示例 # 西里尔字母转拉丁字母 # PUT my-transliterate-index { "settings": { "analysis": { "filter": { "cyrillic_to_latin": { "type": "icu_transform", "id": "Cyrillic-Latin" } }, "analyzer": { "my_translit": { "type": "custom", "tokenizer": "standard", "filter": ["cyrillic_to_latin"] } } } } } 中文转拼音 # PUT my-pinyin-index { "settings": { "analysis": { "filter": { "han_to_latin": { "type": "icu_transform", "id": "Han-Latin" } } } } } 链式转换 # PUT my-chain-index { "settings": { "analysis": { "filter": { "to_ascii": { "type": "icu_transform", "id": "Cyrillic-Latin; NFD; [:Nonspacing Mark:] Remove; NFC" } } } } } 测试效果 # GET /_analyze { "tokenizer": "standard", "filter": [{"type": "icu_transform", "id": "Cyrillic-Latin"}], "text": "Москва" } 响应：Moskvahttps://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/throttling/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/cluster-admin/throttling/写入限流 # Easysearch 从 1.8.0 版本开始引入写入限流功能，支持在节点、索引和分片三个层级对写入速度进行精细化控制。在需要向正在执行查询的集群导入数据时，限流功能可以有效避免写入压力影响查询响应时间。 三级限流架构 # 级别 粒度 适用场景 节点级 整个节点的写入总量 保护节点整体性能，不区分索引 索引级 单个索引的写入速度 限制特定索引，不影响其他索引 分片级 每个分片的写入速度 适合高低配主机混搭的集群 节点级和分片级限流可以同时启用，互不冲突。限流功能不会限制系统索引流量，只针对业务索引。 限流参数参考 # 以下参数均支持动态设置，无需重启集群。 参数 类型 说明 默认值 cluster.throttle.node.write boolean 是否启用节点级别限流 false cluster.throttle.node.write.max_requests int 限定时间范围内单个节点允许的最大写入请求次数 0 cluster.throttle.node.write.max_bytes 字符串 限定时间范围内单个节点允许的最大写入请求字节数（kb, mb, gb 等） 0mb cluster.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/guomi/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/guomi/国密 / TLCP 配置指南 # 在政务、金融等信创场景中，要求使用国密（SM）系列算法进行 TLS 加密。Easysearch 基于 铜锁（Tongsuo） 提供国密 TLCP 双证书能力，支持 SM2/SM3/SM4 加密套件。 国密算法简介 # 算法 类型 对应国际算法 用途 SM2 非对称加密 ECDSA / RSA 数字签名、密钥交换 SM3 哈希 SHA-256 完整性校验 SM4 对称加密 AES 数据加密 国密 TLS 使用 SM2 证书 + SM4 加密 + SM3 哈希，组成完整的加密通信套件。 前置条件 # 条件 说明 节点运行平台 国密运行依赖 Tongsuo JNI 原生库；bin/easysearch 当前会按以下平台加载本地库：linux-x86_64 / linux-aarch64 / darwin-x86_64 / darwin-aarch64。若对应库缺失会启动失败 证书生成平台 generate-tlcp-certs.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/rank-eval/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/rank-eval/排名评估（Rank Eval） # 排名评估 API（_rank_eval）允许您使用一组预定义的查询和已知相关文档来评估搜索结果的排名质量。这对于调优搜索相关性、对比不同查询策略的效果非常有用。 基本概念 # 排名评估的核心流程： 定义请求集：一组代表性的搜索查询 标注相关文档：为每个查询标注哪些文档是相关的（及其相关程度） 选择评估指标：如 Precision、Recall、DCG 等 执行评估：Easysearch 运行查询并根据标注计算指标得分 基本用法 # GET my_index/_rank_eval { "requests": [ { "id": "query_1", "request": { "query": { "match": { "title": "搜索引擎" } } }, "ratings": [ { "_index": "my_index", "_id": "doc1", "rating": 3 }, { "_index": "my_index", "_id": "doc2", "rating": 2 }, { "_index": "my_index", "_id": "doc3", "rating": 0 } ] }, { "id": "query_2", "request": { "query": { "match": { "title": "全文检索" } } }, "ratings": [ { "_index": "my_index", "_id": "doc4", "rating": 3 }, { "_index": "my_index", "_id": "doc5", "rating": 1 } ] } ], "metric": { "precision": { "k": 10, "relevant_rating_threshold": 1 } } } 请求参数说明 # 字段 说明 requests 评估请求数组 requests[].https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/logs/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/operations/logs/系统日志 # Easysearch 日志包含监控群集操作和故障排除问题的重要信息。日志的位置因安装类型而异： 在 Docker 上，Easysearch 将大多数日志写入控制台，并将其余日志存储在 easysearch/logs/ 中。tarball 安装也使用 easysearch/logs/。 在 RPM 和 Debian 安装上，Easysearch 将日志写入 /var/log/easysearch/。 日志可作为 .log （纯文本）和 .json 文件使用。 应用程序日志 # 对于其应用程序日志，Easysearch 使用 Apache Log4j 2 其内置日志级别（从最低到最高）为 TRACE 、 DEBUG 、 INFO 、 WARN 、 ERROR 和 FATAL 。默认 Easysearch 日志级别为 INFO 。 您可以更改各个 Easysearch 模块的日志级别，而不是更改默认日志级别（ logger.level ）： PUT /_cluster/settings { "persistent" : { "logger.org.easysearch.index.reindex" : "DEBUG" } } 此示例更改后，Easysearch 在重新索引操作期间会发出更详细的日志：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/docker-compose/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/docker-compose/Docker Compose 环境下使用 Easysearch # 在使用 docker-compose 运行 Easysearch 集群之前，请确保已进行 系统调优并安装好 Docker 服务，且 Docker 服务正常运行。 # 安装docker-compose curl -L "https://github.com/docker/compose/releases/download/v2.6.1/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose # 增加执行权限 chmod +x /usr/local/bin/docker-compose # 检查版本信息 docker-compose -v 运行 2 节点 docker compose 项目 # 从官网下载文件并解压，然后运行初始化脚本，最后运行启动脚本。 在宿主机上创建工作目录 # 创建操作目录 sudo mkdir -p /data/docker/compose 下载文件并解压 如需测试 3 节点，只需把下面的下载文件名改为 3node.tar.gz 即可。 curl -sSL https://release.infinilabs.com/easysearch/archive/compose/2node.tar.gz | sudo tar -xzC /data/docker/compose --strip-components=1 # 调整目录权限 sudo chown -R ${USER} /data/docker/compose 注意：解压之后，请把镜像的 latest 版本手工更新成具体的版本，可参考下面的命令https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/zhaoxin/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/zhaoxin/兆芯平台安装 # 兆芯平台介绍 # 兆芯平台基于自主可控的 x86 架构，兼容主流 Linux 系统，广泛应用于信创桌面与服务器领域，支持统信 UOS、麒麟等国产操作系统，具备良好的软硬件生态和迁移兼容性。 兆芯平台安装参考 # 目前，Easysearch 已支持在兆芯芯片的国产操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/memory/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/memory/内存与缓存配置 # 本页介绍 easysearch.yml 中与内存锁定和缓存相关的配置项。 bootstrap.memory_lock # bootstrap.memory_lock: true 项目 说明 参数 bootstrap.memory_lock 默认值 false 属性 静态 说明 启动时锁定 JVM 堆内存，防止操作系统将堆内存交换（swap）到磁盘。生产环境强烈建议启用 为什么需要锁定内存？ # 当操作系统将 JVM 堆内存换出到磁盘时，会导致： GC 暂停时间显著增加：GC 需要将被换出的页面重新换入内存。 搜索和索引延迟飙升：毫秒级操作可能变成秒级。 节点被判定为不可用：主节点可能因为超时将该节点踢出集群。 配合设置 # 启用 memory_lock 需要操作系统级的配合： 1. 设置 ulimit（systemd） # /etc/systemd/system/easysearch.service.d/override.conf [Service] LimitMEMLOCK=infinity 2. 设置 limits.conf # /etc/security/limits.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/delete-policy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/delete-policy/删除策略 # 当备份策略不再需要时，可以将其删除。 操作步骤 # 进入备份策略页面：登录 Easysearch UI，左侧导航栏点击「备份管理」，切换至「策略」标签页。 触发删除：找到目标策略（如 test_strategy），点击「操作」列的更多按钮，选择「删除」。 确认执行：在弹出提示框中核对名称，点击「确定」。 验证结果：操作完成后，目标策略从列表移除，仅剩余未删除的策略。 注意事项 # 删除策略仅停止自动备份计划，不会删除已生成的快照数据。 操作前请确认业务不再依赖该策略的自动备份，避免数据无法按预期自动备份。 策略删除后可随时重新创建，已存在的快照需手动管理。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/delete-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/delete-filter/删除过滤条件 # 当不再需要某个过滤条件时，可以将其从过滤列表中删除。 操作步骤 # 方法一：通过菜单删除 # 唤起操作菜单：在数据探索页面，找到已生效的过滤条件标签（如 _id:nYsUlJ0Bc_MPNLBvYYQh），点击该标签，弹出操作菜单。 执行删除操作：在菜单中选择「移除」，系统将彻底删除该过滤条件。 查看结果：过滤标签从页面消失，右侧数据列表恢复展示该索引下的全部文档记录。 方法二：通过标签关闭按钮快速删除 # 定位关闭按钮：找到已生效的过滤条件标签，点击标签右侧的「×」关闭图标。 完成删除：点击后系统将直接删除该过滤条件，标签消失，数据列表自动恢复全量展示。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/force-merge/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/force-merge/合并段文件 # Force Merge（强制合并）将索引的 Lucene 段文件合并，减少段数量，提升查询性能并释放磁盘空间。 操作步骤 # 进入索引列表：在「索引」页面，找到需要合并段文件的目标索引（如 testing_index_creation）。 打开操作菜单：点击该索引行「操作」列的更多按钮（...），在下拉菜单中选择「合并段文件」。 配置合并参数：在弹出的「合并段文件」窗口中，填写最大段数（即合并后每个分片保留的段文件数量，默认值为 1）。 执行合并操作：参数配置完成后，点击「确定」，系统将执行段文件合并。 完成操作：合并成功后，在提示窗口中点击「确定」，即可完成操作。 注意事项 # Force Merge 是一个资源密集型操作，会占用大量磁盘 I/O 和 CPU 资源，强烈建议在业务低峰期执行。 对于仍在活跃写入的索引，不建议执行 Force Merge。频繁写入会持续产生新的段文件，合并效果有限且会增加系统负担。Force Merge 更适合用于不再写入的历史索引或只读索引。 最大段数设为 1 可获得最佳查询性能，但合并过程耗时最长；可根据实际情况适当调大该值以缩短操作时间。 合并过程中，索引仍可正常提供读服务，但整体集群性能可能受到影响。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/cli-reference/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/cli-reference/命令行工具参考 # Easysearch 提供了一组命令行工具，位于安装目录的 bin/ 目录下，用于启动服务、管理安全设置和安装插件等。 bin/easysearch — 启动服务 # 启动 Easysearch 节点。 语法 # bin/easysearch [选项] 命令行选项 # 选项 说明 -d 以守护进程（后台）模式启动。不能与 --pidfile 单独使用时不写 PID 文件 -p <路径> 启动时将进程 ID (PID) 写入指定文件，便于通过 PID 管理进程 -q 关闭标准输出和标准错误的控制台日志输出。日志仍会写入日志文件 -E <设置>=<值> 覆盖配置文件中的设置。可多次使用以覆盖多个设置 -V 显示 Easysearch 版本信息并退出 -h, --help 显示帮助信息 -v, --verbose 显示详细输出 -s, --silent 只显示错误信息 使用示例 # 前台启动（适合开发调试）：https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/multi-tenancy/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/best-practices/data-modeling/multi-tenancy/多租户建模 # 多租户（Multi-tenancy）是指多个用户或组织共享同一个 Easysearch 集群，但各自的数据需要隔离。本页介绍多租户场景下的索引设计、路由策略和容量规划思路。 多租户的两种主要模式 # 模式一：一个用户一个索引 # 通常来说，用户使用 Easysearch 的原因是他们需要添加全文检索或者需要分析一个已经存在的应用。他们创建一个索引来存储所有文档。公司里的其他人也逐渐发现了 Easysearch 带来的好处，也想把他们的数据添加到 Easysearch 中去。 幸运的是，Easysearch 支持多租户，所以每个用户可以在相同的集群中拥有自己的索引。有人偶尔会想要搜索所有用户的文档，这种情况可以通过搜索所有索引实现，但大多数情况下用户只关心它们自己的文档。 一些用户有着比其他人更多的文档，一些用户可能有比其他人更多的搜索次数，所以这种对指定每个索引主分片和副本分片数量能力的需要应该很适合使用"一个用户一个索引"的模式。类似地，较为繁忙的索引可以通过分片分配过滤指定到高配的节点。 提示：不要为每个索引都使用默认的主分片数。想想看它需要存储多少数据。有可能你仅需要一个分片——再多的都只是浪费资源。 大多数 Easysearch 的用户读到这里就已经够了。简单的"一个用户一个索引"对大多数场景都可以满足了。 模式二：共享索引 + 过滤 # 对于例外的场景，你可能会发现需要支持很大数量的用户，都是相似的需求。一个例子可能是为一个拥有几千个邮箱账户的论坛提供搜索服务。一些论坛可能有巨大的流量，但大多数都很小。将一个有着单个分片的索引用于一个小规模论坛已经是足够的了——一个分片可以承载很多个论坛的数据。 我们需要的是一种可以在用户间共享资源的方法，给每个用户他们拥有自己的索引这种印象，而不在小用户上浪费资源。 共享索引的实现 # 我们可以为许多的小用户使用一个大的共享的索引，将用户标识索引进一个字段并且将它用作一个过滤器： PUT /forums { "settings": { "number_of_shards": 10 }, "mappings": { "properties": { "forum_id": { "type": "keyword" }, "title": { "type": "text" } } } } PUT /forums/_doc/1 { "forum_id": "baking", "title": "Easy recipe for ginger nuts", .https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/suggestions/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/fulltext-search/suggestions/建议与纠错 # Easysearch 提供三种 Suggester（建议器），覆盖"拼写纠正→短语纠正→前缀补全"三个典型场景： Suggester 用途 工作方式 Term Suggester 单词拼写纠正 基于编辑距离，对每个词项找索引中相似的词 Phrase Suggester 短语级纠正（“Did you mean …?"） 使用 N-gram 语言模型对整个短语做纠正 Completion Suggester 前缀自动补全 基于 FST 数据结构常驻内存，毫秒级响应 所有 Suggester 通过 _search 请求的 suggest 参数调用，可以与 query 同时使用。 Term Suggester（单词纠正） # 对单个词项，基于编辑距离在索引中查找相似候选词。 GET /articles/_search { "suggest": { "spell-check": { "text": "quer", "term": { "field": "content", "suggest_mode": "popular" } } } } 返回示例：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/quick-open-dev-tools/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/dev-tools/quick-open-dev-tools/快速打开开发工具 # 操作步骤 # 唤起悬浮窗口：点击页面右上角的悬浮窗图标，快速唤起开发工具悬浮窗口。 使用开发工具：在悬浮窗口中编写请求语句、发送请求、查看响应结果，操作逻辑与完整开发工具页一致。 窗口管理：可通过窗口右上角按钮最大化或关闭悬浮窗口。 补充说明 # 悬浮窗口可在任意页面（如概览、索引管理等）快速唤起，无需切换至开发工具页面，适合在运维操作中临时执行查询或调试。 悬浮窗口与完整开发工具页共享同一请求编辑环境，两者的内容保持同步。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/resume-cluster-creation/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/resume-cluster-creation/恢复创建集群 # 可以恢复之前暂停的集群创建流程，继续完成集群部署。 操作步骤 # 进入服务管理页面：在 Agent UI 的「服务管理」页面中，找到状态为「创建暂停」的目标集群。 打开继续操作菜单：点击目标集群操作列的「…」按钮，在下拉菜单中选择「继续」选项。 确认继续操作：在弹出的确认窗口中，点击「确定」按钮，恢复该创建任务。 验证恢复结果：操作完成后，服务列表中该集群的状态将更新为「创建中」，代表恢复成功。 注意事项 # 仅「创建暂停」状态的集群支持恢复创建，其他状态无法执行此操作。 恢复创建后，系统将从暂停的节点继续执行安装流程，无需重新配置参数。 恢复过程中请勿关闭页面或中断网络，避免任务执行异常。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/pinyin-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/pinyin-filter/拼音过滤器 # pinyin 词元过滤器将中文词元转换为拼音表示，来自 analysis-pinyin 插件。 前提条件 # 需要安装 analysis-pinyin 插件： bin/easysearch-plugin install analysis-pinyin 功能说明 # 此过滤器可以： 将汉字转换为拼音全拼或首字母 保留或移除原始中文词元 支持多种输出格式组合 使用示例 # PUT my-pinyin-index { "settings": { "analysis": { "filter": { "my_pinyin": { "type": "pinyin", "keep_full_pinyin": true, "keep_first_letter": true, "keep_original": true, "limit_first_letter_length": 16 } }, "analyzer": { "pinyin_analyzer": { "type": "custom", "tokenizer": "ik_smart", "filter": ["my_pinyin"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "ik_smart", "filter": [{"type": "pinyin", "keep_full_pinyin": true}], "text": "中华人民共和国" } 参数 # 参数 默认值 说明 keep_first_letter true 保留拼音首字母（如 “中国” → zg） keep_full_pinyin true 保留全拼（如 “中” → zhong） keep_joined_full_pinyin false 连接全拼（如 “中国” → zhongguo） keep_original false 保留原始中文词元 keep_none_chinese true 保留非中文字符 keep_none_chinese_in_first_letter true 首字母模式中保留非中文 keep_none_chinese_together true 非中文字符连续保留 none_chinese_pinyin_tokenize true 拼音字母也参与分词 limit_first_letter_length 16 首字母最大长度 lowercase true 拼音小写 trim_whitespace true 移除空白 remove_duplicated_term false 移除重复词项 相关链接 # 拼音分析器 拼音分词器https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/plugins/publishing/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/integrations/plugins/publishing/插件发布与分享 # 打包 # ./gradlew clean build # 查看产物 ls -lh build/distributions/ # 输出示例：my-plugin-0.1.0.zip # 确认 zip 内容 unzip -l build/distributions/my-plugin-0.1.0.zip # 应包含： # my-plugin-0.1.0.jar # plugin-descriptor.properties 安装到 Easysearch # # 从本地路径安装 bin/easysearch-plugin install file:///ABSOLUTE/PATH/build/distributions/my-plugin-0.1.0.zip # 从 URL 安装（发布到 GitHub Releases 后） bin/easysearch-plugin install https://github.com/yourname/my-plugin/releases/download/v0.1.0/my-plugin-0.1.0.zip 重启 Easysearch 后验证： bin/easysearch curl -s "http://localhost:9200/_cat/plugins?v" | grep my-plugin # 预期输出中应包含插件名与版本 卸载插件 # bin/easysearch-plugin remove my-plugin 发布到 GitHub Releases # # 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/upgrade/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/upgrade/版本升级 # Easysearch Operator 支持通过修改 YAML 配置实现滚动升级，升级过程中集群保持可用。 操作步骤 # 查看当前版本 kubectl get pods -l app=easysearch -o jsonpath='{.items[0].spec.containers[0].image}' 修改 Operator YAML 中的版本字段 # 修改前 version: "1.7.0-223" # 修改后 version: "1.7.1-225" 其他配置保持不变： httpPort: 9200 vendor: Easysearch serviceAccount: controller-manager serviceName: threenodes 应用修改 kubectl apply -f easysearch-cluster.yaml 滚动升级流程 # 为保证升级过程中的服务可用性，Operator 采用滚动升级方式： 从 threenodes-masters-0 开始升级 等待该节点完全就绪后，升级 threenodes-masters-1 依次滚动，直到所有节点升级完毕 整个升级过程耗时约 10 分钟（3 节点集群），具体取决于数据量和分片恢复速度。 验证升级结果 # 进入容器验证版本 kubectl exec -it threenodes-masters-0 -- curl -ku admin:PASSWORD https://localhost:9200 确认 version.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/stconvert-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/stconvert-filter/简繁转换过滤器 # stconvert 词元过滤器在简体中文和繁体中文之间进行转换，来自 analysis-stconvert 插件。 前提条件 # 需要安装 analysis-stconvert 插件： bin/easysearch-plugin install analysis-stconvert 功能说明 # 此过滤器支持： 简体 → 繁体（s2t） 繁体 → 简体（t2s） 可用于实现跨简繁的统一搜索。 使用示例 # PUT my-stconvert-index { "settings": { "analysis": { "filter": { "to_simplified": { "type": "stconvert", "convert_type": "t2s" } }, "analyzer": { "unified_chinese": { "type": "custom", "tokenizer": "ik_smart", "filter": ["to_simplified"] } } } } } 测试效果 # GET /_analyze { "tokenizer": "ik_smart", "filter": [{"type": "stconvert", "convert_type": "t2s"}], "text": "計算機程式設計" } 响应：计算机 程式 设计https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/environment-variables/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/environment-variables/环境变量参考 # Easysearch 支持通过环境变量控制启动行为、JVM 设置和运行路径等。本页提供所有支持的环境变量的完整参考。 核心环境变量 # 变量 说明 默认值 ES_HOME Easysearch 安装根目录 从启动脚本位置自动推断 ES_PATH_CONF 配置文件目录路径 $ES_HOME/config ES_JAVA_HOME 自定义 Java 安装路径（推荐使用此变量） 未设置（优先使用内置 JDK） JAVA_HOME Java 安装路径（后备方案，ES_JAVA_HOME 优先） 系统默认 ES_JAVA_OPTS 附加 JVM 选项，如堆大小 空 ES_TMPDIR 临时文件目录 自动创建 ES_STARTUP_SLEEP_TIME 后台启动后的等待时间（秒） 未设置 JDK 选择优先级 # Easysearch 按以下优先级选择 Java 运行环境：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/keystore/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/keystore/Keystore 安全设置 # Easysearch 的 keystore 是一个加密的安全存储，用于保存敏感配置项（如密码、密钥、凭据等）。使用 keystore 可以避免将敏感信息以明文形式写在 easysearch.yml 配置文件中。 为什么使用 Keystore # 方式 安全性 说明 easysearch.yml ⚠️ 明文 配置文件中的密码任何有文件读取权限的用户都能看到 环境变量 ⚠️ 明文 环境变量可能在进程列表、日志中暴露 Keystore ✅ 加密 AES-GCM 加密存储，可选密码保护 适合存入 keystore 的设置示例： S3 快照仓库的 access_key 和 secret_key LDAP 绑定密码 安全插件的管理员密码 任何包含密码或密钥的配置项 Keystore 文件 # keystore 文件名为 easysearch.keystore，存放在配置目录（$ES_PATH_CONF）下。文件权限自动设置为 rw-rw----（660）。 创建 Keystore # bin/easysearch-keystore create 创建带密码保护的 keystore：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/russian-morphology/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/russian-morphology/Russian Morphology 分词过滤器 # russian_morphology 分词过滤器基于 Lucene Morphology 库，专门用于解决俄语搜索中"搜不全"和"语义偏差"的痛点。俄语由于其极其复杂的**变格（Declension）和变位（Conjugation）**系统，是形态分析最具挑战性的语言之一。 相关指南（先读这些） # 文本分析：词干提取 文本分析：规范化 核心处理逻辑 # 该过滤器在处理俄语文本时具备以下核心能力： 变格还原：处理名词、形容词、代词的 6 个格位及单复数变化。 示例：автомобили (复数) 和 автомобилем (单数工具格) 都会还原为 автомоль (汽车)。 动词变位还原：处理动词的人称、时态和语气。 示例：бежал (跑/过去时) 还原为 бежать (跑/原型)。 多路径歧义处理 (Homonymy)：当一个词形对应多个原型时，同时索引它们以防漏搜。 示例：Мире 会同时产生 мир (世界/和平) 和 миро (圣油)。 俄语形态分析的必要性 # 与英语不同，俄语的一个单词根据格、性、数、时态的变化，可能会产生数十种不同的拼写形式。 普通分词器（如 Snowball）：只能简单地去掉词尾（如 -ом, -ами），经常导致词根被错误切分。 形态过滤器 (russian_morphology)：通过查阅俄语语言学词典，将所有变形统一回归到其 第一格（Nominative）或动词不定式（Infinitive） 原型。 安装与使用 # 详见 俄语形态分词器 部分。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/english-morphology/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/text-analysis/token-filters/english-morphology/English Morphology 分词过滤器 # english_morphology 分词过滤器是基于 Lucene Morphology 库的语言处理组件。与传统的算法分词器不同，它不依赖于简单的字符裁剪规则，而是通过语言学词典对单词进行深度的词形还原（Lemmatization）。 相关指南（先读这些） # 文本分析：词干提取 文本分析：规范化 核心处理逻辑 # 该过滤器在处理文本时遵循“字典比对 + 语义还原”的原则，其核心逻辑包括： 屈折变化还原 (Inflectional)：处理动词时态（went → go）、名词单复数（children → child）等。 派生词识别 (Derivational)：识别单词间的词根关联，如将“执行者名词”关联至“动作动词”（runner → run）。 多路径索引 (Token Expansion)：当一个单词具有多重身份时，同时保留原词和还原后的原型（如 running → running, run）。 安装与使用 # 详见 英语形态分词器 部分。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/helm/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/helm/Helm Chart 部署 # INFINI Easysearch 从 1.5.0 版本开始支持 Helm Chart 方式部署。 仓库信息 # INFINI Easysearch Helm Chart 仓库地址: https://helm.infinilabs.com。 可以使用以下命令添加仓库 helm repo add infinilabs https://helm.infinilabs.com 依赖项 # StorageClass INFINI Easysearch Helm Chart 包中默认使用 local-path 进行数据持久化存储，可参考 local-path官方文档进行安装。 如果使用其他 StorageClass，请修改 Chart 包中的 storageClassName: local-path配置项。 Secret INFINI Easysearch Helm Chart 默认使用 cert-manager 进行自签 CA 证书创建及分发, 可参考 cert-manager 官方文档进行安装。 安装示例 # cat << EOF | kubectl apply -n <namespace> -f - apiVersion: cert-manager.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/delete-index/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/delete-index/删除索引 # 删除操作会永久移除索引及其所有数据，不可恢复，请谨慎操作。 操作步骤 # 进入索引列表：在「索引」页面，找到需要删除的目标索引（如 testing_index_creation-clone）。 打开操作菜单：点击该索引行「操作」列的更多按钮（...），在下拉菜单中选择「删除索引」。 确认删除：在弹出的确认提示框中，点击「确定」，系统将执行索引删除操作。 查看结果：操作完成后，索引列表中将不再显示该被删除的索引（如 testing_index_creation-clone 已从列表中移除），即代表删除成功。 注意事项 # ⚠️ 警告：删除索引是不可逆操作，索引的所有数据、Mapping 和设置将被永久移除，且无法通过任何方式恢复。执行前请务必确认： 该索引的数据已不再需要，或已通过快照（Snapshot）等方式完成备份。 没有应用或别名正在引用该索引。 删除系统索引（如以 . 开头的索引）可能导致集群功能异常，请谨慎操作。 如果只是暂时不需要该索引，建议使用「关闭索引」替代删除操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/cancel-cluster-creation/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/cancel-cluster-creation/取消创建集群 # 可以取消正在进行或已暂停的集群创建流程。 操作步骤 # 进入服务管理页面：在 Agent UI 的「服务管理」页面中，找到状态为「创建中」的目标集群。 打开取消操作菜单：点击目标集群操作列的「…」按钮，在下拉菜单中选择「取消」选项。 确认取消操作：系统将自动取消当前的创建任务，并清理相关的临时文件与配置。 验证取消结果：操作完成后，服务列表中该集群条目将被移除，代表取消成功。 注意事项 # 取消操作仅对「创建中」状态的集群生效，已运行或创建暂停的集群无法执行此操作。 取消创建会终止当前任务并删除已下载的文件和配置，此操作不可逆，请谨慎操作。 取消后如需重新创建，需从头开始配置并执行安装流程。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/security-settings/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/security-settings/安全配置 # 本页介绍 easysearch.yml 中与安全模块相关的配置项，包括 TLS 加密、审计日志、节点证书、REST API 权限等。这些都是静态设置，修改后需要重启节点生效。 用户、角色、权限等安全管理操作请参见 安全 API。 详细的 TLS 证书管理请参见 TLS 安全配置。 国密算法配置请参见 国密配置。 安全模块开关 # security.enabled # security.enabled: true 项目 说明 参数 security.enabled 默认值 true 属性 静态 说明 是否启用安全模块。启用后所有 API 请求需要认证，节点间通信需要 TLS 加密 生产环境必须启用安全模块。关闭安全意味着任何人都可以读写集群数据。 审计日志 # security.audit.type # security.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/batch-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/batch-filter/批量操作过滤条件 # 支持对多个过滤条件进行批量启用、停用或删除等操作。 操作步骤 # 打开批量操作菜单：在数据探索页面，点击过滤条件栏左侧的批量操作图标（三条横线带下拉箭头样式），弹出「变更所有过滤条件」菜单。 选择批量操作：点击目标操作，以「反转包含」为例： 选择「反转包含」，系统将批量反转所有过滤条件的匹配逻辑。 查看结果： 过滤标签新增 'NOT' 前缀，所有条件转为排除逻辑； 右侧列表展示不满足原条件的文档，完成批量操作。 其他批量操作功能 # 全部启用：批量恢复所有停用过滤条件 全部禁用：批量暂停所有过滤条件 反转启用状态：批量切换所有过滤条件的启用 / 停用状态 移除全部：批量删除所有过滤条件 注意事项 # 「移除全部」操作不可撤销，执行后所有过滤条件将被永久删除，请谨慎使用。 批量操作会同时作用于所有已添加的过滤条件，包括当前已停用的条件。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/create-repository/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/backup/create-repository/新增存储库 # 存储库用于存放备份快照数据，需要在创建备份前先配置存储库。 操作步骤 # 进入存储库管理页面：登录 Easysearch UI，在左侧导航栏点击「备份管理」，切换至「存储库」标签页。 打开新增存储库弹窗：点击页面右上角的「+ 新增」按钮，弹出配置窗口。 配置存储库信息： 填写「名称」，自定义存储库标识（如 test_repository）。 选择「类型」，这里以 s3 为例。 填写必填项：集群地址、访问密钥、秘密密钥、存储桶名称。 按需配置：存储路径、块大小、备份/恢复最大速率、最大重试次数、只读模式、压缩等参数。 确认创建：所有配置完成后，点击「确定」按钮。 查看新增结果：配置成功后，新的存储库将出现在列表中，状态显示为 Connected，表示已成功连接。 注意事项 # 存储库配置需确保网络能正常访问 S3 服务，且密钥权限具备读写权限。 若开启「只读模式」，存储库将无法写入新的备份数据，仅支持恢复操作。 存储路径建议设置为独立目录，避免与其他存储库数据混淆。 块大小和备份/恢复速率需根据实际带宽和业务需求合理设置，避免影响集群性能。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/aggs-recipes/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/aggregations/aggs-recipes/聚合场景实践 # 本页不再解释每种聚合的语法，而是按“业务问题”给出几类常见的聚合场景实践。 语法细节请先阅读前面的聚合基础/桶聚合/指标聚合章节。 场景一：按状态与应用统计错误率 # 需求：做一个简单的错误率看板，按应用和日志级别统计请求量与错误量。 思路： 先用 bool.filter 限定时间窗口（如最近 15 分钟/1 小时） 使用 terms 按应用分桶 在每个应用桶内，再按日志级别分桶，并计算总数 示例： GET /logs-*/_search { "size": 0, "query": { "bool": { "filter": [ { "range": { "@timestamp": { "gte": "now-15m" } } } ] } }, "aggs": { "by_app": { "terms": { "field": "app_name.keyword", "size": 20 }, "aggs": { "by_level": { "terms": { "field": "log_level.keyword" } } } } } } 可以在应用层根据各级别计数计算错误率，或继续在子聚合中添加 filter 聚合专门统计错误级别。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/cert_manager/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/cert_manager/证书管理 # 使用了 cert-manager 进行自动化管理证书，对于过期证书会自动重新颁发。 在这里我们根据 cert-manager 官方的配置方式配置了3套 Certificate 证书：ca-certificate、easysearch-certs 和 easysearch-admin-certs，分别用于节点间证书、http 访问证书和admin 管理员证书，具体参考下属 yaml 文件，重点需要主要证书的有效期(duration 字段)、更新时间(renewBefore 字段)和 commonName(infinilabs) 字段。 展开查看完整代码 apiVersion: cert-manager.io/v1 kind: Issuer metadata: name: selfsigned-issuer namespace: default spec: selfSigned: {} --- apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: ca-certificate namespace: default spec: secretName: ca-cert duration: 9000h # ~1year renewBefore: 360h # 15d commonName: infinilabs isCA: true privateKey: size: 2048 usages: - digital signature - key encipherment issuerRef: name: selfsigned-issuer --- apiVersion: cert-manager.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/fast-terms/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/query-dsl/term-based-query/fast-terms/Fast Terms 查询 # Fast Terms 是 Easysearch 提供的高性能 terms 查询插件，专为大规模 terms 过滤场景优化。当需要在查询中使用大量 term 值进行过滤时（如数万甚至数十万个 ID），Fast Terms 可以提供比标准 terms 查询更好的性能。 适用场景 # 大规模 ID 过滤：根据外部系统提供的大量 ID 列表过滤文档 权限过滤：根据用户可访问的文档 ID 集合进行过滤 黑/白名单：根据预定义的大规模列表进行包含/排除过滤 高基数字段过滤：在高基数数值字段上进行大量值的匹配 工作原理 # Fast Terms 使用 RoaringBitmap 和零分配哈希（XXHash）等技术对大规模 terms 集合进行压缩和高效匹配，相比标准 terms 查询在以下方面有显著优势： 对比项 标准 terms 查询 Fast Terms 内存占用 较高（每个 term 独立存储） 低（Bitmap 压缩） 大规模 terms 性能 随 terms 数量线性下降 保持稳定 缓存效率 一般 高（LZ4 压缩 + 过期缓存） 使用方法 # Bitmap Value Type # 在 terms 查询中使用 value_type: bitmap 来启用 Fast Terms 优化：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/jvm/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/jvm/JVM 配置 # 本页介绍 config/jvm.options 文件中的 JVM 启动参数。这些参数在 Easysearch 启动时由 JVM 读取，修改后需要重启节点生效。 堆内存设置 # 堆内存是 JVM 配置中最重要的参数。 # 堆大小设为物理内存的 50%，但不超过 31 GB # -Xms 和 -Xmx 必须相同，避免运行时堆调整 -Xms16g -Xmx16g 参数 说明 -Xms JVM 初始堆大小 -Xmx JVM 最大堆大小 设置原则 # -Xms 和 -Xmx 设为相同值：避免运行时堆大小调整带来的性能波动。 不超过物理内存的 50%：剩余内存留给操作系统文件缓存（Lucene 严重依赖 OS 页面缓存）。 不超过 31 GB（建议设为 31g 或 30g）：超过约 32 GB 后 JVM 无法使用压缩对象指针（Compressed OOPs），实际可用内存反而减少。 不低于 1 GB：过小的堆会导致频繁 GC。 验证压缩指针 # GET _nodes/stats/jvm?https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/s3_snapshot/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/s3_snapshot/S3 定期备份 # Easysearch Operator 支持通过 YAML 配置来管理 S3 快照备份策略。Operator 会启动一个 Job，通过集群 API 自动配置相应的备份策略。 工作原理 # 在 Operator YAML 中配置 S3 备份相关参数（Bucket 名称、访问密钥、备份周期等） Operator 创建一个 Job，该 Job 调用 Easysearch 的快照生命周期管理（SLM）API SLM 按照配置的策略自动执行定期快照 相关文档 # 快照生命周期管理 API 备份与恢复https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/modify-cluster-config/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/modify-cluster-config/修改集群配置 # 可以对已创建的集群进行配置修改，如调整节点参数等。 操作步骤 # 进入服务管理页面：在 Agent UI 的「服务管理」页面中，找到状态为「创建暂停」的目标集群。 打开修改配置菜单：点击目标集群操作列的「…」按钮，在下拉菜单中选择「修改配置」选项。 调整集群配置：在弹出的创建集群配置页面中，修改 Easysearch 版本、监听地址、端口、管理员密码、JVM 内存等参数。 重新启动创建：配置修改完成后，点击「重新安装」按钮，系统将根据新的配置继续集群创建流程。 注意事项 # 仅「创建暂停」状态的集群支持修改配置，已运行或创建中的集群无法直接修改。 修改配置会重置当前创建进度，需重新执行安装流程，操作前请确认配置无误。 端口、内存等关键参数修改后，建议使用「检测端口」「重新检测」功能验证配置有效性。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/flat-object/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/flat-object/扁平对象字段类型（Flat Object） # flat_object（也称为 flattened 类型）将整个 JSON 对象作为单个扁平化字段存储。它会将 JSON 对象中所有叶子节点的值提取为关键字（keyword），并支持对这些值进行基本查询。 适用场景 # flat_object 特别适合以下场景： 标签/标注数据：如 Kubernetes 的 labels、annotations 等动态键值对 防止 mapping explosion：当字段名不可预知或数量极多时，避免为每个子字段创建独立的映射条目 半结构化 JSON：存储结构不固定的 JSON 数据，同时保持可搜索性 日志元数据：存储动态的日志属性或自定义元数据 与其他类型对比 # 类型 动态字段支持 查询能力 Mapping 条目 性能 object ✅ 每个子字段独立映射 完整（全文、范围等） 多（每子字段一条） 高（独立索引） nested ✅ 每个子字段独立映射 完整 + 对象关联性 多 + 隐藏文档 中 flat_object ✅ 无需预定义 基本（term、prefix、range） 仅一条 中 创建映射 # PUT my_index { "mappings": { "properties": { "labels": { "type": "flat_object" } } } } flat_object 使用默认配置即可，不需要额外的映射参数。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/search-suggestions/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/search-suggestions/搜索框智能提示 # 搜索框支持智能提示功能，可以在输入查询时自动补全字段名和值。 操作步骤 # 激活搜索框：在数据探索页面顶部的搜索输入框中点击，激活输入状态。 获取字段智能提示：激活后系统自动弹出下拉列表，展示当前索引下的所有可用字段（如 _id、@timestamp、clientip 等），点击目标字段可快速补全到搜索框。 获取语法智能提示：在输入字段名后（如输入 _id），系统会自动弹出语法提示列表，包含查询运算符（:、*）、逻辑连接符（and、or）等，点击可快速补全查询语法。 执行查询：完成查询语句编写后，点击「更新」按钮，系统将执行搜索并展示符合条件的文档记录。 注意事项 # 搜索框默认使用 KQL（Kibana Query Language）语法，也支持切换为 Lucene 查询语法。 使用通配符查询（如 *）时可能影响查询性能，建议尽量使用精确匹配或限定字段范围。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/shenwei/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/shenwei/申威平台安装 # 申威平台介绍 # 申威平台基于自主 Alpha 指令集架构（后演进为 SW64 ），由申威科技研发，主打高性能计算与安全可控，广泛应用于超算、服务器及国防关键领域，全面支持国产操作系统与信创生态。 申威平台安装参考 # 目前，Easysearch 已支持在申威芯片的国产操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/rule-engine/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/rule-engine/Rules 规则引擎 # Rules 插件是 EasySearch 的规则匹配引擎，可在数据写入时自动匹配规则库，为文档添加标签字段，实现高效的内容分类、审核和标注。 功能特性 # ✅ 实时匹配：数据写入时自动匹配规则，无需后处理 ✅ 高性能：基于优化的 C++ 规则引擎，支持复杂规则和大规则库 ✅ 灵活配置：支持自定义字段、正则表达式、数值范围匹配 ✅ 多规则匹配：一条文档可匹配多个规则，所有标签保留到数组中 ✅ 集群广播：多节点环境自动编译规则到所有 Ingest 节点 基本概念 # 规则库 (Repository) # 规则库是规则的集合，每个规则库有唯一的 repo_id，存储在 .match_rules 索引中。 规则 (Rule) # 规则由表达式和描述组成： expression\t#offset#description expression: 匹配表达式（支持 AND/OR/NOT、正则、范围等） offset: 规则序号（从 0 开始，系统自动生成，用于区分不同规则） description: 规则描述（匹配时作为标签返回） 重要说明： offset 是导入到规则索引后系统自动生成的，本身没有业务含义 通过 _import API 导入规则时不需要手动指定 offset 导入时只需提供 expression 和 description，系统会自动分配 offset 标签 (Tag) # 文档匹配规则后，规则的 #offset#description 会添加到文档的 tags 字段。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/remove-readonly/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/remove-readonly/解除索引的只读状态 # 当磁盘使用率超过水位线或手动设置了写入块时，索引会进入只读状态，导致写入失败。 操作步骤 # 进入索引列表：在「索引」页面，找到处于只读模式的目标索引（如 testing_index_creation-split）。 打开操作菜单：点击该索引行「操作」列的更多按钮（...），在下拉菜单中选择「解除只读」。 确认解除操作：在弹出的「解除只读」确认窗口中，点击「确定」，系统将执行只读状态解除操作。 完成操作：系统提示「解除只读成功」后，点击「确定」关闭提示。 查看结果：操作完成后，索引列表中该索引的「只读模式」标识消失，代表索引已恢复正常读写状态。 注意事项 # 如果索引是因为磁盘使用率超过水位线被自动设为只读，仅解除只读状态并不能根治问题——当磁盘使用率再次超标时，索引会再次被自动锁定。建议先清理磁盘空间或扩容，再执行解除只读操作。 可通过「集群设置」调整磁盘水位线阈值（cluster.routing.allocation.disk.watermark.*），但需谨慎操作，避免磁盘被写满导致集群不可用。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/async-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/async-search/异步搜索 # 当需要对海量数据执行复杂聚合或跨大时间范围查询时，同步搜索可能因超时而失败。Easysearch 异步搜索（Async Search）允许将这类"大查询"提交到后台执行，客户端无需保持连接等待，可以随时轮询检查进度并获取部分或最终结果。 适用场景 # 场景 说明 深度聚合分析 对数亿条日志做多维分组聚合，耗时可能达分钟级 大跨度时间查询 查询数月甚至数年的历史数据 快照搜索 在对象存储上搜索冷数据，I/O 延迟较高 跨集群搜索 同时检索多个远程集群，网络延迟不可控 报表与导出 后台生成大规模报表，前端异步展示进度 基本用法 # 提交异步搜索 # 使用 _async_search 端点提交查询： POST /my-index/_async_search { "size": 0, "aggs": { "status_over_time": { "date_histogram": { "field": "@timestamp", "fixed_interval": "1h" }, "aggs": { "avg_response": { "avg": { "field": "response_time" } } } } } } 返回结果中包含一个异步搜索 ID：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/annotated-text/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/annotated-text/标注文本字段类型（Annotated Text） # annotated_text 字段类型是 text 字段的扩展，允许在文本中嵌入标注标记（annotation tokens）。标注标记会在索引时注入到文本的词元流（token stream）中，可以像普通词语一样被搜索。 适用场景 # 命名实体识别（NER）：将文本中识别出的实体（人名、地名、组织名等）作为标注嵌入 文本分类标记：在文本中标记特定类别或主题 知识图谱关联：将文本中的实体链接到知识图谱的节点 自定义标签注入：在索引时为文本添加额外的可搜索标签 前置条件 # annotated_text 字段类型由 mapper-annotated-text 插件提供，需要确认插件已安装： bin/easysearch-plugin list # 应包含 mapper-annotated-text 创建映射 # PUT my_index { "mappings": { "properties": { "content": { "type": "annotated_text" } } } } annotated_text 支持与 text 字段相同的映射参数，如 analyzer、search_analyzer 等。 标注语法 # 标注使用特殊的标记语法嵌入在文本中。标注的格式为： [被标注的文本](标注值) 示例 # 原始文本： "昨天在北京召开了搜索技术大会" 带标注的文本： "昨天在[北京](LOC=北京&wiki=Q956)召开了[搜索技术大会](EVENT=搜索技术大会)" 索引带标注的文档 # PUT my_index/_doc/1 { "content": "昨天[极限实验室](ORG=极限实验室)发布了[Easysearch](PRODUCT=Easysearch) 的新版本" } PUT my_index/_doc/2 { "content": "[张三](PERSON=张三)在[上海](LOC=上海)参加了技术峰会" } 查询 # 搜索标注值 # 标注值作为词元注入到了索引中，可以直接搜索：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/token-count/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/token-count/词元计数字段类型（Token Count） # token_count 是一个特殊的整数字段类型，它在索引时自动计算文本经过分析器处理后产生的词元（token）数量，并将该数量作为字段值存储。这使您可以根据文本的词元数量进行过滤、排序和聚合。 适用场景 # 按内容长度过滤：过滤词元数量在指定范围内的文档（如至少 100 个词的文章） 内容质量评估：短文本可能质量较低，可按词元数量排序 分析器效果评估：了解不同分析器对同一文本产生的词元数量差异 创建映射 # PUT my_index { "mappings": { "properties": { "title": { "type": "text", "fields": { "length": { "type": "token_count", "analyzer": "standard" } } } } } } 映射参数 # 参数 必填 说明 analyzer ✅ 是 用于分析文本的分析器名称。使用该分析器产生的词元数量作为字段值 enable_position_increments 否 是否计算位置增量。默认 true。设为 false 后，停用词等位置增量不计入总数 doc_values 否 默认 true，启用 doc values 以支持排序和聚合 index 否 默认 true，是否索引该字段 null_value 否 当原始文本为 null 时使用的替代值 store 否 默认 false，是否单独存储字段值 索引文档 # PUT my_index/_doc/1 { "title": "快速入门 Easysearch 搜索引擎" } PUT my_index/_doc/2 { "title": "Easysearch" } PUT my_index/_doc/3 { "title": "深入理解 Easysearch 的分布式架构设计与高可用方案" } 查询示例 # 过滤词元数量 # 查找标题至少有 3 个词元的文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/murmur3/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/field-types/murmur3/哈希字段类型（Murmur3） # murmur3 字段类型在索引时计算字段值的 MurmurHash3 128 位哈希值，并将哈希值存储为 doc values。这在 cardinality 聚合中可以提供更高的精度，因为直接使用预计算的哈希值而非运行时计算。 前置条件 # murmur3 字段类型由 mapper-murmur3 插件提供，需要确认插件已安装： bin/easysearch-plugin list # 应包含 mapper-murmur3 创建映射 # PUT my_index { "mappings": { "properties": { "user_id": { "type": "keyword", "fields": { "hash": { "type": "murmur3" } } } } } } 使用示例 # Cardinality 聚合优化 # 使用 murmur3 子字段进行基数统计，可以获得更高的精度： GET my_index/_search { "size": 0, "aggs": { "unique_users": { "cardinality": { "field": "user_id.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/stop-cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/stop-cluster/停止集群 # 可以停止当前正在运行的集群。 操作步骤 # 进入服务管理页面：登录 Agent UI 后，在服务管理页面的「服务列表」中，找到目标集群。 触发停止操作：点击目标集群「操作」列的更多按钮，在下拉菜单中选择「停止」选项。 确认停止操作：在弹出的「停止」确认窗口中，核对节点名称，点击「确定」按钮。 验证停止结果：系统执行停止操作后，返回服务列表页面，目标集群的状态将更新为「已停止」，表示集群已成功关闭。 注意事项 # 停止集群会中断所有正在运行的业务请求，操作前请确认业务已暂停或已切换至其他可用集群。 停止操作不会删除集群配置和数据，仅停止进程，后续可通过「启动」操作恢复运行。 停止过程中请勿关闭页面或中断操作，避免出现进程状态异常的情况。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/cluster/分布式集群安装 # 本文档介绍如何使用 initialize-cluster.sh 脚本快速搭建 Easysearch 分布式集群。该脚本支持伪分布式（单机多节点）和真分布式（多服务器）两种部署模式。 要求 Easysearch 版本 >= 2.0.3。 前置要求 # 已完成 系统调优 JDK 21 或更高版本（脚本可自动下载） 已安装 OpenSSL 真分布式部署需要： 服务器间网络互通 已配置 SSH 互信（无密码登录） 目标路径有写入权限 快速开始 # 交互式安装（推荐） # 交互式模式会引导您输入集群配置信息： cd /data/easysearch bin/initialize-cluster.sh 脚本会依次提示您输入： 集群名称：默认为 easysearch-cluster 证书域名：默认为 infini.cloud 节点数量：默认为 3 每个节点的配置：IP 地址、HTTP 端口、节点名称、节点角色 协议选择：HTTP 或 HTTPS（默认 HTTPS） API 兼容性：是否启用 Elasticsearch API 兼容模式 证书信息：国家、省份、城市、组织、有效期等（可选） 输入示例： ====================================== Easysearch Cluster Initialization ====================================== Enter cluster name [easysearch-cluster]: my-cluster Enter domain for certificates [infini.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/history_version/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/history_version/历史版本 # Easysearch Operator 的历史版本信息请参考 GitHub Releases 页面。 版本 发布时间 说明 最新版本 — 查看 GitHub Releaseshttps://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/size/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/metadata-field/size/文档大小元数据字段（_size） # _size 元数据字段记录每个文档的 _source 字段的原始未压缩大小（字节数）。启用后，可以按文档大小进行过滤、排序和聚合。 前置条件 # _size 字段由 mapper-size 插件提供，需要确认插件已安装： bin/easysearch-plugin list # 应包含 mapper-size 启用 _size 字段 # _size 字段默认未启用，需要在索引映射中显式开启： PUT my_index { "mappings": { "_size": { "enabled": true } } } 使用示例 # 索引文档 # 启用 _size 后，索引文档时会自动计算并存储 _source 的大小： PUT my_index/_doc/1 { "title": "示例文档", "content": "这是一个示例文档，用于演示 _size 字段。" } 查询文档大小 # GET my_index/_search { "query": { "match_all": {} }, "fields": ["_size"], "_source": false } 按大小过滤 # 查找大于 1KB 的文档：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/logging/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/logging/日志配置 # 本页介绍 config/log4j2.properties 日志配置文件以及慢日志设置。 日志文件说明 # Easysearch 使用 Log4j 2 作为日志框架。日志文件默认存储在 ${ES_HOME}/logs/ 目录下（可通过 path.logs 自定义）。 文件 说明 ${cluster.name}.log 主日志文件，记录集群运行的核心事件 ${cluster.name}_server.json JSON 格式日志，便于日志采集工具（如 Filebeat）解析 ${cluster.name}_deprecation.log API 弃用警告日志，记录使用了即将移除的 API ${cluster.name}_slowlog.log 慢查询和慢索引日志 gc.log JVM 垃圾回收日志（由 JVM 参数控制） log4j2.properties # config/log4j2.properties 控制日志行为。Easysearch 的默认配置已经比较完善，通常无需修改。 默认日志级别 # 默认日志级别为 INFO，在 log4j2.properties 中可以修改：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/change-time-range/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/change-time-range/更改时间范围 # 通过调整时间范围，可以控制数据探索中展示的数据时间区间。 操作步骤 # 一、快速选择时间范围 # 打开时间筛选菜单：在数据探索页面右上角，点击时间筛选下拉按钮，展开时间选择菜单。 选择预设时间：直接点击菜单中的预设选项，如「今天」「最近15分钟」「最近7天」等，系统将自动应用对应时间范围。 自定义快速选择： 点击「快速选择」，在右侧面板中设置时间条件（如「最近15分」）。 点击「应用」，完成自定义快速时间范围配置。 二、手动指定时间范围 # 打开时间范围配置：在时间菜单中点击「时间范围」，进入时间设置面板。 设置起止时间：填写「开始时间」和「结束时间」，选择目标时区。 应用时间范围：点击「应用」，系统将筛选出该时间段内的所有数据。 三、图表划动选取时间 # 激活划动选取：在页面顶部的时间趋势图表区域，直接用鼠标划动选取目标时间区间。 自动应用筛选：划动完成后，系统将自动应用该时间范围，更新数据列表展示。 注意事项 # 时间范围筛选依赖索引中的时间字段（如 @timestamp），无时间字段的索引不支持此功能。 选取过大的时间范围可能导致查询响应缓慢，建议根据实际需要合理缩小时间区间。https://docs.infinilabs.com/easysearch/v2.2.0/docs/resources/terminology/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/resources/terminology/术语表 # 本页汇总文档中常用的中英文术语对照，方便写作时统一用词，也方便读者建立清晰的心智模型。 一、数据结构与存储 # 英文术语 中文叫法 说明 Index 索引 逻辑上的数据集合，通常一类业务一组索引，可按时间/租户再拆前缀。 Document 文档 索引中的基本数据单元，以 JSON 形式表示。 Shard 分片 水平切分单位，number_of_shards 只在建索引时生效。 Primary Shard 主分片 负责接受写入并复制到副本。 Replica Shard 副本分片 / 副本 提供高可用与读扩展，副本数可在线调整。 Segment 段 Lucene 的不可变索引文件块，刷新/合并都围绕它展开。 Inverted Index 倒排索引 从词项到文档的映射结构，全文搜索的核心数据结构。 _source _source 文档原文 建议默认保留，是检索展示与重建索引的"真相来源"。 Stored Fields 存储字段 只在少数场景单独使用，更多依赖 _source + doc_values。 doc_values doc_values 列式存储 聚合与排序的核心支撑，应在大多数可聚合/排序字段上启用。 Fielddata fielddata 仅在 text 字段聚合/排序时使用，能不用尽量不用。 Translog 事务日志 写入操作的预写日志（WAL），保证 flush 前的数据不丢失。 Routing 路由 控制文档写入和查询时定向到特定分片的机制，默认按 _id 哈希。 二、Mapping 与文本分析 # 英文术语 中文叫法 说明 Mapping 映射 / Mapping 描述字段类型与索引规则，是一切查询/聚合行为的基础。 text Field 文本字段（text） 做全文检索，用分析器拆分为词项，不适合精确过滤/聚合。 keyword Field 关键字字段（keyword） 精确匹配、过滤、聚合、排序使用，不做分词。 integer / long / float / double 数值字段 数值类型字段，支持范围查询和聚合运算。 date Field 日期字段 支持多种日期格式，底层以毫秒时间戳存储。 boolean Field 布尔字段 仅存储 true/false 值。 geo_point 地理点 存储经纬度坐标，支持地理距离和区域查询。 geo_shape 地理形状 存储多边形、线段等复杂地理形状，支持空间关系查询。 nested 嵌套类型 保持对象数组中字段关联关系的特殊映射类型。 join (Parent/Child) 父子关系 同一索引内建立文档间的层级关系。 object 对象类型 JSON 对象映射为扁平化的点分字段名，不保持数组内对象边界。 knn_dense_float_vector 向量字段类型 用于存储 dense 浮点向量，支持近似最近邻搜索。 Multi-fields 多字段 / multi-fields 一份源数据多个视图，如 title + title.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/view-index-details/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/indices/view-index-details/查看索引详情 # 通过索引详情页，可一站式查看索引的完整信息。 操作步骤 # 进入索引列表：在「索引」页面，找到需要查看详情的目标索引（如 testing_index_creation）。 进入详情页：点击该索引的名称，即可进入索引详情页面。 查看核心信息：在详情页中，可一站式查看该索引的完整信息，包括： 基础信息：索引名称、创建时间、健康状态、索引状态 分片配置：主分片数、副分片数、未分配分片数 数据统计：文档数、删除文档数、存储大小、分段数 性能指标：索引延迟、索引吞吐、查询延迟、查询吞吐等https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/cross-cluster-search/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/cross-cluster-search/跨集群搜索（CCS） # Easysearch 跨集群搜索（Cross-Cluster Search, CCS）允许用户在本地集群发起一个查询请求，同时检索分布在不同地理位置、不同业务环境中的多个远程集群——无需进行数据迁移或归集，即可实现全局视角下的即时分析。 核心能力 # 统一视图，全局洞察 # 一个查询请求即可覆盖全公司范围内的索引数据，无需切换访问点，实现跨业务线的综合分析。 降低成本，按需存储 # 数据保留在产生的源集群中，避免大规模数据传输带来的网络带宽损耗与存储冗余成本。 系统解耦与灵活性 # 各个集群可以独立升级、独立维护，通过 CCS 实现逻辑上的互联互通，降低超大规模架构的运维复杂度。 故障隔离 # 若某个远程集群暂时不可用，CCS 可配置为忽略故障集群并返回其余可用部分的搜索结果，保障服务不中断。 快速上手 # 1. 配置远程集群连接 # 在本地集群上注册远程集群的种子节点： PUT _cluster/settings { "persistent": { "cluster.remote": { "cluster-beijing": { "seeds": ["beijing-node:9300"] }, "cluster-shanghai": { "seeds": ["shanghai-node:9300"] } } } } 2. 跨集群搜索 # 使用 集群名:索引名 的格式指定远程索引： POST /cluster-beijing:logs-*,cluster-shanghai:logs-*/_search { "query": { "range": { "@timestamp": { "gte": "now-1d/d", "lte": "now" } } }, "size": 20 } 3.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/kunpeng/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/kunpeng/鲲鹏平台安装 # 鲲鹏平台介绍 # 鲲鹏平台基于 ARM 架构，由华为自主研发，提供高性能、低功耗的服务器处理器，广泛应用于信创、云计算、大数据和分布式存储等场景，全面适配国产操作系统与生态。 鲲鹏平台安装参考 # 目前，Easysearch 已支持在鲲鹏芯片的国产操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.infini.cloud | bash -s -- -p easysearch -d /opt/easysearch # 进入 Easysearch 目录 cd /opt/easysearch # 初始化 Easysearch bin/initialize.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/national-encryption/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/national-encryption/国密与国产化 # Easysearch 围绕国产密码算法与国产化生态深度设计，为政企与关键行业提供可落地、可审计、可替代的搜索基础能力。 核心能力 # 能力 说明 国密算法 全量支持 SM2/SM3/SM4，替代 RSA/AES/SHA 国产 CPU 适配鲲鹏、飞腾、海光、龙芯、兆芯 国产 OS 适配银河麒麟、统信 UOS、中标麒麟 等保合规 满足等保三级及信创合规要求 国密算法 # Easysearch 基于 铜锁（Tongsuo）实现完整的国密 TLS 能力。 SM2 — 非对称加密 # 替代 RSA/ECDSA，用于： TLS 证书签名与验证 节点间身份认证 客户端证书认证 SM3 — 哈希算法 # 替代 SHA-256，用于： 密码存储与验证 数据完整性校验 审计日志防篡改 SM4 — 对称加密 # 替代 AES，用于：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/FAQ/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/operator/FAQ/FAQ # Easysearch 版本降级会报错 # cannot downgrade a node from version [1.7.0] to version [1.6.1] [2024-01-28T09:42:34,314][ERROR][o.e.b.EasysearchUncaughtExceptionHandler] [onenode-masters-0] uncaught exception in thread [main] org.easysearch.bootstrap.StartupException: java.lang.IllegalStateException: cannot downgrade a node from version [1.7.0] to version [1.6.1] at org.easysearch.bootstrap.easysearch.init(Easysearch.java:173) ~[easysearch-1.6.1.jar:1.6.1] at org.easysearch.bootstrap.easysearch.execute(Easysearch.java:160) ~[easysearch-1.6.1.jar:1.6.1] at org.easysearch.cli.EnvironmentAwareCommand.execute(EnvironmentAwareCommand.java:71) ~[easysearch-1.6.1.jar:1.6.1] at org.easysearch.cli.Command.mainWithoutErrorHandling(Command.java:112) ~[easysearch-cli-1.6.1.jar:1.6.1] at org.easysearch.cli.Command.main(Command.java:75) ~[easysearch-cli-1.6.1.jar:1.6.1] at org.easysearch.bootstrap.easysearch.main(Easysearch.java:125) ~[easysearch-1.6.1.jar:1.6.1] at org.easysearch.bootstrap.easysearch.main(Easysearch.java:67) ~[easysearch-1.6.1.jar:1.6.1] Caused by: java.lang.IllegalStateException: cannot downgrade a node from version [1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/log4j2/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/log4j2/Log4j2 日志配置 # config/log4j2.properties 是 Easysearch 的日志配置文件，控制日志输出格式、级别、文件轮转等。 文件位置与格式 # # 默认位置 $ES_HOME/config/log4j2.properties 该文件使用 Log4j2 的 properties 格式，配置 appenders（日志目标）、loggers（日志器）和日志级别。 修改后无需重启，Easysearch 会自动重新加载配置。 核心概念 # Appenders（日志输出目标） # 定义日志输出到哪里，有以下类型： Appender 说明 Console 控制台输出（测试环境使用） RollingFile 滚动文件输出（轮转、自动删除旧文件） Loggers（日志器） # 根据组件或模块设置不同的日志级别。根 logger (rootLogger) 作用于全局。 日志级别 # 级别 说明 TRACE 最详细 DEBUG 调试信息 INFO 一般信息（默认） WARN 警告 ERROR 错误 FATAL 致命错误 默认日志文件 # Easysearch 默认配置会生成以下日志文件（存储在 ${ES_HOME}/logs/）：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/preserve_position_increments/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/preserve_position_increments/位置增量保留（Preserve Position Increments） # 确定是否在自动完成建议中保留位置增量。 基本用法 # PUT my-index { "mappings": { "properties": { "suggest": { "type": "completion", "preserve_position_increments": true } } } } 适用的字段类型 # completion 默认值 # true 说明 # 当启用时，停用词等被移除的术语所创建的位置间隙被保留。这会影响自动完成建议的精确性和性能。 相关参数 # 分隔符保留（Preserve Separators）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/enable_position_increments/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/enable_position_increments/位置增量启用（Enable Position Increments） # 确定是否在令牌计数中包含位置增量。 基本用法 # PUT my-index { "mappings": { "properties": { "content": { "type": "token_count", "analyzer": "standard", "enable_position_increments": true } } } } 适用的字段类型 # token_count（mapper-extras 模块） 默认值 # true 说明 # 当启用时，停用词等被移除的令牌所创建的位置间隙被计入令牌计数。当禁用时，只计算实际产生的令牌。 相关参数 # 分析器参数（Analyzer）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/preserve_separators/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/preserve_separators/分隔符保留（Preserve Separators） # 确定在自动完成建议中是否保留分隔符。 基本用法 # PUT my-index { "mappings": { "properties": { "suggest": { "type": "completion", "preserve_separators": true } } } } 适用的字段类型 # completion 默认值 # true 说明 # 当启用时，分隔符（如空格、连字符和斜杠）被保留为单独的项。这有助于匹配在分隔符边界处开始的建议。 相关参数 # 位置增量保留（Preserve Position Increments）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/index_prefixes/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/index_prefixes/前缀索引（Index Prefixes） # 启用前缀查询的优化。当启用此参数时，Easysearch 会为前缀查询构建额外的索引结构。 基本用法 # PUT my-index { "mappings": { "properties": { "username": { "type": "text", "index_prefixes": {} } } } } 适用的字段类型 # text match_only_text 参数选项 # { "min_chars": 0, "max_chars": 20 } min_chars: 最小前缀长度（默认值：0） max_chars: 最大前缀长度（默认值：20） 说明 # 启用 index_prefixes 后，通配符查询和前缀查询的性能会显著提高。但会增加索引大小。较小的 min_chars 和 max_chars 值会使索引更大。 相关参数 # 短语索引（Index Phrases） 索引参数（Index）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/locale/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/locale/区域设置（Locale） # 用于解析日期或范围值的区域设置。 基本用法 # PUT my-index { "mappings": { "properties": { "publish_date": { "type": "date", "format": "dd/MM/yyyy", "locale": "fr_FR" } } } } 适用的字段类型 # date date_nanos date_range integer_range float_range long_range double_range 说明 # 某些日期格式取决于特定的区域设置（例如月份名称）。使用此参数指定应用于解析的区域设置。 常见区域设置值 # en_US - 美国英语 fr_FR - 法语（法国） de_DE - 德语（德国） es_ES - 西班牙语（西班牙） zh_CN - 中文（中国） 相关参数 # 格式参数（Format）https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/start-cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/start-cluster/启动集群 # 可以启动之前已停止的集群，使其恢复运行。 操作步骤 # 进入服务管理页面：登录 Agent UI 后，在服务管理页面的「服务列表」中，找到状态为「已停止」的目标集群。 触发启动操作：点击目标集群「操作」列的更多按钮，在下拉菜单中选择「启动」选项。 确认启动操作：在弹出的「启动」确认窗口中，核对节点名称，点击「确定」按钮。 验证启动结果：系统执行启动操作后，返回服务列表页面，目标集群的状态将更新为「运行中」，表示集群已成功启动。 注意事项 # 启动集群前，请确保端口未被占用、相关配置文件未被修改，否则可能导致启动失败。 启动过程中请勿关闭页面或中断操作，避免出现进程状态异常的情况。 集群启动后，需等待片刻服务完全就绪，再进行业务访问操作。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/fielddata_frequency_filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/fielddata_frequency_filter/字段数据频率过滤（Fielddata Frequency Filter） # 为了减少内存占用，可以配置字段数据过滤器来移除低频率的项。 基本用法 # PUT my-index { "mappings": { "properties": { "tags": { "type": "text", "fielddata": true, "fielddata_frequency_filter": { "min": 2, "min_segment_size": 50 } } } } } 适用的字段类型 # text（启用 fielddata 时） 参数选项 # min: 项必须出现的最少次数（默认值：0） max: 项可能出现的最多次数（无上限） min_segment_size: 仅在至少有这么多文档的段中应用过滤器（默认值：0） 说明 # 当启用字段数据用于聚合或排序时，此参数可以降低内存占用。低频项会被从内存中移除。 相关参数 # 字段数据参数（Fielddata）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/contexts/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/contexts/完成上下文（Contexts） # 定义用于过滤自动完成建议的上下文。 基本用法 # PUT my-index { "mappings": { "properties": { "suggest": { "type": "completion", "contexts": [ { "name": "category", "type": "category" }, { "name": "location", "type": "geo", "precision": "5km" } ] } } } } 适用的字段类型 # completion 上下文类型 # category: 按类别过滤建议 geo: 按地理位置过滤建议 说明 # 上下文允许根据多个维度（如类别或地理位置）对完成建议进行分类和过滤。这在需要基于上下文的自动完成的应用中很有用。 相关参数 # 分隔符保留（Preserve Separators） 位置增量保留（Preserve Position Increments）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/ignore_z_value/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/ignore_z_value/忽略Z坐标（Ignore Z Value） # 确定是否忽略地理空间数据中的 Z 坐标（高度）。 基本用法 # PUT my-index { "mappings": { "properties": { "location": { "type": "geo_point", "ignore_z_value": true } } } } 适用的字段类型 # geo_point geo_shape 默认值 # true 说明 # 地理坐标通常是二维的（经度和纬度）。某些输入格式可能包括 Z 坐标（如 GeoJSON 中的高度）。启用此参数时，Z 坐标会被忽略。禁用时，包含 Z 坐标会导致错误。 示例 # POST my-index/_doc/1 { "location": { "lat": 40.7128, "lon": -74.0060, "z": 100 } } 相关参数 # 索引参数（Index）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/max_shingle_size/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/max_shingle_size/最大短语大小（Max Shingle Size） # 搜索自动完成时使用的最大 shingle 大小。 基本用法 # PUT my-index { "mappings": { "properties": { "text": { "type": "search_as_you_type", "max_shingle_size": 3 } } } } 适用的字段类型 # search_as_you_type（mapper-extras 模块） 默认值 # 3 说明 # search_as_you_type 字段类型生成额外的子字段以支持即时搜索。max_shingle_size 参数控制用于前缀查询的 shingle 的最大大小。值越大，索引越大，但查询越快。 相关参数 # 分析器参数（Analyzer） 搜索分析器参数（Search Analyzer）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/max_input_length/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/max_input_length/最大输入长度（Max Input Length） # 限制自动完成建议的最大输入长度。 基本用法 # PUT my-index { "mappings": { "properties": { "suggest": { "type": "completion", "max_input_length": 50 } } } } 适用的字段类型 # completion 默认值 # 50 说明 # 当输入超过指定的长度时，将被截断。这用于限制自动完成索引的大小和内存使用。 相关参数 # 完成上下文（Contexts）https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/hygon/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/hygon/海光平台安装 # 海光平台介绍 # 海光平台基于自主可控的 x86 架构（获 AMD 授权），提供高性能 CPU 和 DCU 产品，广泛应用于服务器、云计算及信创领域，兼容主流生态，支持国产操作系统与关键行业应用。 海光平台安装参考 # 目前，Easysearch 已支持在海光芯片的国产操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/search_quote_analyzer/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/search_quote_analyzer/短语搜索分析器（Search Quote Analyzer） # 指定在处理带引号的短语查询时使用的分析器。 基本用法 # PUT my-index { "mappings": { "properties": { "title": { "type": "text", "analyzer": "standard", "search_quote_analyzer": "keyword" } } } } 适用的字段类型 # text 默认值 # 如果未指定，使用 search_analyzer 的值 如果 search_analyzer 也未指定，使用 analyzer 的值 说明 # 在执行带引号短语查询时，可以使用不同的分析器来改进相关性。例如，可以禁用停用词移除以获得更精确的短语匹配。 相关参数 # 分析器参数（Analyzer） 搜索分析器参数（Search Analyzer）https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/index_phrases/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/index_phrases/短语索引（Index Phrases） # 启用短语查询的优化。当启用此参数时，Easysearch 会为短语查询构建额外的索引结构。 基本用法 # PUT my-index { "mappings": { "properties": { "content": { "type": "text", "index_phrases": true } } } } 适用的字段类型 # text match_only_text 默认值 # false 说明 # 启用 index_phrases 后，短语查询的性能会显著提高，但会增加索引大小。 相关参数 # 前缀索引（Index Prefixes） 索引参数（Index）https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/offline-install/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/offline-install/离线安装 Easysearch # 本文档介绍如何在没有网络连接的环境中安装 Easysearch。离线安装常见于内网、政务、金融等对网络隔离有严格要求的场景。 准备工作（在有网络的环境中） # 在可联网的机器上提前下载所有需要的安装包： 必需文件 # 文件 用途 下载地址 Easysearch Bundle 包 包含 Easysearch + 内置 JDK Linux AMD64 插件包（按需） IK 分词、Pinyin、KNN 等 插件列表 Bundle 包内置了 JDK，是离线安装的最简方式，无需单独准备 JDK。 可选文件 # 文件 用途 INFINI Console 安装包 集群管理和监控 INFINI Gateway 安装包 查询代理和网关 Linux 环境离线安装 # 步骤 1：系统调优 # 在安装 Easysearch 之前，先完成操作系统调优（此步骤不需要网络）：https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/split_queries_on_whitespace/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/split_queries_on_whitespace/空白符拆分查询（Split Queries on Whitespace） # 确定查询是否在空白处拆分。 基本用法 # PUT my-index { "mappings": { "properties": { "status": { "type": "keyword", "split_queries_on_whitespace": true } } } } 适用的字段类型 # keyword wildcard 默认值 # false 说明 # 当设置为 true 时，查询字符串在空白处拆分成多个术语。这在索引短语（如空格分隔的标签）的关键字字段中很有用。 相关参数 # 分析器参数（Analyzer）https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/thread-pool/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/config/node-settings/thread-pool/线程池与断路器配置 # 本页介绍 easysearch.yml 中与线程池、断路器和 API 兼容相关的配置项。 ⚠️ 警告：Easysearch 默认的线程池配置已经过充分调优。除非有明确的性能瓶颈证据，不建议修改线程池参数。盲目增大线程数反而可能导致性能下降。 线程池 # Easysearch 为不同类型的操作使用不同的线程池。 线程池类型 # 线程池 用途 默认大小 默认队列 search 搜索请求 CPU × 3 / 2 + 1（向下取整） 1000 write 索引/删除/更新/bulk 写入 CPU 核数 10000 index 单文档索引 CPU 核数 200 get GET 请求 CPU 核数 1000 analyze 分析请求 1 16 management 集群管理 5 — flush Flush 操作 CPU / 2（向下取整，至少 1） — refresh 刷新操作 CPU / 2（向下取整，至少 1） — snapshot 快照/恢复 CPU / 2（向下取整，至少 1） — warmer 预热操作 CPU / 2（向下取整，至少 1） — force_merge 强制合并 1 — 配置语法 # # 线程池大小 thread_pool.https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/scaling_factor/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/scaling_factor/缩放因子（Scaling Factor） # 缩放比因子用于将浮点值转换为长整数以获得更高的精度。 基本用法 # PUT my-index { "mappings": { "properties": { "price": { "type": "scaled_float", "scaling_factor": 100 } } } } 适用的字段类型 # scaled_float（mapper-extras 模块） 说明 # scaled_float 字段通过将浮点值乘以缩放比因子来将其存储为长整数。这可以节省磁盘空间并提高聚合性能。例如，使用 scaling_factor: 100，值 10.5 被存储为 1050。 缩放比因子必须是正数。常见值包括： 10 - 一位小数 100 - 两位小数 1000 - 三位小数 示例 # POST my-index/_doc/1 { "price": 10.50 } 相关参数 # 索引参数（Index） 文档值参数（Doc Values）https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/auto-refresh/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/auto-refresh/自动刷新数据 # 开启自动刷新后，数据探索页面将按设定的时间间隔自动更新查询结果。 操作步骤 # 开启自动刷新：在数据探索页面右上角，点击播放图标（▶️），即可启动自动刷新，图标同步变为暂停样式（⏸️）。 配置刷新间隔： 点击暂停图标旁的下拉箭头，打开时间设置菜单。 在「刷新间隔」输入框中，填写自定义刷新时长（如示例中的10秒），选择时间单位（秒）。 点击「应用」按钮，保存配置。 暂停自动刷新：点击页面右上角的暂停图标（⏸️），即可停止自动刷新，图标恢复为播放样式。 注意事项 # 刷新间隔设置过短会增加集群查询负载，建议根据业务实际需要合理配置。 页面切换到后台时，自动刷新仍会持续执行，如不需要请及时暂停。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/positive_score_impact/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/mapping-and-analysis/mapping-parameters/positive_score_impact/评分影响方向（Positive Score Impact） # 指示排名特性对得分的影响方向。 基本用法 # PUT my-index { "mappings": { "properties": { "boost": { "type": "rank_feature", "positive_score_impact": true } } } } 适用的字段类型 # rank_feature（mapper-extras 模块） 默认值 # true 说明 # true: 特性值越高，文档得分越高（正相关） false: 特性值越高，文档得分越低（负相关） 此参数告知搜索引擎如何使用排名特性来影响文档评分。 相关参数 # 索引参数（Index）https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/follower-settings/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/replication/follower-settings/跟随者设置 # 跟随者设置用于配置跨集群主从复制中跟随者索引的相关参数。 操作步骤 # 进入设置页面：在左侧导航栏点击「主从复制」，进入「跟随者设置」标签页。 配置参数：根据业务需求，配置块大小、最大并发文件块请求数等核心参数。 提交配置：参数设置完成后，点击「提交」按钮保存配置；若需恢复默认值，可先点击「重置」按钮，再提交配置。 验证结果：配置提交成功后，页面将生效并返回操作结果。 注意事项 # 使用主从复制功能前，需先在集群设置中配置好远程集群连接。 调整参数后，正在进行中的复制任务可能不会立即生效，新配置将在下一次复制周期开始时应用。 复制过程会占用网络带宽和集群资源，建议根据集群硬件配置合理设置块大小和并发数，避免影响主集群的正常业务。 点击「重置」按钮将恢复所有参数为系统默认值，重置后需点击「提交」才能生效。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/console/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/console/一键安装 Console 和 Easysearch # 目前，Easysearch 已提供内置的 Console UI 来管理当前集群，如果您有多个集群需要管理，建议使用 INFINI Console 来统一管理多个 Easysearch 集群。INFINI Console 也可以通过一键安装脚本进行安装，以下是安装步骤： # 启动默认配置 (Console + 1 个 Easysearch 节点) curl -fsSL http://get.infini.cloud/start-local | sh -s # 想要更丰富的体验？试试这个： # 启动 3 个 Easysearch 节点，设置密码，并开启 Agent 指标采集 curl -fsSL http://get.infini.cloud/start-local | sh -s -- up --nodes 3 --password "MyDevPass123." --metrics-agent 具体参数说明请参考博客文章 一键启动：使用 start-local 脚本轻松管理 INFINI Console 与 Easysearch 本地环境。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/delete-cluster/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/delete-cluster/删除集群 # 可以删除不再需要的集群，释放相关资源。 操作步骤 # 进入服务管理页面：在 Agent UI 中进入「服务管理」页面，查看已安装的 Easysearch 服务列表。 打开删除操作菜单：在目标服务的操作列，点击「…」按钮，在下拉菜单中选择「删除」选项。 确认删除操作：在弹出的删除确认窗口中，确认要删除的节点名称，点击「确定」按钮。 验证删除结果：删除完成后，服务列表中将不再显示该节点，代表删除操作成功。 注意事项 # 删除操作会永久移除该服务并同步删除对应数据目录，数据将无法恢复，请谨慎操作。 建议在执行删除前，先停止服务并备份必要数据。 如果该节点是集群中的唯一节点，删除后整个集群也将被移除。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/filter-field-list/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/filter-field-list/过滤字段列表 # 通过搜索或筛选快速定位需要的字段。 操作步骤 # 按名称搜索字段：在数据探索页面左侧的搜索字段名输入框中，输入字段名称（如 id），列表将自动过滤并显示匹配的字段。 按类型筛选字段：点击搜索框旁的筛选图标，打开「按类型筛选」面板： 可按「可聚合/可搜索」状态筛选字段； 可选择字段类型（文本、数值、日期等）； 可开启「隐藏缺失字段」，过滤掉无数据的字段。 查看筛选结果：配置完成后，可用字段列表将同步更新，仅显示符合筛选条件的字段。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/cluster-coordination/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/cluster-coordination/集群协调调优 # 本文介绍 Easysearch 集群协调层的高级调优参数，包括选举、故障检测和集群状态发布。这些参数通常不需要修改，仅在大规模集群或网络条件不佳时才需要调整。 前提：请先阅读 集群发现 了解基础配置。 选举调优 # 选举机制控制集群在主节点失联后如何选出新的主节点。 cluster.election.initial_timeout # 项目 说明 参数 cluster.election.initial_timeout 默认值 100ms 属性 静态 说明 节点首次发起选举前的随机等待上界。初始超时引入随机性，避免多个节点同时发起选举导致票数分裂 cluster.election.back_off_time # 项目 说明 参数 cluster.election.back_off_time 默认值 100ms 属性 静态 说明 每次选举失败后增加的退避时间上界。防止选举风暴 cluster.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/feiteng/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/feiteng/飞腾平台安装 # 飞腾平台介绍 # 飞腾平台基于 ARM 架构，由飞腾公司自主研发，提供高性能、低功耗的 CPU 产品，广泛应用于信创桌面、服务器及嵌入式领域，全面适配统信 UOS、麒麟等国产操作系统，支撑党政、金融、电信等行业国产化替代需求。 飞腾平台安装参考 # 目前，Easysearch 已支持在飞腾芯片的国产操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/ingest-pipeline-config/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/ingest-pipeline-config/Ingest Pipeline 配置指南 # Ingest Pipeline 允许在文档索引之前进行预处理（如字段提取、数据转换、富化等）。本文介绍 Ingest 节点的配置和 Pipeline 的高级使用技巧。 启用 Ingest 功能 # 默认情况下所有节点都具备 Ingest 功能。如需将 Ingest 角色分配给专用节点，请参考 集群节点配置 中的节点角色说明。 Pipeline 管理 # 创建 Pipeline # PUT /_ingest/pipeline/my-pipeline { "description": "日志预处理流水线", "processors": [ { "grok": { "field": "message", "patterns": ["%{COMBINEDAPACHELOG}"] } }, { "date": { "field": "timestamp", "formats": ["dd/MMM/yyyy:HH:mm:ss Z"] } }, { "remove": { "field": "message" } } ] } 查看 Pipeline # # 查看所有 GET /_ingest/pipeline # 查看指定 GET /_ingest/pipeline/my-pipeline # 查看 Pipeline 统计 GET /_nodes/stats/ingest 删除 Pipeline # DELETE /_ingest/pipeline/my-pipeline 模拟测试 # 在正式使用前模拟验证 Pipeline 处理效果：https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/add-table-field/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/add-table-field/新增表格字段 # 可以将字段添加到数据探索的表格视图中进行展示。 操作步骤 # 进入数据探索页面：在左侧导航栏点击「数据探索」，进入数据探索页面。 添加字段到表格：在左侧字段列表，鼠标悬停在字段上，点击「+」图标即可。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/production-env/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/production-env/生产环境部署指南 # 本文提供 Easysearch 生产环境部署的完整建议，涵盖硬件选型、节点规划、高可用架构与上线前检查清单。 硬件推荐 # 组件 CPU 内存 JVM 堆 磁盘 高可用实例数 Easysearch 16 核+ 64 GB+ 31 GB SSD ≥ 3 INFINI Console 8 核 16 GB — ≥ 50 GB 1 INFINI Gateway 8 核 16 GB — ≥ 50 GB ≥ 2 详见 硬件配置。 磁盘选型 # 生产环境：强烈建议使用本地 SSD（NVMe 优先）。随机 IOPS 和吞吐量直接影响索引写入与查询延迟。 避免网络存储：NFS / CIFS 不适用于 Easysearch 数据目录。云环境可使用高性能云盘（如阿里云 ESSD、AWS gp3/io2）。 容量估算：原始数据量 × (1 + 副本数) × 1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/enter-ui-overview/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/enter-ui-overview/进入 Easysearch UI 概览 # 可以从服务管理平台快速跳转到 Easysearch UI 的概览页面。 操作步骤 # 进入服务管理页面：在 Agent UI 的「服务管理」页面中，找到目标集群，点击集群名称。 完成身份验证：在跳转的登录页面中，输入集群地址、用户名和密码，点击箭头按钮进行登录。 进入集群概览页面：登录成功后，即可进入 Easysearch UI 的集群概览页面，查看集群状态、节点信息、资源占用等核心指标。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/kylin/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/kylin/麒麟软件平台安装 # 麒麟软件平台介绍 # 麒麟软件平台是由中国电子旗下麒麟软件有限公司研发的国产操作系统，基于 Linux 内核，提供桌面版和服务器版，广泛应用于党政、国防、金融、能源等关键领域。全面适配龙芯、鲲鹏、兆芯、海光、申威等主流信创 CPU，支持国密算法与可信计算，致力于构建安全、稳定、自主可控的国产基础软件生态。 麒麟软件平台安装参考 # 目前，Easysearch 已支持在麒麟软件操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.infini.cloud | bash -s -- -p easysearch -d /opt/easysearch # 进入 Easysearch 目录 cd /opt/easysearch # 初始化 Easysearch bin/initialize.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/remove-table-field/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/remove-table-field/移除表格字段 # 可以将不需要的字段从数据探索的表格视图中移除。 操作步骤 # 定位需移除的字段：在「数据探索」页面中，找到需要从表格中移除的目标字段（如 _id）。 选择移除方式： 方式一：从「已选择字段」列表移除：在页面左侧「已选择字段」区域，点击目标字段右侧的「×」图标。 方式二：从表格表头移除：在右侧数据表格的表头中，点击目标字段名称右侧的「×」图标。 确认移除结果：两种方式均会立即生效，目标字段将从「已选择字段」列表和数据表格中同步移除。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/index-sorting/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/index-sorting/索引排序配置指南 # 索引排序（Index Sorting）允许在索引阶段对文档按指定字段排序存储。这可以显著加速按排序字段的查询和聚合操作，但会增加索引写入开销。 工作原理 # 默认情况下，Lucene 按文档写入顺序存储。启用索引排序后，每个段（Segment）内的文档将按排序字段有序存储： 默认存储： doc1 → doc2 → doc3 → doc4 → doc5 索引排序后： doc3 → doc1 → doc5 → doc2 → doc4 (按 timestamp 降序) 优势： 按排序字段查询时可提前终止（Early Termination），大幅减少扫描量 提高按排序字段做聚合的效率 改善压缩率（相邻文档字段值更接近） 代价： 索引写入速度降低 ~40%–50%（段合并时需要排序） 索引大小可能增加 排序字段只能在索引创建时指定，无法修改 配置参数 # index.sort.field # 项目 说明 参数 index.sort.field 默认值 无（不排序） 属性 静态（仅在索引创建时设置） 说明 排序字段列表。支持多字段排序。字段类型必须是 boolean、numeric、date 或 keyword index.https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/uniontech/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/uniontech/统信 UOS 平台安装 # 统信 UOS 平台介绍 # 统信 UOS（Unity Operating System）是基于 Linux 内核的国产操作系统，面向党政、金融、能源等关键领域，提供安全、稳定、易用的桌面与服务器版本，深度适配主流信创CPU平台（如龙芯、鲲鹏、兆芯、海光、申威等），构建完善的国产软硬件生态体系。 统信 UOS 平台安装参考 # 目前，Easysearch 已支持在统信 UOS 操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/enter-ui-node-details/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/service-management/enter-ui-node-details/进入 Easysearch UI 节点详情 # 可以从服务管理平台快速跳转到 Easysearch UI 的节点详情页面。 操作步骤 # 进入服务管理页面：在 Agent UI 的「服务管理」页面中，找到目标节点，点击节点名称。 完成身份验证：在跳转的登录页面中，输入集群地址、用户名和密码，点击箭头按钮进行登录。 进入节点详情页面：登录成功后，将直接进入该节点的详情页面，查看节点概览、分片、配置、插件及日志等信息。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/aliyun/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/aliyun/阿里云部署指南 # 本文介绍在阿里云 ECS 上部署 Easysearch 集群的推荐配置与实践。 推荐实例规格 # 节点角色 实例族 规格示例 说明 Master（专用） 通用型 g7 ecs.g7.xlarge (4C16G) 轻量计算，稳定即可 Data 存储增强型 i3 / 本地 SSD 型 ecs.i3.2xlarge (8C64G) 本地 NVMe SSD，高 IOPS Data（云盘方案） 通用型 g7 ecs.g7.4xlarge (16C64G) 搭配 ESSD PL1/PL2 Coordinating 计算型 c7 ecs.c7.2xlarge (8C16G) 按查询并发酌情添加 生产环境至少 3 节点，跨可用区部署以实现高可用。 存储选择 # 存储类型 IOPS 适用场景 本地 NVMe SSD (i 系列) 极高 高写入吞吐、大数据量 ESSD PL1 50,000 通用生产环境 ESSD PL2 100,000 高性能搜索场景 高效云盘 5,000 测试环境 / 冷数据 建议：https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/aws/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/aws/AWS 部署指南 # 本文介绍在 AWS EC2 上部署 Easysearch 集群的推荐配置与实践。 推荐实例类型 # 节点角色 实例族 规格示例 说明 Master（专用） m6i / m7i m6i.xlarge (4C16G) 轻量计算 Data i3 / i3en i3.2xlarge (8C61G) 本地 NVMe SSD Data（EBS 方案） r6i / r7i r6i.4xlarge (16C128G) 搭配 gp3/io2 Coordinating c6i / c7i c6i.2xlarge (8C16G) 按查询并发酌情添加 生产环境至少 3 节点，跨 AZ 部署。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/view-field-top-values/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/view-field-top-values/查看字段高频值 # 可以查看某个字段中出现频率最高的值及其分布情况。 操作步骤 # 进入数据探索页面：在左侧导航栏点击「数据探索」，进入对应索引的数据列表页。 定位目标字段：在页面左侧「可用字段」列表中，找到需要查看高频值的目标字段（如 _id）。 打开高频值面板：点击目标字段，在弹出的面板中点击闪电图标，即可查看该字段的前5个高频值及占比。 查看统计结果：面板中会显示字段的高频值、占比，以及统计基于的样本记录数，帮助快速了解字段数据分布。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/bclinux/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ciip/bclinux/移动云 BC-Linux 平台安装 # 移动云 BC-Linux 平台介绍 # 移动云 BC-Linux 是中国移动自主研发的企业级操作系统，基于 Linux 内核，专为云计算和大数据应用设计，具备高性能、高可靠性和强安全性，广泛应用于中国移动的云计算平台和数据中心。 移动云 BC-Linux 平台安装参考 # 目前，Easysearch 已支持在移动云 BC-Linux 操作系统上运行，联网环境建议使用一键安装脚本进行安装，离线环境建议下载 Bundle 包进行安装，分布式集群安装请参考 分布式集群安装。 前提条件：已参照 系统调优进行了系统优化，同时为 Easysearch 创建了专用的用户。 初始化系统参数及用户命令参考 # # 调整内核配置 echo "vm.max_map_count=262144" >> /etc/sysctl.conf && sysctl -p # 增加用户组与用户 groupadd -r easysearch && useradd -r -g easysearch -d /home/easysearch -s /sbin/nologin -c "Easysearch Service Account" easysearch 安装命令参考 # # 创建数据目录 mkdir -p /opt/easysearch # 下载最新版本的 Easysearch 并安装 curl -sSL http://get.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/quick-add-top-value-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/quick-add-top-value-filter/快速新增高频值过滤条件 # 可以直接点击字段的高频值，快速将其添加为过滤条件。 操作步骤 # 定位目标字段：在「数据探索」页面左侧的「可用字段」列表中，找到目标字段（如 clientip），点击字段名展开字段面板。 查看高频值：在字段面板中，点击闪电图标查看该字段的前5个高频值。 新增高频值过滤条件：在高频值列表中，点击目标值旁的 「+」 或 「–」 按钮： 「+」：新增包含该值的过滤条件（is 类型）。 「–」：新增排除该值的过滤条件（is not 类型）。 查看过滤结果：新增的过滤条件将自动应用到搜索结果中，并在搜索栏下方的过滤条显示。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/tencent-cloud/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/tencent-cloud/腾讯云部署指南 # 本文介绍在腾讯云 CVM 上部署 Easysearch 集群的推荐配置与实践。 推荐实例规格 # 节点角色 实例族 规格示例 说明 Master（专用） 标准型 S6 S6.LARGE16 (4C16G) 轻量计算 Data 高 IO 型 IT5 IT5.4XLARGE64 (16C64G) 本地 NVMe SSD Data（云盘方案） 内存型 M6 M6.4XLARGE64 (16C64G) 搭配增强型 SSD Coordinating 计算型 C6 C6.2XLARGE16 (8C16G) 按查询并发酌情添加 存储选择 # 存储类型 IOPS 适用场景 本地 NVMe SSD (IT5) 极高 高性能搜索 增强型 SSD 50,000 通用生产环境 SSD 云硬盘 26,000 标准场景 高性能云硬盘 6,000 测试环境 网络配置 # VPC 与安全组 # VPC CIDR: 10.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/sort-table-field/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/sort-table-field/表格字段值排序 # 可以按照某个字段的值对表格数据进行升序或降序排列。 操作步骤 # 点击表头排序：在「数据探索」页面的数据表格中，点击目标字段的表头名称，即可切换排序方式（升序↑ / 降序↓）。表头旁会出现箭头图标指示当前排序方向。 注意事项 # 部分字段类型（如 text）默认不支持排序，需启用 fielddata 或使用对应的 keyword 子字段。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ipv6/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/install-guide/ipv6/Easysearch 的 IPv6 配置 # 配置 # Easysearch 支持运行在 IPv6 模式，以下是具体操作： 假设本机 IPv6 地址为：fe80::18df:9883:1e27:b040%en0 修改 config/easysearch.yml 将 ip 相关的参数修改为 IPv6 对应的格式: network.host: ["::1", "fe80::18df:9883:1e27:b040%en0"] http.port: 9200 transport.port: 9300 discovery.seed_hosts: ["[::1]:9300", "[fe80::18df:9883:1e27:b040%en0]:9300"] cluster.initial_master_nodes: ["[fe80::18df:9883:1e27:b040%en0]:9300"] 这个配置表示节点使用 IPv6 地址加入集群的配置，监听本地回环地址和一个特定的链路本地地址。 验证 # 启动 Easysearch，即可使用 curl 工具进行测试： % curl -6 -v -ku "admin:=juNrz?BY4SeSlL%Tm29OfP5" "https://[fe80::18df:9883:1e27:b040%en0]:9200" * Trying fe80::18df:9883:1e27:b040:9200... * Connected to fe80::18df:9883:1e27:b040 (fe80::18df:9883:1e27:b040) port 9200 (#0) * ALPN, offering h2 * ALPN, offering http/1.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/change-column-position/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/change-column-position/更改表格字段列位置 # 可以通过拖拽或其他方式调整表格中字段列的显示顺序。 操作步骤 # 定位表格字段：在「数据探索」页面的数据表格中，找到需要移动的目标字段列。 拖动字段列：将鼠标悬停在目标字段的表头上，按住鼠标左键并拖动到目标位置后松开，即可完成字段列位置的调整。 查看调整结果：拖动完成后，表格列顺序将立即更新。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/view-row-details/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/view-row-details/查看表格行完整数据 # 可以展开表格中的某一行，查看该文档的所有字段和完整数据。 操作步骤 # 展开行详情：在「数据探索」页面的数据表格中，点击目标行左侧的「展开」图标（▶），展开该行的完整数据详情。 查看完整数据：展开后，可以看到该行记录的所有字段和值，包括表格中未显示的字段。 切换视图：支持在「Table」（表格）和「JSON」视图之间切换，方便查看原始 JSON 格式的文档数据。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/quick-add-field-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/quick-add-field-filter/快速新增字段值过滤条件 # 可以直接点击表格中的字段值，快速将其添加为过滤条件。 操作步骤 # 展开行详情：在「数据探索」页面的数据表格中，点击目标行左侧的「展开」图标（▶），展开完整的字段列表。 选择过滤操作：在展开的字段列表中，找到目标字段值，点击右侧的操作图标： 「+」图标：新增包含该字段值的过滤条件（is 类型）。 「–」图标：新增排除该字段值的过滤条件（is not 类型）。 查看过滤结果：新增的过滤条件将自动应用，搜索结果将被筛选，过滤条件显示在搜索栏下方。https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/quick-add-exists-filter/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/quick-add-exists-filter/快速新增存在某字段的过滤条件 # 可以快速添加一个过滤条件，筛选出包含指定字段的文档。 操作步骤 # 定位目标字段：在「数据探索」页面左侧的「可用字段」列表中，找到需要新增「存在」过滤条件的目标字段（如 clientip）。 新增存在过滤条件：点击目标字段，在弹出的字段面板中，点击「存在」（exists）图标，即可新增一个「存在该字段」的过滤条件。 查看过滤结果：新增的过滤条件将自动应用，搜索结果将筛选出包含该字段的记录，过滤条显示在搜索栏下方。https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/advanced-settings/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/deployment/advanced-config/advanced-settings/高级配置参数 # 本页面详细列举 Easysearch 的所有高级配置参数，包括集群、节点、索引等多层级配置。 概述 # Easysearch 配置涉及多个层级： 节点级：影响单个节点的行为（node., path., 等） 集群级：影响整个集群的行为（cluster., discovery., 等） 索引级：影响单个索引的行为（index.*, 等） 传输层：网络通信相关（transport., http., 等） 集群协调配置 # 集群选举、节点发现和主节点选择的相关配置。 选举配置 # 参数 默认值 动态 说明 cluster.election.initial_timeout 100ms ✗ 初始选举超时 cluster.election.back_off_time 100ms ✗ 选举退避时间 cluster.election.max_timeout 10s ✗ 最大选举超时 cluster.election.duration 30s ✗ 选举持续时间 主节点检查配置 # 参数 默认值 动态 说明 cluster.https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/export-csv/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/management/data-explorer/export-csv/导出 CSV 数据 # 可以将当前数据探索的查询结果导出为 CSV 文件，方便离线分析。 操作步骤 # 查询目标数据：在「数据探索」页面中，通过设置索引、时间范围、搜索条件和过滤器等，定位到需要导出的数据。 点击导出按钮：在表格工具栏中，点击「导出」按钮。 配置导出选项：在弹出的导出对话框中，配置以下选项： 文件名：设置导出文件的名称。 导出类型：选择“CSV”格式。 导出范围：选择导出当前页数据或全部数据。 完成导出：点击「导出」按钮，系统将生成 CSV 文件并自动下载到本地。 注意事项 # 导出的数据受当前时间范围、搜索条件和过滤条件的限制，如需导出完整数据，请确认已移除不必要的筛选条件。 选择「全部数据」导出时，数据量较大可能导致导出耗时较长，建议先通过过滤条件缩小数据范围。 导出的 CSV 文件编码为 UTF-8，使用 Excel 打开时如出现中文乱码，可尝试以 UTF-8 编码方式导入。https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-recipes/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/features/geo-search/geo-recipes/地理位置实践 # 本页以“场景实践”的形式给出几个常见地理位置需求下的解决方案，帮助你在实际应用中更好地使用地理位置功能。 在具体 API 上，Easysearch 主要通过： geo_distance / _geo_distance：按距离过滤与排序 geo_shape：做复杂形状的围栏与空间关系判断 geohash_grid / geo_bounds：在地图上做网格聚合与视野控制 下面的配方会围绕这些能力展开。 地理位置聚合 # 虽然按照地理位置对结果进行过滤或者打分很有用，但是在地图上呈现信息给用户通常更加有用。一个查询可能会返回太多结果以至于不能单独地展现每一个地理坐标点，但是地理位置聚合可以用来将地理坐标聚集到更加容易管理的 buckets 中。 处理 geo_point 类型字段的三种聚合： 地理距离聚合 # geo_distance 聚合对一些搜索非常有用，例如找到所有距离我 1km 以内的披萨店。搜索结果应该也的确被限制在用户指定 1km 范围内，但是我们可以添加在 2km 范围内找到的其他结果： GET /attractions/_search { "query": { "bool": { "must": { "match": { "name": "pizza" } }, "filter": { "geo_bounding_box": { "location": { "top_left": { "lat": 40.8, "lon": -74.1 }, "bottom_right": { "lat": 40.4, "lon": -73.https://docs.infinilabs.com/easysearch/v2.2.0/docs/api-reference/rest-api-reference/Mon, 01 Jan 0001 00:00:00 +0000https://docs.infinilabs.com/easysearch/v2.2.0/docs/api-reference/rest-api-reference/Easysearch REST API # async_search.delete # 删除指定的异步搜索请求及其结果。 DELETE _async_search/{id} URL 参数 # 参数 类型 说明 id string 必需。异步搜索请求的 ID。 async_search.get # 获取异步搜索请求的当前状态和可用结果。 GET _async_search/{id} URL 参数 # 参数 类型 说明 id string 必需。异步搜索请求的 ID。 wait_for_completion_timeout string 等待搜索完成的超时时间。 keep_alive string 结果保留的时间长度。 async_search.stats # 获取集群中异步搜索的统计信息。