You need to enable JavaScript to run this app.
导航
ByteHouse云数仓版
  • 文档首页
    • /ByteHouse云数仓版/用户指南/数据导入/导出/数据导出
数据导出
最近更新时间：2025.11.14 14:41:54首次发布时间：2023.07.12 18:15:03
复制全文
我的收藏
有用
有用
无用
无用

ByteHouse 数据导出功能可将数据高效、安全地迁移至对象存储或您的本地路径，满足您数据备份、离线分析和跨平台共享的需求。本文将详细介绍如何通过控制台、CLI、OpenAPI、IDE 工具等多种方式导出数据。

前提条件

在开始操作前，请确保您已经具备以下必要的权限和信息：

  • ByteHouse 云数仓服务的访问权限：
    • 建议具备 AccountAdmin 或 SystemAdmin 的角色。
    • 对新用户授予 ByteHouseFullAccess 的 IAM 策略，请参考权限授予。
  • 如果您想要导出数据到对象存储，请确保拥有以下权限：
    • 获取对象存储服务的 Access Key ID 与 Secret Access Key。如果您使用的是火山引擎对象存储服务（TOS），获取详情请参考 Access Key（密钥）管理。
    • 请在对象存储服务中创建好数据导出后的存储桶，同时，请确保您使用的用户拥有该存储桶拥有全读写权限。如果您使用的是火山引擎 TOS，操作详情请参见创建存储桶及授予桶权限。
    • 如果使用火山引擎 TOS 过程中出现 “Access Denied” 报错，请排查权限问题，详情请参考对象存储 Access Denied 排查建议。

注意事项
  • 将数据导出至对象存储服务时，ByteHouse 支持同地域及跨地域导出，两种方式导出方式一致，且均通过公网访问，因此会产生相关费用。建议您在使用前详细了解您使用服务的计费规则。
  • ByteHouse 支持通过命令和 IDE 工具导出数据，不同方式适用场景如下：
    • 通过命令导出：导出到对象存储服务。
    • 通过 IDE 工具导出：导出到本地。

准备工作

ByteHouse 支持通过控制台、ByteHouse CLI 工具、OpenAPI、IDE 工具导出数据，您可按需选择导出工具。在开始导出前，请确保您已准备好所需工具，并连接至 ByteHouse。

工具

安装及连接文档

ByteHouse CLI 工具

您可参考以下文档安装 ByteHouse CLI，并连接至 ByteHouse：

OpenAPI

您可参考调用方式文档，获取连接地址，连接至 ByteHouse。

IDE 工具

您可使用 IDE 工具连接至 ByteHouse，并导出数据。

通过 SQL 导出

语法

数据导出功能由以下 SQL 语句实现，您可配合 ByteHouse 控制台、ByteHouse CLI、OpenAPI 等工具使用。

SELECT <expr_list> 
FROM db.table
INTO OUTFILE 'destination://file_path/file_name'
[FORMAT format_name] [COMPRESSION compression_name] SETTINGS setting_name

参数说明

参数项

是否必填

说明

<expr_list>

是

指定要导出的数据。

db.table

是

指定数据所在的数据库、表名称。

destination://file_path/file_name

是

指定存储导出文件的对象存储路径和导出文件名称，示例：

  • TOS：vetos://my-testing/data/data-export-test.csv
  • 其他对象存储：s3://bucket/test_outfile.csv

请确保您拥有该存储路径的读写权限。如果您想要导出至 TOS，您可通过 TOS 控制台 > 桶列表 > 权限管理 > 存储桶授权策略管理，查看您是否具有全读写权限。如果您缺少相关权限，可参考 TOS 文档为用户配置 TOSFullAccess 权限。

FORMAT

否

指定导出文件的格式。支持导出为 JSON，TSVWithNames，TSV，CSV，CSVWithNames，JSONEachRow，Parquet，ORC 等常用格式。

COMPRESSION

否

指定导出文件的压缩格式。当前支持的压缩文件类型包括 none，gzip，deflate，br，xz，zstd。

SETTINGS

是

使用 settings 参数配置导出至火山引擎 TOS 的访问信息：

如果您使用了其他对象存储服务，可使用以下 settings 参数配置访问信息：

  • s3_ak_id：对象存储服务的 Access Key ID，您可参考您使用的对象存储服务的官方文档获取 Access Key ID。
  • s3_ak_secret：对象存储服务的 Secret Access Key，您可参考您使用的对象存储服务的官方文档获取 Secret Access Key。
  • s3_region：对象存储服务所属的地域（region） ID，您可参考您使用的对象存储服务的官方文档获取地域。格式示例：oss-cn-beijing、cn-northwest-1。
  • s3_endpoint：对象存储服务的访问域名，您可参考您使用的对象存储服务的官方文档获取访问域名。格式示例：http://s3.eu-west-1.amazonaws.com、https://oss-cn-beijing.aliyuncs.com。
  • s3_use_virtual_hosted_style：设置存储桶的访问方式，默认值为 false，表示使用路径访问风格（path style）访问存储桶。

