date 필드 타입

date 필드 타입

도입 1.0

OpenSearch에서 날짜(date)는 다음 중 하나로 표현할 수 있어요. 날짜 범위를 표현해야 한다면 date range 필드 타입을 사용해요.

  • epoch 이후의 밀리초에 해당하는 long 값. 날짜는 내부적으로 이 형태로 저장돼요.
  • 형식이 지정된 문자열.
  • epoch 이후의 초에 해당하는 정수 값.

출처: 문서

본문

예제

date 필드와 두 개의 날짜 형식을 갖는 매핑을 만들어 볼게요.

PUT testindex
{
  "mappings" : {
    "properties" :  {
      "release_date" : {
        "type" : "date",
        "format" : "strict_date_optional_time||epoch_millis"
      }
    }
  }
}

파라미터

다음 표는 date 필드 타입이 받아들이는 파라미터를 나열해요. 모든 파라미터는 선택 사항이에요.

  • boost: 이 필드의 관련성 점수에 대한 가중치를 지정하는 부동 소수점 값. 1.0보다 큰 값은 필드의 관련성을 높이고, 0.0~1.0 사이의 값은 관련성을 낮춰요. 기본값은 1.0이며 동적으로 업데이트할 수 있어요.
  • doc_values: 필드를 디스크에 저장해 집계, 정렬 또는 스크립팅에 사용할지 여부를 지정하는 Boolean 값. 기본값은 false예요.
  • format: 날짜를 파싱할 형식. 기본값은 strict_date_time_no_millis||strict_date_optional_time||epoch_millis예요.
  • ignore_malformed: 잘못된 값은 무시하고 예외를 던지지 않을지 여부를 지정하는 Boolean 값. 기본값은 false이며 동적으로 업데이트할 수 있어요.
  • index: 필드를 검색 가능하게 할지 여부를 지정하는 Boolean 값. 기본값은 true예요.
  • locale: 날짜를 표현하는 지역 및 언어별 방식. 기본값은 ROOT(지역 및 언어에 중립적인 로케일)예요.
  • meta: 이 필드에 대한 메타데이터를 받아들여요.
  • null_value: null 대신 사용할 값. 필드와 같은 타입이어야 해요. 이 파라미터를 지정하지 않으면 값이 null일 때 필드는 누락된 것으로 처리돼요. 기본값은 null이에요.
  • skip_list: doc values에 대한 skip list 인덱싱을 활성화할지 여부를 지정하는 Boolean 값. 활성화하면 OpenSearch는 쿼리 엔진이 관련 없는 문서 범위를 건너뛸 수 있게 해 범위 쿼리 성능을 개선하는 인덱스형 doc values를 만들어요. skip list 인덱싱은 @timestamp 필드와 인덱스 정렬에 사용되는 필드에 자동으로 활성화돼요. 다른 모든 필드의 기본값은 false예요.
  • store: 필드 값을 저장하고 _source 필드와 별도로 검색할 수 있는지 여부를 지정하는 Boolean 값. 기본값은 false예요.

형식 (Formats)

OpenSearch에는 내장된 날짜 형식이 있지만 사용자 정의 형식도 만들 수 있어요. ||로 구분하여 여러 날짜 형식을 지정할 수 있어요.

기본 형식

OpenSearch 2.12부터 실험적인 기본 날짜 형식인 strict_date_time_no_millis||strict_date_optional_time||epoch_millis를 선택해 사용할 수 있어요. 실험적인 기본값을 사용하려면 opensearch.experimental.optimization.datetime_formatter_caching.enabled 기능 플래그를 true로 설정해요. 기능 플래그 활성화 및 비활성화에 대한 자세한 내용은 실험적 기능 활성화를 참조하세요.

내장 형식

대부분의 날짜 형식에는 strict_ 대응 형식이 있어요. 형식이 strict_로 시작하면 날짜는 형식에 지정된 정확한 자릿수를 가져야 해요. 예를 들어 형식이 strict_year_month_day("yyyy-MM-dd")로 설정되면 월과 일 모두 두 자릿수여야 해요. 따라서 "2020-06-09"는 유효하지만 "2020-6-9"는 유효하지 않아요.

