【Elasticsearch从入门到精通】第09篇：Elasticsearch API规范详解——多索引、日期数学与通用选项

上一篇【第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_unavailabletrueallow_no_indices当通配符表达式没有匹配到任何索引时控制请求是否失败。# foo* 没有匹配任何索引时请求不会失败GET /foo*/_search?allow_no_indicestrue# foo* 没有匹配任何索引时请求会失败GET /foo*/_search?allow_no_indicesfalseexpand_wildcards控制通配符可以扩展到哪些类型的索引。值说明open仅扩展到打开的索引默认值closed仅扩展到关闭的索引hidden仅扩展到隐藏的索引none不接受通配符all扩展到所有类型的索引# 搜索所有打开和关闭的索引GET /logs-*/_search?expand_wildcardsopen,closed1.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_wildcardsopen1.4 多索引参数对比表参数默认值典型用途ignore_unavailablefalse批量操作时跳过已关闭/不存在的索引allow_no_indicestrue通配符可能无匹配时的容错处理expand_wildcardsopen需要操作关闭或隐藏索引时二、日期数学Date Math格式索引名称支持日期解析让你可以在索引名称中使用动态日期表达式这是管理基于时间的索引如日志索引的核心工具。2.1 日期数学的基本语法日期数学索引名称的格式为static_name{date_math_expr{date_format|time_zone}}组成部分说明默认值static_name索引名称的静态文本部分-date_math_expr动态日期数学表达式-date_format日期格式Java DateTimeFormatter兼容yyyy.MM.ddtime_zone时区UTC2.2 URI编码要求日期数学表达式必须用尖括号 包裹且所有特殊字符需要进行URI编码字符URI编码%3C%3E/%2F%2B:%3A{%7B}%7D#%23?%3F2.3 日期数学表达式解析实例假设当前时间为2026-05-22T12:00:00.000ZUTC表达式解析结果now2026-05-22now/d2026-05-22近似到当天now-1d2026-05-21now/d-1d2026-05-21昨天now/w2026-05-18本周一now/M2026-05-01本月第一天now-1M/M2026-04-01上个月第一天now-1h2026-05-22T11logs-{now/d}logs-2026-05-22logs-{now/M}logs-2026-05-012.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-22elastic{ON}-2026-05-012.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?formatyaml3.2 可读输出human统计数据默认以两种格式返回——人类可读格式和机器可读格式{took:150,hits:{max_score:1.0,hits:[]},timed_out:false,_shards:{total:5,successful:5,skipped:0,failed:0}}当humantrue时{took:150ms,hits:{max_score:1.0,hits:[]}}参数说明适用场景humantrue人类可读格式如1h、“1KB”人阅读调试humanfalse机器可读格式如3600000、1024监控系统采集3.3 返回信息过滤filter_pathfilter_path参数可以大幅减少API响应的数据量只返回需要的字段# 只返回特定字段GET /bank/_search?q*sortaccount_number:ascfilter_pathtook,hits.hits._id,hits.hits._score{took:1,hits:{hits:[{_id:0,_score:1.0},{_id:1,_score:1.0},...]}}通配符用法# 使用*通配符匹配字段GET /_cluster/state?filter_pathmetadata.indices.*.stat*# 使用**匹配深层嵌套字段GET /_cluster/state?filter_pathrouting_table.indices.**.state# 使用-排除字段GET /_count?filter_path-_shards# 组合使用先排除再包含GET /_cluster/state?filter_pathmetadata.indices.*.state,-metadata.indices.logstash-*filter_path使用技巧语法说明示例逗号分隔指定多个字段took,hits.total*通配符匹配一层中的多个字段hits.hits._***通配符匹配任意深度的字段indices.**.state-前缀排除字段-_shards组合先排除后包含field.*,-field.debug3.4 启用堆栈跟踪error_trace默认情况下API错误响应不包含堆栈跟踪信息。开发调试时可以开启# 不带error_trace默认POST /bank/_search?sizesurprise_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_tracePOST /bank/_search?sizesurprise_meerror_tracetrue{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_settingstrue{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?prettytruehumanfalse# 错误 - 会报参数解析异常GET /_search?prettyyes数字值所有REST API都支持以字符串形式提供数字参数。# 两种写法都正确GET /_search?size10GET /_search?size10四、单位规范Elasticsearch在各种场景下需要指定不同类型的单位了解这些规范有助于编写正确的API调用。4.1 时间单位当API参数需要指定时间区间如超时、刷新间隔等必须包含单位单位说明等价值ms毫秒1ms 0.001ss秒1s 1000msm分钟1m 60sh小时1h 60md天1d 24h# 超时设置为5秒GET /_cluster/health?timeout5s# 刷新间隔设置为30秒PUT /my_index/_settings{index:{refresh_interval:30s}}# 滚动搜索保持5分钟GET /_search?scroll5m日期数学中的时间解析实例假设now为2001-01-01 12:00:00表达式解析结果now1h2001-01-01 13:00:00now-1d2000-12-31 12:00:00now/d2001-01-01 00:00:004.2 数据单位当需要指定数据的字节大小时必须包含单位。注意使用1024进制1KB 1024字节单位说明等价值b字节1bkb千字节1kb 1024bmb兆字节1mb 1024kbgb吉字节1gb 1024mbtb太字节1tb 1024gbpb拍字节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→87k千7000→7km百万10000000→10mt万亿1000000000000→1tp千万亿1000000000000000→1p五、总结与最佳实践核心要点回顾主题关键语法/参数说明多索引*,-通配符/排除一次操作多个索引日期数学name{expr{fmt|tz}}动态索引名URI编码%3C,%3E,%2F等curl命令中必须编码信息过滤filter_path减少响应体积堆栈跟踪error_tracetrue仅用于开发调试时间单位ms/s/m/h/d所有时间参数必须带单位数据单位b/kb/mb/gb/tb/pb缓冲区大小等参数距离单位m/km/mi/in/ft地理距离查询API使用最佳实践始终指定filter_path在生产代码中调用ES API时使用filter_path过滤不必要的字段可以显著减少网络传输量和内存消耗。日期数学索引结合别名用日期数学创建基于时间的索引再通过别名简化查询。curl中的URI编码在命令行中使用日期数学时记得对所有特殊字符进行URI编码在Kibana中则不需要。使用humanfalse当API的响应需要被程序解析时使用humanfalse确保返回的数值格式一致。生产环境禁用error_trace堆栈跟踪可能包含敏感的内部信息生产环境不应暴露。上一篇【第08篇】Elasticsearch集群扩展与运维——水平扩展与节点管理下一篇【第10篇】Elasticsearch REST API最佳实践——Content-Type、模糊性与访问控制