diff --git a/docs/reference/api-conventions.asciidoc b/docs/reference/api-conventions.asciidoc index f34f2e816887b..5e195a960457b 100644 --- a/docs/reference/api-conventions.asciidoc +++ b/docs/reference/api-conventions.asciidoc @@ -79,19 +79,17 @@ IMPORTANT: Direct access to system indices is deprecated and will no longer be allowed in the next major version. [[date-math-index-names]] -=== Date math support in index names +=== Date math support in index and index alias names -Date math index name resolution enables you to search a range of time series indices, rather -than searching all of your time series indices and filtering the results or maintaining aliases. -Limiting the number of indices that are searched reduces the load on the cluster and improves -execution 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. +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. -Almost all APIs that have an `index` parameter support date math in the `index` parameter -value. - -A date math index name takes the following form: +Most APIs that accept an index or index alias argument support date math. A date +math name takes the following form: [source,txt] ---------------------------------------------------------------------- @@ -101,10 +99,10 @@ A date math index name takes the following form: Where: [horizontal] -`static_name`:: is the static text part of the name -`date_math_expr`:: is a dynamic date math expression that computes the date dynamically -`date_format`:: is the 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`:: is the optional time zone. Defaults to `utc`. +`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`. NOTE: 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 @@ -113,8 +111,8 @@ NOTE: Pay attention to the usage of small vs capital letters used in the `date_f 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 index name expressions within angle brackets, and -all special characters should be URI encoded. For example: +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: [source,console] ---- @@ -139,8 +137,8 @@ The special characters used for date rounding must be URI encoded as follows: `,`:: `%2C` ====================================================== -The following example shows different forms of date math index names and the final index names -they resolve to given the current time is 22nd March 2024 noon utc. +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. [options="header"] |====== @@ -152,7 +150,7 @@ they resolve to given the current time is 22nd March 2024 noon utc. | `` | `logstash-2024.03.23` |====== -To use the characters `{` and `}` in the static part of an index name template, escape them +To use the characters `{` and `}` in the static part of a name template, escape them with a backslash `\`, for example: * `` resolves to `elastic{ON}-2024.03.01` diff --git a/docs/reference/indices/add-alias.asciidoc b/docs/reference/indices/add-alias.asciidoc index e3fc4e0711981..19f8d7cf7f6b5 100644 --- a/docs/reference/indices/add-alias.asciidoc +++ b/docs/reference/indices/add-alias.asciidoc @@ -47,7 +47,8 @@ NOTE: You cannot add <> to an index alias. ``:: (Required, string) -Name of the index alias to create or update. +Name of the index alias to create or update. Supports +<>. [[add-alias-api-query-params]] @@ -68,6 +69,18 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-routing] [[add-alias-api-example]] ==== {api-examples-title} +[[alias-date-math-support]] +===== Date math support + +Index alias names support <>. + +[source,console] +---- +# POST /logs/_alias/ +POST /logs/_alias/%3Clogs_%7Bnow%2FM%7D%3E +---- +// TEST[s/^/PUT logs\n/] + [[alias-adding]] ===== Add a time-based alias @@ -139,3 +152,16 @@ PUT /logs_20302801 } } -------------------------------------------------- + +The create index API also supports <> in index +alias names. + +[source,console] +---- +PUT /logs +{ + "aliases": { + "": {} + } +} +---- diff --git a/docs/reference/indices/aliases.asciidoc b/docs/reference/indices/aliases.asciidoc index db4bc2b81f390..67ef100173e55 100644 --- a/docs/reference/indices/aliases.asciidoc +++ b/docs/reference/indices/aliases.asciidoc @@ -103,19 +103,19 @@ NOTE: You cannot add <> to an index alias. `alias`:: (String) -Comma-separated list or wildcard expression of index alias names to -add, remove, or delete. +Comma-separated list or wildcard expression of index alias names to add, remove, +or delete. Supports <>. + If the `aliases` parameter is not specified, this parameter is required for the `add` or `remove` action. `aliases`:: (Array of strings) -Array of index alias names to -add, remove, or delete. +Array of index alias names to add, remove, or delete. Supports +<>. + -If the `alias` parameter is not specified, -this parameter is required for the `add` or `remove` action. +If the `alias` parameter is not specified, this parameter is required for the +`add` or `remove` action. `filter`:: (Optional, query object) @@ -190,6 +190,20 @@ POST /_aliases -------------------------------------------------- // TEST[s/^/PUT test1\nPUT test2\n/] +Index alias names support <>. + +[source,console] +---- +POST /_aliases +{ + "actions" : [ + { "add" : { "index" : "logs", "alias" : "" } } + ] +} +---- +// TEST[s/^/PUT logs\n/] +// TEST[continued] + [[indices-aliases-api-remove-alias-ex]] ===== Remove an alias diff --git a/docs/reference/indices/create-index.asciidoc b/docs/reference/indices/create-index.asciidoc index 22b9e60d24475..957d95d0172f2 100644 --- a/docs/reference/indices/create-index.asciidoc +++ b/docs/reference/indices/create-index.asciidoc @@ -68,7 +68,7 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=timeoutparms] `aliases`:: (Optional, <>) Index aliases which include the -index. See <>. +index. Index alias names support <>. include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=mappings] @@ -161,6 +161,18 @@ PUT /test } -------------------------------------------------- +Index alias names also support <>. + +[source,console] +---- +PUT /logs +{ + "aliases": { + "": {} + } +} +---- + [[create-index-wait-for-active-shards]] ===== Wait for active shards @@ -173,7 +185,7 @@ what happened: { "acknowledged": true, "shards_acknowledged": true, - "index": "test" + "index": "logs" } -------------------------------------------------- diff --git a/docs/reference/rest-api/common-parms.asciidoc b/docs/reference/rest-api/common-parms.asciidoc index f118479ebe158..82102f14e5741 100644 --- a/docs/reference/rest-api/common-parms.asciidoc +++ b/docs/reference/rest-api/common-parms.asciidoc @@ -25,15 +25,16 @@ end::index-alias[] tag::aliases[] `aliases`:: -(Optional, <>) Index aliases which include the -index. See <>. +(Optional, <>) <> +which include the index. Index alias names support <>. end::aliases[] tag::target-index-aliases[] `aliases`:: (Optional, <>) -Index aliases which include the target index. -See <>. +<> which include the target index. Index alias +names support <>. end::target-index-aliases[] tag::allow-no-indices[]