elasticsearch-java客户端jar包中各模块的应用梳理

最近使用elasticsearch-java客户端实现对elasticsearch服务的Api请求，现对elasticsearch-java客户端jar包中各模块的应用做个梳理。主要是对co.elastic.clients.elasticsearch路径下的各子包的简单说明。使用的版本为：co.elastic.clients:elasticsearch-java:8.16.1。

1、_helpers

通过包名字面意义上理解，像一个辅助包，其包括bulk和esql。对其中的某几个类进行说明：

BulkIngester：用于批量将数据摄入（ingest）到 Elasticsearch 中的工具类。利用了 Elasticsearch 的批量 API（_bulk API）的原理。它会收集多个索引请求，将它们组合成一个或多个批量请求。

EsqlHelper：用于ES|QL数据查询和检索的工具类。

2、_types

基础对象的定义，如：dsl的term查询类、聚合的平均属性、mapping中的属性、分词相关等。

dsl查询相关类的使用，参考前面文章：Elasticsearch Java Api Client中DSL语句的查询方法汇总。

3、async_search

异步搜索API相关类。

Async Search（异步搜索）是一种用于处理长时间运行搜索请求的机制。当面对复杂的搜索查询、大量的数据或者资源受限的情况时，同步搜索可能会导致客户端长时间等待结果。Async Search 允许用户发起搜索请求后，继续执行其他任务，稍后再来获取搜索结果。

4、autoscaling

自动缩放或自动扩展。

在 Elasticsearch API 中，autoscaling（自动缩放）功能用于根据集群的负载情况自动调整资源。这包括自动调整节点数量、资源分配（如 CPU、内存、存储）等，以优化集群性能、降低成本，并确保在不同负载条件下都能提供稳定高效的服务。

5、cat（Compact and aligned text）

在 Elasticsearch API 中，Compact and Aligned Text（CAT）是一组用于获取集群相关信息的接口。这些接口以简洁且格式化的文本形式返回集群的各种状态信息，包括索引信息、节点信息、分片信息等，帮助用户快速了解和监控集群的运行状况。主要命令：

5.1 /_cat/indices

功能：这个命令主要用于查看索引相关的信息。它返回集群中所有索引的详细情况，如索引名称、状态（例如是否打开或关闭）、主分片数量、副本分片数量、文档数量、存储大小等。

health status index        uuid                   pri rep docs.count docs.deleted store.size pri.store.size
green  open   my_index     xxxxxxxxxx             5   1      10000            0      50mb          25mb

5.2 /_cat/nodes

功能：用于获取集群中节点的信息。包括节点名称、IP 地址、端口号、节点角色（如主节点、数据节点等）、负载指标（如 CPU 使用率、内存使用率等）、磁盘使用情况等。

ip        heap.percent ram.percent cpu load_1m load_5m load_15m node.role master name
127.0.0.1           40          70   2    0.20    0.15     0.10 dilmrt    *      node1

5.3 /_cat/shards

提供关于分片的详细信息，包括分片所属的索引、分片的编号、分片所在的节点、分片的状态（如启动中、已分配等）等。

index   shard prirep state      docs  store ip        node
my_index 0     p      STARTED   5000  25mb  127.0.0.1 node1
my_index 0     r      STARTED   5000  25mb  127.0.0.2 node2

6、ccr（Cross-cluster replication）

6.1 概念

跨集群复制是一种高可用解决方案，能够实现数据迁移、数据备份以及降低访问延迟。它采用主备架构模型，在主集群中创建 leader 索引，在备集群中通过主动 Pull 方式复制数据到 follower 索引中，且 follower 索引为只读索引。

6.2 需求

• 数据备份：在不同地理位置的集群间复制数据，以防止单点故障。
• 灾难恢复：在主集群出现故障时，能够迅速切换到备集群。
• 负载平衡：通过跨多个集群分布数据来提高性能和可扩展性。
• 数据分析：跨地理区域整合数据，便于分析。

7、cluster

集群API相关类。

