diff --git a/_opensearch/bucket-agg.md b/_opensearch/bucket-agg.md index 03b047ad..49301420 100644 --- a/_opensearch/bucket-agg.md +++ b/_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: diff --git a/_opensearch/query-dsl/term.md b/_opensearch/query-dsl/term.md index 09964e69..2d997502 100644 --- a/_opensearch/query-dsl/term.md +++ b/_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 diff --git a/_opensearch/supported-field-types/date.md b/_opensearch/supported-field-types/date.md index 65cee29c..b093a56a 100644 --- a/_opensearch/supported-field-types/date.md +++ b/_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
+`M`: Months
+`w`: Weeks
+`d`: Days
+`h` or `H`: Hours
+`m`: Minutes
+`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" + } + } + ] + } +} +``` \ No newline at end of file