导出数据示例

使用 ByteHouse 控制台导出

ByteHouse 支持通过配置对象存储的路径及参数，实现文件导出，可以提供更加稳定、可落盘的导出方案。

  1. 在 ByteHouse 控制台 SQL 工作表页面执行如下语句进行 TOS 数据导出。参数配置请参见参数说明。

    SELECT * FROM db.table
   INTO OUTFILE 'vetos://my-testing/data/data-export-test.csv' 
   FORMAT CSV COMPRESSION 'none'
   SETTINGS 
   tos_access_key = '{YOUR_TOS_ACCESS_KEY}', 
   tos_secret_key = '{YOUR_TOS_SECRET_ACCESS_KEY}',
   tos_region = '{YOUR_REGION_ID}',
   tos_endpoint = 'http://tos-s3-{REGION}.ivolces.com'

  2. 导出完毕后，访问对象存储桶对导出数据进行查看文件是否成功导出。

使用 ByteHouse CLI 导出

  1. 连接至 ByteHouse。

    bytehouse-cli --host tenant-{TENANT_ID}-{REGION}[-{ENVIRONMENT}]-public.bytehouse.volces.com --port 19000 --secure --token XXXXXXXXXXXXX

    参数项

    是否必填

    配置说明

    --host

    是

    集群的访问地址和端口。您可以在 ByteHouse 控制台的租户管理 > 基本信息 > 网络信息中查看网络组配置，详情请参见步骤二：配置网络信息。

    --port

    是

    集群访问地址的端口。端口默认值为 19000，其他常用连接方式所使用的端口请参见集群连接端口。

    --token

    是

    集群的访问密钥，配置为 API Key。您可登录 ByteHouse 控制台，在租户管理 > 连接信息页面中，单击 API Key 表单下的”新建“按钮，创建 API Key。

    注意

    API Key 创建后无法再次查看，建议将秘钥下载到本地保存；
    最多可以创建 2 个 API Key；
    秘钥需要在 90 天内进行刷新以确保安全性。

    --secure

    视情况而定

    定义是否要用 Secure TCP 连接。如果是连接到火山引擎托管的 ByteHouse，则 --secure 为必选字段。默认为 true。

    其他

    否

    更多可选参数配置请参考连接到 ByteHouse。

  2. 使用 ByteHouse CLI 在终端执行如下语句，导出数据。参数配置请参见参数说明。

    SELECT * FROM db.table
   INTO OUTFILE 'vetos://my-testing/data/data-export-test.csv' 
   FORMAT CSV COMPRESSION 'none'
   SETTINGS 
   tos_access_key = '{YOUR_TOS_ACCESS_KEY}', 
   tos_secret_key = '{YOUR_TOS_SECRET_ACCESS_KEY}',
   tos_region = '{YOUR_REGION_ID}',
   tos_endpoint = 'http://tos-s3-{REGION}.ivolces.com'

  3. 访问存储路径，查看文件是否成功导出。如果出现系统报错，可参考常见问题排障。

使用 OpenAPI 调用导出

API 导出通过调用 /sql/sync 实现，更多 API 操作说明请参考 ByteHouse API 列表。
导出数据示例如下：

curl --request POST      --url https://bytemart-{REGION}.bytehouse.volcbiz.com/v1/sql/sync      --header 'accept: application/json'      --header 'authorization: Bearer {accesstoken}'      --header 'content-type: application/json'      --data @- <<EOF
{
  "mode": "ansi_sql",
  "query": "SELECT * FROM db.table INTO OUTFILE 'vetos://my-testing/data/data-export-test.txt' SETTINGS tos_access_key = '{YOUR_TOS_ACCESS_KEY}', tos_secret_key = '{YOUR_TOS_SECRET_ACCESS_KEY}', tos_region = '{YOUR_REGION_ID}', tos_endpoint = 'http://tos-s3-{REGION}.ivolces.com'",
  "vwID": "vw-{environment_id}{account_id}-{virtual_warehouse_name}"
}
EOF

参数

是否必填

配置说明

url

是

OpenAPI URL。该 URL 中不同区域的地址不同，可参考 API 列表 给出的可用区链接获取。例如，华东2（上海）可用区需替换为 --url https://bytemart-cn-shanghai.bytehouse.volcbiz.com/v1/sql/sync。

