ByteHouse 企业版支持通过脚本工具实现离线迁移，可将存储于 ClickHouse 集群中的数据快速迁移至 ByteHouse 企业版并投入生产使用，助力企业实现数据资产的统一管理、开发与价值挖掘。本文将详细介绍数据迁移的适用场景、具体方案及关键注意事项，为迁移工作提供完整指引。

适用场景及迁移方案选型 #

不同网络环境、集群类型对应不同的迁移方案，以下为核心场景分类及方案选型建议，帮助您快速匹配最优迁移路径：

除网络环境外，您可根据表数量和总数据量进一步细化方案选择：

1. 方案 1：适用于 表数量 ≤ 10 个、总数据量 ≤ 100GB 的小体量迁移场景，操作便捷无需脚本开发。
2. 方案 2：支持通过 WHERE 条件筛选迁移数据，适合需按需迁移部分数据的场景，灵活度高。
3. 方案 3：适用于 表数量 > 10 个、总数据量 > 100GB 的大规模迁移场景，注意整体迁移量不超过 1TB。

如果您需要迁移的数据大小超过 1TB，建议联系 ByteHouse 团队处理。ByteHouse 提供专属可视化迁移工具，可辅助您便捷完成大批量数据的迁移工作。

单表数据量超过 1 千万行，建议联系 ByteHouse 团队协助处理。

账号权限 #

• 请确保您使用的 ClickHouse 账号拥有源端 ClickHouse 集群的读权限。
• 请确保您使用的 ByteHouse 账号拥有目标端 ByteHouse 集群的写权限。

网络及费用 #

• 迁移过程中，目标数据库与源数据库、对象存储服务间的网络互通且网络环境稳定。
  • 通常情况下，ClickHouse、对象存储服务、ByteHouse 间需通过公网传输，请确保网络环境稳定；若您已搭建专线，可切换为私网传输，此时需确保专线配置完成且网络环境稳定。
  • 使用火山引擎对象存储服务 TOS 传输到 ByteHouse 时，需确保 TOS 与 ByteHouse 实例处于相同地域，以保障数据传输效率并避免跨地域访问产生额外费用。
• 迁移过程中使用数据服务可能涉及费用，请以产品的实际计费为准。

数据迁移说明 #

• 数据双写策略：用于保障迁移期间数据一致性。

  • 普通表双写：若表存在分区字段，可从任意时间点启动双写（同时向源集群和目标集群写入数据），通过 T+1 方式迁移 T 时间点之前的历史数据，确保全量数据对齐无遗漏。
  • HaUniqueMergeTree/ReplacingMergeTree 表双写：若存在分区字段，处理逻辑与普通表一致；若不存在分区字段，建议先暂停源集群写入，完成全量数据迁移对齐后，再启动双写，避免因去重逻辑导致数据不一致。

• 分区迁移

  • 初始全量迁移：建议先删除目标表对应分区（Drop partition）或者将分区移动（move partition）至临时表，再通过向本地表（local 表）插入数据（insert into）的方式批量迁移数据，提升迁移效率。
  • 增量分区替换：若表已完成全量迁移，仅需替换部分分区数据，优先采用“先插入（insert into）临时表，再通过 move partition 语句将临时表分区迁移至目标表”的方式，减少对目标表正常使用的影响。

• 索引与视图处理：用于提升迁移效率

  • 索引处理：迁移过程中，若目标表已创建索引（index），会大幅降低数据插入速度。建议先删除目标表索引，完成数据迁移后，重新创建索引并执行 rebuild index 操作，确保索引有效性。rebuild index 操作示例如下：

    -- 第一步添加索引
    ALTER TABLE table_name on cluster {cluster_name}
    ADD INDEX
    index_name column_name TYPE bloom_filter(0.01) GRANULARITY 1;
    -- 第二步对数据重建索引
    ALTER TABLE skipindex on cluster {cluster_name} MATERIALIZE INDEX index_name;
    

  • 物化视图处理

    • 当源表关联多个物化视图（MATERIALIZED VIEW），会显著影响迁移效率。推荐优先完成基础数据表（底表）的迁移，再同步视图的 schema 信息。
    • 若需要迁移物化视图数据，可在物化视图 schema 同步完成后执行。
    • 若物化视图结构简单且为一对一映射，可以直接迁移底表数据，物化视图数据自动生成，可根据业务需求忽略并开始直接迁移。如果是一对多映射，建议迁移底表之前不要创建物化视图，迁移完成后再逐个迁移物化视图数据。

• 导入导出格式选型

  • 若迁移表结构包含 Object 类型字段，优先选择 JSON 格式进行导入导出，确保字段类型兼容性。
  • 若迁移表结构包含 Function 函数，优先选择 RowBinary 格式，避免函数解析异常。
  • 压缩格式选择可参考方案 3 中的图表说明。需注意：压缩格式仅支持本地导入，不支持远程导入。

• 迁移前后集群 ShardNum 对齐处理

  • Unique/Replacing 表：必须通过 insert into 分布式表的方式迁移，确保去重逻辑正常生效。
  • 小数据量普通表：可直接通过 insert into 分布式表迁移，操作更简便。
  • 大数据量普通表（且非 HaUniqueMergeTree/ReplacingMergeTree 表）：建议先在本地表（local 表）之间完成数据迁移，按照 shardNum 进行数据导出，写入时写入到 local 表，如果迁移前后 shard 数无法对齐，可以在写入时写入到分布式表，如果数据量较大导致写分布式表有延迟，可以联系 ByteHouse 团队协助处理。

