上一篇【第08篇】Elasticsearch集群扩展与运维——水平扩展与节点管理
下一篇【第10篇】Elasticsearch REST API最佳实践——Content-Type、模糊性与访问控制

---

摘要

Elasticsearch提供了一套功能强大的RESTful API，几乎所有的集群管理和数据操作都通过HTTP请求完成。要高效地使用这些API，理解其规范与约定至关重要。本文详细讲解三个核心主题：多索引操作——如何通过通配符、排除语法和_all关键字在一次请求中操作多个索引；日期数学格式——如何在索引名称中使用动态日期表达式实现基于时间的索引管理；通用选项——包括结果格式化、信息过滤、可读输出、布尔值与数值规范等适用于所有REST API的通用参数。此外，本文还系统总结了Elasticsearch中时间单位、数据单位、距离单位、缩略乘数等规范，帮助读者编写出标准、规范的API调用。

---

一、多索引（Multi-Index）操作

大多数Elasticsearch API都支持跨多个索引执行操作，这在批量查询、批量管理场景中非常实用。

1.1 多索引的基本语法

# 操作多个指定索引
GET /index1,index2,index3/_search

# 操作所有索引
GET /_all/_search

# 使用通配符
GET /test*/_search
GET /*test/_search
GET /te*t/_search
GET /*test*/_search

# 使用排除功能
GET /logs-*, -logs-2024-01-*/_search

多索引语法总结：

语法	说明	示例
逗号分隔	指定多个索引	test1,test2,test3
_all	所有索引	_all
*通配符	匹配零个或多个字符	test*、*test、te*t
-排除	排除特定索引	*,-test3
组合使用	多种语法混合	logs-*, -logs-debug-*

1.2 多索引相关的URL参数

所有多索引API都支持以下查询字符串参数：

ignore_unavailable：控制是否忽略不可用的索引（包括不存在的索引和已关闭的索引）。

# 忽略不存在的索引，不报错
GET /index_exists,index_not_exists,another_missing/_search?ignore_unavailable=true

allow_no_indices：当通配符表达式没有匹配到任何索引时，控制请求是否失败。

# foo* 没有匹配任何索引时，请求不会失败
GET /foo*/_search?allow_no_indices=true

# foo* 没有匹配任何索引时，请求会失败
GET /foo*/_search?allow_no_indices=false

expand_wildcards：控制通配符可以扩展到哪些类型的索引。

值	说明
open	仅扩展到打开的索引（默认值）
closed	仅扩展到关闭的索引
hidden	仅扩展到隐藏的索引
none	不接受通配符
all	扩展到所有类型的索引

# 搜索所有打开和关闭的索引
GET /logs-*/_search?expand_wildcards=open,closed

1.3 多索引操作实战示例

// 在多个索引中搜索
GET /logs-2026-05-20,logs-2026-05-21,logs-2026-05-22/_search
{
  "query": {
    "match": {
      "level": "ERROR"
    }
  }
}

// 在所有匹配的索引中批量获取文档（排除debug索引）
GET /logs-*,-logs-debug-*/_mget
{
  "ids": ["1", "2", "3"]
}

// 使用通配符删除匹配的索引
DELETE /temp-*?expand_wildcards=open

1.4 多索引参数对比表

参数	默认值	典型用途
ignore_unavailable	false	批量操作时跳过已关闭/不存在的索引
allow_no_indices	true	通配符可能无匹配时的容错处理
expand_wildcards	open	需要操作关闭或隐藏索引时

---

二、日期数学（Date Math）格式

索引名称支持日期解析，让你可以在索引名称中使用动态日期表达式，这是管理基于时间的索引（如日志索引）的核心工具。

2.1 日期数学的基本语法

日期数学索引名称的格式为：

<static_name{date_math_expr{date_format|time_zone}}>

组成部分	说明	默认值
static_name	索引名称的静态文本部分	-
date_math_expr	动态日期数学表达式	-
date_format	日期格式（Java DateTimeFormatter兼容）	yyyy.MM.dd
time_zone	时区	UTC

2.2 URI编码要求

日期数学表达式必须用尖括号< >包裹，且所有特殊字符需要进行URI编码：

字符	URI编码
<	%3C
>	%3E
/	%2F
+	%2B
:	%3A
{	%7B
}	%7D
`	`
#	%23
?	%3F

2.3 日期数学表达式解析实例

假设当前时间为 2026-05-22T12:00:00.000Z（UTC）：

