跳到主要内容
版本：1.2

ADMIN

ADMIN 语句用于运行管理函数：

ADMIN function(arg1, arg2, ...)

管理函数​

GreptimeDB 提供了一些管理函数来管理数据库和数据：

  • flush_table(table_name) 根据表名将表的 Memtable 刷新到 SST 文件中。
  • flush_region(region_id) 根据 Region ID 将 Region 的 Memtable 刷新到 SST 文件中。通过 PARTITIONS 表查找 Region ID。
  • compact_table(table_name, [type], [options]) 为表启动一个 compaction 任务，详细信息请阅读 compaction。
  • compact_region(region_id) 为 Region 启动一个 compaction 任务。
  • build_index(table_name) 在新增或修改索引定义后，为表已有的 SST 文件补建缺失的物理索引。
  • migrate_region(region_id, from_peer, to_peer, [timeout]) 在 Datanode 之间迁移 Region，请阅读 Region Migration。
  • procedure_state(procedure_id) 根据 ID 查询 Procedure 状态。
  • flush_flow(flow_name) 将 Flow 的输出刷新到目标接收表。
  • reconcile_table(table_name) 修复指定表的元数据不一致问题，详细信息请阅读 table reconciliation。
  • reconcile_database(database_name) 修复指定数据库中所有表的元数据不一致问题，详细信息请阅读 table reconciliation。
  • reconcile_catalog() 修复整个集群中所有表的元数据不一致问题，详细信息请阅读 table reconciliation。
  • gc_table(table_name, [full_file_listing]) 对对象存储中已删除表的孤立 SST 文件进行垃圾回收，返回已处理的 Region 数量。可选参数 full_file_listing（默认为 false），设为 true 时启用全量文件扫描模式。
  • gc_regions(region_id1, ..., region_idN, [full_file_listing]) 根据 Region ID 对对象存储中指定 Region 的孤立 SST 文件进行垃圾回收，返回已处理的 Region 数量。可选参数 full_file_listing（默认为 false），设为 true 时启用全量文件扫描模式。
  • purge_table(table_name) 永久 purge 一个 soft-dropped table。表名可以是未限定、schema 限定或完整限定名称。该函数仅在 GreptimeDB 企业版中可用，且只能通过 ADMIN 语句调用。

例如：

-- 刷新表 test --
admin flush_table("test");

-- 为表 test 启动 compaction 任务，默认并行度为 1 --
admin compact_table("test");

-- 启动常规 compaction，并行度设置为 2 --
admin compact_table("test", "regular", "parallelism=2");

-- 启动 SWCS compaction，使用默认时间窗口，并行度设置为 2 --
admin compact_table("test", "swcs", "parallelism=2");

-- 启动 SWCS compaction，自定义时间窗口和并行度 --
admin compact_table("test", "swcs", "window=1800,parallelism=2");

-- 对左闭右开的时间范围 [start_time, end_time) 启动常规 compaction --
admin compact_table("test", "regular", "start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z");

-- 对指定时间范围启动 SWCS compaction --
admin compact_table("test", "strict_window", "window=3600,start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z");

-- 在新增或修改索引后，为已有 SST 文件补建索引 --
admin build_index("test");

-- 对已删除的表进行垃圾回收 --
admin gc_table("test");

-- 对已删除的表进行垃圾回收（启用全量文件扫描）--
admin gc_table("test", true);

-- 对指定 Region 进行垃圾回收 --
admin gc_regions(1, 2, 3);

-- 对指定 Region 进行垃圾回收（启用全量文件扫描）--
admin gc_regions(1, 2, 3, true);

-- 永久 purge 一个 soft-dropped table --
admin purge_table("test");

构建索引​

当表元数据要求的索引在部分 SST 文件上还不存在时，可以用 admin build_index 手动为已有数据文件构建索引。典型场景包括：给已有列新增索引、迁移索引功能可用之前写入的数据、上一次索引构建失败后重试。

admin build_index("table_name");

该函数只接受一个字符串参数。表名可以是未限定名，也可以是完整限定名；未限定名按当前查询上下文解析。

例如，为已有数据构建全文索引：

CREATE TABLE logs (
    ts TIMESTAMP TIME INDEX,
    message TEXT
);

INSERT INTO logs VALUES
    (1, 'The quick brown fox jumps over the lazy dog'),
    (2, 'The quick brown fox jumps over the lazy cat');

admin flush_table("logs");

ALTER TABLE logs MODIFY COLUMN message SET FULLTEXT INDEX;

admin build_index("logs");

SELECT message FROM logs WHERE matches_term(message, 'fox');

admin build_index 会向表的所有 Region 下发构建请求。每个 Region 只为索引元数据与当前表元数据不一致的 SST 文件构建索引，已经具备所需索引元数据的文件会被跳过，因此重复执行是安全的。该命令目前返回受影响行数。

用 SHOW INDEX 查看逻辑索引定义：

SHOW INDEX FROM logs;

也可以查询 information_schema.ssts_index_meta 查看 SST 文件的物理索引元数据：

SELECT COUNT(*) AS fulltext_index_meta_count
FROM information_schema.ssts_index_meta
WHERE table_id = (
    SELECT table_id
    FROM information_schema.tables
    WHERE table_schema = 'public'
      AND table_name = 'logs'
)
AND index_type LIKE 'fulltext%';

构建索引需要读取 SST 数据并写入索引文件，会占用 CPU、内存和 I/O 资源。在异步索引构建模式下，自动 flush、compaction 以及 schema 变更触发的构建可能与手动构建同时进行，重复的构建任务会被去重或中止，命令依然可以安全重跑。