> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-trino-dialect.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ClickHouse 中 DateTime64 数据类型的文档，该类型存储具有子秒级精度的时间戳

# DateTime64

可存储一个时间点，以日历日期和一天中的时间表示，并具有指定的子秒级精度

时间粒度 (精度) ：10<sup>-precision</sup> 秒。有效范围：\[ 0 : 9 ]。
通常使用 3 (毫秒) 、6 (微秒) 和 9 (纳秒) 。

**语法：**

```sql theme={null}
DateTime64(precision, [timezone])
```

在内部，它将数据存储为自纪元开始 (1970-01-01 00:00:00 UTC) 以来的若干个 'ticks'，类型为 Int64。tick 的分辨率由 精度 参数决定。此外，`DateTime64` 类型还可以存储整个列统一的 时区，这会影响 `DateTime64` 类型的值以文本 format 显示的方式，以及将字符串形式指定的值 ('2020-01-01 05:00:01.000') parse 的方式。时区 不存储在表的行中 (或结果集中) ，而是存储在列元数据中。详见 [DateTime](/zh/reference/data-types/datetime)。

支持的值范围：\[0000-01-01 00:00:00, 9999-12-31 23:59:59.999999999]

小数点后的位数取决于 精度 参数。

注意：上述完整范围适用于最高 7 的精度。由于 ticks 存储在 `Int64` 中，更高的精度会覆盖更窄的范围：当精度为 8 时，最大值约为 `4892-10-07`；当使用 9 位数字 (纳秒) 的最大精度时，UTC 中支持的范围为 `1677-09-21 00:12:44` 到 `2262-04-11 23:47:16`。

<div id="examples">
  ## 示例
</div>

1. 创建一个包含 `DateTime64` 类型列的表，并向其中插入数据：

```sql theme={null}
CREATE TABLE dt64
(
    `timestamp` DateTime64(3, 'Asia/Istanbul'),
    `event_id` UInt8
)
ENGINE = MergeTree;
```

```sql theme={null}
-- Parse DateTime64
-- - from an integer interpreted as the number of seconds since 1970-01-01 (like DateTime),
-- - from a decimal interpreted as the number of seconds, the fractional part giving sub-second precision,
-- - from a string.

INSERT INTO dt64
VALUES
(1546300800, 1),
(1546300800.123, 2),
('2019-01-01 00:00:00', 3);

SELECT * FROM dt64;
```

```text theme={null}
┌───────────────timestamp─┬─event_id─┐
│ 2019-01-01 03:00:00.000 │        1 │
│ 2019-01-01 03:00:00.123 │        2 │
│ 2019-01-01 00:00:00.000 │        3 │
└─────────────────────────┴──────────┘
```

* 以数值形式插入 datetime 时，会像 `DateTime` 一样将其视为以秒为单位的 Unix 时间戳 (UTC) 。`1546300800` 表示 UTC 的 `'2019-01-01 00:00:00'`。但由于 `timestamp` 列指定了 `Asia/Istanbul` (UTC+3) 时区，因此以字符串形式输出时，该值会显示为 `'2019-01-01 03:00:00'`。插入带小数部分的数值时，处理方式相同：小数点前的部分是以秒为单位的 Unix 时间戳，小数点后的部分则根据列的精度提供子秒级精度。 (在 26.8 版本之前，`JSON` 和 `Values`/`Quoted` 输入路径中的无引号整数——后者涵盖所有使用 `Quoted` 转义规则解析字段的格式：`Values`、`MySQLDump`，以及配置了 `Quoted` 字段转义的 `Template`/`CustomSeparated`/`Regexp`——会被解释为列精度下的原始底层值，因此精度为 3 时，`1546300800000` 表示 `'2019-01-01 00:00:00'`。若要在这些路径中恢复此前的行为，请设置 `input_format_read_datetime_number_as_raw_value = 1` (或 `SET compatibility = '26.7'`) ；这也会影响 `JSONExtract` 函数和 `JSON` 数据类型。兼容性设置仅适用于无引号整数：在 `Values` 格式中，旧版流式 parser 会拒绝带小数部分的数值，随后会回退到 SQL expression 求值并按秒读取——这与 26.8 之前的版本相同。在 `JSONExtract` 和 `JSON` 数据类型中，带小数部分的值会通过 `Float64` 解析，因此位数超过 `Float64` 可保留范围的时间戳可能会舍入为相邻值；而行输入格式会精确解析原始文本。制表符分隔、CSV 及其他转义文本输入格式不受此设置控制，并会保留其对无引号数值的现有解释：较大的值将按 ticks 读取。)
* 以字符串形式插入 datetime 值时，会将其视为采用列时区。`'2019-01-01 00:00:00'` 会被视为采用 `Asia/Istanbul` 时区，并存储为 `1546290000000`。

