ByteHouse 支持通过对象存储服务（如 S3、火山引擎对象存储服务 TOS、阿里云 OSS）实现离线数据导入，适用于大量数据的批量加载，当前支持导入 CSV、JSON、AVRO、PARQUET 文件类型。

从 2025年10月开始，ByteHouse 控制台执行数据导入任务需配置计算组，开始导入前，请确认您具有需使用的计算组的使用（USE）权限。您可通过权限管理 > 用户 > 用户列表路径，单击用户名，在用户详情页中的资源权限下查看获得的计算组权限。如果尚未获得授权，请联系管理员配置，详情请参考资源权限管理。

1. 在 ByteHouse 控制台，单击数据加载页签，单击新建导入任务按钮，进入任务创建界面。
   

2. 填写导入任务基本信息，自定义任务名称和任务描述。
   

3. 选择数据源类型为对象存储，选择供应商，并从下拉列表中选择已创建的数据源。
   
   如果您尚未创建数据源，可单击连接新的数据源，新建并配置数据源，单击连接。不同供应商所需配置的数据源连接信息不同，请以实际界面为准。
   

   配置项	TOS	S3	Alibaba OSS
   源名称	自定义数据源名称。
   开启路径访问模式	无	启用后，支持通过路径访问模式访问指定存储桶。如果不启用，将使用虚拟主机风格（Virtual Hosted Style）。
   访问密钥	配置为火山引擎 TOS 服务的访问密钥（Access Key），获取方式请参见 AccessKey（密钥）管理。	配置为 S3 服务的访问密钥（Access Key），您可登录 S3 服务控制台或联系管理员获取。	配置为 Alibaba OSS 服务的 AccessKey ID，获取方式请参见创建 AccessKey。
   密钥	配置为火山引擎 TOS 服务的密钥（Secret Key），获取方式请参见 AccessKey（密钥）管理。	配置为 S3 服务的密钥（Secret Key），您可登录 S3 服务控制台或联系管理员获取。	配置为 Alibaba OSS 服务的 AccessKey Secret，获取方式请参见创建 AccessKey。
   默认地域	配置为 TOS 服务所在的地域，详情请参见地域和访问域名（Endpoint）。	无	配置为 Alibaba OSS 服务所在的地域，详情请参见 OSS 地域和访问域名。

4. 选择数据源后，配置数据源详细信息，包括存储桶、schema 样例文件路径、存储桶路径、格式等。不同数据源类型，所需配置的数据源详细信息不同，请以实际界面为准。以下是全量参数配置说明：

   参数项	配置说明
   地域	配置为对象存储数据源所在的地域。
   存储桶	选择数据源所在的存储桶。
   Schema 样例文件路径	设置 schema 样例文件，用于后续 schema 解析及生成导入配置。
   存储桶路径	设置导入任务的文件路径前缀，该任务可以导入在该文件路径前缀下任意与样例文件 schema 相同的文件。
   格式	ByteHouse 支持的文件格式有 CSV、JSON、AVRO、Parquet，系统将根据您选择的 schema 样例文件格式自动匹配。 对于 CSV 和 JSON 文件，您可以选择配置对应的格式参数，详见下表说明。

   如果您上传的是 CSV 或 JSON 格式的文件，需配置对应的格式参数。

   格式	配置项	配置说明
   CSV	表头	支持设置为无表头或有表头。 无表头：ByteHouse 将使用 “_c0，_c1” 作为源列名来映射模式与目标表。 有表头：ByteHouse 将分离表头来映射模式到目标表上。
   	CSV 格式	支持设置分隔符、引用字符、跳过行数、Null Value、编码、转义符、多行支持、忽略空格等。
   JSON	多行支持	设置是否启用多行支持。启用多行支持表示文件中的每个 JSON 对象（代表一行）都按单独的行进行格式化。这与'JSON Lines'不同，其中 JSON 对象被展平为每个对象的一行。
   	允许注释	设置是否允许在文件中使用注释。

5. 选择导入的目标数据库和表。
   