• 引擎能力增强说明
  ByteHouse 增强了部分 ClickHouse 社区版引擎的能力，迁移过程中可根据业务需求直接替换，提升数据处理性能。具体对应关系如下：

  功能场景	ClickHouse 表引擎	ByteHouse 增强表引擎	说明
  Kafka 导入	Kafka	HaKafka	无
  去重引擎	ReplacingMergeTree	HaUniqueMergeTree	使用增强引擎后，索引可能导致存储容量略有增加，需提前评估存储资源。
  多副本去重引擎	ReplicatedReplacingMergeTree	HaUniqueMergeTree
  普通引擎	ReplicatedMergeTree	HaMergeTree	无

方案 1：使用 ByteHouse 控制台批式导入功能 #

该方案适用于表数量≤10 个、总数据量≤100GB，且对操作便捷性要求高的场景。无需开发复杂脚本，可直接通过 ByteHouse 控制台的批式导入功能快速完成迁移，高效适配轻量迁移需求。

准备工作 #

• 确保源端 ClickHouse 表结构与目标端 ByteHouse 字段结构一致，表引擎可参考上文中的引擎映射表格进行转换。

• 根据您 ByteHouse 集群所在的地域，在源端 ClickHouse 的 8123 端口为 ByteHouse 对应的网段配置白名单，确保网络互通。

  地域	白名单地址
  北京	180.184.42.121
  上海	180.184.161.161
  柔佛	101.47.6.233
  BytePlus 环境	101.47.144.208

操作步骤 #

1. 请确保 ClickHouse 源数据库/表已准备就绪，且在 ByteHouse 中创建了对应的目标数据库/表，可参考新建数据库/表。
   如果您需要创建的表数量较多，可提交工单或联系 ByteHouse 团队。
2. 登录 ByteHouse 企业版控制台，使用批式导入功能自行操作迁移使用 ByteHouse 批式导入功能，操作详情请参见批式导入。

   注意

   • 强烈建议单个迁移任务的数据量控制在 5G 以内，此规模下迁移耗时约 15 分钟。
   • 若数据量超过 5G，迁移耗时会随数据量成比例增加（如 10G 数据耗时约 30 分钟），建议拆分任务分批导入。
3. 迁移完成后，您可以通过 ByteHouse 控制台的数据查询功能执行数据查询操作，验证数据是否迁移成功，相关命令请参见数据校验。

方案 2：使用 ClickHouse Remote 函数迁移 #

该方式通过 ClickHouse 原生 Remote 函数实现跨集群数据直接迁移，支持配置 where 条件限制迁移的数据，操作更加灵活。

注意事项 #

• 单表迁移限制：INSERT REMOTE 语法不支持在单条命令中直接指定多个数据库或多张表，remote()/remote() function 函数的设计逻辑是针对单表的跨集群数据读写，必须为每张表单独执行迁移命令。
• 单表迁移限制：您可通过 ByteHouse 控制面的数据查询 功能执行 INSERT REMOTE 操作，但 ByteHouse 控制面会自动追加数据限制，当 INSERT REMOTE 操作的数据量超过 10 MB 时会执行失败，因此推荐您使用 DBeaver 客户端或 ByteHouse Client 操作。
• 专线连接配置：如果您的源端 ClickHouse 集群需通过专线连接 ByteHouse，需联系 ByteHouse 运维团队并提供专线连接的相关网络信息，用于 ByteHouse 运维团队在 ByteHouse 相关节点配置辅助网卡。专线连接的事项请联系 ByteHouse 团队进行操作确认。

准备工作 #

1. 根据您使用的 ClickHouse 版本确认并安装对应的链接工具，用于连接源端 ClickHouse 集群和目标端ByteHouse 集群。

   版本	所需操作及工具
   ClickHouse 社区版 v22.3 及以上版本	需在目标端 ByteHouse 集群执行迁移命令，可通过 DBeaver 或 ByteHouse Client 执行相关操作，安装说明如下。 安装 DBeaver：请通过 官方网站 下载并安装 DBeaver 。 安装 ByteHouse Client：您可参考 ByteHouse 官方文档下载并安装 ByteHouse Client，详情请参见ByteHouse Client。请注意，当前 ByteHouse Client 仅支持 Linux 操作系统。
   ClickHouse 社区版 v20.3 及以下版本	需在源端 ClickHouse 集群执行迁移命令，可通过 DBeaver 或 ClickHouse Client 执行相关操作，安装说明如下。 安装 DBeaver：请通过 官方网站 下载并安装 DBeaver 。 安装 ClickHouse Client：您可参考 ClickHouse 社区提供的安装方式，详情请参见安装 ClickHouse Client。

2. 确保源端 ClickHouse 表结构与目标端 ByteHouse 表结构一致，避免迁移过程中字段不兼容。

操作步骤 #

1. 请确保 ClickHouse 源数据库/表已准备就绪，且在 ByteHouse 中创建了对应的目标数据库/表，可参考新建数据库/表。
   如果您需要创建的表数量较多，可提交工单或联系 ByteHouse 团队。

