RESTORE

StarRocks 支持备份和恢复以下对象

• 内部数据库、表（所有类型和分区策略）和分区
• 外部 Catalog 的元数据（从 v3.4.0 版本开始支持）
• 同步物化视图和异步物化视图
• 逻辑视图（从 v3.4.0 版本开始支持）
• 用户定义的函数（从 v3.4.0 版本开始支持）

提示

有关备份和恢复的概述，请参阅备份和恢复指南。

RESTORE 是一个异步操作。您可以使用 SHOW RESTORE 查看 RESTORE 作业的状态，或者使用 CANCEL RESTORE 取消 RESTORE 作业。

注意

• 共享数据 StarRocks 集群不支持数据 BACKUP 和 RESTORE。
• 在每个数据库中，每次只允许运行一个 BACKUP 或 RESTORE 作业。否则，StarRocks 将返回错误。

权限要求

在 v3.0 之前的版本中，具有 admin_priv 权限的用户可以执行此操作。在 v3.0 及更高版本中，要备份特定对象，用户必须具有 System 级别的 REPOSITORY 权限以及相应表或相应数据库下所有表的 EXPORT 权限。例如

• 授予角色导出指定表数据的权限。

  GRANT REPOSITORY ON SYSTEM TO ROLE backup_tbl;
  GRANT EXPORT ON TABLE <table_name> TO ROLE backup_tbl;

• 授予角色导出指定数据库下所有表数据的权限。

  GRANT REPOSITORY ON SYSTEM TO ROLE backup_db;
  GRANT EXPORT ON ALL TABLES IN DATABASE <database_name> TO ROLE backup_db;

• 授予角色导出所有数据库中所有表数据的权限。

  GRANT REPOSITORY ON SYSTEM TO ROLE backup;
  GRANT EXPORT ON ALL TABLES IN ALL DATABASES TO ROLE backup;

兼容早期版本的语法

RESTORE SNAPSHOT <db_name>.<snapshot_name>
FROM <repository_name>
[ ON ( <table_name> [ PARTITION ( <partition_name> [, ...] ) ]
    [ AS <table_alias>] [, ...] ) ]
PROPERTIES ("key"="value", ...)

参数

参数	描述
db_name	要将数据恢复到的数据库的名称。
snapshot_name	数据快照的名称。
repository_name	存储库名称。
ON	要恢复的表的名称。如果未指定此参数，则恢复整个数据库。
PARTITION	要恢复的分区的名称。如果未指定此参数，则恢复整个表。您可以使用 SHOW PARTITIONS 查看分区名称。
PROPERTIES	RESTORE 操作的属性。有效键： backup_timestamp：备份时间戳。必需。您可以使用 SHOW SNAPSHOT 查看备份时间戳。 replication_num：指定要恢复的副本数。默认值：3。 meta_version：此参数仅用作临时解决方案，用于恢复早期版本的 StarRocks 备份的数据。最新版本的备份数据已经包含 meta version，您无需指定。 timeout：任务超时时间。单位：秒。默认值：86400。

v3.4.0 及更高版本支持的语法

-- Restore external catalog metadata.
RESTORE SNAPSHOT [<db_name>.]<snapshot_name> FROM <repository_name>
{ ALL EXTERNAL CATALOGS | EXTERNAL CATALOG[S] <catalog_name>[, EXTERNAL CATALOG[S] <catalog_name> ...] [ AS <alias> ] }
[ DATABASE <db_name_in_snapshot> [AS <target_db>] ]
[ PROPERTIES ("key"="value" [, ...] ) ]

-- Restore databases, tables, partitions, materialized views, logical views, or UDFs.
RESTORE SNAPSHOT [<db_name>.]<snapshot_name> FROM <repository_name>
[ DATABASE <db_name_in_snapshot> [AS <target_db>] ]
[ ON ( restore_object [, ...] ) ]
[ PROPERTIES ("key"="value" [, ...] ) ]

restore_object ::= [
    { ALL TABLE[S]             | TABLE[S] <table_name>[, TABLE[S] <table_name> ...] [AS <alias>] } |
    { ALL MATERIALIZED VIEW[S] | MATERIALIZED VIEW[S] <mv_name>[, MATERIALIZED VIEW[S] <mv_name> ...] [AS <alias>] } |
    { ALL VIEW[S]              | VIEW[S] <view_name>[, VIEW[S] <view_name> ...] [AS <alias>] } |
    { ALL FUNCTION[S]          | FUNCTION[S] <udf_name>[, FUNCTION[S] <udf_name> ...] [AS <alias>] } |
     <table_name> PARTITION (<partition_name>[, ...]) [AS <alias>] ]

参数

参数	描述
db_name.	目标集群中要将对象或快照恢复到的数据库的名称。如果数据库不存在，系统将创建它。您只能指定 AS <target_db> 或 <db_name>.。
snapshot_name	数据快照的名称。
repository_name	存储库名称。
ALL EXTERNAL CATALOGS	恢复所有外部 Catalog 的元数据。
catalog_name	需要恢复的外部 Catalog 的名称。
DATABASE db_name_in_snapshot	对象或快照在源集群中备份时所属的数据库的名称。
AS target_db	目标集群中要将对象或快照恢复到的数据库的名称。如果数据库不存在，系统将创建它。您只能指定 AS <target_db> 或 <db_name>.。
ON	要恢复的对象。如果未指定此参数，则恢复整个数据库。
table_name	要恢复的表的名称。
mv_name	要恢复的物化视图的名称。
view_name	要恢复的逻辑视图的名称。
udf_name	要恢复的 UDF 的名称。
PARTITION	要恢复的分区的名称。如果未指定此参数，则恢复整个表。
AS alias	为目标集群中要恢复的对象设置新名称。
PROPERTIES	RESTORE 操作的属性。有效键： backup_timestamp：备份时间戳。必需。您可以使用 SHOW SNAPSHOT 查看备份时间戳。 replication_num：指定要恢复的副本数。默认值：3。 meta_version：此参数仅用作临时解决方案，用于恢复早期版本的 StarRocks 备份的数据。最新版本的备份数据已经包含 meta version，您无需指定。 timeout：任务超时时间。单位：秒。默认值：86400。

示例

兼容早期版本的语法的示例

示例 1：将 example_repo 存储库中快照 snapshot_label1 中的表 backup_tbl 恢复到数据库 example_db，备份时间戳为 2018-05-04-16-45-08。恢复一个副本。

RESTORE SNAPSHOT example_db.snapshot_label1
FROM example_repo
ON ( backup_tbl )
PROPERTIES
(
    "backup_timestamp"="2018-05-04-16-45-08",
    "replication_num" = "1"
);

示例 2：将 example_repo 中 snapshot_label2 中的表 backup_tbl 的分区 p1 和 p2 以及表 backup_tbl2 恢复到数据库 example_db，并将 backup_tbl2 重命名为 new_tbl。备份时间戳为 2018-05-04-17-11-01。默认恢复三个副本。

RESTORE SNAPSHOT example_db.snapshot_label2
FROM example_repo
ON(
    backup_tbl PARTITION (p1, p2),
    backup_tbl2 AS new_tbl
)
PROPERTIES
(
    "backup_timestamp"="2018-05-04-17-11-01"
);

v3.4.0 及更高版本支持的语法的示例

示例 1：恢复数据库。

-- Restores the database with its original name.
RESTORE SNAPSHOT sr_hub_backup
FROM test_repo
DATABASE sr_hub
PROPERTIES("backup_timestamp" = "2024-12-09-10-25-58-842");

-- Restores the database with a new name.
RESTORE SNAPSHOT sr_hub_backup
FROM test_repo
DATABASE sr_hub AS sr_hub_new
PROPERTIES("backup_timestamp" = "2024-12-09-10-25-58-842");

示例 2：恢复数据库中的表。

-- Restores one table with its original name.
RESTORE SNAPSHOT sr_member_backup
FROM test_repo 
DATABASE sr_hub 
ON (TABLE sr_member) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores one table with a new name.
RESTORE SNAPSHOT sr_member_backup
FROM test_repo 
DATABASE sr_hub  AS sr_hub_new
ON (TABLE sr_member AS sr_member_new) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores multiple tables.
RESTORE SNAPSHOT sr_core_backup
FROM test_repo 
DATABASE sr_hub
ON (TABLE sr_member, TABLE sr_pmc) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores all tables.
RESTORE SNAPSHOT sr_all_backup
FROM test_repo
DATABASE sr_hub
ON (ALL TABLES);

-- Restores one from all tables.
RESTORE SNAPSHOT sr_all_backup
FROM test_repo
DATABASE sr_hub
ON (TABLE sr_member) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

示例 3：恢复表中的分区。

-- Restores one partition.
RESTORE SNAPSHOT sr_par_backup
FROM test_repo
DATABASE sr_hub
ON (TABLE sr_member PARTITION (p1)) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores multiple partitions.
RESTORE SNAPSHOT sr_par_backup
FROM test_repo
DATABASE sr_hub
ON (TABLE sr_member PARTITION (p1,p2)) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

示例 4：恢复数据库中的物化视图。

