날짜/시간 포맷팅 및 파싱 패턴

날짜/시간 포맷팅 및 파싱 패턴 (Datetime Patterns for Formatting and Parsing)

Spark에서 날짜와 타임스탬프를 표현하는 패턴 문자열의 규칙을 설명하는 문서예요. CSV/JSON 데이터소스에서 날짜·시간 내용을 파싱하고 포맷할 때, 그리고 문자열과 날짜 타입을 서로 변환하는 함수에서 사용되는 패턴이에요. 패턴 문자 하나하나의 의미와, 글자 수에 따라 달라지는 포맷 규칙을 정리해 드릴게요.

출처: 문서

본문

Spark에서 datetime 사용에 대한 몇 가지 일반적인 시나리오가 있어요:

• CSV/JSON 데이터소스는 패턴 문자열을 사용해 datetime 내용을 파싱하고 포맷해요.
• StringType을 DateType 또는 TimestampType로/에서 변환하는 datetime 함수들이 있어요. 예를 들어 unix_timestamp, date_format, to_unix_timestamp, from_unixtime, to_date, to_timestamp, from_utc_timestamp, to_utc_timestamp 등이 있어요.

Spark는 날짜와 타임스탬프 파싱 및 포맷을 위해 다음 표의 패턴 문자들을 사용해요:

패턴 문자의 개수가 포맷을 결정해요.

• Text: 사용된 패턴 문자의 수에 따라 텍스트 스타일이 결정돼요. 패턴 문자 4개 미만이면 대개 약어인 짧은 텍스트 형태를 사용해요. 예를 들어 day-of-week Monday는 "Mon"으로 출력될 수 있어요. 정확히 4개의 패턴 문자는 대개 전체 설명인 긴 텍스트 형태를 사용해요. 예를 들어 day-of-week Monday는 "Monday"로 출력될 수 있어요. 5개 이상의 문자는 실패해요.
• Number(n): 여기서 n은 이 유형의 datetime 패턴에 사용될 수 있는 문자의 최대 개수를 나타내요.
  • 포맷할 때 문자 수가 1이면 값은 최소 자릿수로, 패딩 없이 출력돼요. 그 외에는 문자 수가 출력 필드의 너비로 사용되고, 값은 필요에 따라 0으로 패딩돼요.
  • 파싱할 때는 입력 필드에 정확한 자릿수가 기대돼요.
• Number/Text: 패턴 문자의 수가 3 이상이면 위의 Text 규칙을 사용해요. 그렇지 않으면 위의 Number 규칙을 사용해요.
• Fraction: 초의 분수를 파싱하고 포맷하기 위해 하나 이상(최대 9개)의 연속된 'S' 문자를 사용해요. 예: SSSSSS. 파싱의 경우 허용 가능한 분수 길이는 [1, 연속된 'S'의 수]예요. 포맷의 경우 분수 길이는 연속된 'S'의 수에 0으로 패딩돼요. Spark는 마이크로초(micro-of-second) 정밀도(최대 6개의 유효 자릿수)의 datetime을 지원하지만, 초과 부분이 잘린 채 나노초(nano-of-second)를 파싱할 수 있어요.
• Year: 문자의 수가 패딩이 사용되는 최소 필드 너비를 결정해요. 문자의 수가 2이면 줄어든 두 자리 형태(reduced two digit form)를 사용해요. 출력의 경우 가장 오른쪽 두 자리를 출력해요. 파싱의 경우 기준 값 2000을 사용해 파싱해서, 2000부터 2099까지(포함) 범위의 연도가 돼요. 문자의 수가 4 미만(2는 제외)이면 음의 연도에 대해서만 부호가 출력돼요. 그 외에는 'G'가 없을 때 패딩 너비를 초과하면 부호가 출력돼요. 7개 이상의 문자는 실패해요.
• Month: Number/Text 규칙을 따르지만, 파싱의 경우 Number/Text 규칙은 Month에 적용되지 않아요. 텍스트 형태는 문자에 따라 달라져요 - 'M'은 'standard' 형태를, 'L'은 'stand-alone' 형태를 나타내요. 이 두 형태는 특정 언어에서만 달라요. 예를 들어 러시아어에서 'Июль'은 7월의 stand-alone 형태이고, 'Июля'는 standard 형태예요. 지원되는 모든 패턴 문자의 예시는 다음과 같아요:

  • 'M' 또는 'L': 1부터 시작하는 연중 월 번호예요. 'M'과 'L' 사이에 차이는 없어요. 1부터 9까지의 월은 패딩 없이 출력돼요.

    spark-sql> select date_format(date '1970-01-01', "M");
    1
    spark-sql> select date_format(date '1970-12-01', "L");
    12
    

  • 'MM' 또는 'LL': 1부터 시작하는 연중 월 번호예요. 1~9월에는 0 패딩이 추가돼요.

      spark-sql> select date_format(date '1970-1-01', "LL");
      01
      spark-sql> select date_format(date '1970-09-01', "MM");
      09
    

  • 'MMM': standard 형태의 짧은 텍스트 표현이에요. 영어처럼 stand와 stand-alone 형태 사이에 차이가 없는 로케일을 제외하고는, 월 패턴은 단독 월이 아니라 날짜 패턴의 일부여야 해요.

    spark-sql> select date_format(date '1970-01-01', "d MMM");
    1 Jan
    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'dd MMM', 'locale', 'RU'));
    01 янв.
    

  • 'LLL': stand-alone 형태의 짧은 텍스트 표현이에요. 다른 날짜 필드 없이 월만 포맷/파싱하는 데 사용해야 해요.

    spark-sql> select date_format(date '1970-01-01', "LLL");
    Jan
    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'LLL', 'locale', 'RU'));
    янв.
    

  • 'MMMM': standard 형태의 전체 텍스트 월 표현이에요. 날짜/타임스탬프의 일부로 월을 파싱/포맷하는 데 사용돼요.

    spark-sql> select date_format(date '1970-01-01', "d MMMM");
    1 January
    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'd MMMM', 'locale', 'RU'));
    1 января
    

  • 'LLLL': stand-alone 형태의 전체 텍스트 월 표현이에요. 이 패턴은 월만 포맷/파싱하는 데 사용할 수 있어요.

    spark-sql> select date_format(date '1970-01-01', "LLLL");
    January
    spark-sql> select to_csv(named_struct('date', date '1970-01-01'), map('dateFormat', 'LLLL', 'locale', 'RU'));
    январь
    

