What is a catalog-阿里云帮助中心

A catalog is the top-level data management object in AnalyticDB for MySQL. Catalogs let you manage internal data, external data lakes (Hive, Iceberg, Delta, Paimon), and MySQL-compatible databases (RDS for MySQL, StarRocks, and others) under a single instance, providing unified metadata governance and federated query without data movement—the foundation of a lakehouse architecture.

Catalog categories

Catalogs are grouped into two categories based on where their metadata lives:

Category	Name	Metadata location	Typical scenarios
Managed Catalog	`adb` (system-built, one per instance, fixed name, not modifiable).	Built-in metadata service of AnalyticDB for MySQL (highly available distributed storage).	Internal OLAP tables (real-time and batch ingestion). External databases created via `CREATE EXTERNAL DATABASE`. Logical external tables mapped via `CREATE EXTERNAL TABLE` (referencing OSS, Hive, or MaxCompute data sources).
External Catalog	User-defined name (such as `paimon_oss`, `iceberg_prod`, or `mysql_sales`). No limit on the number you can create or drop.	External metadata service (Hive Metastore, Alibaba Cloud DLF, Paimon FileSystem, the target MySQL instance, and so on).	Direct queries against Hive, Iceberg, Delta, or Paimon lake tables. Federated queries against RDS for MySQL, StarRocks, or another AnalyticDB for MySQL instance.

Which catalog to use

Scenario	Recommended catalog
Query or write internal tables of the AnalyticDB for MySQL instance	Managed Catalog `adb` (default; no extra setup needed)
Query data lakes on OSS (Hive / Iceberg / Delta / Paimon)	The matching External Catalog type. See External Catalog
Federated queries against RDS for MySQL / StarRocks / another AnalyticDB for MySQL instance	MySQL Catalog (a type of External Catalog). See External Catalog

Basic operations

List catalogs

Use SHOW CATALOGS to list every catalog in the current instance:

SHOW CATALOGS;

The result has three columns: Catalog (name), Type (either Managed Catalog or External Catalog), and Comment. A new instance has only the built-in adb.

List the databases and tables under a catalog:

-- List databases under a catalog
SHOW DATABASES FROM <catalog_name>;

-- List tables under a database
SHOW TABLES FROM <catalog_name>.<db_name>;

Switch the active catalog

Use SET CATALOG to switch the catalog for the current session:

SET CATALOG <catalog_name>;

-- Example: switch to the default Managed Catalog
SET CATALOG adb;

Use USE to switch both the catalog and the database in one step:

USE <catalog_name>.<database_name>;

-- Example: switch to paimon_db under paimon_catalog
USE paimon_catalog.paimon_db;

-- Switch back to the internal database db1
USE adb.db1;

Specify a catalog through JDBC

When connecting through JDBC, you can include the catalog directly in the connection string. The session opens in that catalog right away:

jdbc:mysql://<host>:<port>/[catalog_name.]database_name

If catalog_name is omitted, the session uses adb by default.

Query data across catalogs

Regardless of the active catalog, you can address any object with the three-part name <catalog>.<database>.<table>. This is the basis for federated queries.

The following example queries paimon_table in paimon_catalog while the session is in adb.adb_db.

SELECT * FROM paimon_catalog.paimon_db.paimon_table;

Join two tables from different catalogs:

SELECT *
FROM   paimon_catalog.paimon_db.paimon_table h
JOIN   adb.adb_db.adb_table o
ON     h.id = o.id;

Catalog overview