-- Restores one materialized view.
RESTORE SNAPSHOT sr_mv1_backup
FROM test_repo
DATABASE sr_hub
ON (MATERIALIZED VIEW sr_mv1) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores multiple materialized views.
RESTORE SNAPSHOT sr_mv2_backup
FROM test_repo
DATABASE sr_hub
ON (MATERIALIZED VIEW sr_mv1, MATERIALIZED VIEW sr_mv2) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores all materialized views.
RESTORE SNAPSHOT sr_mv3_backup
FROM test_repo
DATABASE sr_hub
ON (ALL MATERIALIZED VIEWS) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores one of all materialized views.
RESTORE SNAPSHOT sr_mv3_backup
FROM test_repo
DATABASE sr_hub
ON (MATERIALIZED VIEW sr_mv1) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

示例 5：恢复数据库中的逻辑视图。

-- Restores one logical view.
RESTORE SNAPSHOT sr_view1_backup
FROM test_repo
DATABASE sr_hub
ON (VIEW sr_view1) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores multiple logical views.
RESTORE SNAPSHOT sr_view2_backup
FROM test_repo
DATABASE sr_hub
ON (VIEW sr_view1, VIEW sr_view2) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores all logical views.
RESTORE SNAPSHOT sr_view3_backup
FROM test_repo
DATABASE sr_hub
ON (ALL VIEWS) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores one of all logical views.
RESTORE SNAPSHOT sr_view3_backup
FROM test_repo
DATABASE sr_hub
ON (VIEW sr_view1) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

示例 6：恢复数据库中的 UDF。

-- Restores one UDF.
RESTORE SNAPSHOT sr_udf1_backup
FROM test_repo
DATABASE sr_hub
ON (FUNCTION sr_udf1) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores multiple UDFs.
RESTORE SNAPSHOT sr_udf2_backup
FROM test_repo
DATABASE sr_hub
ON (FUNCTION sr_udf1, FUNCTION sr_udf2) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores all UDFs.
RESTORE SNAPSHOT sr_udf3_backup
FROM test_repo
DATABASE sr_hub
ON (ALL FUNCTIONS) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

-- Restores one of all UDFs.
RESTORE SNAPSHOT sr_udf3_backup
FROM test_repo
DATABASE sr_hub
ON (FUNCTION sr_udf1) 
PROPERTIES ("backup_timestamp" = "2024-12-09-10-52-10-940");

使用说明

• 在全球、数据库、表和分区级别执行备份和恢复操作需要不同的权限。
• 在每个数据库中，每次只允许运行一个 BACKUP 或 RESTORE 作业。否则，StarRocks 将返回错误。
• 由于 BACKUP 和 RESTORE 作业占用 StarRocks 集群的许多资源，您可以在 StarRocks 集群负载不高时备份和恢复数据。
• StarRocks 不支持为数据备份指定数据压缩算法。
• 由于数据以快照的形式备份，因此在快照生成时加载的数据不包含在快照中。因此，如果在快照生成后且 RESTORE 作业完成之前将数据加载到旧集群中，还需要将数据加载到恢复数据的集群中。建议您在数据迁移完成后的一段时间内并行地将数据加载到两个集群中，并在验证数据和服务的正确性后将应用程序迁移到新集群。
• 在 RESTORE 作业完成之前，您无法操作要恢复的表。
• 主键表无法恢复到 v2.5 之前的 StarRocks 集群。
• 您无需在恢复之前在新集群中创建要恢复的表。RESTORE 作业会自动创建它。
• 如果存在与要恢复的表具有重复名称的现有表，StarRocks 首先检查现有表的模式是否与要恢复的表的模式匹配。如果模式匹配，StarRocks 会使用快照中的数据覆盖现有表。如果模式不匹配，则 RESTORE 作业失败。您可以选择使用关键字 AS 重命名要恢复的表，或者在恢复数据之前删除现有表。
• 如果 RESTORE 作业覆盖了现有的数据库、表或分区，则在作业进入 COMMIT 阶段后，被覆盖的数据将无法恢复。如果 RESTORE 作业在此阶段失败或被取消，数据可能会损坏且无法访问。在这种情况下，您只能再次执行 RESTORE 操作并等待作业完成。因此，我们建议您不要通过覆盖来恢复数据，除非您确定当前数据不再使用。覆盖操作首先检查快照与现有数据库、表或分区之间的元数据一致性。如果检测到不一致，则无法执行 RESTORE 操作。
• 目前，StarRocks 不支持备份和恢复与用户帐户、权限和资源组相关的配置数据。
• 目前，StarRocks 不支持备份和恢复表之间的 Colocate Join 关系。