Adds date math documentation (#2171)
* Adds date math documentation Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Incorporated doc review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Incorporated editorial comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
This commit is contained in:
kolchfa-aws
GitHub
parent
4710471e5b
commit
f9a9ea1baf
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue