NoSQL 与搜索 / 系统课时
索引与文档操作
索引与文档操作
本课通过一个可运行的商品示例完成 Elasticsearch 的基本数据闭环:创建索引与映射、写入文档、执行查询、局部更新、删除文档并清理索引。每一步都会打印结果,便于确认 Java API 是否按预期生效。
学习目标
- 使用 Java API 创建带字段映射的索引
- 完成文档写入、搜索、局部更新和删除
- 理解实时读取、刷新与固定文档 ID 的作用
操作模型
索引先定义字段类型,文档再按映射写入。指定固定 _id 可以让同一业务对象重复写入时覆盖原文档,减少重复数据;搜索依赖刷新后可见,而按 ID 获取默认具有近实时之外的实时读取能力。

本例使用 Java 17、elasticsearch-java:8.19.16 和 jackson-databind:2.17.0。若项目尚未引入依赖,可将下面片段加入现有 pom.xml,然后刷新 Maven。
<dependencies>
<dependency>
<groupId>co.elastic.clients</groupId>
<artifactId>elasticsearch-java</artifactId>
<version>8.19.16</version>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.17.0</version>
</dependency>
</dependencies>该片段依赖现有 Maven 项目的基本结构。执行 Maven 重新加载后,能够解析 co.elastic.clients 包即表示配置生效。
完整 CRUD 示例
程序使用独立测试索引 products_java_demo。为保证重复运行结果一致,启动时会先删除同名旧索引,因此不要把示例索引名替换为生产索引。
package com.example;
import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch.core.GetResponse;
import co.elastic.clients.elasticsearch.core.IndexResponse;
import co.elastic.clients.elasticsearch.core.SearchResponse;
import co.elastic.clients.elasticsearch.core.UpdateResponse;
import co.elastic.clients.json.jackson.JacksonJsonpMapper;
import co.elastic.clients.transport.ElasticsearchTransport;
import co.elastic.clients.transport.rest_client.RestClientTransport;
import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.elasticsearch.client.RestClient;
import java.net.URI;
import java.util.Map;
public class DocumentCrudDemo {
private static final String INDEX = "products_java_demo";
private static final String DOC_ID = "p-1001";
public record Product(String id, String name, double price, int stock) {
}
public static void main(String[] args) throws Exception {
try (ElasticsearchClient client = createClient()) {
if (client.indices().exists(e -> e.index(INDEX)).value()) {
client.indices().delete(d -> d.index(INDEX));
}
client.indices().create(c -> c
.index(INDEX)
.mappings(m -> m
.properties("id", p -> p.keyword(k -> k))
.properties("name", p -> p.text(t -> t))
.properties("price", p -> p.double_(d -> d))
.properties("stock", p -> p.integer(i -> i))));
System.out.println("index created=" + INDEX);
Product product = new Product(
DOC_ID,
"Mechanical Keyboard",
299.0,
20
);
IndexResponse indexed = client.index(i -> i
.index(INDEX)
.id(DOC_ID)
.document(product));
System.out.printf(
"indexed id=%s version=%d%n",
indexed.id(),
indexed.version()
);
// 搜索依赖刷新后可见,显式刷新让演示结果保持确定。
client.indices().refresh(r -> r.index(INDEX));
SearchResponse<Product> search = client.search(s -> s
.index(INDEX)
.query(q -> q.match(m -> m
.field("name")
.query("keyboard"))),
Product.class);
Product searched = search.hits().hits().isEmpty()
? null
: search.hits().hits().get(0).source();
System.out.println("searched=" + searched);
Map<String, Object> patch = Map.of(
"price", 279.0,
"stock", 18
);
UpdateResponse<Product> updated = client.update(u -> u
.index(INDEX)
.id(DOC_ID)
.doc(patch),
Product.class);
System.out.println("updated version=" + updated.version());
GetResponse<Product> afterUpdate = client.get(g -> g
.index(INDEX)
.id(DOC_ID),
Product.class);
System.out.println("after update=" + afterUpdate.source());
client.delete(d -> d.index(INDEX).id(DOC_ID));
boolean stillExists = client.exists(e -> e
.index(INDEX)
.id(DOC_ID)).value();
System.out.println("deleted found=" + stillExists);
client.indices().delete(d -> d.index(INDEX));
System.out.println("index deleted=" + INDEX);
}
}
private static ElasticsearchClient createClient() {
URI endpoint = URI.create(requiredEnv("ES_URL"));
String username = requiredEnv("ES_USERNAME");
String password = requiredEnv("ES_PASSWORD");
int port = endpoint.getPort() > 0
? endpoint.getPort()
: ("https".equalsIgnoreCase(endpoint.getScheme()) ? 443 : 80);
BasicCredentialsProvider credentials = new BasicCredentialsProvider();
credentials.setCredentials(
AuthScope.ANY,
new UsernamePasswordCredentials(username, password)
);
RestClient restClient = RestClient.builder(
new HttpHost(endpoint.getHost(), port, endpoint.getScheme()))
.setRequestConfigCallback(request -> request
.setConnectTimeout(5_000)
.setSocketTimeout(30_000))
.setHttpClientConfigCallback(http -> http
.setDefaultCredentialsProvider(credentials))
.build();
ElasticsearchTransport transport = new RestClientTransport(
restClient,
new JacksonJsonpMapper()
);
return new ElasticsearchClient(transport);
}
private static String requiredEnv(String name) {
String value = System.getenv(name);
if (value == null || value.isBlank()) {
throw new IllegalArgumentException(
"Missing environment variable: " + name
);
}
return value;
}
}设置 ES_URL、ES_USERNAME 和 ES_PASSWORD 后运行 main 方法。预期输出如下,版本号在索引被完整重建时从 1 开始。
index created=products_java_demo
indexed id=p-1001 version=1
searched=Product[id=p-1001, name=Mechanical Keyboard, price=299.0, stock=20]
updated version=2
after update=Product[id=p-1001, name=Mechanical Keyboard, price=279.0, stock=18]
deleted found=false
index deleted=products_java_demo关键边界
index 操作在相同 _id 已存在时会替换文档;若业务要求“已存在就失败”,应改用 create 操作。局部更新只修改 doc 中提供的字段,但字段类型仍必须符合映射,否则会返回映射解析错误。
显式 refresh 会增加开销,生产写入链路不应在每条文档后调用。通常让 Elasticsearch 按刷新间隔自动处理;只有测试、低频后台操作或必须立即搜索到新数据的场景才考虑手动刷新。
本课总结
- 索引映射先约束字段类型,文档操作再围绕固定
_id完成数据生命周期 - 搜索结果受刷新影响,按 ID 获取可用于写入或更新后的即时校验
- 示例索引应与生产索引隔离,重复运行前的删除操作不能直接照搬到生产环境
下一课预告
下一课将把单文档操作扩展为业务搜索接口,组合分页、条件查询、排序和结果映射,形成可供应用层调用的查询服务。