elasticsearch API约定(一)

前面我们介绍了一些REST API的基本用法，使读者对API的使用有了一个直观的了解，本文我们来介绍下Elasticsearch中的API约定，这些约定适用于大部分的REST API，在后面文章的介绍中，除非另有说明，否则本文所介绍的API约定都将适用于相应的API。

本文是Elasticsearch系列的第五篇，阅读前面的文章，有助于更好的理解本文：

---

---

多个索引

在前面的查询案例中，我们使用的都是单个索引，实际上Elasticsearch也支持多个索引查询，在多个索引查询中，Elasticsearch支持如下几种方式：

• 支持使用简单表示法，如test1,test2,test3表示法

• 使用_all表示所有索引

• 使用通配符，如 test*或 *test或 te*t或 *test*等

• 也支持排除能力，例如：test*,-test3

在所有的多索引API中都支持以下URL查询参数：

ignore_unavailable

这个参数表示，当指定多个索引时，如果有索引不可用（不存在或者已经关闭）那么是否忽略该索引。true表示忽略，false表示不忽略，默默认为false。
例如如下请求表示查看索引bank和索引bank2中的文档（实际上bank2不存在）：

1. curl -X GET "localhost:9200/bank,bank2/_search?q=*&sort=account_number:asc&pretty"

该请求执行结果如下：

可以看到，由于bank2这个索引不存在，因此执行失败，如果加上ignore_unavailable参数则可以执行成功，如下：

1. curl -X GET "localhost:9200/bank,bank2/_search?q=*&sort=account_number:asc&pretty&ignore_unavailable=true"

执行结果如下：

allownoindices

这个参数表示如果查询的时候使用了通配符，但是通配符没有匹配到任何索引，此时是否查询失败？该参数默认值为true，表示允许通配符匹配不到任何索引，例如如下请求：

1. curl -X GET "localhost:9200/bank3*/_search?q=*&pretty"

实际上，bank3索引是不存在的，但是该请求执行并未报错，如下：

这是因为默认是允许通配符匹配不到任何索引的，如果加上 allow_no_indices参数，并将之设置为false，即不允许通配符匹配不到任何索引，此时再去执行就会报错，如下：

1. curl -X GET "localhost:9200/bank3*/_search?q=*&pretty&allow_no_indices=false"

执行结果如下：

如果别名指向关闭索引，则此设置也适用于别名。

expand_wildcards

expand_wildcards表示查询索引的范围，open表示查询所有匹配并open的索引，closed则表示查询所有匹配的索引，如下：

假设bank关闭，bank2未关闭，执行如下查询：

1. curl -X GET "localhost:9200/bank*/_search?pretty&expand_wildcards=open"

此时，只会展示open的索引信息，如下：

而如果执行如下查询：

1. curl -X GET "localhost:9200/bank*/_search?pretty&expand_wildcards=closed"

结果如下：

索引名中的日期数学支持

Date math索引名称解析可以让开发者搜索一系列time-series indices（时间序列索引），而不用搜索所有时间序列索引然后过滤结果或者维护aliases（别名）。这种方式限制了搜索的索引数量并且减少了集群上的负载，并提高了执行性能。例如，如果使用Elasticsearch来记录软件运行日志，如果想要查看过去两天的日志信息，则可以使用date math name模板将搜索索引限制为过去两天。
几乎所有的具有索引参数的API都支持在index parameter value（索引参数值）中包含 date math。date math索引名称采用以下形式 :

1. <static_name{date_math_expr{date_format|time_zone}}>

上述模版说明：

模版	中文含义
static_name	索引名称中的静态文本部分
datemathexpr	动态计算日期的date math表达式
date_format	日期的显示格式，默认为YYYY.MM.dd
time_zone	可选的时区，默认为utc

date_math索引名称表达式必须包含在尖括号中，并且所有特殊字符都需要进行URL编码，例如如下请求：

1. GET /<logstash-{now/d}>/_search

编码后的请求格式为：

1. curl -X GET "localhost:9200/%3Clogstash-%7Bnow%2Fd%7D%3E/_search" -H 'Content-Type: application/json' -d'

2. {

3.  "query" : {

4.    "match": {

5.      "test": "data"

6.    }

7.  }

8. }

9. '

编码格式表如下：

字符	编码
<	%3C
>	%3E
/	%2F
{	%7B
}	%7D
|	%7C
+	%2B
:	%3A
,	%2C

下面是几个解析案例，供读者参考，设置当前的默认时间为2024年3月22日中午utc。

表达式	解析结果
<logstash-{now/d}>	logstash-2024.03.22
<logstash-{now/M}>	logstash-2024.03.01
<logstash-{now/M{YYYY.MM}}>	logstash-2024.03
<logstash-{now/M-1M{YYYY.MM}}>	logstash-2024.02
<logstash-{now/d{YYYY.MM.dd |+12:00}}>	logstash-2024.03.23

如果想要在索引名称的静态部分使用 {和 }，则可以使用 \进行转义，如下：

1. <elastic\\{ON\\}-{now/M}>

最终结果为：

1. elastic{ON}-2024.03.01

Demo

例如现在有如下3个过去三天的日志索引：

想要查询过去两天的日志索引：

1. GET /<log-{now/d-1d}>,<log-{now/d}>/_search

查询请求如下：

1. curl -X GET "localhost:9200/%3Clog-%7Bnow%2Fd-1d%7D%3E%2C%3Clog-%7Bnow%2Fd%7D%3E/_search?pretty" -H 'Content-Type: application/json' -d'

2. {

3.  "query" : {

4.    "match_all": {}

5.  }

6. }

7. '

请求执行结果如下：

好了，本文就先介绍到这里，有问题欢迎留言讨论。