Epoch는 1970년 1월 1일 00:00:00 UTC로 정의돼요.

  • y: 연도
  • Y: 주 기반 연도 (week-based year)
  • M: 월
  • w: 연도의 순번 주 (01~53)
  • d: 일
  • D: 연도의 순번 일 (001~365, 윤년이면 366)
  • e: 주의 순번 요일 (1(월요일)~7(일요일))
  • H: 시간 (0~23)
  • m: 분
  • s: 초
  • S: 초의 소수 부분
  • Z: 시간대 오프셋 (예: +0400; -0400; -04:00)
숫자 날짜 형식
  • epoch_millis: epoch 이후의 밀리초 수. 최소값은 -263, 최대값은 263 − 1. 예: 1553391286000
  • epoch_second: epoch 이후의 초 수. 최소값은 -263 ÷ 1000, 최대값은 (263 − 1) ÷ 1000. 예: 1553391286
기본 날짜 형식

기본 날짜 형식의 구성 요소는 구분자로 분리되지 않아요. 예: "20190323".

  • basic_date_time: T로 구분된 기본 날짜와 시간. 패턴 "yyyyMMddTHHmmss.SSSZ", 예 "20190323T213446.123-04:00"
  • basic_date_time_no_millis: 밀리초가 없는 기본 날짜와 시간, T로 구분. 패턴 "yyyyMMddTHHmmssZ", 예 "20190323T213446-04:00"
  • basic_date: 네 자리 연도, 두 자리 월, 두 자리 일로 된 날짜. 패턴 "yyyyMMdd", 예 "20190323"
  • basic_time: 두 자리 시, 분, 초, 세 자리 밀리초, 시간대 오프셋이 있는 시간. 패턴 "HHmmss.SSSZ", 예 "213446.123-04:00"
  • basic_time_no_millis: 밀리초가 없는 기본 시간. 패턴 "HHmmssZ", 예 "213446-04:00"
  • basic_t_time: T가 앞에 오는 기본 시간. 패턴 "THHmmss.SSSZ", 예 "T213446.123-04:00"
  • basic_t_time_no_millis: 밀리초가 없고 T가 앞에 오는 기본 시간. 패턴 "THHmmssZ", 예 "T213446-04:00"
  • basic_ordinal_date_time: 전체 서수 날짜와 시간. 패턴 "yyyyDDDTHHmmss.SSSZ", 예 "2019082T213446.123-04:00"
  • basic_ordinal_date_time_no_millis: 밀리초가 없는 전체 서수 날짜와 시간. 패턴 "yyyyDDDTHHmmssZ", 예 "2019082T213446-04:00"
  • basic_ordinal_date: 네 자리 연도와 세 자리 서수 일로 된 날짜. 패턴 "yyyyDDD", 예 "2019082"
  • basic_week_date_time / strict_basic_week_date_time: T로 구분된 전체 주 기반 날짜와 시간. 패턴 "YYYYWwweTHHmmss.SSSZ", 예 "2019W126213446.123-04:00"
  • basic_week_date_time_no_millis / strict_basic_week_date_time_no_millis: 밀리초가 없는 기본 주 기반 연도 날짜와 시간, T로 구분. 패턴 "YYYYWwweTHHmmssZ", 예 "2019W126213446-04:00"
  • basic_week_date / strict_basic_week_date: 네 자리 주 기반 연도, 두 자리 주, 한 자리 요일로 된 전체 주 기반 날짜, W로 구분. 패턴 "YYYYWwwe", 예 "2019W126"
전체 날짜 형식

