操作分区和数据块

可用的 分区 操作如下

• DETACH PARTITION|PART — 将分区或数据块移动到 detached 目录并将其忽略。
• DROP PARTITION|PART — 删除分区或数据块。
• DROP DETACHED PARTITION|PART - 从 detached 目录删除数据块或分区的全部数据块。
• FORGET PARTITION — 如果分区为空，则从 ZooKeeper 删除分区元数据。
• ATTACH PARTITION|PART — 将 detached 目录中的分区或数据块添加到表中。
• ATTACH PARTITION FROM — 将数据分区从一个表复制到另一个表并添加。
• REPLACE PARTITION — 将数据分区从一个表复制到另一个表并替换。
• MOVE PARTITION TO TABLE — 将数据分区从一个表移动到另一个表。
• CLEAR COLUMN IN PARTITION — 重置分区中指定列的值。
• CLEAR INDEX IN PARTITION — 重置分区中指定的二级索引。
• FREEZE PARTITION — 创建分区的备份。
• UNFREEZE PARTITION — 移除分区的备份。
• FETCH PARTITION|PART — 从另一台服务器下载数据块或分区。
• MOVE PARTITION|PART — 将分区/数据块移动到另一个磁盘或卷。
• UPDATE IN PARTITION — 根据条件更新分区内的的数据。
• DELETE IN PARTITION — 根据条件删除分区内的的数据。
• REWRITE PARTS — 完全重写表（或特定分区）中的数据块。

DETACH PARTITION|PART

ALTER TABLE table_name [ON CLUSTER cluster] DETACH PARTITION|PART partition_expr

将指定分区的所有数据移动到 detached 目录。服务器会忘记分离的数据分区，就像它不存在一样。除非您执行 ATTACH 查询，否则服务器将不知道这些数据。

示例

ALTER TABLE mt DETACH PARTITION '2020-11-21';
ALTER TABLE mt DETACH PART 'all_2_2_0';

请参阅 如何设置分区表达式 部分，了解如何设置分区表达式。

查询执行后，您可以对 detached 目录中的数据执行任何操作——从文件系统中删除它，或者只是保留它。

此查询是复制的——它将数据移动到所有副本上的 detached 目录。请注意，您只能在领导者副本上执行此查询。要确定副本是否为领导者，请对 system.replicas 表执行 SELECT 查询。或者，更容易的方法是在所有副本上执行 DETACH 查询——所有副本都会抛出异常，除了领导者副本（因为允许多个领导者）。

DROP PARTITION|PART

ALTER TABLE table_name [ON CLUSTER cluster] DROP PARTITION|PART partition_expr

从表中删除指定的分区。此查询将分区标记为非活动状态，并在大约 10 分钟内完全删除数据。

请参阅 如何设置分区表达式 部分，了解如何设置分区表达式。

该查询是复制的——它在所有副本上删除数据。

示例

ALTER TABLE mt DROP PARTITION '2020-11-21';
ALTER TABLE mt DROP PART 'all_4_4_0';

DROP DETACHED PARTITION|PART

ALTER TABLE table_name [ON CLUSTER cluster] DROP DETACHED PARTITION|PART ALL|partition_expr

从 detached 目录中删除指定的数据块或指定分区的所有数据块。请参阅 如何设置分区表达式 部分，了解如何设置分区表达式。

FORGET PARTITION

ALTER TABLE table_name FORGET PARTITION partition_expr

从 ZooKeeper 中删除关于空分区的元数据。如果分区非空或未知，则查询失败。请确保仅对将不再使用的分区执行此操作。

请参阅 如何设置分区表达式 部分，了解如何设置分区表达式。

示例

ALTER TABLE mt FORGET PARTITION '20201121';

ATTACH PARTITION|PART

ALTER TABLE table_name ATTACH PARTITION|PART partition_expr

将数据从 detached 目录添加到表中。可以添加整个分区的数据，也可以添加单独的数据块。示例

ALTER TABLE visits ATTACH PARTITION 201901;
ALTER TABLE visits ATTACH PART 201901_2_2_0;