在 Elasticsearch 中，Cluster API 是一组用于管理和获取集群相关信息的接口。它允许用户对整个集群的状态、配置、节点等方面进行操作和查询，是维护和监控 Elasticsearch 集群健康运行的重要工具。

7.1 集群健康状态查询（Cluster Health）

功能描述：通过/_cluster/health端点可以获取集群的健康状况。返回的信息包括集群状态（如绿色、黄色或红色），绿色表示所有主分片和副本分片都已正确分配，黄色表示至少有一个副本分片未分配，红色表示存在未分配的主分片，这通常意味着数据丢失风险。还能获取到活动的分片数量、未分配的分片数量等详细信息。

7.2 集群状态查询（Cluster State）

功能描述：/_cluster/state端点提供了集群的完整状态信息。这包括集群的元数据，如索引的设置、映射、分片分配情况，以及节点的信息，如节点的角色（主节点、数据节点等）、节点的连接状态等。与集群健康状态查询相比，它提供了更全面、更详细的集群信息。

7.3 集群设置管理（Cluster Settings）

功能描述：使用/_cluster/settings端点可以获取和修改集群的设置。这包括一些全局的配置参数，如集群的名称、自动发现节点的方式、索引的默认配置等。用户可以通过 API 来更新这些设置，以适应不同的业务需求和环境变化。

8、connector

此包下，主要分为Connector和Sync Jobs 两个API。 用于管理数据连接（Connectors）和同步作业（Sync Jobs）。这些 API 允许用户将外部数据源与 Elasticsearch 集成，确保数据能够持续、高效地从外部系统同步到 Elasticsearch 中，以便进行后续的搜索、分析等操作。

9、core

核心模块，请求与响应相关类的定义。

10、dangling_indices

悬空索引的API。

10.1 定义

在 Elasticsearch 中，悬空索引（Dangling Index）是一种特殊的索引状态。它主要是指在集群状态更新过程中，索引的元数据在集群状态中被标记为已删除，但索引的实际数据（如分片）仍然存在于节点的存储中。这种情况可能会导致一些问题，例如占用磁盘空间，并且可能会干扰集群的正常操作。

10.2 产生原因

• **集群状态更新冲突：**当集群在进行复杂的状态更新操作时，比如同时处理多个索引的创建、删除和更新操作。如果在索引删除操作的过程中出现了故障或者网络问题，就可能导致索引的元数据在集群状态中被删除，但实际的索引数据没有被完全清理。例如，主节点发送了删除索引的指令，但是在部分从节点还没有完成删除操作时，集群状态就已经更新为索引已删除，那么这些从节点上的索引分片就会成为悬空索引。
• **节点故障恢复异常：**当节点出现故障后重新加入集群时，如果在故障前节点正在处理索引相关操作，恢复过程可能出现问题。比如，节点在故障前正在删除索引，但是恢复时没有正确处理这个未完成的删除操作，就可能导致索引数据残留，形成悬空索引。

11、enrich

丰富API。

在 Elasticsearch API 中，Enrich API 用于通过将外部数据与现有索引数据相结合，来丰富（enrich）索引中的文档内容。这有助于在搜索和分析过程中提供更全面的信息，提升数据的价值。

11.1 创建 Enrich Policy

创建一个富集策略来定义如何从外部数据源获取数据以及如何将这些数据与索引中的文档进行匹配。可以通过在请求体中指定源索引（source index）和匹配字段（matching fields）来实现。

例如，假设有一个客户信息索引和一个订单索引，想要将客户的详细信息（如姓名、联系方式等）添加到订单文档中，可以创建一个富集策略，将客户信息索引作为源索引，使用客户 ID 作为匹配字段。

{
  "name": "customer_info_enrichment",
  "match": {
    "indices": "customer_info_index",
    "match_field": "customer_id",
    "enrich_fields": ["customer_name", "customer_contact_info"]
  }
}

11.2 执行 Enrich Policy

