org.apache.flink.table.utils

Class DateTimeUtils

java.lang.Object

org.apache.flink.table.utils.DateTimeUtils

@Internal
public class DateTimeUtils
extends Object

Utility functions for datetime types: date, time, timestamp.

These utils include:

• parse[type]: methods for parsing strings to date/time/timestamp
• format[type]: methods for formatting date/time/timestamp
• to[externalTypeName] and toInternal: methods for converting values from internal date/time/timestamp types from/to java.sql or java.time types
• Various operations on timestamp, including floor, ceil and extract
• DateTimeUtils.TimeUnit and DateTimeUtils.TimeUnitRange enums

Currently, this class is a bit messy because it includes a mix of functionalities both from common and planner. We should strive to reduce the number of functionalities here, eventually moving some methods closer to where they're needed. Connectors and formats should not use this class, but rather if a functionality is necessary, it should be part of the public APIs of our type system (e.g a new method in TimestampData or in TimestampType). Methods used only by the planner should live inside the planner whenever is possible.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	DateTimeUtils.TimeUnit Enumeration of time units used to construct an interval.
static class	DateTimeUtils.TimeUnitRange A range of time units.

Field Summary

Fields

Modifier and Type	Field and Description
static int	EPOCH_JULIAN The julian date of the epoch, 1970-01-01.
static TimeZone	LOCAL_TZ The local time zone.
static long	MILLIS_PER_DAY The number of milliseconds in a day.
static TimeZone	UTC_ZONE The UTC time zone.

Constructor Summary

Constructors

Constructor and Description
DateTimeUtils()

Method Summary