2. 根据您使用的 ClickHouse 版本，使用连接工具连接源端 ClickHouse 集群或目标端 ByteHouse 集群。

   客户端	操作说明
   DBeaver	适用于所有 ClickHouse 版本。 通过 DBeaver 连接 ClickHouse、ByteHouse 默认会有行数和数据大小限制，导致使用 DBeaver 执行数据迁移操作（insert into xxx select remote）仅能导入部分数据，因此需要放开软件的行数限制，具体操作如下： 在 Dbeaver 中，单击顶部数据库，单击驱动管理器，在列表中选中 ClickHouse，并单击右侧编辑。 在弹出的对话框中，单击高级参数，配置 Driver supports result set limit 和 Driver supports structure cache 参数值为 100000。如果您需要导出的数据量较大，请联系 ByteHouse 团队处理。 在 DBeaver 中，根据您使用 ClickHouse 版本，连接源端 ClickHouse 集群或目标端 ByteHouse 集群。 连接至 ClickHouse 集群请参见使用 DBeaver 连接到 ClickHouse。 连接至 ByteHouse 集群请参请参见连接到 ByteHouse。
   ByteHouse Client	适用于 ClickHouse 社区版 v22.3 及以上版本或 ByteHouse 数据迁移至 ByteHouse 的场景。 您可通过 ByteHouse Client 连接 ByteHouse 集群，详情请参见ByteHouse Client。 执行以下命令，连接至 ByteHouse 企业版集群。 bytehouse client --host <host> # ByteHouse 企业版连接地址 --user <user> # ByteHouse 企业版集群的用户名 --password <password> # Bytehouse 企业版集群的密码 host：ByteHouse 企业版连接地址，您可登录 ByteHouse 企业版控制台，通过集群管理 > 集群列表 > 集群名称 > 基本信息路径，在网络信息模块，查看到当前集群的私网或公网连接地址（即 Host 地址）。 user：ByteHouse 企业版集群的用户名，您可登录 ByteHouse 企业版控制台，单击右上角 ByteHouse 企业版个人中心，单击账号管理，查看并复制集群连接账号名。 password：Bytehouse 企业版集群的密码，您可登录 ByteHouse 企业版控制台，单击右上角 ByteHouse 企业版个人中心，单击账号管理，查看并复制集群连接密码。
   ClickHouse Client	适用于 ClickHouse 社区版 v20.3 及以下版本数据迁移至 ByteHouse 的场景。 您可通过 ClickHouse Client 连接 ByteHouse 集群，详情请参见 ClickHouse Client。 登录 ByteHouse 企业版集群，通过集群管理 > 集群列表 > 集群名称 > 连接集群路径，查看并复制其中 ClickHouse Client 的连接命令示例，修改其中的密码字段。ByteHouse 提供了私网和公网连接示例，您可按需单击页签切换并复制对应的命令示例。 连接语句基本语法说明如下： clickhouse client --host <host> # ByteHouse 企业版连接地址 --user <user> # ByteHouse 企业版集群的用户名 --password <password> # Bytehouse 企业版集群的密码 ByteHouse 连接示例已为您自动填充了连接地址、用户名，您仅需填写密码，密码获取方式请参见获取账号与密码。 执行上述连接命令，连接到 ByteHouse 集群。

3. 根据源端 ClickHouse 版本，选择对应的 INSERT REMOTE 命令执行数据迁移。

   • 场景 1：源端为 ClickHouse 社区版 v22.3 及以上版本
     在目标端 ByteHouse 集群执行以下命令，ByteHouse 将直接从源端拉取数据：

     insert into ${db}.${table} 
     select * from remote(
       '${remote_host}:${port}',  
       ${db},                    
       ${table},           
       '${user}',    
       '${password}' 
     );
     

     参数	配置说明
     插入配置（insert into）	{db}：指定需导入的 ByteHouse 目标数据库名称。
     	{table} ：指定需导入的 ByteHouse 目标数据表名称。
     查询配置（select）	{remote_host}：源端 ClickHouse 地址。
     	{port}：ClickHouse 端口号，填写为 8123。
     	{db}：ClickHouse 需导出的数据库名称。
     	{table}：ClickHouse 数据库中需导出的表名称。
     	{user}：ClickHouse 的用户名。
     	{password}：ClickHouse 登录密码。

   • 场景 2：源端为 ClickHouse 社区版 v20.3 及以下版本
     在源端 ClickHouse 集群执行以下命令，ClickHouse 将主动推送数据至目标端：

     insert into function remote(
       '${remote_host}:${port}',  
       ${db}, 
       ${table},    
       '${user}',  
       '${password}'  
     ) 
     select * from ${db}.${table};
     

     参数	配置说明
     插入配置（insert into）	{remote_host}：目标端 ByteHouse 地址。
     	{port}：目标端 ByteHouse 端口号，填写为 8123。
     	{db}：需导入的 ByteHouse 目标数据库名称。
     	{table}：需导入的 ByteHouse 目标数据表名称。
     	{user}：ByteHouse 的用户名。
     	{password}：ByteHouse 登录密码。
     查询配置（select）	{db}：源端 ClickHouse 需导出的数据库名称。
     	{table} ：源端 ClickHouse 需导出的数据表名称。

4. 迁移完成后，您可以通过 ByteHouse 控制面执行数据查询操作，验证数据是否迁移成功，相关命令请参见数据校验。

方案 3：使用迁移脚本迁移数据 #

该方案为离线迁移模式，通过脚本将 ClickHouse 数据先导出至对象存储（支持 TOS/AWS S3 / 阿里云 OSS / 华为云 OBS/MinIO 等），再导入 ByteHouse，适用于表数量>10 个、总数据量>100GB的场景。如果您需迁移的数据大于 1TB，请联系 ByteHouse 团队协助处理。

迁移流程 #

该方案展示了如何将数据通过离线方式，从 ClickHouse 迁移到 ByteHouse 的过程，迁移流程包含以下三大步骤：

1. 将表数据从 ClickHouse 导出到对象存储中。
2. （可选）若源端对象存储非火山引擎 TOS，通过火山引擎存储迁移服务 DMS 将数据同步至 TOS。
3. 将表数据从 TOS 导入到 ByteHouse。

准备工作 #

1. 开通并配置对象存储服务：
   • 火山引擎 TOS：开通火山引擎对象存储服务 TOS，并在火山引擎 TOS 控制台创建接收数据的存储桶（bucket）和文件目录，开通及配置操作详情请参考快速入门。请确保该 TOS 存储桶所在的区域与 ByteHouse 企业版目标库的区域一致，例如，ByteHouse 企业版目标库位于上海区域，则创建 TOS Bucket 时，需选择上海区域，避免跨区费用。
   • 第三方对象存储：确保账号拥有读写权限，并记录 Access Key、Secret Key、存储路径。
2. （可选）开通存储迁移服务 DMS：用于将数据从源端对象存储迁移至火山引擎对象存储服务 TOS，开通操作详情请参见存储迁移服务快速入门。
3. 环境准备：
   • 安装 Python 3.7+，用于执行导出脚本。
   • 若选择 run_sql_mode=cli 连接方式，需安装 ClickHouse Client（仅 Linux/macOS 支持）。

步骤一：准备目标表 #

请确保 ClickHouse 源数据库/表已准备就绪，且在 ByteHouse 中创建了对应的目标数据库/表，可参考新建数据库/表。
如果您需要创建的表数量较多，可提交工单或联系 ByteHouse 团队。

步骤二：ClickHouse 导出至对象存储 #

1. 下载迁移至对象存储服务所需的 ByteHouse 自研 ClickHouse 数据导出脚本文件。下载后，请将该脚本文件存储至您自定义的路径，并记录该路径，用于后续执行脚本时配置。
   

   

   data-migrator-clickhouse-to-s3.py

   未知大小

   
   
   该脚本提供了两种方式连接您的 ClickHouse 集群，您可通过在下述步骤 2 中的 ini 文件中设置 run_sql_mode 参数，以使用对应的连接方式。
   • 方式一：通过 Python ClickHouse driver 连接
     默认连接方式，需将 run_sql_mode 参数设置为 driver，适用于环境中不支持安装 ClickHouse Client 的场景。
   • 方式二：通过执行环境的中的 ClickHouse Client 执行文件连接
     需将 run_sql_mode 参数设置为 cli。如果您的环境已安装 ClickHouse Client 命令行工具，可使用该方式连接。

