类别：

转换函数、日期和时间函数

TO_DATE、DATE

将输入表达式转换为日期：

  • 对于 VARCHAR 表达式，将字符串转换为日期的结果。

  • 对于 TIMESTAMP 表达式，来自时间戳的日期。

  • 对于 VARIANT 表达式：

    • 如果 VARIANT 包含字符串，则执行字符串转换。

    • 如果 VARIANT 包含日期，则日期值将按原样保留。

    • 如果 VARIANT 包含 JSON null 值，则输出为 NULL。

  • 对于 NULL 输入，输出为 NULL。

对于所有其他值，将生成转换错误。

另请参阅：

TRY_TO_DATE

语法

TO_DATE( <string_expr> [, <format> ] )
TO_DATE( <timestamp_expr> )
TO_DATE( '<integer>' )
TO_DATE( <variant_expr> )

DATE( <string_expr> [, <format> ] )
DATE( <timestamp_expr> )
DATE( '<integer>' )
DATE( <variant_expr> )

实参

必填：

其中之一：

string_expr

要从中提取日期的字符串，例如 '2024-01-31'。

timestamp_expr

一个 TIMESTAMP 表达式。提取 DATE 中的 TIMESTAMP 值部分。

'integer'

计算结果为包含整型的字符串的表达式。例如：'15000000'。根据字符串的大小，它可以解释为秒、毫秒、微秒或纳秒。有关详细信息，请参阅此函数的 用法说明。

variant_expr

类型 VARIANT 的表达式。

VARIANT 必须包含以下内容之一：

  • 要从中提取日期的字符串。

  • 一个日期。

  • 一个字符串，包含一个表示秒数或毫秒数的整数。

虽然 TO_DATE 接受一个 TIMESTAMP 值，但它不接受 VARIANT 内的 TIMESTAMP 值。

可选：

format

string_expr 或 AUTO 的日期格式说明符，用于指定 Snowflake 自动检测要使用的格式。有关更多信息，请参阅 转换函数中的日期和时间格式。

默认值为 DATE_INPUT_FORMAT 会话参数的当前值（默认为 AUTO）。

返回

返回值的数据类型是 DATE。如果输入为 NULL，则返回 NULL。

使用说明

  • 输出中日期的显示格式由 DATE_OUTPUT_FORMAT 会话参数（默认为 YYYY-MM-DD）确定。

  • 如果输入参数的格式是包含整数的字符串：

    • 将字符串转换为整数后，该整数被视为自 Unix 纪元时间 (1970-01-01 00:00:00.000000000 UTC) 开始后的秒数、毫秒数、微秒数或纳秒数。

      • 如果整数小于 31536000000（一年中的毫秒数），则该值被视为秒数。

      • 如果该值大于或等于 31536000000 且小于 31536000000000，则该值被视为毫秒数。

      • 如果该值大于或等于 31536000000000 且小于 31536000000000000，则该值被视为微秒数。

      • 如果该值大于或等于 31536000000000000，则该值被视为纳秒数。

    • 如果评估多行（例如，如果输入内容是包含多行的表的列名），则每个值都将单独得到检查，以确定该值表示的是秒数、毫秒数、微秒数还是纳秒数。

示例

以下示例使用 TO_DATE 和 DATE 函数。

基本示例

SELECT TO_DATE('2024-05-10'), DATE('2024-05-10');

+-----------------------+--------------------+
| TO_DATE('2024-05-10') | DATE('2024-05-10') |
|-----------------------+--------------------|
| 2024-05-10            | 2024-05-10         |
+-----------------------+--------------------+

从时间戳中提取日期的示例

TO_DATE 函数接受 TIMESTAMP 格式中的 TIMESTAMP 值甚至字符串，但丢弃时间信息（小时、分钟等）。

创建并加载表：

CREATE OR REPLACE TABLE date_from_timestamp(ts TIMESTAMP);

INSERT INTO date_from_timestamp(ts)
  VALUES (TO_TIMESTAMP('2024.10.02 04:00:00', 'YYYY.MM.DD HH:MI:SS'));

查询表中的 TIMESTAMP 值：

SELECT ts FROM date_from_timestamp;

+-------------------------+
| TS                      |
|-------------------------|
| 2024-10-02 04:00:00.000 |
+-------------------------+

使用 TO_DATE 函数查询表中的 TIMESTAMP 值：

