LakeBase Catalog使用说明

CREATE CATALOG

CREATE [ OR REPLACE ] CATALOG [ IF NOT EXISTS ] catalog_name
    TYPE { lance | paimon | postgres | duckdb }
    [ OPTIONS ( option_name 'option_value' [, ...] ) ];

DROP CATALOG

删除Catalog元数据。底层存储文件不会被删除。如果当前会话已将该Catalog设置为默认Catalog，DROP会拒绝执行（错误码ERRCODE_OBJECT_IN_USE），需先执行RESET CATALOG。

DROP CATALOG [ IF EXISTS ] catalog_name;

ALTER CATALOG

• 语法

  ALTER CATALOG catalog_name RENAME TO new_name;
  ALTER CATALOG catalog_name OWNER TO new_owner;

• 权限要求：Catalog owner或高权限用户。

• 行为说明

  • RENAME：将Catalog重命名为 new_name。目标名称不能是保留名称（如 pg_catalog），也不能与当前数据库名冲突，且不能与已有 Catalog 重名。

  • OWNER TO：将Catalog的所有者变更为 new_owner。变更时会同步更新Catalog上已有的数据访问权限（ACL）条目，将旧 owner 的权限映射到新 owner。如果新 owner 与当前 owner 相同，则为空操作。

查看Catalog信息

SHOW CREATE CATALOG catalog_name;

COMMENT ON CATALOG catalog_name IS '描述文字';
COMMENT ON CATALOG catalog_name IS NULL;        -- 清除注释

Schema和Table管理

USE / SET CATALOG / SWITCH / RESET

-- 设置默认 catalog（以下三种等价）
USE catalog_name;
SET CATALOG catalog_name;
SWITCH catalog_name;

-- 同时设置 catalog 和 schema
USE catalog_name.schema_name;

-- 设置默认 schema
SET SCHEMA schema_name;

-- 查看当前设置
SHOW CATALOG;
SHOW SCHEMA;

-- 重置
RESET CATALOG;          -- 清除默认 catalog 和 schema
RESET SCHEMA;           -- 仅清除默认 schema

设置默认Catalog后，可使用二段名（schema.table）访问数据。

GRANT / REVOKE ON CATALOG

权限要求：Catalog owner或高权限用户。

GRANT { USAGE | CREATE | ALL [ PRIVILEGES ] }
    ON CATALOG catalog_name TO role_name [, ...];

REVOKE { USAGE | CREATE | ALL [ PRIVILEGES ] }
    ON CATALOG catalog_name FROM role_name [, ...];

SHOW GRANTS ON CATALOG catalog_name;

EXPLAIN

EXPLAIN SELECT * FROM demo.main.orders WHERE amount > 50;
EXPLAIN ANALYZE SELECT * FROM demo.main.orders;

DDL

CREATE SCHEMA demo.analytics;
CREATE SCHEMA IF NOT EXISTS demo.analytics;
SHOW SCHEMAS FROM demo;
DROP SCHEMA demo.analytics;
DROP SCHEMA IF EXISTS demo.analytics CASCADE;

CREATE TABLE demo.main.orders (
    id        INT,
    customer  VARCHAR,
    amount    DOUBLE,
    order_ts  TIMESTAMP
);
SHOW TABLES FROM demo.main;
DESCRIBE TABLE demo.main.orders;
SHOW CREATE TABLE demo.main.orders;
DROP TABLE demo.main.orders;

-- 插入
INSERT INTO demo.main.orders VALUES
    (1, 'Alice', 99.50,  '2026-01-15 10:00:00'),
    (2, 'Bob',   250.00, '2026-02-20 14:30:00');

-- 查询
SELECT customer, amount FROM demo.main.orders WHERE amount > 100;

-- 更新
UPDATE demo.main.orders SET amount = 100.00 WHERE id = 1;

-- 删除
DELETE FROM demo.main.orders WHERE id = 2;

-- 聚合
SELECT count(*), sum(amount) FROM demo.main.orders;

Catalog 管理权限

数据访问权限（ACL）

规则说明

• 新建Catalog默认所有非owner的普通用户被拒绝访问。

• 执行GRANT后ACL生效，未授权用户被拒绝。

• REVOKE ALL后仅 owner 和高权限用户可访问。

• ACL 在三段名数据路径上强制执行（SELECT / DML / DDL 均检查）。

示例

CREATE ROLE analyst LOGIN;
CREATE CATALOG reports TYPE duckdb;
CREATE TABLE reports.main.sales (id INT, amount DOUBLE);

GRANT USAGE ON CATALOG reports TO analyst;
SET ROLE analyst;
SELECT * FROM reports.main.sales;              -- OK
CREATE TABLE reports.main.tmp (x INT);         -- ERROR: Requires CREATE privilege
RESET ROLE;

REVOKE USAGE ON CATALOG reports FROM analyst;
SET ROLE analyst;
SELECT * FROM reports.main.sales;              -- ERROR: Requires USAGE privilege
RESET ROLE;

SHOW GRANTS ON CATALOG reports;