跳转到主要内容
以下是对分区可用的操作:

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 目录。请注意,你只能在 leader 副本上执行此查询。要判断某个副本是否为 leader,请对 system.replicas 表执行 SELECT 查询。或者,更简单的做法是,在所有副本上执行 DETACH 查询——除 leader 副本外,其他所有副本都会抛出异常 (因为允许存在多个 leader) 。

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 中移除指定的 part,或移除指定分区中的所有 parts。 有关如何设置分区表达式的更多信息,请参阅如何设置分区表达式一节。

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 请注意:
  • table1table2 中的数据都不会被删除。
  • table1 可以是临时表。
要使查询成功执行,必须满足以下条件:
  • 两个表必须具有相同的结构。
  • 两个表必须具有相同的分区键、相同的 ORDER BY 键和相同的主键。
  • 两个表必须具有相同的存储策略。
  • 目标表必须包含源表中的所有索引和投影。如果目标表启用了 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 可以是临时表。
要使查询成功运行,必须满足以下条件:
  • 两个表必须具有相同的结构。
  • 两个表必须具有相同的分区键、相同的 ORDER BY 键,以及相同的主键。
  • 两个表必须具有相同的存储策略。
  • 目标表必须包含源表中的所有索引和投影。如果在目标表中启用了 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 中的数据。 要使该查询成功运行,必须满足以下条件:
  • 两个表必须具有相同的结构。
  • 两个表必须具有相同的分区键、相同的 ORDER BY 键以及相同的主键。
  • 两个表必须具有相同的存储策略。
  • 两个表必须属于同一引擎家族 (复制型或非复制型) 。
  • 目标表必须包含源表中的所有索引和投影。如果在目标表中启用了 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/ 是在 config 中指定的 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 查询,将数据添加到表中。
从备份恢复数据无需停止服务器。 该查询会并行处理 parts,线程数由 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. 从指定的分片拉取分区|part。在 ‘path-in-zookeeper’ 中,必须指定该分片在 ZooKeeper 中的路径。
  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;
  1. 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 查询不会被复制。它只会将分片或分区放到本地服务器上的 detached 目录中。
  • ALTER TABLE ... ATTACH 查询会被复制。它会将数据添加到所有副本。数据会从 detached 目录添加到其中一个副本,而其他副本则从相邻副本添加。
在拉取之前,系统会检查分区是否存在,以及表结构是否匹配。系统会从健康的副本中自动选择最合适的副本。 尽管该查询名为 ALTER TABLE,但它不会更改表结构,也不会立即更改表中的可用数据。

MOVE PARTITION|PART

用于 MergeTree 引擎家族的表,将分区或数据 parts 移动到其他卷或磁盘。请参阅 使用多个块设备进行数据存储
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 查询,或后台数据 merging 过程中移动。在这种情况下,用户无需执行任何额外操作。
示例:
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

用于操作指定分区中与指定过滤表达式匹配的数据。它作为一种变更来实现。 语法:
ALTER TABLE [db.]table [ON CLUSTER cluster] UPDATE column1 = expr1 [, ...] [IN PARTITION partition_expr] WHERE filter_expr

示例

-- 使用分区名称
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION 2 WHERE p = 2;

-- 使用分区 ID
ALTER TABLE mt UPDATE x = x + 1 IN PARTITION ID '2' WHERE p = 2;

另见

DELETE IN PARTITION

删除指定分区中与指定过滤表达式匹配的数据。该操作通过变更实现。 语法:
ALTER TABLE [db.]table [ON CLUSTER cluster] DELETE [IN PARTITION partition_expr] WHERE filter_expr

示例

-- 使用分区名称
ALTER TABLE mt DELETE IN PARTITION 2 WHERE p = 2;

-- 使用分区 ID
ALTER TABLE mt DELETE IN PARTITION ID '2' WHERE p = 2;

重写 parts

这会使用所有新设置从头重写这些 parts。这样做是合理的,因为默认情况下,像 use_const_adaptive_granularity 这样的表级设置只会应用到新写入的 parts。

示例

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

另请参阅

如何设置分区表达式

你可以在 ALTER ... PARTITION 查询中通过以下不同方式指定分区表达式:
  • 使用 system.parts 表中 partition 列的值。例如,ALTER TABLE visits DETACH PARTITION 201901
  • 使用关键字 ALL。它只能与 DROP/DETACH/ATTACH/ATTACH FROM 一起使用。例如,ALTER TABLE visits ATTACH PARTITION ALL
  • 使用由表达式或常量组成的元组,且该元组的类型必须与表分区键元组一致。如果分区键只有一个元素,则表达式应包装在 tuple (...) 函数中。例如,ALTER TABLE visits DETACH PARTITION tuple(toYYYYMM(toDate('2019-01-25')))
  • 使用分区 ID。分区 ID 是分区的字符串标识符 (如果可以,会采用便于人工识别的形式) ,在文件系统和 ZooKeeper 中用作分区名称。分区 ID 必须在 PARTITION ID 子句中以单引号指定。例如,ALTER TABLE visits DETACH PARTITION ID '201901'
  • ALTER ATTACH PARTDROP DETACHED PART 查询中,如需指定某个 part 的名称,请使用字符串字面量,其值取自 system.detached_parts 表的 name 列。例如,ALTER TABLE visits ATTACH PART '201901_1_1_0'
指定分区时是否使用引号取决于分区表达式的类型。例如,对于 String 类型,必须用引号 (') 指定其名称。对于 DateInt* 类型,则不需要引号。 上述所有规则也同样适用于 OPTIMIZE 查询。如果在优化非分区表时需要指定唯一的分区,请将表达式设为 PARTITION tuple()。例如:
OPTIMIZE TABLE table_not_partitioned PARTITION tuple() FINAL;
IN PARTITION 用于指定在 ALTER TABLE 查询中应用 UPDATEDELETE 表达式的分区。只有指定分区才会创建新的 parts。这样一来,当表被划分为许多分区,而你只需要对个别数据点进行更新时,IN PARTITION 有助于降低负载。 ALTER ... PARTITION 查询的示例可参见测试 00502_custom_partitioning_local00502_custom_partitioning_replicated_zookeeper
最后修改于 2026年6月10日