请参阅 如何设置分区表达式 部分，了解更多信息。

此查询是复制的。发起者副本会检查 detached 目录中是否存在数据。如果存在数据，则查询会检查其完整性。如果一切正确，则查询会将数据添加到表中。

如果是非发起者副本，收到 attach 命令后，在自己的 detached 文件夹中找到具有正确校验和的数据块，则无需从其他副本获取，直接附加数据。如果找不到具有正确校验和的数据块，则从任何拥有该数据块的副本下载数据。

您可以将数据放入一个副本的 detached 目录，并使用 ALTER ... ATTACH 查询将其添加到所有副本上的表中。

ATTACH PARTITION FROM

ALTER TABLE table2 [ON CLUSTER cluster] ATTACH PARTITION partition_expr FROM table1

此查询将数据分区从 table1 复制到 table2。

请注意

• 数据既不会从 table1 也不从 table2 中删除。
• table1 可以是临时表。

为了使查询成功运行，必须满足以下条件

• 两个表必须具有相同的结构。
• 两个表必须具有相同的分区键、相同的排序键和相同的主键。
• 两个表必须具有相同的存储策略。
• 目标表必须包含源表中的所有索引和投影。如果目标表启用了 enforce_index_structure_match_on_partition_manipulation 设置，则索引和投影必须相同。否则，目标表可以拥有源表的索引和投影的超集。

REPLACE PARTITION

ALTER TABLE table2 [ON CLUSTER cluster] REPLACE PARTITION partition_expr FROM table1

此查询将数据分区从 table1 复制到 table2，并替换 table2 中的现有分区。该操作是原子的。

请注意

• 数据不会从 table1 中删除。
• table1 可以是临时表。

为了使查询成功运行，必须满足以下条件

• 两个表必须具有相同的结构。
• 两个表必须具有相同的分区键、相同的排序键和相同的主键。
• 两个表必须具有相同的存储策略。
• 目标表必须包含源表中的所有索引和投影。如果目标表启用了 enforce_index_structure_match_on_partition_manipulation 设置，则索引和投影必须相同。否则，目标表可以拥有源表的索引和投影的超集。

MOVE PARTITION TO TABLE

ALTER TABLE table_source [ON CLUSTER cluster] MOVE PARTITION partition_expr TO TABLE table_dest

此查询将数据分区从 table_source 移动到 table_dest，并从 table_source 中删除数据。

为了使查询成功运行，必须满足以下条件

• 两个表必须具有相同的结构。
• 两个表必须具有相同的分区键、相同的排序键和相同的主键。
• 两个表必须具有相同的存储策略。
• 两个表必须是相同的引擎族（复制或非复制）。
• 目标表必须包含源表中的所有索引和投影。如果目标表启用了 enforce_index_structure_match_on_partition_manipulation 设置，则索引和投影必须相同。否则，目标表可以拥有源表的索引和投影的超集。

CLEAR COLUMN IN PARTITION

ALTER TABLE table_name [ON CLUSTER cluster] CLEAR COLUMN column_name IN PARTITION partition_expr

重置分区中指定列中的所有值。如果创建表时确定了 DEFAULT 子句，则此查询会将列值设置为指定的默认值。

示例

ALTER TABLE visits CLEAR COLUMN hour in PARTITION 201902

FREEZE PARTITION

ALTER TABLE table_name [ON CLUSTER cluster] FREEZE [PARTITION partition_expr] [WITH NAME 'backup_name']

此查询创建指定分区的本地备份。如果省略 PARTITION 子句，则查询将一次备份所有分区。

注意

整个备份过程在不停止服务器的情况下执行。

请注意，对于旧式表，您可以指定分区名称的前缀（例如，2019）——然后查询将为所有相应分区创建备份。请参阅 如何设置分区表达式 部分，了解如何设置分区表达式。

在执行时，对于数据快照，查询会为表数据创建硬链接。硬链接放置在 /var/lib/clickhouse/shadow/N/... 目录中，其中

• /var/lib/clickhouse/ 是配置文件中指定的 ClickHouse 工作目录。
• N 是备份的增量编号。
• 如果指定了 WITH NAME 参数，则使用 'backup_name' 参数的值代替增量编号。

