ByteHouse 云数仓版支持通过对象表管理对象存储中非结构化数据的元信息，适用于多模态数据管理场景。本文将介绍如何通过 SQL 语句和控制台可视化界面管理对象表。

功能概述

对象表（Object Table）是 ByteHouse 云数仓版中的特殊表类型，用于获取对象存储中非结构化数据（如文本、图像等）的元信息（不存储原始数据）。对象表通过读取对象存储指定路径下文件中的元数据，生成索引并映射为固定表结构，表中字段与对象存储中的文件一一对应。
当前 ByteHouse 仅支持读取来自火山引擎对象存储 TOS 中的对象元信息，通常采用固定表结构，包含以下内容：

建表配置与同步逻辑

• 建表配置：建表时，需指定对象存储目标路径，并配置刷新策略。建表后，您也可通过修改表属性修改刷新策略和对象存储相关信息，操作详情请参见修改对象表。
• 同步逻辑：ByteHouse 当前支持异步刷新和同步（手动）刷新：
  • 异步刷新将根据您在建表时设置的定时规则执行全量更新，将目标路径的最新元数据同步到表中。ByteHouse 也支持手动临时触发刷新。
  • 同步（手动）刷新需要通过 REFRESH TABLE 语句或控制台按钮手动触发。
  • 刷新操作请参见以下文档：
    • REFRESH TABLE 语句：刷新对象表
    • 控制台按钮手动触发：手动刷新对象表

支持功能
ByteHouse 支持通过 SQL 语句或控制台可视化界面便捷管理对象表，当前支持的功能说明如下：

应用场景

对象表适用于多模态数据管理（如 AI 场景下的图像、文本等非结构化数据）场景，可提升数据管理效率、增强业务适配灵活性，同时保障数据存储安全。

费用说明

• 对象表在 ByteHouse 侧将产生计算费用和元数据的存储费用，遵循 ByteHouse 计算资源计费规则。
• 使用对象表功能时，对象表的数据不会复制一份存在 ByteHouse 上并产生存储费用。存储费用请关注对象表数据源存储侧计费规则。
• 使用 ByteHouse 对象表访问对象表数据源时，对象表数据源可能会产生计算、访问、数据传输等费用，具体以对象表数据源计费方式为准，请关注相应产品的说明。

• 该功能为 Beta 功能，请联系提交工单或联系 ByteHouse 团队获取白名单权限。
• 该功能要求 ByteHouse 引擎版本为 2.3.3 及以上。使用前请确认您的引擎版本满足此要求，可通过 ByteHouse 控制台的租户管理 > 基本信息页面查看当前引擎版本。如果您的引擎版本不符合要求，可提交工单，联系 ByteHouse 团队升级引擎。

使用对象表前，请获取火山引擎对象存储服务 TOS 的相关权限和连接信息。

本节将介绍如何使用 SQL 语句创建、刷新、修改对象表。

创建对象表

创建对象表时无需指定表结构，这是因为对象表可按照固定模式读取对象存储数据的元信息，并自动生成表结构，更多说明请参见功能概述。
建表后，您可通过查看表结构的 SQL 语句，查看某张对象表的表结构，详情请参见查看对象表结构。您也可通过 ByteHouse 控制台查看，详情请参见查看对象表。

语法

CREATE OBJECT TABLE [IF NOT EXISTS] [db.]ob_table_name
ENGINE = CnchMergeTree
REFRESH = [ASYNC [EVERY (INTERVAL refresh_interval) ] | MANUAL]
PROPERTIES 
    [type = 'TOS'],
    region = 'region',
    endpoint = 'end_point',
    access_key_id = 'access_key_id',
    secret_access_key = 'secret_access_key',
    locations = ['bucket_name/[folder_name]/*', ...]
[COMMENT comment]

以下示例展示 ByteHouse 云数仓版对象表的创建方法，涵盖不同文件路径匹配、数据刷新模式（手动 / 自动）等典型场景。执行示例语句前，将示例中的占位符（如地域、访问端点、访问密钥、存储桶名称、文件路径等）替换为您的对象存储实际配置信息。