创建好富集策略后，需要执行它来实际进行数据富集。通过向/_enrich/policy/{policy_name}/_execute端点（其中{policy_name}是富集策略的名称）发送请求来执行策略。执行过程中，Elasticsearch 会按照策略中的定义，扫描源索引和目标索引，找到匹配的文档，并将指定的字段内容添加到目标文档中。

例如，对于上面创建的 "customer_info_enrichment" 策略，执行后，订单索引中的文档（假设订单索引中有客户 ID 字段）会根据客户 ID 与客户信息索引中的记录进行匹配，然后将客户姓名和联系方式等信息添加到订单文档中。

---

12、eql（Event Query Language）

在 Elasticsearch API 中，Event Query Language（EQL）是一种专门用于处理事件数据的查询语言。它的目的是让用户能够高效地从存储在 Elasticsearch 中的大量事件数据中检索、分析和关联事件，尤其适用于安全分析、系统监控和故障排查等场景。

12.1 事件序列查询

EQL 的一个重要特点是能够进行事件序列查询。例如，通过sequence by子句可以指定按照某个字段（如用户 ID）对事件进行分组，然后查询事件的先后顺序。

12.2 条件筛选与逻辑组合

与传统查询语言类似，EQL 支持条件筛选。可以使用where子句来指定事件需要满足的条件。

12.3 事件关联与聚合

EQL 支持事件之间的关联和聚合操作。例如，通过关联用户登录事件和文件访问事件，可以分析用户在登录系统后访问了哪些文件。

13、esql （Elasticsearch Query Language (ES|QL)）

The Elasticsearch Query Language (ES|QL) 是 Elasticsearch 提供的一种高级查询语言。它旨在提供一种更简单、更直观的方式来查询和检索存储在 Elasticsearch 中的数据，融合了传统数据库查询语言的一些特点和 Elasticsearch 特有的功能，用于处理结构化和半结构化数据。

13.1 基础查询

SELECT field1, field2
FROM index_name
WHERE condition;

13.2 函数使用

SELECT AVG(price)
FROM product_index;

13.3 关联查询与子查询

SELECT o.order_id, c.customer_name
FROM orders_index o
JOIN customers_index c ON o.customer_id = c.customer_id;

13.4 聚合与分组查询

SELECT product_category, SUM(sales_amount)
FROM sales_index
GROUP BY product_category;

14、features

功能API，查询和重置Elasticsearch和Elasticsearch插件提供的功能。

15、fleet

队列API。包括：获取全局检查点、队列搜索、队列多重搜索，支持Fleet使用Elasticsearch作为内部代理和操作数据的数据存储。这些API是实验性的，仅供Fleet内部使用。

16、graph

Graph explore API（图形浏览API）

在 Elasticsearch API 中，Graph API 用于处理和分析数据之间的关系，构建和查询图结构数据。它允许用户发现文档之间隐藏的关联关系，这在知识图谱构建、社交网络分析、推荐系统等诸多领域都非常有用。

17、ilm（Index lifecycle management）

索引生命周期管理的API，是elasticsearch提供的一种用于自动管理索引的生命周期的功能。允许使用者定义索引的各个阶段，从创建至删除。并允许使用者在每个阶段定义索引需要执行的特定动作。这些动作包含索引创建，rollover滚动规则， shrink收缩索引，索引降冷，删除索引等动作。极大程度的降低了elasticsearch索引管理的成本。

参考文档：elasticsearch的ILM(Index Lifecycle Management)操作详解-腾讯云开发者社区-腾讯云

18、indices

索引API。

能够管理单个索引、索引设置、别名、映射和索引模板。

19、inference

推理API。

在 Elasticsearch 中，Inference API 用于在数据索引和搜索过程中集成机器学习推理能力。它允许用户利用预训练的机器学习模型对文本或其他数据类型进行处理，例如分类、实体识别、文本嵌入等操作，从而增强 Elasticsearch 的数据分析和检索功能。

20、ingest

摄取API。