authorization: Bearer {accesstoken}

是

ByteHouse API Key，可通过 ByteHouse 云数仓版控制台 > 租户管理 > 连接信息路径获取。

mode

是

SQL 语言模式，可设置为 "ansi_sql" 或 "clickhouse_sql"。

query

是

导出数据的 SQL 命令，请使用实际的数据库、表、对象存储路径、Access Key ID、Secret Access Key、地域等信息替换示例命令中的占位符，获取方式请参见参数说明。

vwID

是

计算组 ID，指定执行此SQL查询所使用的计算资源组。可通过 ByteHouse 云数仓版控制台 > 计算组路径，查看并复制计算组 ID。格式示例：vw-{environment_id}{account_id}-{virtual_warehouse_name}

使用 IDE 工具导出数据

您可以使用第三方 IDE 工具，如 DataGrip 和 DBeaver，连接到 ByteHouse 并导出数据。

  1. 使用 IDE 工具连接至 ByteHouse，操作详情请参见以下文档：

    工具

    文档链接

    DataGrip（TCP）

    DataGrip（TCP）

    DataGrip（ClickHouse）

    DataGrip（ClickHouse）

    DataGrip（MySQL）

    DataGrip（MySQL）

    DBeaver（ClickHouse）

    DBeaver（ClickHouse）

    DBeaver（TCP）

    DBeaver（TCP）

    DBeaver（MySQL）

    DBeaver（MySQL）

    Navicat（MySQL）

    Navicat（MySQL）

    TablePlus（MySQL&ClickHouse）

    TablePlus（MySQL&ClickHouse）

  2. 执行查询语句以获得需要导出的结果集。

  3. 通过 IDE 工具中的导出按钮导出数据。
    以 DBeaver 为例，完成查询后，在查询结果视图中，单击导出数据，按照界面提示设置导出目标、抽取、格式、导出路径等信息，单击继续，即可导出数据至指定路径。
    Image

常见问题

Q1：导出到 TOS 报错 InvalidPathAccess Message: Forbidden path to access server

指定参数 s3_use_virtual_hosted_style = 1。TOS 仅支持虚拟主机风格（Virtual Hosted Style）访问存储桶，因此需配置 s3_use_virtual_hosted_style = 1。

Q2：导出到 TOS 报错 Invalid tos region: xxx

可能是 ByteHouse 引擎尚未支持 SQL 使用的 TOS 可用区。此时，可手动指定 TOS endpoint，示例如下：

SELECT * FROM db.table
INTO OUTFILE 'vetos://my-testing/data/data-export-test.txt' 
SETTINGS 
tos_access_key = '<YOUR_TOS_ACCESS_KEY>', 
tos_secret_key = '<YOUR_TOS_SECRET_ACCESS_KEY>',
tos_region = '{REGION}'
tos_endpoint = 'http://tos-s3-{REGION}.ivolces.com'

更多可用区的 TOS endpoint 请参见地域和访问域名（endpoint），填入命令时，请使用表格中的 S3 Endpoint。

Q3：导出到 TOS 报错 URI is not allowed in config.xml

ByteHouse 从引擎 v2.3.1.xx（2025年6月发布）开始针对 endpoint 加了一些正则的限制，需检查 endpoint 是否符合以下正则的要求：

注意

Endpoint 需要添加 http 或者 https 协议，格式为 http[s]://endpoint，例如 http://tos-s3-cn-beijing.volces.com

<host_regexp_1>.*[.]volces[.]com</host_regexp_1>
<host_regexp_2>.*[.]ivolces[.]com</host_regexp_2>
<host_regexp_3>.*[.]volcbiz[.]com</host_regexp_3>
<host_regexp_4>.*[.]amazonaws[.]com</host_regexp_4>
<host_regexp_5>.*[.]amazonaws[.]com[.]cn</host_regexp_5>
<host_regexp_6>.*[.]googleapis[.]com</host_regexp_6>
<host_regexp_7>.*[.]aliyuncs[.]com</host_regexp_7>
<host_regexp_8>.*[.]azure[.]com</host_regexp_8>
<host_regexp_9>.*[.]tencentcloudapi[.]com</host_regexp_9>
<host_regexp_10>.*[.]myhuaweicloud[.]com</host_regexp_10>
<host_regexp_11>.*[.]bytepluses[.]com</host_regexp_11>
<host_regexp_12>.*[.]ibytepluses[.]com</host_regexp_12>

Q4：导出指定压缩报错：Syntax error: failed at position 75 ('COMPRESSION')

建议按照以下语法顺序：

SELECT xxx INTO OUTFILE FORMAT xxx COMPRESSION xxx