From 49889b44f03f421027e25b6cb231be1c191e6011 Mon Sep 17 00:00:00 2001
From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Date: Wed, 25 Oct 2023 11:31:14 -0400
Subject: [PATCH] Add new default date format (#5163)

* Add new default date format

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Update _field-types/supported-field-types/date.md

Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>

* Add enabling experimental features section

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

---------

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
---
 _field-types/supported-field-types/date.md | 14 +++-
 experimental.md                            | 89 ++++++++++++++++++++++
 2 files changed, 100 insertions(+), 3 deletions(-)
 create mode 100644 experimental.md

diff --git a/_field-types/supported-field-types/date.md b/_field-types/supported-field-types/date.md
index 09b11107..93724cb6 100644
--- a/_field-types/supported-field-types/date.md
+++ b/_field-types/supported-field-types/date.md
@@ -48,7 +48,7 @@ Parameter | Description
 :--- | :--- 
 `boost` | A floating-point value that specifies the weight of this field toward the relevance score. Values above 1.0 increase the field's relevance. Values between 0.0 and 1.0 decrease the field's relevance. Default is 1.0.
 `doc_values` | A Boolean value that specifies whether the field should be stored on disk so that it can be used for aggregations, sorting, or scripting. Default is `false`.
-`format` | The format for parsing dates. Default is `strict_date_optional_time||epoch_millis`.
+`format` | The format for parsing dates. Default is `strict_date_time_no_millis||strict_date_optional_time||epoch_millis`.
 `ignore_malformed` | A Boolean value that specifies to ignore malformed values and not to throw an exception. Default is `false`.
 `index` | A Boolean value that specifies whether the field should be searchable. Default is `true`.
 `locale` | A region- and language-specific way of representing the date. Default is [`ROOT`](https://docs.oracle.com/javase/8/docs/api/java/util/Locale.html#ROOT) (a region- and language-neutral locale).
@@ -58,7 +58,11 @@ Parameter | Description
 
 ## Formats
 
-OpenSearch has built-in date formats, but you can also create your own custom formats. The default format is `strict_date_optional_time||epoch_millis`. You can specify multiple date formats, separated by `||`.
+OpenSearch has built-in date formats, but you can also create your own custom formats. You can specify multiple date formats, separated by `||`.
+
+## Default format
+
+As of OpenSearch 2.12, the default date format is `strict_date_time_no_millis||strict_date_optional_time||epoch_millis`. To revert the default format back to `strict_date_optional_time||epoch_millis` (the default format for OpenSearch 2.11 and earlier), set the `opensearch.experimental.optimization.datetime_formatter_caching.enabled` feature flag to `false`. For more information about enabling and disabling feature flags, see [Enabling experimental features]({{site.url}}{{site.baseurl}}/experimental/).
 
 ## Built-in formats
 
@@ -223,7 +227,11 @@ GET testindex/_search
 
 The date field type supports using date math to specify durations in queries. For example, the `gt`, `gte`, `lt`, and `lte` parameters in [range queries]({{site.url}}{{site.baseurl}}/query-dsl/term/range/) and the `from` and `to` parameters in [date range aggregations]({{site.url}}{{site.baseurl}}/query-dsl/aggregations/bucket/date-range/) accept date math expressions.
 
-A date math expression contains a fixed date, optionally followed by one or more mathematical expressions. The fixed date may be either `now` (current date and time in milliseconds since the epoch) or a string ending with `||` that specifies a date (for example, `2022-05-18||`). The date must be in the `strict_date_optional_time||epoch_millis` format.
+A date math expression contains a fixed date, optionally followed by one or more mathematical expressions. The fixed date may be either `now` (current date and time in milliseconds since the epoch) or a string ending with `||` that specifies a date (for example, `2022-05-18||`). The date must be in the [default format](#default-format) (which is `strict_date_time_no_millis||strict_date_optional_time||epoch_millis` by default).
+
+If you specify multiple date formats in the field mapping, OpenSearch uses the first format to convert the milliseconds since the epoch value to a string. <br>
+If a field mapping for a field contains no format, OpenSearch uses the `strict_date_optional_time` format to convert the epoch value to a string.
+{: .note}
 
 Date math supports the following mathematical operators.
 
diff --git a/experimental.md b/experimental.md
new file mode 100644
index 00000000..05a2faa1
--- /dev/null
+++ b/experimental.md
@@ -0,0 +1,89 @@
+---
+layout: default
+title: Enabling experimental features
+nav_order: 10
+parent: OpenSearch documentation
+---
+
+# Enabling experimental features
+
+OpenSearch releases may contain experimental features that you can enable or disable as needed. There are several methods for enabling feature flags, depending on the installation type. 
+
+## Enable in opensearch.yml
+
+If you are running an OpenSearch cluster and want to enable feature flags in the config file, add the following line to `opensearch.yml`:
+
+```yaml
+opensearch.experimental.feature.<feature_name>.enabled: true
+```
+{% include copy.html %}
+
+## Enable on Docker containers
+
+If you’re running Docker, add the following line to `docker-compose.yml` under the `opensearch-node` > `environment` section:
+
+```bash
+OPENSEARCH_JAVA_OPTS="-Dopensearch.experimental.feature.<feature_name>.enabled=true"
+```
+{% include copy.html %}
+
+## Enable on a tarball installation
+
+To enable feature flags on a tarball installation, provide the new JVM parameter either in `config/jvm.options` or `OPENSEARCH_JAVA_OPTS`.
+
+### Option 1: Modify jvm.options
+
+Add the following lines to `config/jvm.options` before starting the `opensearch` process to enable the feature and its dependency:
+
+```bash
+-Dopensearch.experimental.feature.<feature_name>.enabled=true
+```
+{% include copy.html %}
+
+Then run OpenSearch:
+
+```bash
+./bin/opensearch
+```
+{% include copy.html %}
+
+### Option 2: Enable with an environment variable
+
+As an alternative to directly modifying `config/jvm.options`, you can define the properties by using an environment variable. This can be done using a single command when you start OpenSearch or by defining the variable with `export`.
+
+To add the feature flags inline when starting OpenSearch, run the following command:
+
+```bash
+OPENSEARCH_JAVA_OPTS="-Dopensearch.experimental.feature.<feature_name>.enabled=true" ./opensearch-{{site.opensearch_version}}/bin/opensearch
+```
+{% include copy.html %}
+
+If you want to define the environment variable separately prior to running OpenSearch, run the following commands:
+
+```bash
+export OPENSEARCH_JAVA_OPTS="-Dopensearch.experimental.feature.<feature_name>.enabled=true"
+```
+{% include copy.html %}
+
+```bash
+./bin/opensearch
+```
+{% include copy.html %}
+
+## Enable for OpenSearch development
+
+To enable feature flags for development, you must add the correct properties to `run.gradle` before building OpenSearch. See the [Developer Guide](https://github.com/opensearch-project/OpenSearch/blob/main/DEVELOPER_GUIDE.md) for information about to use how Gradle to build OpenSearch.
+
+Add the following properties to run.gradle to enable the feature:
+
+```gradle
+testClusters {
+    runTask {
+      testDistribution = 'archive'
+      if (numZones > 1) numberOfZones = numZones
+      if (numNodes > 1) numberOfNodes = numNodes
+      systemProperty 'opensearch.experimental.feature.<feature_name>.enabled', 'true'
+    }
+  }
+```
+{% include copy.html %}
\ No newline at end of file