Modifier and Type	Method and Description
static int	addMonths(int date, int m) Adds a given number of months to a date, represented as the number of days since the epoch.
static long	addMonths(long timestamp, int m) Adds a given number of months to a timestamp, represented as the number of milliseconds since the epoch.
static String	convertTz(String dateStr, String tzFrom, String tzTo) Convert datetime string from a time zone to another time zone.
static TimestampData	dateToTimestampWithLocalZone(int date, TimeZone tz)
static long	extractFromDate(DateTimeUtils.TimeUnitRange range, int date)
static long	extractFromDate(DateTimeUtils.TimeUnitRange range, long date)
static long	extractFromTimestamp(DateTimeUtils.TimeUnitRange range, TimestampData ts, TimeZone tz)
static String	formatDate(int date) Helper for CAST({date} AS VARCHAR(n)).
static String	formatIntervalDayTime(long v)
static String	formatIntervalYearMonth(int v)
static String	formatTimestamp(TimestampData ts, String format)
static String	formatTimestamp(TimestampData ts, String format, TimeZone zone)
static String	formatTimestamp(TimestampData ts, TimeZone tz, int precision)
static String	formatTimestampMillis(int time, int precision)
static String	formatTimestampMillis(long ts, String format, TimeZone tz)
static String	formatTimestampString(String dateStr, String toFormat)
static String	formatTimestampString(String dateStr, String fromFormat, String toFormat, TimeZone tz)
static String	formatTimestampString(String dateStr, String toFormat, TimeZone tz)
static String	formatUnixTimestamp(long unixtime, String format, TimeZone tz) Convert unix timestamp (seconds since '1970-01-01 00:00:00' UTC) to datetime string in the given format.
static String	formatUnixTimestamp(long unixtime, TimeZone tz) Convert unix timestamp (seconds since '1970-01-01 00:00:00' UTC) to datetime string in the "yyyy-MM-dd HH:mm:ss" format.
static long	fromTimestamp(long ts)
static StringBuilder	number(StringBuilder buf, int v, int n)
static Integer	parseDate(String s)
static int	parseDate(String dateStr, String fromFormat) Returns the epoch days since 1970-01-01.
static Integer	parseTime(String v)
static TimestampData	parseTimestampData(String dateStr)
static TimestampData	parseTimestampData(String dateStr, int precision)
static TimestampData	parseTimestampData(String dateStr, int precision, TimeZone timeZone)
static TimestampData	parseTimestampData(String dateStr, String format)
static int	subtractMonths(int date0, int date1) Finds the number of months between two dates, each represented as the number of days since the epoch.
static int	subtractMonths(long t0, long t1)
static long	timestampCeil(DateTimeUtils.TimeUnitRange range, long ts, TimeZone tz) Keep the algorithm consistent with Calcite DateTimeUtils.julianDateFloor, but here we take time zone into account.
static long	timestampFloor(DateTimeUtils.TimeUnitRange range, long ts, TimeZone tz)
static int	timestampMillisToDate(long ts) Get date from a timestamp.
static int	timestampMillisToTime(long ts) Get time from a timestamp.
static TimestampData	timestampToTimestampWithLocalZone(TimestampData ts, TimeZone tz)
static int	timestampWithLocalZoneToDate(TimestampData ts, TimeZone tz)
static int	timestampWithLocalZoneToTime(TimestampData ts, TimeZone tz)
static TimestampData	timestampWithLocalZoneToTimestamp(TimestampData ts, TimeZone tz)
static TimestampData	timeToTimestampWithLocalZone(int time, TimeZone tz)
static int	toInternal(Date date) Converts the Java type used for UDF parameters of SQL DATE type (Date) to internal representation (int).
static int	toInternal(LocalDate date)
static int	toInternal(LocalTime time)
static int	toInternal(Time time) Converts the Java type used for UDF parameters of SQL TIME type (Time) to internal representation (int).
static long	toInternal(Timestamp ts) Converts the Java type used for UDF parameters of SQL TIMESTAMP type (Timestamp) to internal representation (long).
static LocalDate	toLocalDate(int date)
static LocalDateTime	toLocalDateTime(long timestamp)
static LocalTime	toLocalTime(int time)
static Date	toSQLDate(int v) Converts the internal representation of a SQL DATE (int) to the Java type used for UDF parameters (Date).
static Time	toSQLTime(int v) Converts the internal representation of a SQL TIME (int) to the Java type used for UDF parameters (Time).
static Timestamp	toSQLTimestamp(long v) Converts the internal representation of a SQL TIMESTAMP (long) to the Java type used for UDF parameters (Timestamp).
static TimestampData	toTimestampData(DecimalData v, int precision)
static TimestampData	toTimestampData(double v, int precision)
static TimestampData	toTimestampData(long v, int precision)
static long	toTimestampMillis(LocalDateTime dateTime)
static TimestampData	truncate(TimestampData ts, int precision)
static long	unixDateCeil(DateTimeUtils.TimeUnitRange range, long date)
static long	unixDateFloor(DateTimeUtils.TimeUnitRange range, long date)
static long	unixTimestamp() Returns a Unix timestamp in seconds since '1970-01-01 00:00:00' UTC as an unsigned integer.
static long	unixTimestamp(long ts) Returns the value of the timestamp to seconds since '1970-01-01 00:00:00' UTC.
static long	unixTimestamp(String dateStr, String format, TimeZone tz) Returns the value of the argument as an unsigned integer in seconds since '1970-01-01 00:00:00' UTC.
static long	unixTimestamp(String dateStr, TimeZone tz) Returns the value of the argument as an unsigned integer in seconds since '1970-01-01 00:00:00' UTC.
static long	unixTimestampCeil(DateTimeUtils.TimeUnitRange range, long timestamp)
static long	unixTimestampFloor(DateTimeUtils.TimeUnitRange range, long timestamp)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

EPOCH_JULIAN

public static final int EPOCH_JULIAN

The julian date of the epoch, 1970-01-01.

See Also:

Constant Field Values

MILLIS_PER_DAY

public static final long MILLIS_PER_DAY

The number of milliseconds in a day.

This is the modulo 'mask' used when converting TIMESTAMP values to DATE and TIME values.

See Also:

Constant Field Values

UTC_ZONE

public static final TimeZone UTC_ZONE

The UTC time zone.

LOCAL_TZ

public static final TimeZone LOCAL_TZ

The local time zone.

Constructor Detail

DateTimeUtils

public DateTimeUtils()

Method Detail

toSQLDate

public static Date toSQLDate(int v)

Converts the internal representation of a SQL DATE (int) to the Java type used for UDF parameters (Date).

