跳到主要内容
版本：1.0

常见问题

想了解基础信息？

通用问题​

哪里可以找到开箱即用的 Demo？​

可以看 demo-scene 仓库，里面有覆盖常见场景（metrics、logs、IoT 等）的端到端示例，本地用 Docker Compose 即可运行。

GreptimeDB 的性能表现如何？​

GreptimeDB 针对 metrics、logs、traces 场景优化，写入吞吐高、查询延迟低、存储成本低。以下是已发布的基准测试报告：

架构层面的对比参见对比表格。

GreptimeDB 的设计权衡有哪些？​

GreptimeDB 针对可观测性和时序工作负载做了专门优化，与通用 OLTP 数据库有不同的取舍：

  • 不支持 ACID 事务：优先保证高吞吐写入，而非事务一致性。
  • 支持删除，但不适合高频删除场景：GreptimeDB 支持数据删除和基于 TTL 的自动过期，但不适合需要频繁细粒度删除的场景——可观测性数据本身就是追加为主的。
  • 支持 Join，但暂时不是优化重点：GreptimeDB 支持 SQL Join，但查询引擎主要针对时序数据的过滤-聚合模式优化。简单 Join（如关联查询、metrics 与 logs 的交叉分析）可以正常使用。
  • 面向时序数据：针对 IoT、metrics、logs、traces 优化，而非通用 OLTP。

GreptimeDB 和 InfluxDB 有什么区别？​

主要区别：

  • 开源策略：GreptimeDB 的整个分布式系统完全开源。
  • 架构：基于 Region 的分片设计，针对可观测性工作负载优化。
  • 查询语言：SQL + PromQL vs. InfluxQL + SQL。
  • 统一模型：在一个系统中原生支持 metrics、logs 和 traces。
  • 存储：可插拔引擎，针对不同场景做专项优化。
  • 云原生：原生支持 Kubernetes，计算存储分离（参见 Kubernetes 部署指南）。

详细对比参见 GreptimeDB vs InfluxDB。更多产品对比（如 vs. ClickHouse、Loki 等）可在官网的对比菜单中找到。

数据模型与 Schema​

Tag 列和 Field 列有什么区别？​

GreptimeDB 使用三种语义列类型：Tag、Timestamp 和 Field。

  • Tag 列用于标识时间序列。具有相同 Tag 值的行属于同一条时间序列。Tag 列默认加入主键索引，查询过滤快。在 SQL 中通过 PRIMARY KEY 声明。
  • Field 列存储实际测量值（数值、字符串等）。Field 列默认不建索引，但可以按需添加索引。
  • Timestamp 是时间索引，每张表必须有且仅有一个。

例如，在 system_metrics 表中，host 和 idc 是 Tag，cpu_util 和 memory_util 是 Field，ts 是 Timestamp。

详细说明和示例参见数据模型和表设计指南。

GreptimeDB 支持无 Schema 写入吗？​

支持。通过 gRPC、InfluxDB Line Protocol、OpenTSDB、Prometheus Remote Write、OpenTelemetry、Loki 或 Elasticsearch 兼容 API 写入时，GreptimeDB 会在首次写入时自动创建表和列，无需手动定义 Schema。

详见自动 Schema 生成。

使用自动建表时，如何指定默认的表选项（TTL、append mode 等）？​

有三种方式为自动创建的表设置 ttl、append_mode、merge_mode、skip_wal、sst_format 等表选项：

  1. 写入时通过 HTTP Header 指定：在请求中添加 x-greptime-hints 头传递表选项，例如 x-greptime-hints: ttl=7d, append_mode=true，表在自动创建时会应用这些选项。详见 HTTP Hints。

  2. 建表后通过 ALTER TABLE 修改：部分选项支持在建表后修改，包括 ttl、append_mode、compaction.* 和 sst_format：

    ALTER TABLE my_table SET 'ttl' = '7d';
    ALTER TABLE my_table SET 'append_mode' = 'true';

    注意 merge_mode 和 skip_wal 不支持建表后修改，必须在建表时指定。所有支持的选项和约束参见 ALTER TABLE。

  3. 设置数据库级别的默认选项：创建或修改数据库时指定默认选项，后续自动创建的表会继承这些值：

    CREATE DATABASE my_db WITH (ttl = '7d', append_mode = 'true');
    -- 或
    ALTER DATABASE my_db SET 'ttl' = '7d';

    其中 ttl 和 compaction.* 选项具有持续效果——没有单独设置的表会一直继承数据库的值。其他选项（append_mode、merge_mode、skip_wal、sst_format）仅作为新建表的默认值。所有可用选项参见 CREATE DATABASE。

