Add new default date format (#5163)

* Add new default date format Signed-off-by: Fanit Kolchina <[email protected]> * Update _field-types/supported-field-types/date.md Signed-off-by: kolchfa-aws <[email protected]> * Add enabling experimental features section Signed-off-by: Fanit Kolchina <[email protected]> --------- Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: kolchfa-aws <[email protected]>
opensearch-project · Oct 25, 2023 · 49889b4 · 49889b4
1 parent 81c858f
commit 49889b4
Show file tree

Hide file tree

Showing 2 changed files with 100 additions and 3 deletions.
diff --git 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
@@ -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 %}