StarRocks Default Catalog（默认内部 Catalog）完全指南：认识与管理集群内置数据-开发者社区

StarRocks Default Catalog（默认内部 Catalog）完全指南：认识与管理集群内置数据

【免费下载链接】starrocksThe world's fastest open query engine for sub-second analytics both on and off the data lakehouse. With the flexibility to support nearly any scenario, StarRocks provides best-in-class performance for multi-dimensional analytics, real-time analytics, and ad-hoc queries. A Linux Foundation project.项目地址: https://gitcode.com/GitHub_Trending/st/starrocks

导读

本文以 StarRocks 的Default Catalog（默认内部 Catalog）为主题，系统讲解内部 Catalog 的概念定位、与外部 Catalog 的区别，以及如何通过它查询集群内部数据。阅读完本文，你将掌握default_catalog的底层实现原理（含 FE 端源码佐证）、数据库切换与三段式全限定表名的用法，并能用SHOW DATABASES、SET CATALOG、USE、SELECT四条语句完成从连接到查询的完整实战流程。本主题对应仓库文档为 default_catalog.md，建议配合 catalog_overview.md 一起阅读。

什么是 Default Catalog

StarRocks 从2.3 版本开始引入 Catalog（数据目录）功能，用于统一管理内部数据与外部数据。在此基础上，每个 StarRocks 集群都内置且仅内置一个名为default_catalog的内部 Catalog，专门负责管理 StarRocks 自身存储的内部数据。

内部数据指的是由 StarRocks 自己管理的数据：当你执行CREATE DATABASE、CREATE TABLE等语句创建数据库或表时，这些对象就被存储在内部 Catalog 中。与之相对，外部数据指存储在 Apache Hive™、Apache Iceberg、Apache Hudi、Delta Lake、JDBC 兼容数据源等外部系统中的数据，需要借助外部 Catalog才能访问。

关于default_catalog有几个关键限制，需要明确：

每个集群只有唯一一个内部 Catalog，名称固定为default_catalog；
当前无法修改内部 Catalog 的名称；
当前无法创建新的内部 Catalog。

源码视角：内部 Catalog 如何被定义

上述行为在 FE 源码中有明确实现。在 InternalCatalog.java 中，内部 Catalog 的默认名称与 ID 被定义为常量：

public class InternalCatalog extends Catalog { public static final String DEFAULT_INTERNAL_CATALOG_NAME = "default_catalog"; public static final long DEFAULT_INTERNAL_CATALOG_ID = -11; public InternalCatalog(long id, Map<String, String> config, String comment) { super(id, DEFAULT_INTERNAL_CATALOG_NAME, config, comment); } ... }

可以看到，InternalCatalog在构造时被硬编码为名称default_catalog，因此集群中不可能出现第二个同名的内部 Catalog。

在 CatalogMgr.java（FE 端 Catalog 管理器）中，default_catalog被视为始终存在的 Catalog：

public boolean catalogExists(String catalogName) { if (catalogName.equalsIgnoreCase(InternalCatalog.DEFAULT_INTERNAL_CATALOG_NAME)) { return true; } ... } public static boolean isInternalCatalog(String name) { return name.equalsIgnoreCase(InternalCatalog.DEFAULT_INTERNAL_CATALOG_NAME); } public static boolean isInternalCatalog(long catalogId) { return catalogId == InternalCatalog.DEFAULT_INTERNAL_CATALOG_ID; }

catalogExists()对default_catalog直接返回true，说明它并不依赖动态注册，而是集群自带的固定成员；isInternalCatalog()则被用于区分内部与外部 Catalog 的逻辑分支。另外，在CatalogMgr的CatalogProcNode中，default_catalog的类型被标识为Internal，其注释为 “An internal catalog contains this cluster's self-managed tables.”，即“内部 Catalog 包含本集群自管理的数据表”，见 CatalogMgr.java。

使用 Default Catalog 查询内部数据

在default_catalog下查询内部数据的完整流程分为连接、查看、切换、查询四个步骤。

第 1 步：连接 StarRocks 集群

使用MySQL 客户端连接集群后，默认即处于default_catalog中，无需任何额外操作。
使用JDBC连接时，可以通过在连接参数中指定default_catalog.db_name（例如default_catalog.example_db），让连接建立后直接进入默认 Catalog 中的目标数据库。