2. 过滤 `DateTime64` 值

```sql theme={null}
SELECT * FROM dt64 WHERE timestamp = toDateTime64('2019-01-01 00:00:00', 3, 'Asia/Istanbul');
```

```text theme={null}
┌───────────────timestamp─┬─event_id─┐
│ 2019-01-01 00:00:00.000 │        3 │
└─────────────────────────┴──────────┘
```

与 `DateTime` 不同，`DateTime64` 类型的值不会自动由 `String` 转换而来。

```sql theme={null}
SELECT * FROM dt64 WHERE timestamp = toDateTime64(1546300800.123, 3);
```

```text theme={null}
┌───────────────timestamp─┬─event_id─┐
│ 2019-01-01 03:00:00.123 │        1 │
│ 2019-01-01 03:00:00.123 │        2 │
└─────────────────────────┴──────────┘
```

与插入数值时一样，`toDateTime64` 函数会将数值参数视为秒数，因此子秒级精度需在小数点后给出。

3. 获取 `DateTime64` 类型值的时区：

```sql theme={null}
SELECT toDateTime64(now(), 3, 'Asia/Istanbul') AS column, toTypeName(column) AS x;
```

```text theme={null}
┌──────────────────column─┬─x──────────────────────────────┐
│ 2023-06-05 00:09:52.000 │ DateTime64(3, 'Asia/Istanbul') │
└─────────────────────────┴────────────────────────────────┘
```

4. 时区转换

```sql theme={null}
SELECT
toDateTime64(timestamp, 3, 'Europe/London') AS lon_time,
toDateTime64(timestamp, 3, 'Asia/Istanbul') AS istanbul_time
FROM dt64;
```

```text theme={null}
┌────────────────lon_time─┬───────────istanbul_time─┐
│ 2019-01-01 00:00:00.123 │ 2019-01-01 03:00:00.123 │
│ 2019-01-01 00:00:00.123 │ 2019-01-01 03:00:00.123 │
│ 2018-12-31 21:00:00.000 │ 2019-01-01 00:00:00.000 │
└─────────────────────────┴─────────────────────────┘
```

**另请参阅**

* [类型转换函数](/zh/reference/functions/regular-functions/type-conversion-functions)
* [日期和时间函数](/zh/reference/functions/regular-functions/date-time-functions)
* [`date_time_input_format` 设置](/zh/reference/settings/formats/date-time#date_time_input_format)
* [`date_time_output_format` 设置](/zh/reference/settings/formats/date-time#date_time_output_format)
* [`timezone` server 配置参数](/zh/reference/settings/server-settings/settings/other#timezone)
* [`session_timezone` 设置](/zh/reference/settings/session-settings/other#session_timezone)
* [日期和时间运算符](/zh/reference/operators/index#operators-for-working-with-dates-and-times)
* [`Date` 数据类型](/zh/reference/data-types/date)
* [`DateTime` 数据类型](/zh/reference/data-types/datetime)