• am-pm: 오전/오후(am-pm-of-day)를 출력해요. 패턴 문자 수는 1이어야 해요.
• Zone ID(V): 시간대 ID를 표시해요. 패턴 문자 수는 2여야 해요.
• Zone names(z): 시간대 ID의 텍스트 이름을 표시해요. 문자 수가 1, 2, 3이면 짧은 이름이 출력돼요. 문자 수가 4이면 전체 이름이 출력돼요. 5개 이상의 문자는 실패해요.
• Offset X와 x: 패턴 문자의 수에 따라 오프셋을 포맷해요. 한 문자는 시간만 출력해요. 예: '+01'. 단, 분이 0이 아니면 분도 출력돼요. 예: '+0130'. 두 문자는 콜론 없이 시간과 분을 출력해요. 예: '+0130'. 세 문자는 콜론과 함께 시간과 분을 출력해요. 예: '+01:30'. 네 문자는 콜론 없이 시간과 분, 선택적 초를 출력해요. 예: '+013015'. 다섯 문자는 콜론과 함께 시간과 분, 선택적 초를 출력해요. 예: '+01:30:15'. 6개 이상의 문자는 실패해요. 패턴 문자 'X'(대문자)는 출력할 오프셋이 0이면 'Z'를 출력하는 반면, 패턴 문자 'x'(소문자)는 '+00', '+0000' 또는 '+00:00'을 출력해요.
• Offset O: 패턴 문자의 수에 따라 지역화된 오프셋을 포맷해요. 한 문자는 지역화된 오프셋의 짧은 형태를 출력해요. 이는 'GMT' 같은 지역화된 오프셋 텍스트로, 앞에 0이 없는 시간, 0이 아니면 선택적 2자리 분과 초, 콜론을 포함해요. 예: 'GMT+8'. 네 문자는 전체 형태를 출력해요. 이는 'GMT' 같은 지역화된 오프셋 텍스트로, 2자리 시간과 분 필드, 0이 아니면 선택적 초 필드, 콜론을 포함해요. 예: 'GMT+08:00'. 다른 문자 수는 실패해요.
• Offset Z: 패턴 문자의 수에 따라 오프셋을 포맷해요. 한, 두, 세 문자는 콜론 없이 시간과 분을 출력해요. 예: '+0130'. 오프셋이 0이면 출력은 '+0000'이 돼요. 네 문자는 Offset-O의 네 문자와 동일한 지역화된 오프셋의 전체 형태를 출력해요. 오프셋이 0이면 출력은 해당하는 지역화된 오프셋 텍스트가 돼요. 다섯 문자는 0이 아니면 선택적 초와 함께 시간과 분을 콜론과 함께 출력해요. 오프셋이 0이면 'Z'를 출력해요. 6개 이상의 문자는 실패해요.
• 선택 구간 시작과 끝 (Optional section start and end): []를 사용해 선택 구간을 정의하고, 중첩할 수도 있어요. 포맷하는 동안 모든 유효한 데이터는 선택 구간에 있어도 출력돼요. 파싱하는 동안 전체 구간이 파싱된 문자열에서 빠져 있을 수 있어요. 선택 구간은 [로 시작하고 ](또는 패턴의 끝)로 끝나요.
• 'E', 'F', 'q', 'Q' 기호는 date_format 같은 datetime 포맷에만 사용할 수 있어요. to_timestamp 같은 datetime 파싱에는 사용할 수 없어요.

더 알아보기 (Learn more)

• 아파치 스파크 SQL 참조 (원문)
• Data Types — 날짜/시간 타입을 포함한 데이터 타입
• ANSI Compliance — ANSI 모드와 타입 변환
• Built-in Functions — 날짜/시간 함수를 포함한 내장 함수