toSQLTime

public static Time toSQLTime(int v)

Converts the internal representation of a SQL TIME (int) to the Java type used for UDF parameters (Time).

toSQLTimestamp

public static Timestamp toSQLTimestamp(long v)

Converts the internal representation of a SQL TIMESTAMP (long) to the Java type used for UDF parameters (Timestamp).

toInternal

public static int toInternal(Date date)

Converts the Java type used for UDF parameters of SQL DATE type (Date) to internal representation (int).

Converse of toSQLDate(int).

toInternal

public static int toInternal(Time time)

Converts the Java type used for UDF parameters of SQL TIME type (Time) to internal representation (int).

Converse of toSQLTime(int).

toInternal

public static long toInternal(Timestamp ts)

Converts the Java type used for UDF parameters of SQL TIMESTAMP type (Timestamp) to internal representation (long).

Converse of toSQLTimestamp(long).

toLocalDate

public static LocalDate toLocalDate(int date)

toInternal

public static int toInternal(LocalDate date)

toLocalTime

public static LocalTime toLocalTime(int time)

toInternal

public static int toInternal(LocalTime time)

toLocalDateTime

public static LocalDateTime toLocalDateTime(long timestamp)

toTimestampMillis

public static long toTimestampMillis(LocalDateTime dateTime)

toTimestampData

public static TimestampData toTimestampData(long v,
                                            int precision)

toTimestampData

public static TimestampData toTimestampData(double v,
                                            int precision)

toTimestampData

public static TimestampData toTimestampData(DecimalData v,
                                            int precision)

parseTimestampData

public static TimestampData parseTimestampData(String dateStr)
                                        throws DateTimeException

Throws:

DateTimeException

parseTimestampData

public static TimestampData parseTimestampData(String dateStr,
                                               int precision)
                                        throws DateTimeException

Throws:

DateTimeException

parseTimestampData

public static TimestampData parseTimestampData(String dateStr,
                                               int precision,
                                               TimeZone timeZone)
                                        throws DateTimeException

Throws:

DateTimeException

parseTimestampData

public static TimestampData parseTimestampData(String dateStr,
                                               String format)

parseDate

public static int parseDate(String dateStr,
                            String fromFormat)

Returns the epoch days since 1970-01-01.

parseDate

public static Integer parseDate(String s)

parseTime

public static Integer parseTime(String v)

formatTimestamp

public static String formatTimestamp(TimestampData ts,
                                     String format)

formatTimestamp

public static String formatTimestamp(TimestampData ts,
                                     String format,
                                     TimeZone zone)

formatTimestamp

public static String formatTimestamp(TimestampData ts,
                                     TimeZone tz,
                                     int precision)

formatTimestampMillis

public static String formatTimestampMillis(long ts,
                                           String format,
                                           TimeZone tz)

formatTimestampString

public static String formatTimestampString(String dateStr,
                                           String fromFormat,
                                           String toFormat,
                                           TimeZone tz)

formatTimestampString

public static String formatTimestampString(String dateStr,
                                           String toFormat,
                                           TimeZone tz)

formatTimestampString

public static String formatTimestampString(String dateStr,
                                           String toFormat)

formatTimestampMillis

public static String formatTimestampMillis(int time,
                                           int precision)

formatDate

public static String formatDate(int date)

Helper for CAST({date} AS VARCHAR(n)).

formatIntervalYearMonth

public static String formatIntervalYearMonth(int v)

number

public static StringBuilder number(StringBuilder buf,
                                   int v,
                                   int n)

formatIntervalDayTime

public static String formatIntervalDayTime(long v)

extractFromTimestamp

public static long extractFromTimestamp(DateTimeUtils.TimeUnitRange range,
                                        TimestampData ts,
                                        TimeZone tz)

extractFromDate

public static long extractFromDate(DateTimeUtils.TimeUnitRange range,
                                   long date)

extractFromDate

public static long extractFromDate(DateTimeUtils.TimeUnitRange range,
                                   int date)

timestampFloor

public static long timestampFloor(DateTimeUtils.TimeUnitRange range,
                                  long ts,
                                  TimeZone tz)

