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

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 集群中的执行情况。它允许用户在不实际执行可能会对数据产生影响的操作（如索引、搜索、更新等操作）的情况下，查看这些操作会如何被集群处理，包括查看查询的解析过程、聚合的执行方式以及相关的性能影响等诸多方面。

后续更新