如何自定义 InfluxDB / Prometheus 协议写入时的默认列名？​

通过无 Schema 协议写入时，GreptimeDB 会为自动生成的列加上 greptime_ 前缀。时间戳列在所有无 Schema 协议中默认命名为 greptime_timestamp。值列 greptime_value 仅用于单值协议（如 Prometheus Remote Write、OpenTelemetry Metrics），因为每条时间序列只有一个数值。多字段协议（如 InfluxDB Line Protocol）直接使用传入数据的字段名，只有时间戳列会使用默认前缀。

要修改前缀，在 standalone.toml 或 frontend.toml 中设置 default_column_prefix：

# 去掉 "greptime_" 前缀，列名变为 "value" 和 "timestamp"
default_column_prefix = ""

# 或使用自定义前缀，列名变为 "my_value" 和 "my_timestamp"
# default_column_prefix = "my"

不设置时默认使用 greptime_ 前缀。该选项是顶层配置项，修改后需要重启生效。

建表后能修改列的数据类型吗？​

可以。使用 ALTER TABLE ... MODIFY COLUMN 修改 Field 列的数据类型：

ALTER TABLE monitor MODIFY COLUMN load_15 STRING;

目标列必须是 Field 列（不能是 Tag 或时间索引），且必须可为空（nullable），这样类型转换失败时返回 NULL 而非报错。

完整的 ALTER TABLE 语法参见 SQL 参考。

GreptimeDB 如何处理迟到数据和乱序数据？​

GreptimeDB 接受任意时间戳的写入，没有写入时间窗口或顺序要求。迟到和乱序数据正常写入后立即可查。存储引擎的 Compaction会在后台自动排序和合并数据。

对于 Append Only 表（常用于日志），行不会被去重，迟到数据只是新增行。对于有主键的表，Tag + Timestamp 组合相同的行遵循更新语义。

集成与迁移​

GreptimeDB 支持哪些协议、工具和 SDK？​

写入协议：OpenTelemetry (OTLP)、Prometheus Remote Write、InfluxDB Line Protocol、Loki、Elasticsearch、MySQL、PostgreSQL、gRPC——参见协议概述。

查询语言：SQL、PromQL。

可视化：Grafana（官方插件 + MySQL/PostgreSQL 数据源），以及任何支持 MySQL 或 PostgreSQL 协议的工具。

数据管道：Vector、Fluent Bit、Telegraf、Kafka——参见集成概述。

SDK：

  • Go
  • Java
  • Rust
  • Erlang
  • .NET
  • TypeScript
  • 其他语言（Python、Ruby 等）：可以使用任何 OpenTelemetry SDK、InfluxDB 客户端库或 MySQL/PostgreSQL 驱动，GreptimeDB 均兼容。

如何选择合适的写入协议？​

GreptimeDB 支持多种写入协议，吞吐性能差异很大。以下数据来自本地测试环境（100 万时间序列，batch size 1,000）——请关注相对比例而非绝对数值，实际吞吐取决于硬件和负载：

协议相对吞吐
gRPC Bulk (Arrow Flight)最高（约 37 倍 SQL）
gRPC Stream约 21 倍 SQL
gRPC SDK (Unary)约 16 倍 SQL
InfluxDB Line Protocol约 12 倍 SQL
OTLP Logs约 8.5 倍 SQL
MySQL / PostgreSQL INSERT基线

选择建议：

  • 通用场景：gRPC SDK——简洁易用且性能好，支持无 Schema 写入。
  • 批量导入（数据迁移、回填）：gRPC Bulk——吞吐最高，需要预先建表。
  • 持续流式写入（IoT、监控采集器）：gRPC Stream——长连接上持续高吞吐。
  • 生态集成：InfluxDB Line Protocol（兼容 Telegraf）或 OTLP（兼容 OpenTelemetry）——吞吐不错且工具生态丰富。
  • 开发调试：SQL 协议（MySQL / PostgreSQL）——吞吐较低但方便排查。

完整的基准测试细节和方法参见写入协议基准测试博客。

如何将 Grafana 连接到 GreptimeDB？​

GreptimeDB 支持三种 Grafana 数据源接入方式：

详细配置参见 Grafana 集成指南。

如何从其他数据库迁移到 GreptimeDB？​