timestampCeil

public static long timestampCeil(DateTimeUtils.TimeUnitRange range,
                                 long ts,
                                 TimeZone tz)

Keep the algorithm consistent with Calcite DateTimeUtils.julianDateFloor, but here we take time zone into account.

convertTz

public static String convertTz(String dateStr,
                               String tzFrom,
                               String tzTo)

Convert datetime string from a time zone to another time zone.

Parameters:

dateStr - the date time string

tzFrom - the original time zone

tzTo - the target time zone

timestampMillisToDate

public static int timestampMillisToDate(long ts)

Get date from a timestamp.

Parameters:

ts - the timestamp in milliseconds.

Returns:

the date in days.

timestampMillisToTime

public static int timestampMillisToTime(long ts)

Get time from a timestamp.

Parameters:

ts - the timestamp in milliseconds.

Returns:

the time in milliseconds.

fromTimestamp

public static long fromTimestamp(long ts)

formatUnixTimestamp

public static String formatUnixTimestamp(long unixtime,
                                         TimeZone tz)

Convert unix timestamp (seconds since '1970-01-01 00:00:00' UTC) to datetime string in the "yyyy-MM-dd HH:mm:ss" format.

formatUnixTimestamp

public static String formatUnixTimestamp(long unixtime,
                                         String format,
                                         TimeZone tz)

Convert unix timestamp (seconds since '1970-01-01 00:00:00' UTC) to datetime string in the given format.

unixTimestamp

public static long unixTimestamp()

Returns a Unix timestamp in seconds since '1970-01-01 00:00:00' UTC as an unsigned integer.

unixTimestamp

public static long unixTimestamp(long ts)

Returns the value of the timestamp to seconds since '1970-01-01 00:00:00' UTC.

unixTimestamp

public static long unixTimestamp(String dateStr,
                                 TimeZone tz)

Returns the value of the argument as an unsigned integer in seconds since '1970-01-01 00:00:00' UTC.

unixTimestamp

public static long unixTimestamp(String dateStr,
                                 String format,
                                 TimeZone tz)

Returns the value of the argument as an unsigned integer in seconds since '1970-01-01 00:00:00' UTC.

timestampToTimestampWithLocalZone

public static TimestampData timestampToTimestampWithLocalZone(TimestampData ts,
                                                              TimeZone tz)

timestampWithLocalZoneToTimestamp

public static TimestampData timestampWithLocalZoneToTimestamp(TimestampData ts,
                                                              TimeZone tz)

timestampWithLocalZoneToDate

public static int timestampWithLocalZoneToDate(TimestampData ts,
                                               TimeZone tz)

timestampWithLocalZoneToTime

public static int timestampWithLocalZoneToTime(TimestampData ts,
                                               TimeZone tz)

dateToTimestampWithLocalZone

public static TimestampData dateToTimestampWithLocalZone(int date,
                                                         TimeZone tz)

timeToTimestampWithLocalZone

public static TimestampData timeToTimestampWithLocalZone(int time,
                                                         TimeZone tz)

truncate

public static TimestampData truncate(TimestampData ts,
                                     int precision)

unixDateCeil

public static long unixDateCeil(DateTimeUtils.TimeUnitRange range,
                                long date)

unixDateFloor

public static long unixDateFloor(DateTimeUtils.TimeUnitRange range,
                                 long date)

unixTimestampFloor

public static long unixTimestampFloor(DateTimeUtils.TimeUnitRange range,
                                      long timestamp)

unixTimestampCeil

public static long unixTimestampCeil(DateTimeUtils.TimeUnitRange range,
                                     long timestamp)

addMonths

public static long addMonths(long timestamp,
                             int m)

Adds a given number of months to a timestamp, represented as the number of milliseconds since the epoch.

addMonths

public static int addMonths(int date,
                            int m)

Adds a given number of months to a date, represented as the number of days since the epoch.

subtractMonths

public static int subtractMonths(int date0,
                                 int date1)

Finds the number of months between two dates, each represented as the number of days since the epoch.

subtractMonths

public static int subtractMonths(long t0,
                                 long t1)