注意

如果您使用 为表的数据存储使用一组磁盘，则 shadow/N 目录将出现在每个磁盘上，存储与 PARTITION 表达式匹配的数据块。

与 /var/lib/clickhouse/ 内部的目录结构相同，在备份内部创建相同的目录结构。查询对所有文件执行 chmod，禁止对其进行写入。

创建备份后，您可以将数据从 /var/lib/clickhouse/shadow/ 复制到远程服务器，然后从本地服务器删除它。请注意，ALTER t FREEZE PARTITION 查询不会复制。它仅在本地服务器上创建本地备份。

该查询几乎立即创建备份（但首先会等待当前查询完成对相应表的运行）。

ALTER TABLE t FREEZE PARTITION 仅复制数据，不复制表元数据。要备份表元数据，请复制文件 /var/lib/clickhouse/metadata/database/table.sql

要从备份恢复数据，请执行以下操作

1. 如果表不存在，则创建表。要查看查询，请使用 .sql 文件（将 ATTACH 替换为 CREATE）。
2. 将备份的 data/database/table/ 目录中的数据复制到 /var/lib/clickhouse/data/database/table/detached/ 目录。
3. 运行 ALTER TABLE t ATTACH PARTITION 查询将数据添加到表中。

从备份恢复不需要停止服务器。

该查询并行处理数据块，线程数由 max_threads 设置控制。

有关备份和恢复数据的更多信息，请参阅 “ClickHouse 中的备份和恢复” 部分。

UNFREEZE PARTITION

ALTER TABLE table_name [ON CLUSTER cluster] UNFREEZE [PARTITION 'part_expr'] WITH NAME 'backup_name'

从磁盘中删除具有指定名称的 frozen 分区。如果省略 PARTITION 子句，则查询将一次删除所有分区的备份。

CLEAR INDEX IN PARTITION

ALTER TABLE table_name [ON CLUSTER cluster] CLEAR INDEX index_name IN PARTITION partition_expr

此查询的工作方式类似于 CLEAR COLUMN，但它重置索引而不是列数据。

FETCH PARTITION|PART

ALTER TABLE table_name [ON CLUSTER cluster] FETCH PARTITION|PART partition_expr FROM 'path-in-zookeeper'

从另一台服务器下载分区。此查询仅适用于复制的表。

该查询执行以下操作

1. 从指定的 shard 下载分区|数据块。在 'path-in-zookeeper' 中，必须指定 ZooKeeper 中 shard 的路径。
2. 然后，查询会将下载的数据放入 table_name 表的 detached 目录。使用 ATTACH PARTITION|PART 查询将数据添加到表中。

例如

1. FETCH PARTITION

ALTER TABLE users FETCH PARTITION 201902 FROM '/clickhouse/tables/01-01/visits';
ALTER TABLE users ATTACH PARTITION 201902;

2. FETCH PART

ALTER TABLE users FETCH PART 201901_2_2_0 FROM '/clickhouse/tables/01-01/visits';
ALTER TABLE users ATTACH PART 201901_2_2_0;

请注意

• ALTER ... FETCH PARTITION|PART 查询不会被复制。它只会将 part 或 partition 放置在本地服务器的 detached 目录中。
• ALTER TABLE ... ATTACH 查询会被复制。它会将数据添加到所有副本。数据会从 detached 目录添加到其中一个副本，从相邻副本添加到其他副本。

在下载之前，系统会检查 partition 是否存在以及表结构是否匹配。系统会自动从健康的副本中选择最合适的副本。

虽然该查询名为 ALTER TABLE，但它不会更改表结构，也不会立即更改表中可用的数据。

MOVE PARTITION|PART

将 partition 或数据 part 移动到另一个卷或磁盘，用于 MergeTree 引擎表。请参阅 使用多个块设备存储数据。

ALTER TABLE table_name [ON CLUSTER cluster] MOVE PARTITION|PART partition_expr TO DISK|VOLUME 'disk_name'

ALTER TABLE t MOVE 查询