전체 날짜 형식의 구성 요소는 날짜에 - 구분자, 시간에 : 구분자로 분리돼요. 예: "2019-03-23T21:34".

  • date_optional_time / strict_date_optional_time: 일반적인 전체 날짜와 시간. 연도는 필수이고, 월, 일, 시간은 선택 사항이에요. 시간은 T로 날짜와 구분돼요. 여러 패턴. 예: "2019-03-23T21:34:46", "2019-03-23T21:34", "2019"
  • strict_date_optional_time_nanos: 일반적인 전체 날짜와 시간. 연도는 필수이고, 월, 일, 시간은 선택 사항이에요. 시간을 지정하면 시, 분, 초를 포함해야 하며 초의 소수 부분은 선택 사항이에요. 초의 소수 부분은 1~9자리이고 나노초 정밀도를 가져요. 시간은 T로 날짜와 구분돼요. 여러 패턴. 예: "2019-03-23T21:34:46.123456789-04:00", "2019", "2019-03-23T21:34:46"
  • date_time / strict_date_time: T로 구분된 전체 날짜와 시간. 패턴 "yyyy-MM-ddTHH:mm:ss.SSSZ", 예 "2019-03-23T21:34:46.123-04:00"
  • date_time_no_millis / strict_date_time_no_millis: 밀리초가 없는 전체 날짜와 시간, T로 구분. 패턴 "yyyy-MM-dd'T'HH:mm:ssZ", 예 "2019-03-23T21:34:46-04:00"
  • date_hour_minute_second_fraction / strict_date_hour_minute_second_fraction: T로 구분된 전체 날짜, 두 자리 시, 분, 초, 1~9자리 초의 소수 부분. 패턴 "yyyy-MM-ddTHH:mm:ss.SSSSSSSSS", 예 "2019-03-23T21:34:46.123456789", "2019-03-23T21:34:46.1"
  • date_hour_minute_second_millis / strict_date_hour_minute_second_millis: T로 구분된 전체 날짜, 두 자리 시, 분, 초, 세 자리 밀리초. 패턴 "yyyy-MM-ddTHH:mm:ss.SSS", 예 "2019-03-23T21:34:46.123"
  • date_hour_minute_second / strict_date_hour_minute_second: T로 구분된 전체 날짜, 두 자리 시, 분, 초. 패턴 "yyyy-MM-ddTHH:mm:ss", 예 "2019-03-23T21:34:46"
  • date_hour_minute / strict_date_hour_minute: 전체 날짜, 두 자리 시, 분. 패턴 "yyyy-MM-ddTHH:mm", 예 "2019-03-23T21:34"
  • date_hour / strict_date_hour: T로 구분된 전체 날짜와 두 자리 시. 패턴 "yyyy-MM-ddTHH", 예 "2019-03-23T21"
  • date / strict_date: 네 자리 연도, 두 자리 월, 두 자리 일. 패턴 "yyyy-MM-dd", 예 "2019-03-23"
  • year_month_day / strict_year_month_day: 네 자리 연도, 두 자리 월, 두 자리 일. 패턴 "yyyy-MM-dd", 예 "2019-03-23"
  • year_month / strict_year_month: 네 자리 연도와 두 자리 월. 패턴 "yyyy-MM", 예 "2019-03"
  • year / strict_year: 네 자리 연도. 패턴 "yyyy", 예 "2019"
  • rfc3339_lenient: RFC3339 호환 DateTimeFormatter로, strict_date_optional_time 같은 다른 전체 날짜 관대 형식보다 훨씬 빠르게 동작해요. 예: "YYYY" → "2019", "YYYY-MM" → "2019-03", "YYYY-MM-DD" → "2019-03-23", "YYYY-MM-DDThh:mmTZD" → "2019-03-23T21:34Z", "YYYY-MM-DDThh:mm:ssTZD" → "2019-03-23T21:34:46Z", "YYYY-MM-DDThh:mm:ss.sTZD" → "2019-03-23T21:34:46.123456789-04:00", "YYYY-MM-DDThh:mm:ss,sTZD" → "2019-03-23T21:34:46,123456789-04:00"
  • time / strict_time: 두 자리 시, 분, 초, 1~9자리 초의 소수 부분, 시간대 오프셋. 패턴 "HH:mm:ss.SSSSSSSSSZ", 예 "21:34:46.123456789-04:00", "21:34:46.1-04:00"
  • time_no_millis / strict_time_no_millis: 두 자리 시, 분, 초, 시간대 오프셋. 패턴 "HH:mm:ssZ", 예 "21:34:46-04:00"
  • hour_minute_second_fraction / strict_hour_minute_second_fraction: 두 자리 시, 분, 초, 1~9자리 초의 소수 부분. 패턴 "HH:mm:ss.SSSSSSSSS", 예 "21:34:46.1", "21:34:46.123456789"
  • hour_minute_second_millis / strict_hour_minute_second_millis: 두 자리 시, 분, 초, 세 자리 밀리초. 패턴 "HH:mm:ss.SSS", 예 "21:34:46.123"
  • hour_minute_second / strict_hour_minute_second: 두 자리 시, 분, 초. 패턴 "HH:mm:ss", 예 "21:34:46"
  • hour_minute / strict_hour_minute: 두 자리 시와 두 자리 분. 패턴 "HH:mm", 예 "21:34"
  • hour / strict_hour: 두 자리 시. 패턴 "HH", 예 "21"
  • t_time / strict_t_time: 두 자리 시, 분, 초, 1~9자리 초의 소수 부분, 시간대 오프셋, T가 앞에 옴. 패턴 "THH:mm:ss.SSSSSSSSSZ", 예 "T21:34:46.123456789-04:00", "T21:34:46.1-04:00"
  • t_time_no_millis / strict_t_time_no_millis: 두 자리 시, 분, 초, 시간대 오프셋, T가 앞에 옴. 패턴 "THH:mm:ssZ", 예 "T21:34:46-04:00"
  • ordinal_date_time / strict_ordinal_date_time: T로 구분된 전체 서수 날짜와 시간. 패턴 "yyyy-DDDTHH:mm:ss.SSSZ", 예 "2019-082T21:34:46.123-04:00"
  • ordinal_date_time_no_millis / strict_ordinal_date_time_no_millis: 밀리초가 없는 전체 서수 날짜와 시간, T로 구분. 패턴 "yyyy-DDDTHH:mm:ssZ", 예 "2019-082T21:34:46-04:00"
  • ordinal_date / strict_ordinal_date: 네 자리 연도와 세 자리 서수 일로 된 전체 서수 날짜. 패턴 "yyyy-DDD", 예 "2019-082"
  • week_date_time / strict_week_date_time: T로 구분된 전체 주 기반 날짜와 시간. 주 날짜는 네 자리 주 기반 연도, 두 자리 주, 한 자리 요일로 구성돼요. 시간은 두 자리 시, 분, 초, 1~9자리 초의 소수 부분, 시간대 오프셋이에요. 패턴 "YYYY-Www-eTHH:mm:ss.SSSSSSSSSZ", 예 "2019-W12-6T21:34:46.1-04:00", "2019-W12-6T21:34:46.123456789-04:00"
  • week_date_time_no_millis / strict_week_date_time_no_millis: 밀리초가 없는 전체 주 기반 날짜와 시간, T로 구분. 주 날짜는 네 자리 주 기반 연도, 두 자리 주, 한 자리 요일로 구성돼요. 시간은 두 자리 시, 분, 초, 시간대 오프셋이에요. 패턴 "YYYY-Www-eTHH:mm:ssZ", 예 "2019-W12-6T21:34:46-04:00"
  • week_date / strict_week_date: 네 자리 주 기반 연도, 두 자리 주, 한 자리 요일로 된 전체 주 기반 날짜. 패턴 "YYYY-Www-e", 예 "2019-W12-6"
  • weekyear_week_day / strict_weekyear_week_day: 네 자리 주 기반 연도, 두 자리 주, 한 자리 요일. 패턴 "YYYY-'W'ww-e", 예 "2019-W12-6"
  • weekyear_week / strict_weekyear_week: 네 자리 주 기반 연도와 두 자리 주. 패턴 "YYYY-Www", 예 "2019-W12"
  • weekyear / strict_weekyear: 네 자리 주 기반 연도. 패턴 "YYYY", 예 "2019"

