当前位置：首页 > news >正文

[特殊字符] Elasticsearch 双剑合璧：HTTP API 与 Java API 实战整合指南

news 来源：原创 2025/9/17 0:39:05

🚀 Elasticsearch 双剑合璧：HTTP API 与 Java API 实战整合指南

一、HTTP API

定义与用途

Elasticsearch 的 HTTP API 是基于 RESTful 接口设计的核心交互方式，支持通过 URL 和 JSON 数据直接操作索引、文档、集群等资源。适用于快速调试、脚本调用和跨语言集成。

1. 索引管理

(1) 创建索引（指定分片与映射）

PUT /products 
{"settings": {"number_of_shards": 3,"number_of_replicas": 1},"mappings": {"properties": {"name": { "type": "text" },"price": { "type": "integer" }}}
}

用途：初始化数据结构，定义字段类型和分片策略。
参数说明：
- number_of_shards：主分片数（不可修改）。
- mappings：字段类型（如 text 支持分词，keyword 精确匹配）。

product：只是一个代表，是你要创建的索引的名称，索引可以理解为mysql中的一个表
settings ：配置

properties：其内容就是你要写入到es的对象具体内容

(2) 删除索引

DELETE /products

风险提示：删除索引会清空所有数据，需谨慎操作。

2. 文档操作

(1) 新增文档（自动生成 ID）

POST /products/_doc
{"name": "iPhone 14","price": 6999
}

响应示例：返回自动生成的 _id（如 _id: "x123"）。

如上，请求体给出具体写到文档中的内容，文档可以理解为mysql中的一行数据记录

(2) 局部更新文档

POST /products/_update/x123
{"doc": { "price": 6499 }
}

优势：仅更新指定字段，减少网络传输和索引重建开销。

3. 查询与聚合

(1) 条件查询（分页与排序）

GET /products/_search
{"query": {"match": { "name": "iPhone" }},"from": 0,"size": 10,"sort": [ { "price": "desc" } ]
}

性能注意：深度分页（from > 10000）需改用 Search After 或 Scroll API。

from和size用于分页，from表示从第n个数据开始，size表示返回这个开始数据算起的m条文档数据

sort 表示按照什么字段排序，升序还是降序

(2) 聚合统计（平均值）

GET /products/_search
{"aggs": {"avg_price": { "avg": { "field": "price" } }}
}

结果路径：aggregations -> avg_price -> value。

4. 批量操作

(1) 批量写入/删除

POST /_bulk
{ "index": { "_index": "products", "_id": "1" } }
{ "name": "iPad", "price": 3999 }
{ "delete": { "_index": "products", "_id": "2" } }

性能建议：单次批量操作不超过 10MB，避免超时。

二、Java API

定义与用途

Java API 是 Elasticsearch 官方提供的高层客户端库（RestHighLevelClient），封装了 HTTP 请求的复杂性，支持强类型操作和异步处理。适用于后端服务开发。

1. RestHighLevelClient 常用方法

定义与用途

RestHighLevelClient 是 Java 客户端的入口类，通过调用其方法执行索引、文档、搜索等操作。需注意在 Elasticsearch 8.x 中已逐步迁移至新客户端 ElasticsearchClient，但旧版仍广泛使用。

(1) 索引管理方法

方法签名	用途	对应 Request 类
`indices().create()`	创建索引	`CreateIndexRequest`
`indices().delete()`	删除索引	`DeleteIndexRequest`
`indices().exists()`	检查索引是否存在	`GetIndexRequest`

示例：创建索引

CreateIndexRequest request = new CreateIndexRequest("products").settings(Settings.builder().put("number_of_shards", 3)).mapping(Map.of("properties", Map.of("name", Map.of("type", "text"))));
client.indices().create(request, RequestOptions.DEFAULT);

(2) 文档操作方法

方法签名	用途	对应 Request 类
`index()`	新增/全量替换文档	`IndexRequest`
`update()`	局部更新文档	`UpdateRequest`
`delete()`	删除文档	`DeleteRequest`

示例：局部更新文档

UpdateRequest request = new UpdateRequest("products", "x123").doc(Map.of("price", 6499));
client.update(request, RequestOptions.DEFAULT);

(3) 查询与聚合方法

方法签名	用途	对应 Request 类
`search()`	执行搜索	`SearchRequest`
`scroll()`	滚动查询大数据量	`SearchScrollRequest`

示例：条件查询

SearchSourceBuilder source = new SearchSourceBuilder().query(QueryBuilders.matchQuery("name", "iPhone")).size(10);
SearchRequest request = new SearchRequest("products").source(source);
SearchResponse response = client.search(request, RequestOptions.DEFAULT);

2. Request 与 Builder 常用方法

定义与用途

每个操作对应一个 Request 类，通过 Builder 模式链式设置参数（如查询条件、分页、聚合等）。新版客户端（8.x）推荐使用流式语法（Lambda 表达式），旧版通过 XxxRequestBuilder 类构建。