• 不会被复制，因为不同的副本可以具有不同的存储策略。
• 如果指定的磁盘或卷未配置，则返回错误。如果存储策略中指定的数据移动条件无法应用，查询也会返回错误。
• 如果待移动的数据已经被后台进程移动、并发的 ALTER TABLE t MOVE 查询或后台数据合并的结果，则可能会返回错误。在这种情况下，用户无需执行任何其他操作。

示例

ALTER TABLE hits MOVE PART '20190301_14343_16206_438' TO VOLUME 'slow'
ALTER TABLE hits MOVE PARTITION '2019-09-01' TO DISK 'fast_ssd'

UPDATE IN PARTITION

操作与指定的过滤表达式匹配的指定 partition 中的数据。作为 mutation 实现。

语法

ALTER TABLE [db.]table [ON CLUSTER cluster] UPDATE column1 = expr1 [, ...] [IN PARTITION partition_expr] WHERE filter_expr

示例

-- using partition name
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION 2 WHERE p = 2;

-- using partition id
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION ID '2' WHERE p = 2;

参见

• UPDATE

DELETE IN PARTITION

删除与指定的过滤表达式匹配的指定 partition 中的数据。作为 mutation 实现。

语法

ALTER TABLE [db.]table [ON CLUSTER cluster] DELETE [IN PARTITION partition_expr] WHERE filter_expr

示例

-- using partition name
ALTER TABLE mt DELETE IN PARTITION 2 WHERE p = 2;

-- using partition id
ALTER TABLE mt DELETE IN PARTITION ID '2' WHERE p = 2;

REWRITE PARTS

这将从头开始重写 part，使用所有新的设置。这很有意义，因为表级别设置（如 use_const_adaptive_granularity）默认情况下仅应用于新写入的 part。

示例

ALTER TABLE mt REWRITE PARTS;
ALTER TABLE mt REWRITE PARTS IN PARTITION 2;

参见

• DELETE

如何设置 Partition 表达式

可以在 ALTER ... PARTITION 查询中以不同的方式指定 partition 表达式

• 作为 system.parts 表的 partition 列中的值。例如，ALTER TABLE visits DETACH PARTITION 201901。
• 使用关键字 ALL。它只能与 DROP/DETACH/ATTACH/ATTACH FROM 一起使用。例如，ALTER TABLE visits ATTACH PARTITION ALL。
• 作为与表 partitioning keys 元组类型匹配的表达式或常量的元组。对于单个元素 partitioning key，表达式应包装在 tuple (...) 函数中。例如，ALTER TABLE visits DETACH PARTITION tuple(toYYYYMM(toDate('2019-01-25')))。
• 使用 partition ID。Partition ID 是 partition 的字符串标识符（如果可能，可读），用作文件系统和 ZooKeeper 中的 partition 名称。Partition ID 必须在单引号中指定在 PARTITION ID 子句中。例如，ALTER TABLE visits DETACH PARTITION ID '201901'。
• 在 ALTER ATTACH PART 和 DROP DETACHED PART 查询中，要指定 part 的名称，请使用来自 system.detached_parts 表的 name 列中的字符串字面量。例如，ALTER TABLE visits ATTACH PART '201901_1_1_0'。

指定 partition 时引号的使用取决于 partition 表达式的类型。例如，对于 String 类型，必须用引号（'）指定其名称。对于 Date 和 Int* 类型，不需要引号。

以上所有规则也适用于 OPTIMIZE 查询。如果需要在优化非 partitioning 表时仅指定一个 partition，请设置表达式 PARTITION tuple()。例如

OPTIMIZE TABLE table_not_partitioned PARTITION tuple() FINAL;

IN PARTITION 指定将 ALTER TABLE 查询的结果应用于 UPDATE 或 DELETE 表达式的 partition。仅从指定的 partition 创建新 part。这样，IN PARTITION 有助于减少表分成许多 partition 并且只需要逐点更新数据时的负载。

ALTER ... PARTITION 查询的示例在测试 00502_custom_partitioning_local 和 00502_custom_partitioning_replicated_zookeeper 中进行了演示。