사용자 정의 형식

date 필드에 대한 사용자 정의 형식을 만들 수 있어요. 예를 들어 다음 요청은 일반적인 "MM/dd/yyyy" 형식의 날짜를 지정해요.

PUT testindex
{
  "mappings" : {
    "properties" :  {
      "release_date" : {
        "type" : "date",
        "format" : "MM/dd/yyyy"
      }
    }
  }
}

날짜가 있는 문서를 색인해요.

PUT testindex/_doc/21 
{
  "release_date" : "03/21/2019"
}

정확한 날짜를 검색할 때는 해당 날짜를 같은 형식으로 제공해요.

GET testindex/_search
{
  "query" : {
    "match": {
      "release_date" : {
        "query": "03/21/2019"
      }
    }
  }
}

범위 쿼리는 기본적으로 필드의 매핑된 형식을 사용해요. format 파라미터를 제공해 다른 형식으로 날짜 범위를 지정할 수도 있어요.

GET testindex/_search
{
  "query": {
    "range": {
      "release_date": {
        "gte": "2019-01-01",
        "lte": "2019-12-31",
        "format": "yyyy-MM-dd"
      }
    }
  }
}

날짜 수학 (Date math)

date 필드 타입은 쿼리에서 기간을 지정할 때 날짜 수학을 사용하는 것을 지원해요. 예를 들어 범위 쿼리의 gt, gte, lt, lte 파라미터와 date range 집계의 from, to 파라미터는 날짜 수학 표현식을 받아들여요.

