本文将详细介绍ES索引管理相关的API。
ES索引管理API主要包含如下API:
创建索引,通常创建索引API包含3个部分:索引配置、索引映射、索引别名,例如:
1PUT test
2{
3 "settings" : { //@1
4 "number_of_shards" : 1
5 },
6 "mappings" : { // @2
7 "_doc" : {
8 "properties" : {
9 "field1" : { "type" : "text" }
10 }
11 }
12 },
13 "aliases" : { // @3
14 "alias_1" : {},
15 "alias_2" : {
16 "filter" : {
17 "term" : {"user" : "kimchy" }
18 },
19 "routing" : "kimchy"
20 }
21 }
22}
代码@1:索引的配置属性。请详细参考如下博文: 代码@2:定义映射,有点类似于关系型数据库中的定义表结构,详情请参考:Elasticsearch Mapping parameters(主要参数一览)、Elasticsearch Mapping类型映射概述与元字段详解 代码@3:为索引指定别名设置。
对应的JAVA示例代码:
1public static void createSuggestMapping() {
2 RestHighLevelClient client = EsClient.getClient();
3 try {
4 CreateIndexRequest request = new CreateIndexRequest("suggest_mapping_001");
5 XContentBuilder jsonBuilder = XContentFactory.jsonBuilder()
6 .startObject()
7 .startObject("properties")
8 .startObject("context")
9 .field("type", "text")
10 .field("analyzer", "ik_smart")
11 .field("search_analyzer", "ik_smart")
12 .endObject()
13 .endObject()
14 .endObject();
15 request.mapping("_doc", jsonBuilder);
16 System.out.println(client.indices().create(request, RequestOptions.DEFAULT));
17 } catch (Throwable e) {
18 e.printStackTrace();
19 } finally {
20 EsClient.close(client);
21 }
22 }
查找、删除、打开与关闭索引的使用方法与创建索引类似,都是通过RestHighLevelClient#indices()对应的方法来实现。
接下来从Request类图入手,展示上述API重点的参数。
IndicesOptions$WildcardStates枚举类型主要定义通配符的作用范围,例如OPEN,表示处于打开状态的索引,而CLOSE表示处于关闭状态的索引。
IndicesOptions$Option定义操作选项:
IndicesOptions针对上面进行组合,默认给出了一些常量组合:
上面是对IndicesOptions中的枚举类型与默认定义的索引选项进行了一个说明,当然也可以通过IndicesOptions#fromOptions来自定义。
删除、打开、查找,关闭等API的使用类似,下面给出一个简单的JAVA示例:
1public static final void testGetIndex() {
2 RestHighLevelClient client = EsClient.getClient();
3 try {
4 GetIndexRequest request = new GetIndexRequest();
5 request.indices("suggest_mapping_001*")
6 //.indicesOptions(IndicesOptions.STRICT_EXPAND_OPEN)
7 //.indicesOptions(IndicesOptions.STRICT_SINGLE_INDEX_NO_EXPAND_FORBID_CLOSED)
8 //.indicesOptions(IndicesOptions.LENIENT_EXPAND_OPEN)
9 //.includeDefaults(true) 是否输出包含默认配置(settings),默认为false
10 // .indicesOptions(IndicesOptions.STRICT_EXPAND_OPEN_FORBID_CLOSED)
11 .indicesOptions(IndicesOptions.STRICT_SINGLE_INDEX_NO_EXPAND_FORBID_CLOSED)
12 ;
13 System.out.println(client.indices().get(request, RequestOptions.DEFAULT));
14 } catch (Throwable e) {
15 e.printStackTrace();
16 } finally {
17 EsClient.close(client);
18 }
19}
Split Index,拆分索引。
收缩索引。收缩索引API允许您将现有索引收缩为具有较少主碎片的新索引(下文为们称之为目标索引)。伸缩后的索引主分片的个数必须是原分片的公约数,举例说明,如果原先索引的个数为15,那伸缩后的索引主分片数量可以是3、5、1。 索引收缩过程:
收缩索引前置条件:
首先使用如下API更新源索引的配置信息(settings):
1PUT /my_source_index/_settings
2{
3 "settings": {
4 "index.routing.allocation.require._name": "shrink_node_name", // @1
5 "index.blocks.write": true // @2
6 }
7}
代码@1:index.routing.allocation.require._name:强制将索引下所有的副本转移到指定名称(node.name)。 代码@2:设置该索引数据只读,无法再添加新的索引数据,但可以改变索引元数据。
注意:此过程可能需要一段时间,可以通过(_cat recovery api)或cluster health API查看其进度。
Shrink API使用示例:
1POST my_source_index/_shrink/my_target_index?copy_settings=true
2{
3 "settings": {
4 "index.routing.allocation.require._name": null, // @1
5 "index.blocks.write": null // @2
6 }
7}
这里要特别注意,由于在收缩之前,改变了原索引的相关配置,收缩后的索引,需要恢复这些配置。
对应的JAVA示例:
1public static final void testShrinkIndex() {
2 RestHighLevelClient client = EsClient.getClient();
3 try {
4 Map settings = new HashMap();
5 settings.put("index.routing.allocation.require._name", null);
6 settings.put("index.blocks.write", false);
7 ResizeRequest resizeRequest = new ResizeRequest("targetIndex", "sourceIndex");
8 resizeRequest.setCopySettings(true);
9 resizeRequest.getTargetIndexRequest().settings(settings);
10 ResizeResponse result = client.indices().shrink(resizeRequest, RequestOptions.DEFAULT);
11 System.out.println(result);
12 } catch (Throwable e) {
13 e.printStackTrace();
14 } finally {
15 EsClient.close(client);
16 }
17}
上面的请求,只要目标索引在集群中配置,立即胡返回,不会等到收缩完成。
收缩索引的必要条件如下:
索引收缩是可以通过_cat recovery api和cluster health api来监控shrink的过程,这两个命令将在后续文章中详解。
收缩索引由于需要创建索引,故支持wait_for_active_shards参数。
拆分索引。 注意:在elasticsearch7.0版本之前,如果将来需要使用split api拆分索引,那么需要在创建索引的时候指定number_of_routing_shards参数,方便日后进行索引的拆分。 number_of_routing_shards用来指定指定内部用于跨具有一致哈希的分片分发文档的哈希空间。例如,一个拥有5个主分片的索引,其number_of_routing_shards设置为30 (5 x 2 x 3)的5切分索引可以除以2或3的因数,其拆分方式如下:
索引拆分过程
拆分索引前置条件:
其对应的API:
1PUT /my_source_index/_settings
2{
3 "settings": {
4 "index.blocks.write": true // 设置原索引只读
5 }
6}
然后使用Split Index拆分索引。
1POST my_source_index/_split/my_target_index?copy_settings=true
2{
3 "settings": {
4 "index.number_of_shards": 2
5 }
6}
其对应的JAVA代码:
1@SuppressWarnings({ "rawtypes", "unchecked" })
2 public static final void testSplinkIndex() {
3 RestHighLevelClient client = EsClient.getClient();
4 try {
5 Map settings = new HashMap();
6 settings.put("index.number_of_shards", 2);
7 ResizeRequest resizeRequest = new ResizeRequest("targetIndex", "sourceIndex");
8 resizeRequest.setCopySettings(true);
9 resizeRequest.getTargetIndexRequest().settings(settings);
10 ResizeResponse result = client.indices().split(resizeRequest, RequestOptions.DEFAULT);
11 System.out.println(result);
12 } catch (Throwable e) {
13 e.printStackTrace();
14 } finally {
15 EsClient.close(client);
16 }
17 }
拆分索引的必要条件如下:
拆分过程的监控与收缩索引相同,不重复介绍。
rollover index API,当认为现有索引太大或太旧时,可以使用rollover index API将别名滚到新索引。该API必须接收一个索引别名和一个条件列表(用来从老的索引中过滤需要迁移的文档)。根据别名指向索引的类别,别名元数据将以不同的方式更新。两种情况如下:
支持如下条件参数:
示例: step1:创建索引,并指定一个别名。
1PUT /logs-000001
2{
3 "aliases": {
4 "logs_write": {}
5 }
6}
step2:向该索引中添加超过1000个文档。
1# Add > 1000 documents to logs-000001
step3:rollover 索引
1POST /logs_write/_rollover
2{
3"conditions": {
4 "max_age": "7d", // @1
5 "max_docs": 1000, // @2
6 "max_size": "5gb" // @3
7}
8}
代码@1:索引是否已创建7天。 代码@2:索引中包含的文档数量。 代码@3:索引的主分片大小。
如果现有索引的名称以-和一个数字结束,例如logs-000001。然后,新索引的名称将遵循相同的模式,增加数字(log -000002)。无论旧索引名是什么,该数字都是零,长度为6。 如果原索引的名称不符合该格式,则需要手动指定新索引的名称。
1POST /my_alias/_rollover/my_new_index_name
2{
3 "conditions": {
4 "max_age": "7d",
5 "max_docs": 1000,
6 "max_size": "5gb"
7 }
8}
4.2 date mesh方式
1# PUT /<logs-{now/d}-1> with URI encoding:
2
3PUT /%3Clogs-%7Bnow%2Fd%7D-1%3E // @1
4{
5 "aliases": {
6 "logs_write": {}
7 }
8}
9
10PUT logs_write/_doc/1
11{
12 "message": "a dummy log"
13}
14
15POST logs_write/_refresh
16
17# Wait for a day to pass
18
19POST /logs_write/_rollover // @2
20{
21 "conditions": {
22 "max_docs": "1"
23 }
24}
代码@1:使用date mesh格式定义新索引的格式。 代码@2:创建一个以今天的日期(例如)命名的索引log -2016.10.31-1:,转到具有今天日期的新索引,例如如果立即运行,log -2016.10.31-000002,如果24小时后运行,log -2016.11.01-000002。
rollover API支持dry_run模式,在这种模式下,无需执行实际的翻转就可以检查请求条件。
1public static final void testRolloverIndex() {
2 RestHighLevelClient client = EsClient.getClient();
3 try {
4 // public RolloverRequest(String alias, String newIndexName)
5 RolloverRequest resizeRequest = new RolloverRequest("logs_write", null);
6 resizeRequest.addMaxIndexAgeCondition(TimeValue.parseTimeValue("7d", "max_age"));
7 resizeRequest.addMaxIndexDocsCondition(50);
8 resizeRequest.addMaxIndexSizeCondition(ByteSizeValue.parseBytesSizeValue("5G", "max_index_size"));
9 resizeRequest.dryRun(true);
10 RolloverResponse result = client.indices().rollover(resizeRequest, RequestOptions.DEFAULT);
11 System.out.println(result);
12 } catch (Throwable e) {
13 e.printStackTrace();
14 } finally {
15 EsClient.close(client);
16 }
17 }
在创建RolloverRequest时,newIndexName可以指定为空,新索引的命名遵循4.1、4.2中的规则。
本节详细介绍了索引管理相关的API,主要包括Index Create、Delete Index、Get index、indices Exists Index、Open/Close Index 、Shrink Index、Split Index、Rollover Index。有关于索引的更新,包括(映射Mapping、配置Settings)的更新比较简单,就不做介绍,下一节,我们重点探讨索引模板(Index Templates)。