表达式	解析结果
<now>	2026-05-22
<now/d>	2026-05-22（近似到当天）
<now-1d>	2026-05-21
<now/d-1d>	2026-05-21（昨天）
<now/w>	2026-05-18（本周一）
<now/M>	2026-05-01（本月第一天）
<now-1M/M>	2026-04-01（上个月第一天）
<now-1h>	2026-05-22T11
<logs-{now/d}>	logs-2026-05-22
<logs-{now/M}>	logs-2026-05-01

2.4 实战：搜索过去三天的日志

假设索引命名格式为logstash-yyyy.MM.dd，要搜索过去三天的数据：

# URI编码后的请求
GET /%3Clogstash-%7Bnow-2d%2Fd%7D%3E,%3Clogstash-%7Bnow-1d%2Fd%7D%3E,%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
  "query": {
    "match": {
      "message": "error"
    }
  }
}

在Kibana Dev Tools中可以直接使用尖括号语法（无需编码）：

GET /<logstash-{now-2d/d}>,<logstash-{now-1d/d}>,<logstash-{now/d}>/_search
{
  "query": {
    "match": { "message": "error" }
  }
}

2.5 日期数学在静态名称中的转义

如果需要在索引名称的静态部分使用{和}字符，需要用反斜杠转义：

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

解析结果（假设当前时间为2026-05-22）：elastic{ON}-2026-05-01

2.6 日期数学常用模式速查

需求	表达式
今天的索引	<logs-{now/d}>
昨天的索引	<logs-{now-1d/d}>
最近7天的索引	<logs-{now-6d/d}>,<logs-{now-5d/d}>,...,<logs-{now/d}>
本月的索引	<logs-{now/M}>
上个月的索引	<logs-{now-1M/M}>
最近3个月的索引	<logs-{now-2M/M}>,<logs-{now-1M/M}>,<logs-{now/M}>

---

三、通用查询参数

以下选项适用于所有的Elasticsearch REST API。

3.1 格式化输出（pretty）

# 返回格式化的JSON（适用于调试）
GET /_cluster/health?pretty

# 返回YAML格式（更易读）
GET /_cluster/health?format=yaml

3.2 可读输出（human）

统计数据默认以两种格式返回——人类可读格式和机器可读格式：

{
  "took": 150,
  "hits": {
    "max_score": 1.0,
    "hits": []
  },
  "timed_out": false,
  "_shards": {
    "total": 5,
    "successful": 5,
    "skipped": 0,
    "failed": 0
  }
}

当human=true时：

{
  "took": "150ms",
  "hits": {
    "max_score": 1.0,
    "hits": []
  }
}

参数	说明	适用场景
human=true	人类可读格式（如"1h"、“1KB”）	人阅读调试
human=false	机器可读格式（如3600000、1024）	监控系统采集

3.3 返回信息过滤（filter_path）

filter_path参数可以大幅减少API响应的数据量，只返回需要的字段：

# 只返回特定字段
GET /bank/_search?q=*&sort=account_number:asc&filter_path=took,hits.hits._id,hits.hits._score

{
  "took" : 1,
  "hits" : {
    "hits" : [
      { "_id" : "0", "_score" : 1.0 },
      { "_id" : "1", "_score" : 1.0 },
      ...
    ]
  }
}

通配符用法：

# 使用*通配符匹配字段
GET /_cluster/state?filter_path=metadata.indices.*.stat*

# 使用**匹配深层嵌套字段
GET /_cluster/state?filter_path=routing_table.indices.**.state

# 使用-排除字段
GET /_count?filter_path=-_shards

# 组合使用：先排除再包含
GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*

filter_path使用技巧：

语法	说明	示例
逗号分隔	指定多个字段	took,hits.total
*通配符	匹配一层中的多个字段	hits.hits._*
**通配符	匹配任意深度的字段	indices.**.state
-前缀	排除字段	-_shards
组合	先排除后包含	field.*,-field.debug

3.4 启用堆栈跟踪（error_trace）

默认情况下，API错误响应不包含堆栈跟踪信息。开发调试时可以开启：

# 不带error_trace（默认）
POST /bank/_search?size=surprise_me

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "Failed to parse int parameter [size] with value [surprise_me]"
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "Failed to parse int parameter [size] with value [surprise_me]"
  },
  "status": 400
}

# 带error_trace
POST /bank/_search?size=surprise_me&error_trace=true

{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "Failed to parse int parameter [size] with value [surprise_me]",
        "stack_trace": "org.elasticsearch.common.xcontent.XContentParser$NumberFormatException..."
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "Failed to parse int parameter [size] with value [surprise_me]",
    "stack_trace": "org.elasticsearch.common.xcontent.XContentParser$NumberFormatException..."
  },
  "status": 400
}

