上一篇【第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、模糊性与访问控制

# elasticsearch # jenkins # 大数据 # 全文检索 # 搜索引擎
Logo
AtomGit开源社区

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念，把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起，为开发者提供从开发、训练到部署的一站式体验。

更多推荐

cover

当你的品牌在AI搜索中“消失”：为什么搜极星是唯一的救命稻草？

avatar AtomGit开源社区
cover

2026年中国市场最受欢迎的五大AI招聘系统厂商盘点

avatar AtomGit开源社区
cover

Hermes记忆升级记：当 vecmem记忆层被污染之后

avatar AtomGit开源社区