Adds date math documentation (opensearch-project#2171)

* Adds date math documentation

Signed-off-by: Fanit Kolchina <[email protected]>

* Incorporated doc review comments

Signed-off-by: Fanit Kolchina <[email protected]>

* Incorporated editorial comments

Signed-off-by: Fanit Kolchina <[email protected]>

Signed-off-by: Fanit Kolchina <[email protected]>

Author: kolchfa-aws

_opensearch/bucket-agg.md

@@ -697,7 +697,7 @@ Sample Response
 }
 ```
 
-The `date_histogram` aggregation uses date math to generate histograms for time-series data.
+The `date_histogram` aggregation uses [date math]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/#date-math) to generate histograms for time-series data.
 
 For example, you can find how many hits your website gets per month:
 

_opensearch/query-dsl/term.md

@@ -329,9 +329,9 @@ GET products/_search
 }
 ```
 
-Specify relative dates by using basic math expressions.
+Specify relative dates by using [date math]({{site.url}}{{site.baseurl}}/opensearch/supported-field-types/date/#date-math).
 
-To subtract 1 year and 1 day from the specified date:
+To subtract 1 year and 1 day from the specified date, use the following query:
 
 ```json
 GET products/_search

_opensearch/supported-field-types/date.md

@@ -209,3 +209,127 @@ GET testindex/_search
   }
 }
 ```
+
+## Date math
+
+The date field type supports using date math to specify duration in queries. For example, the `gt`, `gte`, `lt`, and `lte` parameters in [range queries]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/term/#range-query) and the `from` and `to` parameters in [date range aggregations]({{site.url}}{{site.baseurl}}/opensearch/bucket-agg/#range-date_range-ip_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.
+
+Date math supports the following mathematical operators.
+
+Operator | Description | Example
+:--- | :--- | :---
+`+` | Addition | `+1M`: Add 1 month.
+`-` | Subtraction | `-1y`: Subtract 1 year.
+`/` | Rounding down | `/h`: Round to the beginning of the hour.
+
+Date math supports the following time units:
+
+`y`: Years<br>
+`M`: Months<br>
+`w`: Weeks<br>
+`d`: Days<br>
+`h` or `H`: Hours<br>
+`m`: Minutes<br>
+`s`: Seconds
+{: .note }
+
+### Example expressions
+
+The following example expressions illustrate using date math:
+
+- `now+1M`: The current date and time in milliseconds since the epoch, plus 1 month.
+- `2022-05-18||/M`: 05/18/2022, rounded to the beginning of the month. Resolves to `2022-05-01`.
+- `2022-05-18T15:23||/h`: 15:23 on 05/18/2022, rounded to the beginning of the hour. Resolves to `2022-05-18T15`.
+- `2022-05-18T15:23:17.789||+2M-1d/d`: 15:23:17.789 on 05/18/2022 plus 2 months minus 1 day, rounded to the beginning of the day. Resolves to `2022-07-17`.
+
+
+### Using date math in a range query
+
+The following example illustrates using date math in a [range query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/term/#range-query).
+
+Set up an index with `release_date` mapped as `date`:
+
+```json
+PUT testindex 
+{
+  "mappings" : {
+    "properties" :  {
+      "release_date" : {
+        "type" : "date"
+      }
+    }
+  }
+}
+```
+
+Index two documents into the index:
+
+```json
+PUT testindex/_doc/1
+{
+  "release_date": "2022-09-14"
+}
+
+PUT testindex/_doc/2
+{
+  "release_date": "2022-11-15"
+}
+```
+
+The following query searches for documents with `release_date` within 2 months and 1 day of 09/14/2022. The lower boundary of the range is rounded to the beginning of the day on 09/14/2022:
+
+```json
+GET testindex/_search
+{
+  "query": {
+    "range": {
+      "release_date": {
+        "gte": "2022-09-14T15:23||/d",
+        "lte": "2022-09-14||+2M+1d"
+      }
+    }
+  }
+}
+```
+
+The response contains both documents:
+
+```json
+{
+  "took" : 1,
+  "timed_out" : false,
+  "_shards" : {
+    "total" : 1,
+    "successful" : 1,
+    "skipped" : 0,
+    "failed" : 0
+  },
+  "hits" : {
+    "total" : {
+      "value" : 2,
+      "relation" : "eq"
+    },
+    "max_score" : 1.0,
+    "hits" : [
+      {
+        "_index" : "testindex",
+        "_id" : "2",
+        "_score" : 1.0,
+        "_source" : {
+          "release_date" : "2022-11-14"
+        }
+      },
+      {
+        "_index" : "testindex",
+        "_id" : "1",
+        "_score" : 1.0,
+        "_source" : {
+          "release_date" : "2022-09-14"
+        }
+      }
+    ]
+  }
+}
+```