概述
DataBuddy 数据目录除了管理内部托管的资产（表、卷、模型）外，还支持将 外部数据 纳入治理体系。外部数据管理包含两类对象：
External Location（外部存储） ：将一段腾讯云 COS 路径注册为治理对象，作为创建外部 Volume 或外部表的存储入口，统一管理跨工作空间的存储授权。
External Catalog（外部数据目录 / Foreign Catalog） ：基于已配置的数据源连接（Connection）创建的「镜像」型 Catalog。它不存储数据，仅同步外部数据源的元数据，让用户可以像访问内部 Catalog 一样查询外部数据库。
本文介绍这两类对象的创建与管理方法。
前提条件
已开通 DataBuddy 服务并完成空间初始化。
创建 External Location 需要 控制台管理员 角色。
创建 External Catalog 需要先在 数据源 中创建 Connection，并具备 Connection 的 owner 权限或被授予的相应权限。
已在 CAM 中配置好 TC Catalog 服务角色（
ccatalog_QCSLinkedRoleInMetadataManagement），并为其分配 COS 访问权限（cos:* action / cos:* resource）。使用限制
限制项 | 说明 |
存储类型 | External Location 当前仅支持腾讯云 COS |
创建 External Location 权限 | 仅控制台管理员可创建；其他用户对应入口置灰 |
路径唯一性 | 同一 COS 路径不可重复注册 |
External Catalog 数据源范围 | 当前仅支持 TencentDB PostgreSQL ；MySQL、Hive、TCHouse-D 等数据源在后续版本逐步支持 |
External Catalog 操作 | Foreign Catalog 是只读镜像，不支持在 Catalog 内创建 / 修改 Schema、表；表的 DDL 与数据写入必须在源数据库中执行 |
External Catalog 表详情 | 不展示「表变更历史」「血缘」Tab；保留概览、详情、数据预览、权限、工作空间 Tab |
External Location 管理
创建 External Location
步骤 1：进入外部存储页面
1. 登录 DataBuddy 控制台，切换到目标工作空间。
2. 在左侧导航栏选择 数据目录 。
3. 在顶部点击 外部数据 ，进入外部数据管理页。
4. 切换到 外部存储 Tab。
步骤 2：创建外部存储
1. 在外部存储页面右上角点击 创建 。
2. 在创建页面填写参数：
服务角色 ：从已配置的 TC Catalog 服务角色中提取，目前固定为 ccatalog_QCSLinkedRoleInMetadataManagement。
存储类型 ：当前仅支持 腾讯云 COS 。
存储地址 ：从下拉中选择目标 COS Bucket 路径地址。
描述 ：可选，便于团队协作。
1. 点击 创建 提交。
平台会调用 COS API（
ListBucket）执行以下校验：Bucket 是否存在。
路径是否与已注册的 External Location 重复。
服务角色是否未被云策略拒绝访问该路径。
校验失败时会展示具体错误（例如：「平台服务角色无权访问该路径，请联系云管理员检查 CAM 策略」）。校验通过后页面顶部提示「创建成功」。
注意
默认策略 ：External Location 创建时默认对所有用户授予
browse 权限，对所有工作空间授予访问权限。如需限制范围，请在创建后到权限页调整。External Location 列表页
在 数据目录 > 外部数据 > 外部存储 页面，您可以：
通过名称搜索框对名称做模糊搜索。
在列表中查看名称、URL、创建人、创建时间、描述。
点击右上角 创建外部存储 进入创建页（仅控制台管理员可点击；其他用户置灰，hover 提示「仅控制台管理员可创建外部存储」）。
External Location 详情页
点击列表中的 External Location 名称，进入详情页：
区域 | 内容 |
顶部面包屑 | 外部数据管理 > 外部存储名称 |
操作 | 重命名 、删除 |
基本信息 | 描述（可编辑）、存储类型、URL、创建时间、创建人 |
权限 Tab | 该 External Location 的授权情况 |
重命名、删除
在详情页右上角：
重命名 ：弹窗修改名称后保存。
删除 ：二次确认后删除注册信息。
警告
删除 External Location 仅解除 DataBuddy 的注册关系，不会 删除 COS 上的实际文件。但若已有外部 Volume 或外部表基于此 Location 创建，删除前请先移除依赖，否则相关资产会失效。
External Location 权限管理
权限点
权限点 | 含义 |
CREATE EXTERNAL TABLE | 基于该 Location 创建 / 修改外部表 |
CREATE EXTERNAL VOLUME | 基于该 Location 创建 / 修改外部 Volume |
ALL PRIVILEGES | 上述全部权限 |
MANAGE | 可编辑、删除 Location，并可二次授权 |
配置权限
1. 进入 External Location 详情页 权限 Tab。
2. 点击 新增授权 ，选择授权主体（用户或用户组）。
3. 勾选权限点。
4. 点击 确定 完成授权。
仅控制台管理员、Location 创建人和被授予
MANAGE 的用户可发起授权。基于 External Location 创建 Volume
当您需要复用一段已注册的 COS 路径作为非结构化资产容器时，可以基于 External Location 创建 外部 Volume 。整个流程不会复制数据，仅在 DataBuddy 中建立元数据注册关系。
操作步骤
1. 在左侧导航栏选择 数据目录 ，进入目标 Volume 类 Catalog 的 Schema 详情页。
2. 点击右上角添加数据对象> Volume 。
3. 在弹窗中 Volume 类型选择外部 volume
4. 在 External Location 下拉中选择已注册的目标 Location；可在该 Location 下进一步指定子路径（可选）。
5. 填写 Volume 名称与描述，点击 确定 完成创建。
权限要求
当前用户需对所选 External Location 拥有
CREATE EXTERNAL VOLUME（或 ALL PRIVILEGES）权限。当前用户需对目标 Schema 拥有
create volumes 权限。行为说明
多个外部 Volume 可指向 同一 External Location 下的不同子路径，相互之间隔离。
删除外部 Volume 仅 解除元数据注册，不会清理 External Location 上的实际文件。
External Location 上的文件如果被外部进程修改，外部 Volume 内容会随之变化（DataBuddy 不进行二次缓存）。
External Catalog（基于数据源创建外部数据目录）
External Catalog 让您像访问内部 Catalog 一样查询外部关系型数据库（如 TencentDB PostgreSQL），无需先做数据接入或 ETL，适合 临时查询 与 数据探索 场景。
创建 External Catalog
DataBuddy 提供两个入口创建 External Catalog：
入口 A：从已有数据源创建
适合已经创建过数据源但还未创建 Catalog 的场景。
1. 在左侧导航栏选择 数据目录 。
2. 顶部点击 外部数据管理 ，进入数据源列表。
3. 点击目标数据源名称进入详情页。
4. 在详情页右上角点击 创建外部数据目录 ，弹出配置页面。
入口 B：在创建数据源后引导创建
适合首次创建数据源的场景。
1. 在 数据源管理中创建数据源。
2. 创建完成后，弹窗中选择 创建外部数据目录 。
3. 走创建外部数据目录流程
创建外部数据目录与创建数据接入任务的区别：
选项 | 适用场景 |
创建外部数据目录 | 临时查询、数据探索；不复制数据 |
创建数据接入任务 | 高性能查询、数据转换；将外部数据同步到 DataBuddy 内部存储 |
引导规则：
MySQL 类数据源 ：默认引导用户创建外部数据目录。
其他数据源 ：默认引导用户进行数据接入。
步骤 2：填写 Catalog 配置
1. 在创建外部目录配置页填写基础信息：
参数 | 说明 | 是否必填 | 默认值 |
Catalog 名称 | 手动填写 | 是 | - |
目录来源 | 默认是直连数据源 | 是 | 直连数据源 |
数据源 | 选择数据源名称 | 是 | - |
描述 | - | 否 | - |
提示
当前仅支持基于 Doris、Starrocks、GaussDB、 PostgreSQL、MySQL 创建外部数据目录。其他数据源类型在后续版本逐步支持。
1. 点击确认 提交。创建成功后，自动跳转到该 Catalog 详情页，并提示「创建 Catalog 成功」。
External Catalog 详情页特点
External Catalog 与内部 Catalog 详情页结构相似，但有以下差异：
差异点 | 内部 Catalog | External Catalog |
Connection 字段 | 无 | 显示关联 Connection 名称，可跳转到 Connection 详情页 |
创建 Schema / 表 | 支持 | 不支持（Foreign Catalog 仅是镜像） |
修改 / 删除 | 支持 | 当前仅只读，描述、删除、修改等操作暂不支持 |
表详情 Tab | 概览、数据预览、权限、血缘、表变更历史等 | 概览、详情、数据预览、权限 |
注意
External Catalog 是源数据库元数据的镜像。如需变更 Schema 与表结构，请在源数据库中执行 DDL，External Catalog 会同步反映元数据变化。
External Catalog 权限管理
External Catalog 的权限模型与普通 Catalog 一致：
默认对
all account user 授予 browse 权限。可对授权主体进行 Catalog 层权限授权。
创建外部 Catalog 的权限与创建内部 Catalog 的权限点保持一致。
具体的权限判断规则：
操作 | 允许的角色 |
创建 External Catalog | Connection owner / 控制台管理员 / 被授予「创建 Catalog 权限」且具备 use connection 的用户或用户组 |
修改 Connection 描述 | Connection owner / 控制台管理员 / 被授予 use connection 的用户或用户组 |
转交 Connection owner | Connection owner / 控制台管理员 / 被授予 use connection 的用户或用户组 |
元数据同步行为
External Catalog 不存储数据，但会在以下时机从源数据库拉取元数据，确保 DataBuddy 中看到的 Schema / 表结构与源数据库保持一致：
触发场景 | 同步方式 | 用户可见性 |
Catalog 创建完成 | 立即同步一次全量元数据 | 创建成功后即可在目录树中看到 Schema 与表 |
用户在目录树展开 Catalog / Schema | 按需拉取（懒加载） | 展开节点时实时从源库读取 |
进入表详情页 | 实时拉取该表的字段、属性等元数据 | 进入页面时刷新 |
源库 DDL 变更后再次访问 | 下一次访问时自动同步 | 用户重新打开节点 / 详情页即可看到最新结构 |
提示
External Catalog 不维护后台定时同步任务。当源数据库元数据变更后，DataBuddy 在用户下一次访问对应资产时按需刷新；如同步过程中失败（如源库不可达、Connection 失效、网络异常等），界面会展示同步错误，并提示用户检查 Connection 与计算资源的网络可达性。
跨工作空间共享
External Location 与 External Catalog 都支持跨工作空间共享：
External Location ：所有有权限的工作空间均可在该 Location 上创建外部 Volume / 外部表。
External Catalog ：默认对所有工作空间只读可见。如需限制，可在创建时取消默认勾选并指定可访问工作空间列表。
常见问题
Q：External Location 与 External Catalog 是同一个东西吗？
A：不是。
External Location 是一段被注册为治理对象的 COS 存储路径，主要用于 创建外部 Volume / 外部表的存储位置 。
External Catalog 是基于 Connection 创建的 外部数据库元数据镜像 ，用于在 DataBuddy 中查询外部关系型数据库。
两者解决的问题不同：External Location 关注外部存储治理，External Catalog 关注外部数据库元数据治理。
Q：基于 External Location 创建的 Volume 与托管 Volume 有什么区别？
A：
托管 Volume 由平台分配存储路径，删除 Volume 时同时清理底层文件。
外部 Volume 复用 External Location 上的 COS 路径，多个外部 Volume 可指向同一 Location 下的不同子路径。删除外部 Volume 仅解除元数据注册，不删除文件。
Q：External Catalog 中能不能
INSERT INTO 写入数据？A：当前不支持。Foreign Catalog 是只读镜像。如需写入外部数据库，请直接在源数据库中执行，或使用离线/实时数据同步任务。
Q：External Catalog 的查询性能如何？
A：查询通过计算引擎下推到外部数据库执行，性能取决于源数据库的查询能力与网络。对于高并发或大数据量查询，建议使用数据接入任务把数据同步到 DataBuddy 内部 Catalog。
Q：删除 External Location 时它上面的外部 Volume 会怎样？
A：删除前请先移除所有依赖该 Location 的外部 Volume / 外部表，否则这些资产会失效。
