# format （日期格式）
在**JSON** 文档中,日期表示为字符串.**Elasticsearch** 使用一组预先配置的格式来识别和解析这些字符串表示为 **milliseconds-since-the-epoch in UTC.**
除了内置格式,你可以使用熟悉的**yyyy/MM/dd**语法指定自己的自定义格式.
```
curl -XPUT 'localhost:9200/my_index?pretty' -H 'Content-Type: application/json' -d'
{
"mappings": {
"my_type": {
"properties": {
"date": {
"type": "date",
"format": "yyyy-MM-dd"
}
}
}
}
}
'
```
支持日期值的许多API还支持日期数学表达式,例如**now-1m/d**，即当前时间,减去一个月,向下舍入到最近的一天.
> tip:
>
> 格式设置在相同索引中相同名称的字段要有相同的设置.可以使用[**PUT mapping API**](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/indices-put-mapping.html)在现有字段上更新其值.
## Custom date formats （标准的日期格式）
支持完全可定制的日期格式,这些语法[**in the Joda docs**](http://www.joda.org/joda-time/apidocs/org/joda/time/format/DateTimeFormat.html)**.**
## Built In Formats （以格式化构建）
以下大多数日期都有严格的伴随日期,这意味着,本周的年月日必须有前置的零数字才有效.这意味着,像5/11/1这样的日期是无效的,你需要制定完整的日期,例如2005/11/01。所以,你需要指定**strict\_date\_optional\_time（**严格的日期选择） 来代替 **date\_optional\_time**.
下表列出了支持的所有默认ISO格式:
`epoch_millis`
一个毫秒的格式化程序.请注意,这个时间戳受 **Java** `Long.MIN_VALUE和Long.MAX_VALUE限制.`
`epoch_second`
.一个秒的格式化程序.请注意,时间戳受 **Java** `Long.MIN_VALUE和Long.MAX_VALUE限制.MAX_VALUE除以1000（一秒钟的毫秒数）.`
[`date_optional_time` or `strict_date_optional_time`](https://www.elastic.co/guide/en/elasticsearch/reference/5.3/mapping-date-format.html#strict-date-time)
```
通用 ISO 日期时间解析器，其中日期是必需的，时间是可选的。
```
[Full details here](http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateOptionalTimeParser--).`basic_date`
一个对完整日期的格式化,四位数字年份,两位数字的月份,两位数字的日期: **yyyMMdd**
`basic_date_time`
一个包含基本日期和时间的格式化程序,通过'T'分割：`yyyyMMdd'T'HHmmss.SSSZ`.
`basic_date_time_no_millis`
一个包含基本日期和时间且没有毫秒的格式化程序,通过 ‘T’ 分割：**yyyyMMdd'T'HHmmssZ.**
`basic_ordinal_date`
一个用于 **ordinal date**的格式化程序，使用四位数字的年份和三位数的日期，yyyyDDD。
`basic_ordinal_date_time`
一个用于完整的 **ordinal**日期和时间的格式化程序,使用四位数的年份和三位数的日期: `yyyyDDD'T'HHmmss.SSSZ`**.**
`basic_ordinal_date_time_no_millis`
一个用于完整的 **ordinal** 日期和时间且没有毫秒的格式化程序,使用四位数的年份和三位数的日期: `yyyyDDD'T'HHmmssZ`**.**
`basic_time`
一个两位数的小时,两位数的分钟,两位数的秒,三位数的毫秒以及时间偏移量的格式化程序:**HHmmss.SSSZ.**
`basic_time_no_millis`
一个两位数的小时,两位数的分钟,两位数的秒以及时间偏移量的格式化程序:**HHmmssZ**
`basic_t_time`
一个两位数的小时,两位数的分钟,两位数的秒,三位数的毫秒以及以T为前缀的时区：`'T'HHmmss.SSSZ`.
`basic_t_time_no_millis`
`一个两位数的小时,两位数的分钟,两位数的秒以及以T为前缀的时区：'T'HHmmssZ`.
`basic_week_date` or `strict_basic_week_date`
一个四位数的weekyear,两位数的周数,一位数的天数:**xxxx'W'wwe。**
`basic_week_date_time` or `strict_basic_week_date_time`
一个包含基础的 weekyear 日期和时间的格式化程序,通过T分割: `xxxx'W'wwe'T'HHmmss.SSSZ`**.**
`basic_week_date_time_no_millis` or `strict_basic_week_date_time_no_millis`
一个包含基础的 weekyear 日期和时间且不包含毫秒的格式化程序,通过T分割 :`xxxx'W'wwe'T'HHmmssZ`.
`date` or `strict_date`
一个完整日期的格式化程序,四位数的年,两位数的月,两位数的天: `yyyy-MM-dd.`
`date_hour` or `strict_date_hour`
一个包含完整日期和两位数的小时的格式化程序: `yyyy-MM-dd'T'HH`**.**
`date_hour_minute` or `strict_date_hour_minute`
一个包含完整日期,两位数的天数,两位数的分钟的格式化程序: `yyyy-MM-dd'T'HH:mm`**.**
`date_hour_minute_second` or `strict_date_hour_minute_second`
一个包含完整日期,两位数的天数,两位数的分钟,两位数的秒数: `yyyy-MM-dd'T'HH:mm:ss`.
`date_hour_minute_second_fraction` or `strict_date_hour_minute_second_fraction`
一个包含完整日期,两位数的小时数,两位数的分钟数,两位数的秒数,三位数的秒的分数：`yyyy-MM-dd'T'HH:mm:ss.SSS`**.**
`date_hour_minute_second_millis` or `strict_date_hour_minute_second_millis`
一个包含完整日期,两位数的小时,两位数的分钟,两位数的秒数,三位数的秒的分数: `yyyy-MM-dd'T'HH:mm:ss.SSS`**.**
`date_time` or `strict_date_time`
一个包含完整日期和时间,通过T分割的格式化程序: `yyyy-MM-dd'T'HH:mm:ss.SSSZZ`**.**
`date_time_no_millis` or `strict_date_time_no_millis`
一个包含完整日期和时间且没有毫秒的,通过T分割的格式化程序: `yyyy-MM-dd'T'HH:mm:ssZZ`**.**
`hour` or `strict_hour`
一个两位数的小时数的格式化程序: **HH**
`hour_minute` or `strict_hour_minute`
一个两位数的小时数和两位数的分钟数:`HH:mm`.
`hour_minute_second` or `strict_hour_minute_second`
一个两位数的小时数,两位数的分钟数和两位数的秒数:`HH:mm:ss`.
`hour_minute_second_fraction` or `strict_hour_minute_second_fraction`
一个两位数的小时数,两位数的分钟数,两位数的秒数，三位数的秒的分数:`HH:mm:ss.SSS`.
`hour_minute_second_millis` or `strict_hour_minute_second_millis`
一个两位数的小时数,两位数的分钟数,两位数的秒数,三位数的秒的分数: `HH:mm:ss.SSS`.
`ordinal_date` or `strict_ordinal_date`
一个完整日期的格式化程序,使用四位数的年数和三位数年的天数:`yyyy-DDD`.
`ordinal_date_time` or `strict_ordinal_date_time`
一个完整ordinal 日期和时间的格式化程序,使用四位数的年数和三位数的天数:`yyyy-DDD'T'HH:mm:ss.SSSZZ`.
`ordinal_date_time_no_millis` or `strict_ordinal_date_time_no_millis`
一个完整日期和时间没有毫秒的格式化程序,使用四位数的年份和三位数的年的天数： `yyyy-DDD'T'HH:mm:ssZZ`.
`time` or `strict_time`
一个两位数的天数,两位数的小时,两位数的秒,三位数的秒的分数,以及时间偏移量：`HH:mm:ss.SSSZZ`.
`time_no_millis` or `strict_time_no_millis`
一个两位数的小时,两位数的分钟,两位数的秒以及时间偏移量:`HH:mm:ssZZ`.
`t_time` or `strict_t_time`
一个两位数的小时,两位数的分钟,两位数的秒,三位数的秒的分数以及以T为前缀的时间偏移量: `'T'HH:mm:ss.SSSZZ`.
`t_time_no_millis` or `strict_t_time_no_millis`
一个两位数的小时,两位数的分钟,两位数的秒以及以T为前缀的时间偏移量:`'T'HH:mm:ssZZ`.
`week_date` or `strict_week_date`
一个完整日其的格式化程序,四位数的weekyear,两位数的周数,一位数的天数： `xxxx-'W'ww-e`.
`week_date_time` or `strict_week_date_time`
一个包含完整weekyear 日期和时间的格式化程序,通过T进行分割：`xxxx-'W'ww-e'T'HH:mm:ss.SSSZZ`.
`week_date_time_no_millis` or `strict_week_date_time_no_millis`
一个包含完整 weekyear 日期和时间没有毫秒,以T分割的格式化程序: `xxxx-'W'ww-e'T'HH:mm:ssZZ`.
`weekyear` or `strict_weekyear`
一个四位数的 weekyear 的格式化程序:xxxx
`weekyear_week` or `strict_weekyear_week`
一个四位数的 weekyear 和两位数的周数:`xxxx-'W'ww`.
weekyear\_week\_day or strict\_weekyear\_week\_day
一个四位数的weekyear 两位数的周数,一位数的天数: `xxxx-'W'ww-e`.
`year` or `strict_year`
一个四位数年份的格式化程序:yyyy.
`year_month` or `strict_year_month`
一个四位数年份和两位数月份的格式化程序: `yyyy-MM`.
`year_month_day` or `strict_year_month_day`
一个四位数的年份和两位数的月份,两位数的天数的格式化程序：`yyyy-MM-dd`.