2. 在 ClickHouse 数据导出脚本同一路径下，创建并配置 ini 文件。本文示例中将 ini 文件命名为 config-template-export.ini。
   请使用实际的 ClickHouse 连接信息、对象存储的目标存储路径、数据迁移参数值替换示例中的占位符或示例参数值，以便脚本正确执行数据导出操作。参数详细配置信息请参见参数说明。

   TOS

   AWS S3

   阿里云 OSS

   华为云 OBS

   MinIO

   适用于对象存储服务为火山引擎对象存储 TOS。

   # 设置是否启用 dryrun 模式，默认值为 0，表示不启用；设置成 1 表示只打印导出 SQL 但不实际执行。
   dryrun=0
   # 设置连接 ClickHouse 集群的方式，默认值为 driver，表示使用 Python ClickHouse driver 连接
   # 如果您的环境已安装 ClickHouse Client，可将设置为 run_sql_mode=cli，脚本将使用 ClickHouse Client 连接
   run_sql_mode=driver
   #### ClickHouse 的连接信息
   # ClickHouse 的 host 节点，可以使用逗号分割选择多个节点
   clickhouse_host=127.0.0.1
   clickhouse_port=9000
   clickhouse_user=default
   clickhouse_password={your_clickhouse_password}
   
   #### 对象存储连接信息
   s3_access_key={tos_access_key}
   s3_secret_key={tos_secret_access_key}
   s3_url=https://{bucket_name}.tos-s3-{region}.volces.com/{dir_name}
   
   #### 导出数据表的相关信息
   database_name={database_name}
   table_names={table_name1},{table_name2},...
   ;field_rules=
   ;export_field_rules=
   
   #### 切分方式
   # 分区级别分隔参数
   split_in_partition=1
   selected_partitions=
   # 全局/分区分割（split）参数，可以基于分区（partition）/整表再进行分批导出
   split_count=-1
   # 作为 hash 进行分割的列，可以配置多个列，按照逗号隔开，按照顺序选择存在表中的数据，选择的优先级：在 orderby 配置中的离散列，int 或者 string 类型的列
   split_column=
   
   #### 查询的额外条件
   where=
   limit=
   
   #### 断点续传能力，可以控制成功后的导出 SQL 不再执行。
   # 是否清理状态。1 为清理，默认为 0 不清理
   empty_status=0
   
   #### 额外参数
   # 最大重试次数
   max_retries=1
   # 每次重试延迟，单位为秒（s）
   retry_delay_seconds=1
   # SQL 的 Settings，目前建议配置为 timeout 的一些配置，单位为秒（s）。
   # 您也可以按需配置 s3_truncate_on_insert=true，表示如果存在原有文件，系统将删除这些，即覆盖原有文件。
   s3_insert_settings=send_timeout=3600, receive_timeout=3600, max_execution_time=3600,output_format_json_quote_64bit_integers=0
   # 文件格式及压缩配置
   file_format=Parquet
   data_compression_method=none
   # 需要导出的 ClickHouse 表引擎
   filter_tables_by_engine=MergeTree
   
   #### 并发参数，控制导出 SQL 在 ByteHouse 执行的并发
   parallelism=8
   

   适用于对象存储服务为 AWS S3。

   # 设置是否启用 dryrun 模式，默认值为 0，表示不启用；设置成 1 表示只打印导出 SQL 但不实际执行。
   dryrun=0
   # 设置连接 ClickHouse 集群的方式，默认值为 driver，表示使用 Python ClickHouse driver 连接
   # 如果您的环境已安装 ClickHouse Client，可将设置为 run_sql_mode=cli，脚本将使用 ClickHouse Client 连接
   run_sql_mode=driver
   #### ClickHouse 的连接信息
   # ClickHouse 的 host 节点，可以使用逗号分割选择多个节点
   clickhouse_host=127.0.0.1
   clickhouse_port=9000
   clickhouse_user=default
   clickhouse_password={your_clickhouse_password}
   
   #### 对象存储连接信息
   s3_access_key={aws_access_key_id}
   s3_secret_key={aws_secret_access_key}
   s3_url=https://{bucket_name}.s3.{region}.amazonaws.com/{dir_name}
   
   #### 导出数据表的相关信息
   database_name={database_name}
   table_names={table_name1},{table_name2},...
   ;field_rules=
   ;export_field_rules=
   
   #### 切分方式
   # 分区级别分隔参数
   split_in_partition=1
   selected_partitions=
   # 全局/分区分割（split）参数，可以基于分区（partition）/整表再进行分批导出
   split_count=-1
   # 作为 hash 进行分割的列，可以配置多个列，按照逗号隔开，按照顺序选择存在表中的数据，选择的优先级：在 orderby 配置中的离散列，int 或者 string 类型的列
   split_column=
   
   #### 查询的额外条件
   where=
   limit=
   
   #### 断点续传能力，可以控制成功后的导出 SQL 不再执行。
   # 是否清理状态。1 为清理，默认为 0 不清理
   empty_status=0
   
   #### 额外参数
   # 最大重试次数
   max_retries=1
   # 每次重试延迟，单位为秒（s）
   retry_delay_seconds=1
   # SQL 的 Settings，目前建议配置为 timeout 的一些配置，单位为秒（s）。
   # 您也可以按需配置 s3_truncate_on_insert=true，表示如果存在原有文件，系统将删除这些，即覆盖原有文件。
   s3_insert_settings=send_timeout=3600, receive_timeout=3600, max_execution_time=3600,output_format_json_quote_64bit_integers=0
   # 文件格式及压缩配置
   file_format=Parquet
   data_compression_method=none
   # 需要导出的 ClickHouse 表引擎
   filter_tables_by_engine=MergeTree
   
   #### 并发参数，控制导出 SQL 在 ByteHouse 执行的并发
   parallelism=8
   

   适用于对象存储服务为阿里云 OSS。

   # 设置是否启用 dryrun 模式，默认值为 0，表示不启用；设置成 1 表示只打印导出 SQL 但不实际执行。
   dryrun=0
   # 设置连接 ClickHouse 集群的方式，默认值为 driver，表示使用 Python ClickHouse driver 连接
   # 如果您的环境已安装 ClickHouse Client，可将设置为 run_sql_mode=cli，脚本将使用 ClickHouse Client 连接
   run_sql_mode=driver
   #### ClickHouse 的连接信息
   # ClickHouse 的 host 节点，可以使用逗号分割选择多个节点
   clickhouse_host=127.0.0.1
   clickhouse_port=9000
   clickhouse_user=default
   clickhouse_password={your_clickhouse_password}
   
   #### 对象存储连接信息
   s3_access_key={oss_access_key_id}
   s3_secret_key={oss_secret_access_key}
   s3_url=https://{bucket_name}.oss.{region}.aliyuncs.com/{dir_name}
   
   #### 导出数据表的相关信息
   database_name={database_name}
   table_names={table_name1},{table_name2},...
   ;field_rules=
   ;export_field_rules=
   
   #### 切分方式
   # 分区级别分隔参数
   split_in_partition=1
   selected_partitions=
   # 全局/分区分割（split）参数，可以基于分区（partition）/整表再进行分批导出
   split_count=-1
   # 作为 hash 进行分割的列，可以配置多个列，按照逗号隔开，按照顺序选择存在表中的数据，选择的优先级：在 orderby 配置中的离散列，int 或者 string 类型的列
   split_column=
   
   #### 查询的额外条件
   where=
   limit=
   
   #### 断点续传能力，可以控制成功后的导出 SQL 不再执行。
   # 是否清理状态。1 为清理，默认为 0 不清理
   empty_status=0
   
   #### 额外参数
   # 最大重试次数
   max_retries=1
   # 每次重试延迟，单位为秒（s）
   retry_delay_seconds=1
   # SQL 的 Settings，目前建议配置为 timeout 的一些配置，单位为秒（s）。
   # 您也可以按需配置 s3_truncate_on_insert=true，表示如果存在原有文件，系统将删除这些，即覆盖原有文件。
   s3_insert_settings=send_timeout=3600, receive_timeout=3600, max_execution_time=3600,output_format_json_quote_64bit_integers=0
   # 文件格式及压缩配置
   file_format=Parquet
   data_compression_method=none
   # 需要导出的 ClickHouse 表引擎
   filter_tables_by_engine=MergeTree
   
   #### 并发参数，控制导出 SQL 在 ByteHouse 执行的并发
   parallelism=8
   

   适用于对象存储服务为华为云 OBS。

   # 设置是否启用 dryrun 模式，默认值为 0，表示不启用；设置成 1 表示只打印导出 SQL 但不实际执行。
   dryrun=0
   # 设置连接 ClickHouse 集群的方式，默认值为 driver，表示使用 Python ClickHouse driver 连接
   # 如果您的环境已安装 ClickHouse Client，可将设置为 run_sql_mode=cli，脚本将使用 ClickHouse Client 连接
   run_sql_mode=driver
   #### ClickHouse 的连接信息
   # ClickHouse 的 host 节点，可以使用逗号分割选择多个节点
   clickhouse_host=127.0.0.1
   clickhouse_port=9000
   clickhouse_user=default
   clickhouse_password={your_clickhouse_password}
   
   #### 对象存储连接信息
   s3_access_key={obs_access_key_id}
   s3_secret_key={obs_secret_access_key}
   s3_url=https://{bucket_name}.obs.{region}.myhuaweicloud.com/{dir_name}
   
   #### 导出数据表的相关信息
   database_name={database_name}
   table_names={table_name1},{table_name2},...
   ;field_rules=
   ;export_field_rules=
   
   #### 切分方式
   # 分区级别分隔参数
   split_in_partition=1
   selected_partitions=
   # 全局/分区分割（split）参数，可以基于分区（partition）/整表再进行分批导出
   split_count=-1
   # 作为 hash 进行分割的列，可以配置多个列，按照逗号隔开，按照顺序选择存在表中的数据，选择的优先级：在 orderby 配置中的离散列，int 或者 string 类型的列
   split_column=
   
   #### 查询的额外条件
   where=
   limit=
   
   #### 断点续传能力，可以控制成功后的导出 SQL 不再执行。
   # 是否清理状态。1 为清理，默认为 0 不清理
   empty_status=0
   
   #### 额外参数
   # 最大重试次数
   max_retries=1
   # 每次重试延迟，单位为秒（s）
   retry_delay_seconds=1
   # SQL 的 Settings，目前建议配置为 timeout 的一些配置，单位为秒（s）。
   # 您也可以按需配置 s3_truncate_on_insert=true，表示如果存在原有文件，系统将删除这些，即覆盖原有文件。
   s3_insert_settings=send_timeout=3600, receive_timeout=3600, max_execution_time=3600,output_format_json_quote_64bit_integers=0
   # 文件格式及压缩配置
   file_format=Parquet
   data_compression_method=none
   # 需要导出的 ClickHouse 表引擎
   filter_tables_by_engine=MergeTree
   
   #### 并发参数，控制导出 SQL 在 ByteHouse 执行的并发
   parallelism=8
   

   适用于对象存储服务为 MinIO。

   # 设置是否启用 dryrun 模式，默认值为 0，表示不启用；设置成 1 表示只打印导出 SQL 但不实际执行。
   dryrun=0
   # 设置连接 ClickHouse 集群的方式，默认值为 driver，表示使用 Python ClickHouse driver 连接
   # 如果您的环境已安装 ClickHouse Client，可将设置为 run_sql_mode=cli，脚本将使用 ClickHouse Client 连接
   run_sql_mode=driver
   #### ClickHouse 的连接信息
   # ClickHouse 的 host 节点，可以使用逗号分割选择多个节点
   clickhouse_host=127.0.0.1
   clickhouse_port=9000
   clickhouse_user=default
   clickhouse_password={your_clickhouse_password}
   
   #### 对象存储连接信息
   s3_access_key={minio_access_key_id}
   s3_secret_key={minio_secret_access_key}
   s3_url=http://{host}:{port}/{bucket_name}/{dir_name}
   
   #### 导出数据表的相关信息
   database_name={database_name}
   table_names={table_name1},{table_name2},...
   ;field_rules=
   ;export_field_rules=
   
   #### 切分方式
   # 分区级别分隔参数
   split_in_partition=1
   selected_partitions=
   # 全局/分区分割（split）参数，可以基于分区（partition）/整表再进行分批导出
   split_count=-1
   # 作为 hash 进行分割的列，可以配置多个列，按照逗号隔开，按照顺序选择存在表中的数据，选择的优先级：在 orderby 配置中的离散列，int 或者 string 类型的列
   split_column=
   
   #### 查询的额外条件
   where=
   limit=
   
   #### 断点续传能力，可以控制成功后的导出 SQL 不再执行。
   # 是否清理状态。1 为清理，默认为 0 不清理
   empty_status=0
   
   #### 额外参数
   # 最大重试次数
   max_retries=1
   # 每次重试延迟，单位为秒（s）
   retry_delay_seconds=1
   # SQL 的 Settings，目前建议配置为 timeout 的一些配置，单位为秒（s）。
   # 您也可以按需配置 s3_truncate_on_insert=true，表示如果存在原有文件，系统将删除这些，即覆盖原有文件。
   s3_insert_settings=send_timeout=3600, receive_timeout=3600, max_execution_time=3600,output_format_json_quote_64bit_integers=0
   # 文件格式及压缩配置
   file_format=Parquet
   data_compression_method=none
   # 需要导出的 ClickHouse 表引擎
   filter_tables_by_engine=MergeTree
   
   #### 并发参数，控制导出 SQL 在 ByteHouse 执行的并发
   parallelism=8
   

   配置 Key	类型	描述
   dryrun	int	设置是否启用 dryrun 模式，默认值为 0，表示不启用；设置成 1 表示只打印导出 SQL 但不实际执行。
   run_sql_mode	string	设置连接 ClickHouse 集群的方式，默认值为 driver，表示使用 Python ClickHouse driver 连接。 如果您的环境已安装 ClickHouse Client，可将设置为 cli，脚本将使用 ClickHouse Client 连接。
   clickhouse_host	string	ClickHouse 的地址，可以用逗号分割选择多个 shard 节点。
   clickhouse_port	string	ClickHouse 的端口，配置为 9000。
   clickhouse_user	string	ClickHouse 的用户名。
   clickhouse_password	string	ClickHouse 的密码。
   s3_access_key	string	存储导出文件的对象存储服务的 Access Key ID。 如果您使用的是火山引擎 TOS，获取方式可参考 Access Key（密钥）管理。
   s3_secret_key	string	存储导出文件的对象存储服务的 Secret Access Key。 如果您使用的是火山引擎 TOS，获取方式可参考 Access Key（密钥）管理。
   s3_url	string	导出文件在对象存储中的目标存储目录。格式示例如下： 导出到 TOS： # 公网 https://{bucket_name}.tos-s3-{region}.volces.com/some-dir # 私网 https://{bucket_name}.tos-s3-{region}.ivolces.com/some-dir 导出到其他对象存储服务： # AWS S3 s3_url=https://{bucket_name}.s3.{region}.amazonaws.com/some-dir # MinIO 或者其他对象存储 s3_url=http://{host}:{port}/{bucket_name}/some-dir
   database_name	string	ClickHouse 需导出的数据库名称。
   table_names	string	ClickHouse 数据库中需导出的表名称，如果需要导出多张表，可使用逗号分开。如果使用星号（*），则代表导出数据库中的所有表。
   field_rules	string	用于对特殊类型的数据进行导出预处理，可使用当前默认值，非特殊情况无需配置。如果有多个参数，可使用分号连接。 默认规则：针对不同位宽的 groupBitmap 聚合函数类型（如 AggregateFunction(groupBitmap, UInt8) 至UInt256 ），统一通过 bitmapToArray($Field$) 函数将位图数据转换为数组格式。 当前已配置的默认值如下： AggregateFunction(groupBitmap, UInt8):bitmapToArray($Field$);AggregateFunction(groupBitmap, UInt16):bitmapToArray($Field$);AggregateFunction(groupBitmap, UInt32):bitmapToArray($Field$);AggregateFunction(groupBitmap, UInt64):bitmapToArray($Field$);AggregateFunction(groupBitmap, UInt128):bitmapToArray($Field$);AggregateFunction(groupBitmap, UInt256):bitmapToArray($Field$)
   export_field_rules	string	用于定义特殊类型数据导出后的目标类型，可使用当前默认值，非特殊情况无需配置。如果有多个参数，可使用分号连接。 默认规则：针对不同位宽的 groupBitmap 聚合函数类型（如 AggregateFunction(groupBitmap, UInt8) 至 UInt256），指定导出后的数据类型为对应位宽的数组（如 Array(UInt8) 至 Array(UInt256)）。 当前已配置的默认值如下： AggregateFunction(groupBitmap, UInt8):Array(UInt8);AggregateFunction(groupBitmap, UInt16):Array(UInt16);AggregateFunction(groupBitmap, UInt32):Array(UInt32);AggregateFunction(groupBitmap, UInt64):Array(UInt64);AggregateFunction(groupBitmap, UInt128):Array(UInt128);AggregateFunction(groupBitmap, UInt256):Array(UInt256)
   split_in_partition	int	设置是否按照分区（partition）分割（split）导出。可设置为 1 或 0。 默认设置为 1，系统将按照分区分割导出数据。 设置为 0 时，系统将不按照分区分割导出，按照全表进行导出。
   selected_partitions	string	一般情况下，该参数无需设置。 当出现部分分区导出失败的情况时，可使用该参数选择指定分区执行导出操作，如果指定多个分区导出，分区间可使用逗号分隔。
   split_count	int	一般情况下，该参数建议设置为 -1，表示不执行分隔操作。 如果出现数据导出时性能不佳的情况，可使用该参数指定导出表时分割的文件数量，启用后，全表级别和分区级别均可生效，可用于导出加速。
   split_column	string	一般情况下，该参数无需设置。 如果出现数据导出时性能不佳的情况，可使用该参数指定用于数据分割的列。导出大量数据时，脚本工具将利用列的哈希值将数据分割成多个部分，加速导出。支持配置多个列，多个列名之间用逗号分隔，系统将按照顺序选择存在表中的数据，具体优先级如下： 优先级 1：优先选择在 Order By 中配置的离散列； 优先级 2：其次选择 int 或者 string 类型的列； 默认列：若以上均无，则默认选择 id。
   where	string	可使用该参数为某张表设置 filter 条件。 如果您需要为不同的表设置不同的筛选条件，请按照 table_names 进行细分，并为每张表生成新的配置文件执行导出任务。
   limit	string	可使用该参数为某张表配置条数限制条件。 如果您需要为不同的表设置不同的筛选条件，请根据 table_names 细分，并为每张表生成对应的配置文件执行导出任务。
   empty_status	int	断点续传能力开关，用于设置导出时是否参考之前的断点信息。默认为 0，表示参考之前的断点信息，即开启断点续传。设置为 1 时，本次导出时将不参考之前的断点信息。
   max_retries	int	失败后最大的重试次数，默认值为 10。
   retry_delay_seconds	int	每次重试延迟多久，默认值为 5，单位：秒。
   file_format	string	导出文件的格式，默认格式为 Parquet，也支持设置为 JSONEachRow。
   data_compression_method	string	导出文件的压缩方式，Parquet 设置为 none，JSONEachRow 设置为 gzip。
   s3_insert_settings	string	该设置用于避免导出超时，建议使用默认值： send_timeout=3600, receive_timeout=3600, max_execution_time=3600,output_format_json_quote_64bit_integers=0,s3_truncate_on_insert=true 参数说明如下： send_timeout：数据传输超时设置。建议使用默认值 3600，单位为秒。 receive_timeout：数据接收超时设置。建议使用默认值 3600，单位为秒。 max_execution_time：单次查询最长执行时间。建议使用默认值 3600，单位为秒。 output_format_json_quote_64bit_integers：控制 ClickHouse 以 JSON 格式输出时，是否用双引号包裹 64 位整数值。设置为 0 时，表示不包裹，输出数字格式；设置为 1 时，表示包裹，输出字符串格式。建议设置为 0。 s3_truncate_on_insert=true：导入时是否清空对象存储服务的目录。设置为 true 时，则会在每次导入时，清空对象存储服务的目录。建议设置为 true。
   filter_tables_by_engine	string	设置为需要导出的 ClickHouse 表引擎，支持设置为 MergeTree 和 ReplacingMergeTree。默认值为 ReplacingMergeTree。
   parallelism	int	设置并发导出的参数，代表并发数。默认为 4。

