Date math support in index and index alias names

edit

Date math support in index and index alias names

edit

Date math name resolution lets you to search a range of time series indices or index aliases rather than searching all of your indices and filtering the results. Limiting the number of searched indices reduces cluster load and improves search performance. For example, if you are searching for errors in your daily logs, you can use a date math name template to restrict the search to the past two days.

Most APIs that accept an index or index alias argument support date math. A date math name takes the following form:

<static_name{date_math_expr{date_format|time_zone}}>

Where:

static_name

Static text

date_math_expr

Dynamic date math expression that computes the date dynamically

date_format

Optional format in which the computed date should be rendered. Defaults to yyyy.MM.dd. Format should be compatible with java-time https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html

time_zone

Optional time zone. Defaults to UTC.

Pay attention to the usage of small vs capital letters used in the date_format. For example: mm denotes minute of hour, while MM denotes month of year. Similarly hh denotes the hour in the 1-12 range in combination with AM/PM, while HH denotes the hour in the 0-23 24-hour range.

Date math expressions are resolved locale-independent. Consequently, it is not possible to use any other calendars than the Gregorian calendar.

You must enclose date math names in angle brackets. If you use the name in a request path, special characters must be URI encoded. For example:

# PUT /<my-index-{now/d}>
PUT /%3Cmy-index-%7Bnow%2Fd%7D%3E

Percent encoding of date math characters

The special characters used for date rounding must be URI encoded as follows:

<

%3C

>

%3E

/

%2F

{

%7B

}

%7D

|

%7C

+

%2B

:

%3A

,

%2C

The following example shows different forms of date math names and the final names they resolve to given the current time is 22nd March 2024 noon UTC.

Expression Resolves to

<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

To use the characters { and } in the static part of a name template, escape them with a backslash \, for example:

  • <elastic\{ON\}-{now/M}> resolves to elastic{ON}-2024.03.01

The following example shows a search request that searches the Logstash indices for the past three days, assuming the indices use the default Logstash index name format, logstash-yyyy.MM.dd.

# GET /<logstash-{now/d-2d}>,<logstash-{now/d-1d}>,<logstash-{now/d}>/_search
GET /%3Clogstash-%7Bnow%2Fd-2d%7D%3E%2C%3Clogstash-%7Bnow%2Fd-1d%7D%3E%2C%3Clogstash-%7Bnow%2Fd%7D%3E/_search
{
  "query" : {
    "match": {
      "test": "data"
    }
  }
}