GreptimeDB 提供以下迁移指南：

  • 从 InfluxDB 迁移：Line Protocol 和数据迁移
  • 从 Prometheus 迁移：Remote Write 和历史数据迁移
  • 从 ClickHouse 迁移：表结构和数据迁移
  • 从 MySQL/PostgreSQL 迁移：基于 SQL 的迁移

详细说明参见迁移概述。

部署与运维​

有哪些部署方式？​

集群部署（生产环境）：

  • 至少 3 个节点保证高可用
  • 三个组件：metasrv、frontend、datanode
  • 组件可以合并部署或独立部署
  • 参见容量规划指南

单机部署（开发 / 边缘 / IoT）：

  • 单个二进制文件，所有组件集成在一个进程中
  • 支持 Linux、macOS、Android ARM64、Raspberry Pi
  • 参见安装指南

存储后端：S3、GCS、Azure Blob（推荐生产）；本地磁盘（开发测试或者中小规模）。元数据：集群模式使用推荐 RDS 或 etcd，单机模式本地存储。

完整介绍参见部署与管理概述。

Metasrv 的元数据存储后端应该选哪个？​

GreptimeDB 的 metasrv 组件支持 etcd、MySQL 和 PostgreSQL 作为元数据存储后端。

生产环境下，推荐使用 PostgreSQL 或 MySQL（包括云 RDS 服务）——大多数团队对关系型数据库有更丰富的运维经验、监控方案和容灾策略。

etcd 仍然完全受支持并持续维护，并非被废弃。如果你的团队在 etcd 运维方面有丰富经验和成熟工具链，etcd 也是完全可行的选择。

最终取决于团队的技术栈和已有基础设施。各后端的配置方式参见元数据存储配置。

如何管理 GreptimeDB？​

GreptimeDB 使用标准 SQL 作为管理接口。你可以通过 SQL 完成表的基本操作如建表删表、修改 Schema、设置 TTL 策略、配置索引等操作，不用写配置文件，也不用调专有 API。

节点级别的配置参见配置指南。

如何升级 GreptimeDB？​

参见升级指南，包含升级步骤、兼容性说明和不兼容变更。

如何备份和恢复数据？​

GreptimeDB 提供数据导出和导入工具，支持全库备份与恢复，包括仅导出 Schema 和 S3 导出。

参见数据导出与导入。

能否在单机模式和集群模式之间迁移数据？​

可以。使用 COPY TO 从单机模式导出表数据，再用 COPY FROM 导入到集群（反过来也一样）。数据以 Parquet 格式导出，可以存放在本地或对象存储（S3、GCS）中。

WAL 目录越来越大，正常吗？​

WAL（Write-Ahead Log）空间在数据刷写到持久存储后会循环复用。如果 WAL 目录看起来很大，通常是因为数据尚未刷写，或者 WAL 保留设置需要调整。WAL 是临时空间，评估存储用量时只看数据目录（data）就行。

WAL 配置参见配置指南。

查询报 Too many files to read concurrently 怎么处理？​

这表示单条查询要扫描的 SST 文件数超过了单查询并发上限。典型错误形如：

Too many files to read concurrently: 1528, max allowed: 384

常见原因有两类：

  • 小 SST 文件过多 —— 多见于历史数据回填且时间戳跨度大、compaction 还没追上的场景。
  • 默认的并发文件上限对你的硬件来说过于保守。

诊断：用 SSTS_MANIFEST 视图看每张表每天的文件数。结果集很大时建议按 min_ts 过滤：

SELECT table_id, date_trunc('day', min_ts), COUNT(*) AS files, SUM(num_rows) AS rows
FROM information_schema.ssts_manifest
WHERE min_ts > '2026-05-01 00:00:00'
GROUP BY table_id, date_trunc('day', min_ts)
ORDER BY files DESC;

处理方式：

  1. 调高 datanode（或 standalone）[region_engine.mito] 下的单查询文件上限：

    [region_engine.mito]
    max_concurrent_scan_files = 1024

    默认 384 是偏保守的值。CPU 和内存余量更充裕的机器，可以适当调大让大查询不被拒。改完需要重启对应 datanode。

  2. 用 SWCS 触发手动 compaction。如果单天的小文件特别多，可以把窗口调到比默认 1 天更小，参见 Compaction：

    -- 1 小时窗口，并行度 2
    ADMIN COMPACT_TABLE('<table_name>', 'swcs', 'window=3600,parallelism=2');