3. 运行 Python 脚本文件，即可将 ClickHouse 中的数据导出至对象存储服务中。
   运行前，请确保当前工作目录为脚本所在目录，或使用绝对路径指定脚本位置。

   python3 data-migrator-clickhouse-to-s3.py config-template-export.ini 
   

4. ClickHouse 数据导出后，检查对象存储中的导出的数据和目录是否符合预期。
   使用上述步骤导出的数据文件将以按照以下目录结构存储在对象存储中，您可按照以下示例路径，在您使用的对象存储服务中查看目录和数据是否符合预期。该示例展示了 AWS S3 的路径信息，TOS 和 MinIO 路径类似。

   https://{bucket_name}.s3.{region}.amazonaws.com/ck-to-bytehouse/{database_name}/{table_name}/{database_name}_{table_name}_{partition_id}_{hash_num_order}.JSONEachRow.gz 
   

（可选）步骤三：从源端公有云对象存储同步数据到 TOS #

本节演示了如何使用火山引擎迁移服务，将公有云对象存储中的数据迁移到火山引擎 TOS。如果您使用的对象存储服务为火山引擎 TOS，则可跳过本节，直接执行步骤四中的内容。

1. 使用火山引擎存储迁移服务将源端对象存储中的数据迁移到 TOS，操作步骤及参数说明详情请参见创建迁移任务-使用公共网络。
   源端及目标端配置注意事项如下：

   数据端	注意事项
   源端	配置源端时，请将源端桶名设置为步骤二中用于存储源端数据的存储桶名，文件前缀指定为准备工作中创建的源端对象存储目录名，详情请参考步骤二：ClickHouse 导出至对象存储。
   目标端	目的端写入模式选择为经典模式。目标端桶名设置为准备工作中设置的 TOS 存储桶名，详情请参考准备工作。