날짜 수학 표현식은 고정 날짜와, 선택적으로 하나 이상의 수학 표현식을 포함해요. 고정 날짜는 now(epoch 이후 밀리초로 표시한 현재 날짜와 시간)이거나 ||로 끝나는 문자열(예: 2022-05-18||)일 수 있어요. 날짜는 기본 형식(기본적으로 strict_date_time_no_millis||strict_date_optional_time||epoch_millis)이어야 해요.

필드 매핑에 여러 날짜 형식을 지정하면 OpenSearch는 첫 번째 형식을 사용해 epoch 이후 밀리초 값을 문자열로 변환해요.

필드에 대한 매핑에 형식이 없으면 OpenSearch는 strict_date_optional_time 형식을 사용해 epoch 값을 문자열로 변환해요.

날짜 수학은 다음 수학 연산자를 지원해요.

연산자 설명 예
+ 더하기 +1M: 1개월 더하기
- 빼기 -1y: 1년 빼기
/ 내림 반올림 /h: 시간의 시작으로 반올림

날짜 수학은 다음 시간 단위를 지원해요.

  • y: 연도
  • M: 월
  • w: 주
  • d: 일
  • h 또는 H: 시간
  • m: 분
  • s: 초
예시 표현식

다음 예시 표현식은 날짜 수학 사용법을 보여줘요.

  • now+1M: epoch 이후 밀리초로 표시한 현재 날짜와 시간에 1개월을 더한 값.
  • 2022-05-18||/M: 05/18/2022를 월의 시작으로 반올림. 2022-05-01로 해석돼요.
  • 2022-05-18T15:23||/h: 05/18/2022의 15:23을 시간의 시작으로 반올림. 2022-05-18T15로 해석돼요.
  • 2022-05-18T15:23:17.789||+2M-1d/d: 05/18/2022의 15:23:17.789에 2개월을 더하고 1일을 뺀 값을 일의 시작으로 반올림. 2022-07-17로 해석돼요.
범위 쿼리에서 날짜 수학 사용

다음 예제는 범위 쿼리에서 날짜 수학을 사용하는 방법을 보여줘요.

release_date가 date로 매핑된 인덱스를 설정해요.

PUT testindex 
{
  "mappings" : {
    "properties" :  {
      "release_date" : {
        "type" : "date"
      }
    }
  }
}

인덱스에 두 문서를 색인해요.

PUT testindex/_doc/1
{
  "release_date": "2022-09-14"
}

PUT testindex/_doc/2
{
  "release_date": "2022-11-15"
}

다음 쿼리는 09/14/2022로부터 2개월 1일 이내에 있는 release_date를 가진 문서를 검색해요. 범위의 하한 경계는 09/14/2022의 일 시작으로 반올림돼요.

GET testindex/_search
{
  "query": {
    "range": {
      "release_date": {
        "gte": "2022-09-14T15:23||/d",
        "lte": "2022-09-14||+2M+1d"
      }
    }
  }
}

응답에는 두 문서가 모두 포함돼요.

{
  "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"
        }
      }
    ]
  }
}

파생 소스 (Derived source)

인덱스가 파생 소스를 사용하면 OpenSearch는 소스를 재구성하는 동안 다중 값 date 필드의 값을 정렬할 수 있어요. format 매핑 파라미터 아래에서 ||로 구분된 여러 date 형식을 구성하는 경우, 파생 소스는 첫 번째 제공된 형식의 결과를 반환해요.

파생 소스를 활성화하고 여러 형식으로 date 필드를 구성하는 인덱스를 만들어 볼게요.

PUT sample-index1
{
  "settings": {
    "index": {
      "derived_source": {
        "enabled": true
      }
    }
  },
  "mappings": {
    "properties": {
      "date": {
        "type": "date",
        "format": "strict_date_time_no_millis||strict_date_optional_time||epoch_millis"
      }
    }
  }
}

혼합된 날짜 형식을 가진 문서를 인덱스에 색인해요.

PUT sample-index1/_doc/1
{
  "date": [1758504860, "2025-09-22T00:34", "2025-09-22T01:34:20Z"]
}

OpenSearch가 _source를 재구성한 후 모든 날짜는 strict_date_time_no_millis 형식이에요.

{
  "date": ["1970-01-21T08:28:24Z", "2025-09-22T00:34:00Z", "2025-09-22T01:34:20Z"]
}

출처: 문서

더 알아보기 (Learn more)