6. 定义 Schema 映射。设置数据源和目标表后，系统会自动填充 Schema 映射表，生成数据源与目标表的映射关系。ByteHouse 当前支持以下 Schema 映射配置操作，您可按需调整生成的 Schema 映射。
   

   • 调整 Schema 映射逻辑
     如果生成的 Schema 不符合预期或者您需要调整源列与目标列的映射关系，您可单击解析，系统将重新解析。
   • 调整目标表
     您可打开新的浏览器标签页，进入数据库页面并调整目标表，调整后，在数据导入页面中定义 Schema 映射模块单击刷新目标表，系统将自动读取目标表的调整并更新 Schema 映射表。
   • 日期解析格式配置
     ByteHouse 数据导入默认支持自动解析的日期格式为：yyyy-MM-dd'T'HH:mm:ss ( Java 默认的时间格式），注意年月日和十份秒中间用常量 T 隔开。如果您的数据使用其他格式，则需要手动配置，配置操作请参见如何配置日期解析格式？。
   • 时区配置
     如果您需要导入的数据包含带有日期的字段且该日期包含时区信息，请参考导入文件时如何配置时区？调整数据格式，避免时区导入异常。

7. 配置导入任务的加载类型，您可按需选择增量写入或全量覆盖写。
   

   • 增量写入：在每次执行作业中，数据将被增量写入到目标表，存量数据不会被覆盖。
   • 覆盖写入：用最新的数据替换整个目标表，可以选分区覆盖或者全量覆盖。选择分区覆盖写前，需确认目标表定义了分区键。
   • 计算组：从下拉列表选择导入任务使用的计算组。请确保您拥有该计算组的使用权限。

   注意

   如果您选择新建一个同步表，则该表和导入任务会依次进行创建，因此可能会出现导入任务创建失败但是表创建成功的场景。如果您遇到了类似情况，请退回至步骤 6，选择导入至已有表中进行导入。

8. 单击创建，即可生成导入任务。导入任务创建后，系统将跳转至任务详情页面，此时任务将处于暂停状态，您可单击开启，启动任务。
   

9. 在启动作业弹窗中，确认需上传的文件名，单击确定，系统将执行数据加载任务。
   如果您有新文件需上传，您可从下拉列表中选择并替换。以下为 TOS 为导入数据源时的界面示例：
   
   对象存储作业支持启用通配搜索，启用后，模糊搜索文件并导入多个文件，支持情况如下：

   • 支持星号（*）匹配零个或多个任意字符。
   • 支持问号（?）匹配不多于问号个数的任意字符。
   • 支持方括号（[ ]）匹配在此范围内的任意字符。

在数据加载页面，您可以通过任务视图查看已创建的所有任务。

您也可以通过执行视图查看任务执行状态，查看任务执行日志和配置。当任务类型为成功状态时，即可进行数据查询。

• 查看任务执行日志
  单击目标任务行的日志按钮，查看当前任务的执行日志，您可单击复制或下载日志。
  
• 查看配置
  单击目标任务行的配置按钮，查看当前任务的执行日志，您可单击复制或下载配置 JSON 文件，可用作通过 OpenAPI 导入数据的配置参考。
  
• 排查导入任务
  如果要对已经导入的任务进行排查，可单击任务名称，单击同步历史记录下的执行 ID，查看导入状态、错误详情、日志等详细信息，便于对导入情况进行判断和优化。
  

1. 在任务列表中，单击源类型下拉列表，选择您的存储服务供应商，筛选导入任务。
2. 单击目标任务行的开启按钮，启动当前导入任务。
   
3. 单击任务名称，进入任务详情页面，可查看任务同步历史记录和当前配置的 schema 映射、日志、配置。
   
4. 如果需要停止导入任务，可单击停止。

1. 在任务列表中，单击源类型下拉列表，选择您的存储服务供应商，筛选导入任务。
2. 单击目标任务行的编辑按钮，进入导入任务配置页面。
   
3. 按需调整任务配置，编辑完成后，单击更新。

如果您需要通过 OpenAPI 导入数据，可复制任务配置作为配置参考。
操作步骤：

1. 在任务列表中，单击源类型下拉列表，选择您的存储服务供应商，筛选导入任务。
2. 单击目标任务行的 ... 按钮，单击复制配置，系统将复制当前导入任务的配置。
   

在任务列表中，单击目标任务行的 ... 按钮，单击删除任务，确认后即可删除当前任务。