2. 创建迁移任务并开始迁移后，在迁移任务列表查看任务状态，等待迁移任务完成。
   

3. 迁移任务完成后，登录火山引擎 TOS 控制台，在对应存储桶中查看并确认数据已迁移。
   

步骤四：从 TOS 导入数据到 ByteHouse #

1. 下载导入脚本。
   

   

   run_clickhouse_to_bh.zip

   未知大小

   

2. 解压第一步中下载的脚本。

   unzip run_clickhouse_to_bh.zip
   cd run_clickhouse_to_bh
   chmod +x run_clickhouse_to_bh_all.sh
   chmod +x run_clickhouse_to_bh.sh
   

3. 配置 tables.txt 文件，填写源端 ClickHouse 的数据库、表名称。

   说明

   表名请使用分布式表名，不允许使用_local 本地表。

   db1.tbl1
   db1.tbl2
   db2.tbl1
   db2.tbl2
   

4. 修改 run_clickhouse_to_bh.sh 中的信息。

   #!/bin/bash
   
   ak=""
   sk=""
   region="cn-beijing" # cn-beijing,ce-shanghai,cn-guangzhou
   bucket_name="" # tos bucket name
   base_path="" # tos bucket path
   database=$1
   table=$2
   target_database=$1
   target_table=$2
   tos_file_path="./${target_database}_${target_table}-files.txt"
   internal=1
   
   hosts="" # bytehouse hosts，多个使用逗号分隔
   port="9000"
   user="" # bytehouse user
   password="" # bytehouse password
   unique_write_mode="upsert" # bytehouse unique_write_mode, upsert or append
   format="Parquet"
   max_threads="4"
   run_clickhouse_tos=1
   run_tos_to_bh=1
   if [[ $run_clickhouse_tos -eq 1 ]]; then
       ./clickhouse-tos/clickhouse-tos -i $ak -k $sk -r $region -b $bucket_name -o $base_path -d $database -t $table -n $internal > $tos_file_path
   
       if [ $? -ne 0 ]; then
           echo "clickhouse-tos failed"
           exit 1
       fi
       echo "clickhouse-tos finish"
   fi
   
   if [[ $run_tos_to_bh -eq 1 ]]; then
       ./tos2bh/tos2bh --hosts=$hosts --port=$port --user $user --password $password --tos_file_path=$tos_file_path --database=$target_database --table=$target_table --format=$format --unique_write_mode=$unique_write_mode --access_key=$ak --secret_key=$sk --max_threads=$max_threads --source doris
   
       if [ $? -ne 0 ]; then
           echo "tos2bh failed"
           exit 1
       fi
       echo "tos2bh finish"
   fi
   