示例 1：locations 仅指定 bucket

locations 仅指定对象存储桶（bucket）时，创建的对象表将遍历该存储桶中的所有子目录。

CREATE OBJECT TABLE test_ob.ob_demo_1
ENGINE = CnchMergeTree
REFRESH ASYNC EVERY (INTERVAL 10 SECOND) 
PROPERTIES
   region = 'your_region',
   endpoint = 'https://tos-your-region.volces.com',
   access_key_id = 'your_access_key_id',
   secret_access_key = 'your_secret_access_key',
   locations = 'bh-demo-bucket';

示例 2：locations 使用通配符

locations 指定对象存储桶（bucket）并使用通配符时，创建的对象表将遍历该存储桶中的所有子目录，效果与示例 1 一致。

CREATE OBJECT TABLE test_ob.ob_demo_2
ENGINE = CnchMergeTree
REFRESH ASYNC EVERY (INTERVAL 10 SECOND) 
PROPERTIES
   region = 'your_region',
   endpoint = 'https://tos-your-region.volces.com',
   access_key_id = 'your_access_key_id',
   secret_access_key = 'your_secret_access_key',
   locations = 'bh-demo-bucket/*';

示例 3：locations 指定路径和文件格式

locations 精准指定子目录，并通过后缀筛选文件格式，对象表仅读取该目录下符合格式的文件。

CREATE OBJECT TABLE test_ob.ob_demo_3
ENGINE = CnchMergeTree
REFRESH ASYNC EVERY (INTERVAL 10 SECOND) 
PROPERTIES
   region = 'your_region',
   endpoint = 'https://tos-your-region.volces.com',
   access_key_id = 'your_access_key_id',
   secret_access_key = 'your_secret_access_key',
   locations = 'bh-demo-bucket/test/*.pdf';

示例 4：手动刷新

CREATE OBJECT TABLE test_ob.ob_demo_4
ENGINE = CnchMergeTree
REFRESH MANUAL
PROPERTIES
   region = 'your_region',
   endpoint = 'https://tos-your-region.volces.com',
   access_key_id = 'your_access_key_id',
   secret_access_key = 'your_secret_access_key',
   locations = 'bh-demo-bucket/test/*.pdf';

示例 5：指定多个文件夹

locations 配置同一存储桶下的多个路径，对象表会遍历所有指定路径，并筛选符合格式的文件，适合需读取分散在多个目录的同类型数据。

CREATE OBJECT TABLE test_ob.ob_demo_5
ENGINE = CnchMergeTree
REFRESH ASYNC EVERY (INTERVAL 10 SECOND) 
PROPERTIES
   region = 'your_region',
   endpoint = 'https://tos-your-region.volces.com',
   access_key_id = 'your_access_key_id',
   secret_access_key = 'your_secret_access_key',
   locations = 'bh-demo-bucket/test1/*,bh-demo-bucket/test2/*.pdf';

查看对象表

对象表的查看操作和普通表的操作一致。

查看表结构

语法

DESCRIBE TABLE [db.]ob_table_name

示例

DESCRIBE TABLE test_ob.ob_demo_1

查看建表 DDL 信息

语法

SHOW CREATE TABLE [db.]ob_table_name

示例

SHOW CREATE TABLE test_ob.ob_demo_1

刷新对象表

建表后，您也可通过 REFRESH 命令触发对象表刷新操作，支持同步刷新和异步刷新。您也可通过 ByteHouse 云数仓版控制台手动执行刷新，详情请参见刷新对象表。
建表时配置的 REFRESH 策略定义了对象表的默认数据同步规则，建表后，您可通过 REFRESH OBJECT TABLE 命令按需手动触发刷新操作。该命令支持同步（SYNC）和异步（ASYNC）两种执行方式，满足不同场景的刷新需求。

语法

REFRESH OBJECT TABLE [db.]ob_table_name [SYNC | ASYNC];

示例 1：建表配置异步刷新

以下示例中，建表后，系统会立即启动“10 秒一次的自动异步刷新任务”，同时您也可通过手动命令触发刷新。

