Package org.apache.flink.table.utils

Class 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.

    • 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)

      • parseDate

        public static int parseDate​(String dateStr,
                            String fromFormat)
        Returns the epoch days since 1970-01-01.

      • formatTimestampMillis

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

      • formatTimestampStringWithOffset

        public static String formatTimestampStringWithOffset​(String dateStr,
                                                     String fromFormat,
                                                     String toFormat,
                                                     TimeZone tz,
                                                     long offsetMills)

      • 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)

      • formatIntervalDayTime

        public static String formatIntervalDayTime​(long v)

      • 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.

      • 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)

      • 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)