5. 执行导入。

   run_clickhouse_to_bh_all.sh tables.txt
   

6. 执行完成后，成功和失败的文件将分别输出至 $tos_file_path.success.report 和 $tos_file_path.failed.report 文件中。如需重新执行导入脚本，以导入失败的数据，需要先清理相应的 report 文件。

7. 迁移完成后，您可以通过 ByteHouse 控制面执行数据查询操作，验证数据是否迁移成功，相关命令请参见数据校验。

行数校验 #

确认迁移前后同一库表、同一分区的行数完全一致，确保无数据遗漏/重复。

SELECT ${partition},count(*) FROM ${db}.${table} GROUP BY ${partition}

正确性校验 #

您可通过多种方式校验数据正确性，您可先确认需使用的方法，然后使用该方法对比迁移前后的数据正确性。例如，您可以随机选取一个数值列，通过对比该列的求和结果（sum (数值列)），验证数据是否一致。

--- 随机数值列 
SELECT c.name AS column_name
    FROM system.tables AS t
    INNER JOIN system.columns AS c ON (t.database = c.database) AND (t.name = c.table)
    WHERE (t.database = '{db}') AND (t.name = '{table}') AND ((c.type LIKE '%Int%') OR (c.type LIKE '%UInt%') OR (c.type LIKE '%Float%')) limit 1;
    
--- 数值列求和
select ${partition},sum(column) from ${db}.${table} group by ${partition}