Ingest API 是 Elasticsearch 中一个强大的工具，用于在数据进入 Elasticsearch 之前对其进行预处理。它允许用户定义一系列的处理器（processors），这些处理器可以对文档进行各种操作，如转换、过滤、丰富数据内容等，以确保进入索引的文档符合特定的要求或包含更有价值的信息。处理器可以组合使用，形成一个管道（pipeline）。

• a、创建和管理 Ingest 管道（Pipeline）。
• b、在索引过程中应用 Ingest 管道
• c、geo：地理ip统计
• d、simulate：模拟操作，主要用于模拟请求在 Elasticsearch 集群中的执行情况。它允许用户在不实际执行可能会对数据产生影响的操作（如索引、搜索、更新等操作）的情况下，查看这些操作会如何被集群处理，包括查看查询的解析过程、聚合的执行方式以及相关的性能影响等诸多方面。

21、license

Licensing APIs 主要用于管理 Elasticsearch 的许可证。这些 API 提供了一种方式来获取许可证信息、安装新的许可证、更新现有许可证以及检查许可证的有效性，确保软件的使用符合许可协议的规定。

22、logstash

Logstash APIs 主要用于管理和监控 Logstash 与 Elasticsearch 之间的交互。Logstash 是一个数据收集引擎，它可以从多种数据源获取数据，并将其发送到 Elasticsearch 进行存储和后续分析。这些 API 提供了对 Logstash 配置、管道状态、监控数据等方面的操作和查询功能。

---

23、migration

迁移Apis，主要针对deprecations和system_features的处理。

• migration/deprecations相关内容中，主要涉及到在迁移过程中已弃用（deprecations）功能的处理。随着 Elasticsearch 版本的不断更新，一些旧的功能、配置或 API 可能会因为技术改进、性能优化或安全原因而被标记为弃用。理解和正确处理这些弃用内容是顺利进行迁移的关键。
• migration/system_features相关的 API 主要用于处理系统特性在版本升级过程中的迁移问题。

24、ml（Machine learning）

Machine Learning API 是用于在 Elasticsearch 中构建、训练、部署和管理机器学习模型的接口。它使企业能够利用数据中的模式和趋势，通过机器学习算法进行异常检测、预测分析等操作，从而挖掘数据的潜在价值，提升数据分析的深度和广度。

25、monitoring

它主要用于高效地将大量的监控信息发送到 Elasticsearch 进行存储和后续分析。这些监控数据可以来自 Elasticsearch 自身的各个组件，如节点的性能数据、索引的状态数据，也可以是与 Elasticsearch 集成的外部系统的数据。

26、nodes

Nodes API 是一组用于获取和管理集群中节点相关信息的接口。这些接口可以帮助用户了解节点的状态、配置、性能指标等诸多方面的情况，对于监控、维护和优化 Elasticsearch 集群的运行非常关键。

27、query_rules

此功能为8.15.0版本新增。

"Query Rules" 是用于控制和定制查询行为的规则集合。这些规则可以帮助用户根据特定的业务需求、数据特点或性能要求，对查询操作进行优化、限制或扩展。

主要应用场景：查询优化规则、安全与访问控制规则、数据过滤与限制规则

28、rollup

Rollup APIs 用于创建和管理数据聚合（rollup）任务。Rollup 是一种数据处理技术，它可以将原始的详细数据按照一定的规则（如时间间隔、字段值范围等）进行聚合，生成汇总数据。这有助于减少数据存储量、提高查询性能，尤其适用于处理大规模的时间序列数据。

29、search_application

Search Application APIs 是用于构建和管理搜索应用程序的一组接口。这些 API 允许用户自定义搜索体验，包括配置搜索策略、管理搜索结果的展示、处理用户输入、行为分析等，从而满足各种复杂的搜索需求，如企业级文档搜索、电商产品搜索或知识图谱搜索等。

30、searchable_snapshots

searchable - snapshots（可搜索快照）是一种用于以低成本存储和高效查询大量数据的功能。它允许用户将数据快照存储在低成本的存储介质（如对象存储）上，并且能够像查询本地存储数据一样对这些快照进行搜索，而无需将数据全部恢复到本地磁盘。