SELECT TO_DATE(ts) FROM date_from_timestamp;

+-------------+
| TO_DATE(TS) |
|-------------|
| 2024-10-02  |
+-------------+

使用不同输入格式的示例

下面的示例通过不同的输入格式规范使用 TO_DATE 和 DATE 函数。返回输出中的日期格式由 DATE_OUTPUT_FORMAT 会话参数的设置决定。

SELECT TO_DATE('2024.05.10', 'YYYY.MM.DD'), DATE('2024.05.10', 'YYYY.MM.DD');

+-------------------------------------+----------------------------------+
| TO_DATE('2024.05.10', 'YYYY.MM.DD') | DATE('2024.05.10', 'YYYY.MM.DD') |
|-------------------------------------+----------------------------------|
| 2024-05-10                          | 2024-05-10                       |
+-------------------------------------+----------------------------------+

SELECT TO_DATE('2024-05-10', 'AUTO'), DATE('2024-05-10', 'AUTO');

+-------------------------------+----------------------------+
| TO_DATE('2024-05-10', 'AUTO') | DATE('2024-05-10', 'AUTO') |
|-------------------------------+----------------------------|
| 2024-05-10                    | 2024-05-10                 |
+-------------------------------+----------------------------+

SELECT TO_DATE('05/10/2024', 'MM/DD/YYYY'), DATE('05/10/2024', 'MM/DD/YYYY');

+-------------------------------------+----------------------------------+
| TO_DATE('05/10/2024', 'MM/DD/YYYY') | DATE('05/20/2024', 'MM/DD/YYYY') |
|-------------------------------------+----------------------------------|
| 2024-05-10                          | 2024-05-20                       |
+-------------------------------------+----------------------------------+

使用不同输出格式的示例

以下示例显示了以下情况下的查询结果：DATE_OUTPUT_FORMAT 会话参数设置为 DD-MON-YYYY：

ALTER SESSION SET DATE_OUTPUT_FORMAT = 'DD-MON-YYYY';

SELECT TO_DATE('2024-05-10', 'YYYY-MM-DD'), DATE('2024-05-10', 'YYYY-MM-DD');

+-------------------------------------+----------------------------------+
| TO_DATE('2024-05-10', 'YYYY-MM-DD') | DATE('2024-05-10', 'YYYY-MM-DD') |
|-------------------------------------+----------------------------------|
| 10-May-2024                         | 10-May-2024                      |
+-------------------------------------+----------------------------------+

SELECT TO_DATE('05/10/2024', 'MM/DD/YYYY'), DATE('05/10/2024', 'MM/DD/YYYY');

+-------------------------------------+----------------------------------+
| TO_DATE('05/10/2024', 'MM/DD/YYYY') | DATE('05/10/2024', 'MM/DD/YYYY') |
|-------------------------------------+----------------------------------|
| 10-May-2024                         | 10-May-2024                      |
+-------------------------------------+----------------------------------+

使用包含整数的字符串的示例

当输入是包含整数的字符串时，该整数的大小会影响它是会被解释为秒还是毫秒等。以下示例显示了函数如何根据值的大小选择要使用的单位（秒、毫秒、微秒或纳秒）。

创建并加载表：

CREATE OR REPLACE TABLE demo1 (
  description VARCHAR,
  value VARCHAR -- string rather than bigint
);

INSERT INTO demo1 (description, value) VALUES
  ('Seconds',      '31536000'),
  ('Milliseconds', '31536000000'),
  ('Microseconds', '31536000000000'),
  ('Nanoseconds',  '31536000000000000');

将字符串传递给函数：

SELECT description,
       value,
       TO_TIMESTAMP(value),
       TO_DATE(value)
  FROM demo1
  ORDER BY value;

+--------------+-------------------+-------------------------+----------------+
| DESCRIPTION  | VALUE             | TO_TIMESTAMP(VALUE)     | TO_DATE(VALUE) |
|--------------+-------------------+-------------------------+----------------|
| Seconds      | 31536000          | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Milliseconds | 31536000000       | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Microseconds | 31536000000000    | 1971-01-01 00:00:00.000 | 1971-01-01     |
| Nanoseconds  | 31536000000000000 | 1971-01-01 00:00:00.000 | 1971-01-01     |
+--------------+-------------------+-------------------------+----------------+