CREATE OBJECT TABLE test_ob.ob_demo_1
ENGINE = CnchMergeTree
REFRESH ASYNC EVERY (INTERVAL 10 SECOND) 
PROPERTIES
   region = 'your_region',
   endpoint = 'https://tos-your-region.volces.com',
   access_key_id = 'your_access_key_id',
   secret_access_key = 'your_secret_access_key',
   locations = 'bh-demo-bucket/test1/*';

如需手动触发刷新任务，可执行以下命令：

• 手动触发异步刷新任务

  REFRESH OBJECT TABLE test_ob.ob_demo_1 ASYNC
  

• 手动触发同步刷新任务

  REFRESH OBJECT TABLE test_ob.ob_demo_1 SYNC
  

示例 2：建表配置同步刷新

以下示例中，建表时配置了同步刷新策略，系统无自动刷新动作，仅能通过 REFRESH OBJECT TABLE 命令触发数据同步。

CREATE OBJECT TABLE test_ob.ob_demo_2
ENGINE = CnchMergeTree
REFRESH MANUAL
PROPERTIES
   region = 'your_region',
   endpoint = 'https://tos-your-region.volces.com',
   access_key_id = 'your_access_key_id',
   secret_access_key = 'your_secret_access_key',
   locations = 'bh-demo-bucket/test1/*';

建表后无任何自动刷新动作，首次查询对象表时无数据返回。

此时，您可以通过手动执行刷新命令，读取数据。

• 手动触发异步刷新任务

  REFRESH OBJECT TABLE test_ob.ob_demo_2 ASYNC
  

• 触发同步刷新任务

  REFRESH OBJECT TABLE test_ob.ob_demo_2 SYNC
  

刷新后，再次查询对象表，此时表中已有数据。

查询对象表

对象表的查询和普通表的查询操作一致。

SELECT * FROM [db.]ob_table_name WHERE xxx;

修改对象表

创建对象表后，ByteHouse 支持通过 ALTER TABLE 语句调整对象表的核心配置，包括刷新策略（REFRESH）和对象存储关联属性（PROPERTY），无需重建表即可适配业务场景变更（如数据刷新频率调整、对象存储密钥轮换、数据路径迁移等）。

语法

ALTER TABLE [db.]ob_table_name MODIFY REFRESH|PROPERTY expr

示例 1：将刷新策略从手动刷新修改为异步刷新

ALTER TABLE test_ob.ob_demo_1 MODIFY REFRESH ASYNC EVERY(INTERVAL 10 second);

示例 2：将刷新策略从异步刷新修改为手动刷新

ALTER TABLE test_ob.ob_demo_2 MODIFY REFRESH MANUAL

示例 3：修改表属性

ALTER TABLE test_ob.ob_demo_2 MODIFY PROPERTY region = 'your_new_region',
   endpoint = 'https://tos-your-new-region.volces.com',
   access_key_id = 'your_new_access_key_id',
   secret_access_key = 'your_new_secret_access_key',
   locations = 'bh-demo-bucket-new/*'

删除对象表

对象表的删除和普通表的操作一致。

DROP TABLE [db.]ob_table_name;

您可在 ByteHouse 云数仓版控制台上管理对象表，支持通过 SQL 工作表执行对象表创建和使用语句，也支持在数据库页面查看已创建的对象表、查看建表 DDL、手动执行刷新对象表。

通过 SQL 工作表创建和使用对象表

在 ByteHouse 云数仓版控制台上，您可在 SQL 工作表中使用上述章节中的 SQL 语句创建并使用对象表。更多 SQL 工作表的使用详情请参见使用 SQL 工作表。

查看对象表

对象表创建完成后，您可单击顶部数据库，在数据库列表中找到目标数据库，单击目标数据库名称，在数据库详情页单击对象表页签，查看当前数据库中已创建的对象表。

您可单击对象表名称，进入对象表详情页面，查看对象表的列、同步任务情况。

查看对象表的建表 DDL

您可在对象表详情页面上单击 DDL 按钮，查看建表 DDL。

手动刷新对象表

您可在对象表详情页面，单击同步任务，单击手动执行，系统将自动刷新对象表。