31、security

Security API 是用于管理和配置 Elasticsearch 安全相关功能的一组接口。它的主要目的是确保数据的安全性、用户访问的合法性以及集群操作的安全性，涵盖用户认证、授权、加密等多个安全领域。

主要功能：用户认证（用户管理）、授权（角色与权限管理）、加密（数据加密、密钥管理）。

32、shutdown

Shutdown API 是用于安全关闭 Elasticsearch 节点或获取节点关闭状态的一组接口。

---

33、slm（Snapshot lifecycle management）

快照生命周期管理（Snapshot Lifecycle Management，简称 SLM）是 Elasticsearch 中的一个功能，用于自动化地创建、保留和删除索引快照。它的目的是确保数据备份的一致性、高效性和合规性，帮助用户有效地管理数据备份策略，以应对数据丢失、灾难恢复等情况。

34、snapshot

快照（Snapshot）是数据在某一时刻的备份，而快照和恢复 API（Snapshot and Restore APIs）用于创建、管理这些数据备份，并在需要时将数据从备份中恢复。这对于数据保护、灾难恢复和数据迁移等场景至关重要。

35、sql

SQL API 提供了一种使用类 SQL 语法来查询 Elasticsearch 数据的方式。这使得熟悉 SQL 的用户能够更方便地与 Elasticsearch 中的数据进行交互，降低了查询数据的学习成本，并且在某些复杂查询场景下提供了更简洁、高效的查询途径。

在使用sql时，可使用对应的sql插件，如：OpenDistro for Elasticsearch SQL

36、ssl

SSL（Secure Sockets Layer）API 主要用于管理与 SSL/TLS（Transport Layer Security）相关的配置。SSL/TLS 是一种加密协议，用于确保数据在网络传输过程中的安全性和保密性。这些 API 允许用户配置节点之间以及客户端与节点之间通信的加密方式，从而保护敏感数据免受窃听、篡改等网络安全威胁。

37、synonyms

Synonyms API 用于管理同义词。同义词是指在语义上相近或相同的词汇。通过使用这些 API，可以有效地处理用户查询中的同义词，从而提高搜索的准确性和召回率。例如，当用户搜索 "汽车"，也能返回包含 "轿车""机动车" 等同义词的文档。

38、tasks

Tasks API 主要用于管理和查询集群中正在执行的任务。它允许用户获取任务的详细信息，包括任务的状态、执行时间、所属节点等，帮助用户监控和控制集群中的任务执行情况，以便更好地管理集群资源、排查问题以及优化任务执行效率。

我用到的地方：Reindex重置索引时，请求参数**wait_for_completion=false（不等待完成）**时，会返回一个taskId，可使用此taskId通过task接口获取索引重置的进度。

39、text_structure

Text Structure API 来帮助用户更好地理解和处理文本数据的结构，以便更有效地将其摄入到 Elasticsearch 中进行后续的分析和检索等操作。

40、transform

Transform API 用于创建和管理数据转换任务。它的主要目的是将原始数据从一个或多个索引中提取出来，按照用户定义的规则进行转换，然后将转换后的数据存储到新的目标索引中。这种数据转换可以用于多种场景，如数据聚合、数据清理、数据格式调整等，以满足不同的数据分析和应用需求。

41、watcher

Watcher API 是用于创建、管理和执行监控任务（称为 "watch"）的接口。它允许用户定义一系列条件来监控 Elasticsearch 集群的状态、索引数据的变化或者外部数据源的信息，并且在满足特定条件时触发相应的操作，如发送通知、执行脚本或者更新文档等，从而实现自动化的监控和响应机制。

42、xpack

X - Pack API 是 Elasticsearch 中与 X - Pack 插件相关的一组接口。X - Pack 是 Elasticsearch 的一个扩展包，提供了安全、监控、告警、机器学习等一系列高级功能。X - Pack API 的目的是让用户能够以编程方式对这些高级功能进行配置、管理和获取信息，从而实现对 Elasticsearch 集群更精细的管控和更深入的洞察。