作者介绍:《RocketMQ技术内幕》作者,中间件兴趣圈微信公众号维护者。
本节将重点介绍ElasticSearch Doucment Get API(根据ID获取文档)。
从《ElasticSearch Client详解》可知,ElasticSearch Get Rest Hign level Get Api声明如下:
- public final GetResponse get(GetRequest getRequest, RequestOptions options) throws IOException
- public final void getAsync(GetRequest getRequest, RequestOptions options, ActionListener listener)
上述两个API,一个同步调用,一个异步调用,同步调用方法直接组装GetResponse 并返回,而异步方法通过回调ActionListener,并将执行结果(GetResponse )传入回调方法。
从中可以看出,Get API的核心是GetRequest 与RequestOptions,RequestOptions在上节中已详细说明,接下来将重点关注GetRequest。
1、GetRequest
GetRequest完整的类继承层次如下:
其核心属性如图所示:
下面我们一一来介绍一下GetRequest的核心属性。
- protected String index:索引库,对应关系型数据库的Database。
- private String type:类型,对应关系型数据库的表。
- private String id:文档ID,对应关系型数据库表中一行的主键ID。
- private String routing:路由值。
- private String parent:
- private String preference:get请求选取执行节点的偏好,倾向性,在下文会详细介绍。
- private String[] storedFields:显示的指定需要返回的字段,默认会返回_source中所有字段。
- private FetchSourceContext fetchSourceContext:指定需要返回字段的上下文,是storedFields的补充与完善,支持通配符,下文会详细分析。
- private boolean refresh = false:是否刷新。
- boolean realtime = true:是否实时执行,默认为true。
- private VersionType versionType = VersionType.INTERNAL:版本类型,已在《Elasticsearch Document Get API详解、原理与示例》中详细介绍
- private long version = Versions.MATCH_ANY:数据版本,关于数据的版本管理,已在《Elasticsearch Document Get API详解、原理与示例》中详细介绍。
2、Get API Demo
1、示例一:
public static void testGet() {
RestHighLevelClient client = EsClient.getClient();
try {
GetRequest request = new GetRequest("twitter", "_doc", "1");
GetResponse result = client.get(request, RequestOptions.DEFAULT);
System.out.println(result);
} catch(Throwable e) {
e.printStackTrace();
} finally {
EsClient.close(client);
}
}
返回值:
{
"_index":"twitter",
"_type":"_doc",
"_id":"1",
"_version":3,
"found":true,
"_source":{
"post_date":"2009-11-16T14:12:12",
"message":"trying out Elasticsearch",
"user":"dingw"
}
}
2、示例二:基于getRequest#storeFields进行source字段过滤
public static void testGet_storeFields() {
RestHighLevelClient client = EsClient.getClient();
try {
GetRequest request = new GetRequest("twitter", "_doc", "1");
request.storedFields("user");
GetResponse result = client.get(request, RequestOptions.DEFAULT);
System.out.println(result);
} catch(Throwable e) {
e.printStackTrace();
} finally {
EsClient.close(client);
}
}
返回值:
{
"_index":"twitter",
"_type":"_doc",
"_id":"1",
"_version":3,
"found":true
}
不符合预期,这是为什么呢?将在下文给出答案。
3、示例三:使用fetchSourceContext进行字段的过滤
public static void testGet_fetchSourceContext() {
RestHighLevelClient client = EsClient.getClient();
try {
GetRequest request = new GetRequest("twitter", "_doc", "1");
= new String[]{"message", "*date"};
FetchSourceContext fsc = new FetchSourceContext(true, includes, null);
request.fetchSourceContext(fsc);
GetResponse result = client.get(request, RequestOptions.DEFAULT);
System.out.println(result);
} catch(Throwable e) {
e.printStackTrace();
} finally {
EsClient.close(client);
}
}
返回结果:
{
"_index":"twitter",
"_type":"_doc",
"_id":"1",
"_version":3,
"found":true,
"_source":{
"post_date":"2009-11-16T14:12:12",
"message":"trying out Elasticsearch"
}
}
符合预期,只获取_source中的message与以date结尾的属性。
3、Get API 内部工作机制分析
3.1 实时性(Realtime)
默认情况下,get API是实时的,并且不会受到索引刷新频率的影响。如果一个文档被更新了(update),但是还没有刷新,那么get API将会发出一个刷新调用,以使文档可见。这也会使其他文档在上一次刷新可见后发生变化。如果不使用实时获取,可以将realtime=false。
3.2 source字段过滤
按需返回所需字段,例如SQL语句select * 返回所有字段,可以通过select a.id,a.name返回所需字段。
Elasticsearch提供了如下两种方式对_source字段进行过滤:
3.2.1 Stored Fields
get操作允许通过传递storedFields参数来指定一组需要获取储存的字段。如果所请求的字段没有被存储,它们将被忽略。请考虑以下映射:
PUT twitter
{
"mappings": {
"_doc": {
"properties": {
"counter": {
"type": "integer",
"store": false
},
"tags": {
"type": "keyword",
"store": true
}
}
}
}
}
注意映射在定义时,store字段,如果设置为false,就算指定storedFields=["counter"],也不会返回结果,也就时上述【示例2】没有返回 _source的原因。
3.2.2 FetchSourceContext
fetchSourceContext顾名思义,就是fetch source的上下文环境,提供更加完善的过滤逻辑,主要特性为支持include、exclude和支持通篇符过滤。
FetchSourceContext的构造函数:
public FetchSourceContext(boolean fetchSource, String[] includes, String[] excludes) {
this.fetchSource = fetchSource;
this.includes = includes == null ? Strings.EMPTY_ARRAY : includes;
this.excludes = excludes == null ? Strings.EMPTY_ARRAY : excludes;
}
可以从两个维度includes(包含)、excludes(排除)。还支持带""的通配符,例如includes = ["msg"]表示以msg开头的属性。通配符的解析逻辑:
org.elasticsearch.common.regex#simpleMatchToAutomaton
/** Return an {@link Automaton} that matches the given pattern. */
public static Automaton simpleMatchToAutomaton(String pattern) {
List<Automaton> automata = new ArrayList<>();
int previous = 0;
for (int i = pattern.indexOf('*'); i != -1; i = pattern.indexOf('*', i + 1)) {
automata.add(Automata.makeString(pattern.substring(previous, i)));
automata.add(Automata.makeAnyString());
previous = i + 1;
}
automata.add(Automata.makeString(pattern.substring(previous)));
return Operations.concatenate(automata);
}
3.3 路由机制
如果路由字段不是ID,请使用routing属性,更好的转发请求,否则会全部转发到所有的复制组,然后汇聚并返回。
3.4 倾向性(优先级、Preference)
Preference参数控制get请求对同一个复制组内多个副本的选择,默认情况下,该操作是在碎片副本之间进行随机分配的。一言以蔽之,preference的作用是同一个复制组中的路由规则。
其可选值:
- _primary
操作将只在主分片上执行。 - _local
如果可能的话,操作将更倾向于在本地分配的碎片上执行。当请求发到一个Node上,如果该Node上有对应的副本,则在该节点上执行,
不会再将请求转发到其他 节点。
- 自定义字符串值
同一个自定义值,将会固定使用同一个分片(路由),该值通常会和会话信息绑定在一起,例如用户名,sessionId等,在应用层面对各
分片节点进行分流。
3.5 刷新机制
refersh如果设置为true,以便在get操作之前刷新相关分片,并使其可搜索,会刷新整个分片节点,此参数不建议使用,因为get操作默认是实时的,无性能损耗。
其他分布式特性、版本支持是ElasticSearch的公用通信,就不再重复讲解了。
本节首先罗列了文档Get API,并对GetRequest进行了详细分析,接着通过3个 示例展示Get API的使用,最后重点分析GET API 内部的实现机制(实时性、source过滤、路由、复制组内分片节点倾向性、刷新机制等)。