第 2 步（可选）：查看数据库

使用SHOW DATABASES查看当前 Catalog 下的所有数据库：

SHOW DATABASES;

也可以显式指定 Catalog 名称来查看某个 Catalog 下的数据库：

SHOW DATABASES FROM <catalog_name>;

语法细节可参考 SHOW DATABASES。由于一个集群只有一个内部 Catalog，在默认场景下上述两条语句查看的都是default_catalog内的数据库；当切换或指定到外部 Catalog 时，第二条语句可用于查看外部数据源中的数据库。

第 3 步（可选）：切换 Catalog 与数据库

在当前会话中切换到目标 Catalog：

SET CATALOG <catalog_name>;

该语句的完整说明见 SET CATALOG。切换 Catalog 后，再使用USE指定当前会话的活动数据库：

USE <db_name>;

或者，直接用一条USE语句进入目标 Catalog 下的活动数据库：

USE <catalog_name>.<db_name>;

USE语句的语法见 USE。对于default_catalog场景，等效写法为：

USE default_catalog.<db_name>;

第 4 步：查询内部数据

在选定 Catalog 和数据库后，即可用SELECT查询内部数据：

SELECT * FROM <table_name>;

如果在前面的步骤中没有指定活动数据库，可以直接在 SELECT 中指定数据库：

SELECT * FROM <db_name>.<table_name>;

也可以使用包含 Catalog 的三段式全限定名，显式指定default_catalog：

SELECT * FROM default_catalog.<db_name>.<table_name>;

SELECT语句的完整语法参见 SELECT。

完整示例：查询 olap_db.olap_table

假设集群中存在数据库olap_db和表olap_table，要查询其中的数据，以下三种写法完全等价：

写法一：先切换数据库，再查询

USE olap_db; SELECT * FROM olap_table limit 1;

写法二：在 SELECT 中指定数据库

SELECT * FROM olap_db.olap_table limit 1;

写法三：使用三段式全限定名（含 Catalog）

SELECT * FROM default_catalog.olap_db.olap_table limit 1;

第三种写法最值得关注：它展示了 Catalog、Database、Table 三层命名空间的组织方式，即使当前会话停留在其他 Catalog 或数据库，也能精确锁定default_catalog中的数据对象。

拓展：Default Catalog 与跨 Catalog 联邦查询

理解了default_catalog后，很容易进一步掌握 StarRocks 的跨 Catalog 联邦查询能力。在 catalog_overview.md 中给出了多组示例，其核心规则是：使用catalog_name.database_name.table_name格式显式指定数据所在位置，即可跨越当前 Catalog 进行查询，甚至让内部表与外部表直接 JOIN。

例如，当前会话位于hive_catalog.hive_db（一个外部 Hive Catalog），要查询default_catalog中的内部表：

SELECT * FROM default_catalog.olap_db.olap_table;

又如，将外部表hive_table与内部表olap_table进行 JOIN：

SELECT * FROM hive_table h JOIN default_catalog.olap_db.olap_table o WHERE h.id = o.id;

在这些场景中，default_catalog作为三段式名称的第一段，是内部数据在联邦查询中被稳定引用的关键身份标识。

与外部 Catalog 的关系

从 catalog_overview.md 可以看到，StarRocks 目前提供两类 Catalog：

内部 Catalog（Internal catalog）：管理 StarRocks 内部数据，即本文主角default_catalog；
外部 Catalog（External catalog）：如同指向外部元数据服务的“连接器”，允许直接访问 Hive、Iceberg、Hudi、Delta Lake、JDBC、Elasticsearch、Paimon、Fluss、Unified 等外部数据源，实现零数据加载/迁移的直查。

从 FE 源码看，二者在 CatalogMgr.java 中被显式区分：

public static boolean isExternalCatalog(String name) { return !Strings.isNullOrEmpty(name) && !isInternalCatalog(name) && !isResourceMappingCatalog(name); }

即“不是内部 Catalog、也不是资源映射 Catalog 的就是外部 Catalog”。如需了解如何通过外部 Catalog 查询外部数据，可参考 Query external data。