注意：error_trace仅用于开发调试，生产环境不应启用，避免暴露内部信息。

3.5 展开设置（flat_settings）

# 平铺格式返回设置信息
GET /bank/_settings?flat_settings=true

{
  "bank": {
    "settings": {
      "index.creation_date": "1557845762384",
      "index.number_of_replicas": "1",
      "index.number_of_shards": "1",
      "index.provided_name": "bank",
      "index.uuid": "abc123...",
      "index.version.created": "7010099"
    }
  }
}

3.6 布尔值与数字值

布尔值：所有REST API参数都支持true和false，其他值会报错。

# 正确
GET /_search?pretty=true&human=false

# 错误 - 会报参数解析异常
GET /_search?pretty=yes

数字值：所有REST API都支持以字符串形式提供数字参数。

# 两种写法都正确
GET /_search?size=10
GET /_search?size=10

---

四、单位规范

Elasticsearch在各种场景下需要指定不同类型的单位，了解这些规范有助于编写正确的API调用。

4.1 时间单位

当API参数需要指定时间区间（如超时、刷新间隔等），必须包含单位：

单位	说明	等价值
ms	毫秒	1ms = 0.001s
s	秒	1s = 1000ms
m	分钟	1m = 60s
h	小时	1h = 60m
d	天	1d = 24h

# 超时设置为5秒
GET /_cluster/health?timeout=5s

# 刷新间隔设置为30秒
PUT /my_index/_settings
{
  "index": {
    "refresh_interval": "30s"
  }
}

# 滚动搜索保持5分钟
GET /_search?scroll=5m

日期数学中的时间解析实例（假设now为2001-01-01 12:00:00）：

表达式	解析结果
now+1h	2001-01-01 13:00:00
now-1d	2000-12-31 12:00:00
now/d	2001-01-01 00:00:00

4.2 数据单位

当需要指定数据的字节大小时，必须包含单位。注意：使用1024进制（1KB = 1024字节）：

单位	说明	等价值
b	字节	1b
kb	千字节	1kb = 1024b
mb	兆字节	1mb = 1024kb
gb	吉字节	1gb = 1024mb
tb	太字节	1tb = 1024gb
pb	拍字节	1pb = 1024tb

# 设置索引缓冲区大小
PUT /my_index/_settings
{
  "index": {
    "indices.memory.index_buffer_size": "10mb"
  }
}

4.3 距离单位

地理距离查询中使用的单位，默认为米（m）：

单位	说明
m	米（默认）
km	千米
mi	英里
cm	厘米
mm	毫米
yd	码
in	英寸
ft	英尺
nmi	海里

// 查询距离指定坐标10公里内的文档
GET /locations/_search
{
  "query": {
    "geo_distance": {
      "distance": "10km",
      "location": {
        "lat": 39.9,
        "lon": 116.4
      }
    }
  }
}

4.4 缩略乘数

对于无单位的数量值，ES会自动进行缩略显示：

乘数	名称	示例
`` (无)	个	87 → 87
k	千	7000 → 7k
m	百万	10000000 → 10m
t	万亿	1000000000000 → 1t
p	千万亿	1000000000000000 → 1p

---

五、总结与最佳实践

核心要点回顾

主题	关键语法/参数	说明
多索引	*,-通配符/排除	一次操作多个索引
日期数学	<name{expr{fmt|tz}}>	动态索引名
URI编码	%3C, %3E, %2F等	curl命令中必须编码
信息过滤	filter_path	减少响应体积
堆栈跟踪	error_trace=true	仅用于开发调试
时间单位	ms/s/m/h/d	所有时间参数必须带单位
数据单位	b/kb/mb/gb/tb/pb	缓冲区大小等参数
距离单位	m/km/mi/in/ft	地理距离查询

API使用最佳实践

1. 始终指定filter_path：在生产代码中调用ES API时，使用filter_path过滤不必要的字段，可以显著减少网络传输量和内存消耗。
2. 日期数学索引结合别名：用日期数学创建基于时间的索引，再通过别名简化查询。
3. curl中的URI编码：在命令行中使用日期数学时，记得对所有特殊字符进行URI编码；在Kibana中则不需要。
4. 使用human=false：当API的响应需要被程序解析时，使用human=false确保返回的数值格式一致。
5. 生产环境禁用error_trace：堆栈跟踪可能包含敏感的内部信息，生产环境不应暴露。

---

上一篇【第08篇】Elasticsearch集群扩展与运维——水平扩展与节点管理
下一篇【第10篇】Elasticsearch REST API最佳实践——Content-Type、模糊性与访问控制

---