GreptimeDB 的扩展能力如何？​

  • 表和列的数量没有严格限制，性能主要取决于主键设计而非表数量。
  • Region 内数据自动按时间组织。
  • 通过 PARTITION 子句手动分片——参见表分片指南。
  • 多层缓存（写入缓存 + LRU 读缓存）优化性能。
  • 对象存储后端（S3/GCS/Azure Blob）提供几乎无限的存储容量。
  • 分布式查询执行，支持 MPP 处理大规模数据集。

数据如何分布？​

  • 建表时通过 PARTITION 子句手动分区——参见表分片指南。
  • Region 内按时间自动组织。
  • 支持手动 Region 迁移进行负载均衡——参见 Region 迁移指南。
  • 自动 Region 故障转移保障容灾——参见 Region 故障转移。

有哪些灾备方案？​

GreptimeDB 提供多种灾备策略：

  • 单机灾备：远程 WAL + 对象存储，RPO=0，RTO 分钟级。
  • Region 故障转移：单个 Region 自动切换，停机时间极短。
  • 双活容灾（企业版）：双节点间同步复制请求。
  • 跨区域单集群：横跨三个区域，零 RPO，区域级容错。
  • 备份与恢复：定期数据备份，RPO 取决于备份频率。

参见灾备方案概述。

写入报 Procedure poison key already exists 怎么处理？​

这种错误会阻塞写入。原因是 schema-on-write 触发的 ALTER TABLE（比如为新进来的 attribute 自动加列）在默认 12 次重试后仍然失败，在元数据存储里留下了一个未清理的 poison key。后续依赖 schema 演化的写入都会被这把锁挡住。

典型错误形如：

Procedure poison key already exists with a different value
Key: /__procedure_poison/table/<table_id>

恢复步骤：

  1. 从元数据存储中删除该 poison key。按你的实际后端和地址替换 --backend 与 --store-addrs，参见元数据交互：

    greptime cli meta del key \
        --store-addrs=$ENDPOINT \
        --backend=postgres-store \
        /__procedure_poison/table/<table_id>

  2. 触发表元数据修复，让 Metasrv 与 Datanode 一致。用受影响的 schema 与表名，参见表元数据修复：

    USE <schema>;
    ADMIN reconcile_table('<table_name>');

  3. 如果写入仍然报 Column ... not found in logical region，说明逻辑表的列元数据已经和物理表不一致。用 CLI 工具修复，参见修复逻辑表：

    greptime cli meta repair logical-tables \
        --store-addrs=$ENDPOINT \
        --backend=postgres-store \
        --table-names=<table_name> \
        --schema-name=<schema> \
        --catalog-name=greptime

排查提示：如果 ADMIN reconcile_* 立刻返回 Done，但 Metasrv 日志里完全没有 Reconciling table: 这类输出，多半是连到了另一个 Metasrv 实例（比如同集群另一个 namespace 里的 GreptimeDB 部署）。先用 kubectl get pods -A | grep meta 之类命令确认拓扑，再重试。

如何监控和排查问题？​

GreptimeDB 暴露 Prometheus 兼容的监控指标，并提供健康检查端点。监控配置和故障排查指南参见监控概述。

开源版 vs 企业版 vs 云服务​

各版本有什么区别？​

  • 开源版：完整的分布式系统、多协议支持、基础认证。
  • 企业版：在开源版基础上增加 CBO 查询优化、双活容灾、自动扩缩容和索引、RBAC/LDAP 集成、7×24 技术支持。
  • GreptimeCloud：全托管方案，为生产工作负载提供资源和性能保障、可预测的定价、SLA 保障。

详细功能对比参见价格与功能。

GreptimeDB Dashboard 有没有鉴权功能？​

开源版 GreptimeDB Dashboard 本身不包含鉴权功能。如需限制访问，你可以：

  • 在 Dashboard 前面放一个反向代理（如 Nginx、Caddy），配置 HTTP Basic Auth 或其他认证机制。
  • 将 Dashboard 托管在你的内部 HTTP 服务后面，结合组织内部的认证体系。

GreptimeDB 企业版提供内置鉴权和访问管理的管理控制台。

有哪些安全功能？​

开源版：

  • 用户名/密码认证
  • 用户读写权限控制
  • TLS/SSL 连接加密

企业版 / 云服务：

  • 基于角色的访问控制（RBAC）
  • LDAP 支持
  • 团队管理和 API 密钥
  • 静态数据加密
  • 合规审计日志