(1) `SearchRequest` 与 `SearchSourceBuilder`

用途：构建复杂查询（分页、排序、聚合）。

Request 方法
- indices(String... indices)：指定搜索的索引。
- source(SearchSourceBuilder source)：绑定查询条件、分页、排序等。
Builder 方法
- query(QueryBuilder query)：设置查询条件（如 matchQuery）。
- aggregation(AggregationBuilder aggregation)：添加聚合逻辑（如 avg）。
- from(int).size(int)：分页控制

对于QueryBuilders 的详细介绍，看这篇文章
玩转Elasticsearch 查询利器！QueryBuilders 核心方法全解析-CSDN博客

核心方法：

SearchSourceBuilder source = new SearchSourceBuilder().query(QueryBuilders.boolQuery().must(QueryBuilders.matchQuery("name", "iPhone")).filter(QueryBuilders.rangeQuery("price").gte(5000))).aggregation(AggregationBuilders.avg("avg_price").field("price")).from(0).size(10);
SearchRequest request = new SearchRequest("products").source(source);

(2) `BulkRequest`（批量操作）

用途：混合执行增删改操作。

Request 方法
- add(IndexRequest/UpdateRequest/DeleteRequest)：混合添加增删改操作。
Builder 方法
- setRefreshPolicy(WriteRequest.RefreshPolicy)：设置刷新策略（如 IMMEDIATE 实时生效）。

示例：

BulkRequest bulkRequest = new BulkRequest();
bulkRequest.add(new IndexRequest("products").id("1").source("name", "iPad"));
bulkRequest.add(new DeleteRequest("products").id("2"));
client.bulk(bulkRequest, RequestOptions.DEFAULT);

(3) `UpdateByQueryRequest`（按条件更新）

用途：批量更新符合查询条件的文档。

Request 方法
- setQuery(QueryBuilder query)：筛选目标文档。
- setScript(Script script)：定义更新逻辑。

示例：

UpdateByQueryRequest request = new UpdateByQueryRequest("products");
request.setQuery(QueryBuilders.termQuery("status", "pending"));
request.setScript(new Script("ctx._source.status = 'processed'"));
client.updateByQuery(request, RequestOptions.DEFAULT);

3. 整合示例：Request 与 Builder 协作

场景：构建复杂查询（分页 + 聚合 + 高亮）

// 1. 构建查询条件
SearchSourceBuilder source = new SearchSourceBuilder().query(QueryBuilders.boolQuery().must(QueryBuilders.matchQuery("name", "iPhone")).filter(QueryBuilders.rangeQuery("price").gte(5000))).aggregation(AggregationBuilders.avg("avg_price").field("price")).highlighter(new HighlightBuilder().field("name").preTags("<em>").postTags("</em>")).from(0).size(10);// 2. 创建 Request 对象
SearchRequest request = new SearchRequest("products").source(source).indices("products", "sales"); // 跨索引查询// 3. 执行查询
SearchResponse response = client.search(request, RequestOptions.DEFAULT);

关键点：
- SearchSourceBuilder 负责组装查询逻辑。
- SearchRequest 绑定查询条件并指定索引范围

三、最佳实践

性能优化
- 使用 BulkProcessor 自动分批次提交文档。
- 设置 setRefreshPolicy(WriteRequest.RefreshPolicy.NONE) 减少实时刷新开销。

错误处理

try {client.index(request, RequestOptions.DEFAULT);
} catch (ElasticsearchException e) {if (e.status() == RestStatus.CONFLICT) {// 处理版本冲突}
}

版本迁移

Elasticsearch 8.x 推荐使用新客户端 ElasticsearchClient，语法更简洁：

client.search(s -> s.index("products").query(q -> q.match(m -> m.field("name").query("iPhone")))
, Product.class);

🚀 Elasticsearch 双剑合璧：HTTP API 与 Java API 实战整合指南

一、HTTP API

定义与用途

1. 索引管理

(1) 创建索引（指定分片与映射）

(2) 删除索引

2. 文档操作

(1) 新增文档（自动生成 ID）

(2) 局部更新文档

3. 查询与聚合

(1) 条件查询（分页与排序）

(2) 聚合统计（平均值）

4. 批量操作

(1) 批量写入/删除

二、Java API

定义与用途

1. RestHighLevelClient 常用方法

定义与用途

(1) 索引管理方法

(2) 文档操作方法

(3) 查询与聚合方法

2. Request 与 Builder 常用方法

定义与用途

(1) SearchRequest 与 SearchSourceBuilder

(2) BulkRequest（批量操作）

(3) UpdateByQueryRequest（按条件更新）

3. 整合示例：Request 与 Builder 协作

场景：构建复杂查询（分页 + 聚合 + 高亮）

三、最佳实践

相关文章：

(1) `SearchRequest` 与 `SearchSourceBuilder`

(2) `BulkRequest`（批量操作）

(3) `UpdateByQueryRequest`（按条件更新）