Frequently Asked Questions

Looking for introductory information?

• What is GreptimeDB / Use cases → Why GreptimeDB
• Performance benchmarks → Key Features
• Metrics, logs, and traces → Key Features
• High cardinality → Key Features
• Data model → Data Model

General

Where can I find ready-to-run demos?

Check out the demo-scene repository. It contains end-to-end examples covering common use cases (metrics, logs, IoT, etc.) that you can run locally with Docker Compose.

How is GreptimeDB's performance compared to other solutions?

GreptimeDB is designed for high-throughput write, low-latency query, and cost-efficient storage across metrics, logs, and traces workloads. Benchmark results are available in the following reports:

• GreptimeDB vs. InfluxDB
• GreptimeDB vs. TimescaleDB
• GreptimeDB vs. Grafana Mimir
• GreptimeDB vs. ClickHouse vs. Elasticsearch (Log Benchmark)
• GreptimeDB vs. SQLite
• GreptimeDB vs. Loki
• JSONBench #1 (1 Billion Cold Run)

For a summary of how GreptimeDB compares architecturally, see the comparison table.

What are GreptimeDB's design trade-offs?

GreptimeDB is optimized for observability and time-series workloads, which means it makes different trade-offs than a general-purpose OLTP database:

• No ACID transactions: Prioritizes high-throughput writes over transactional consistency.
• Delete is supported but not optimized for high-frequency use: GreptimeDB supports row deletion and TTL-based expiration, but it is not designed for workloads that require frequent, fine-grained deletes — as is typical for append-heavy observability data.
• Joins are functional but currently not the primary focus: GreptimeDB supports SQL joins, but the query engine is optimized for time-series filter-aggregate patterns rather than complex multi-way relational joins. Simple joins (e.g., enrichment lookups, correlating metrics with logs) work well.
• Time-series focused: Optimized for IoT, metrics, logs, and traces rather than general OLTP.

What's the difference between GreptimeDB and InfluxDB?

Key differences:

• Open Source: GreptimeDB's entire distributed system is fully open source.
• Architecture: Region-based sharding design optimized for observability workloads.
• Query Languages: SQL + PromQL vs. InfluxQL + SQL.
• Unified Model: Native support for metrics, logs, and traces in one system.
• Storage: Pluggable engines with dedicated optimizations.
• Cloud-Native: Built for Kubernetes with disaggregated compute/storage (see Kubernetes Deployment Guide).

For a detailed comparison, see GreptimeDB vs InfluxDB. Additional product comparisons (vs. ClickHouse, Loki, etc.) are available in the Compare menu on the website.

Data Model & Schema

What's the difference between Tag and Field columns?

GreptimeDB uses three semantic column types: Tag, Timestamp, and Field.

• Tag columns identify a time-series. Rows with the same tag values belong to the same series. Tags are indexed by default for fast filtering. In SQL, tag columns are declared via PRIMARY KEY.
• Field columns contain the measured values (numbers, strings, etc.). Fields are not indexed by default, but you can add indexes as needed.
• Timestamp is the time index — every table must have exactly one.

For example, in a system_metrics table, host and idc are tags, cpu_util and memory_util are fields, and ts is the timestamp.

For full details and examples, see Data Model and the schema design guide.

Does GreptimeDB support schemaless data ingestion?

Yes. When writing via gRPC, InfluxDB Line Protocol, OpenTSDB, Prometheus Remote Write, OpenTelemetry, Loki, or Elasticsearch-compatible APIs, GreptimeDB creates tables and columns automatically on first write. No manual schema definition is needed.

For details, see Automatic Schema Generation.

How do I set default table options (TTL, append mode, etc.) for auto-created tables?

There are three ways to control table options such as ttl, append_mode, merge_mode, skip_wal, and sst_format for tables created via automatic schema generation:

1. Set options at ingestion time via HTTP header: Use the x-greptime-hints header to pass table options when writing data. For example, x-greptime-hints: ttl=7d, append_mode=true. These options apply when the table is auto-created. See HTTP Hints for all supported hints.

2. Modify options after table creation: Some options can be changed on an existing table via ALTER TABLE. For example, ttl, append_mode, compaction.*, and sst_format are supported:

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

   Note that merge_mode and skip_wal cannot be altered after creation — they must be set at table creation time. See ALTER TABLE for all supported options and constraints.

3. Set database-level defaults: Create or alter the database with default options. New auto-created tables will inherit these values:

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

   Note that ttl and compaction.* options have ongoing effect — tables without their own settings continuously inherit the database value. Other options (append_mode, merge_mode, skip_wal, sst_format) only serve as defaults for newly created tables. See CREATE DATABASE for all available options.

How do I customize the default column names for InfluxDB / Prometheus protocols?

When writing via certain protocols, GreptimeDB generates default column names with a greptime_ prefix. The timestamp column is named greptime_timestamp for all schemaless protocols. The value column greptime_value is used by single-value protocols such as Prometheus Remote Write and OpenTelemetry Metrics, where each time series carries only one numeric value. Multi-field protocols like InfluxDB Line Protocol use the field names from the input data directly — only the timestamp column gets the default prefix.

To change the prefix, set the default_column_prefix option in your standalone.toml or frontend.toml:

# Remove the "greptime_" prefix — columns become "value" and "timestamp"
default_column_prefix = ""

# Or use a custom prefix — columns become "my_value" and "my_timestamp"
# default_column_prefix = "my"

If unset, the default greptime_ prefix is used. This is a top-level configuration option and requires a restart to take effect.

Can I change a column's type after table creation?

Yes. Use ALTER TABLE ... MODIFY COLUMN to change a field column's data type:

ALTER TABLE monitor MODIFY COLUMN load_15 STRING;

The column must be a field (not a tag or time index) and must be nullable, so that values that cannot be cast return NULL instead of failing.

For the full ALTER TABLE syntax, see the SQL reference.

How does GreptimeDB handle late-arriving or out-of-order data?

GreptimeDB accepts writes with any timestamp — there is no ingestion-time window or ordering requirement. Late-arriving and out-of-order data is written normally and becomes queryable immediately. The storage engine's compaction process merges and sorts data in the background.

For append-only tables (commonly used for logs), rows are never deduplicated, so late-arriving data simply adds new rows. For tables with a primary key, rows with the same tag + timestamp combination follow the update semantics.

Integration & Migration

What protocols, tools, and SDKs does GreptimeDB support?

Write protocols: OpenTelemetry (OTLP), Prometheus Remote Write, InfluxDB Line Protocol, Loki, Elasticsearch, MySQL, PostgreSQL, gRPC — see Protocols Overview.

Query languages: SQL, PromQL.

Visualization: Grafana (official plugin + MySQL/PostgreSQL data sources), and any tool that speaks MySQL or PostgreSQL wire protocol.

Data pipeline: Vector, Fluent Bit, Telegraf, Kafka — see Integrations Overview.

SDKs:

• Go
• Java
• Rust
• Erlang
• .NET
• For other languages (Python, Ruby, Node.js, etc.): use any OpenTelemetry SDK, InfluxDB client library, or MySQL/PostgreSQL driver — GreptimeDB is compatible with all of them.

How do I choose the right ingestion protocol?

GreptimeDB supports multiple ingestion protocols with very different throughput characteristics. The following results are from a local benchmark at 1 million time series (batch size 1,000) — focus on the relative ratios rather than absolute numbers, as actual throughput varies by hardware and workload:

Protocol	Relative throughput
gRPC Bulk (Arrow Flight)	Highest (~55x SQL)
gRPC Stream	~40x SQL
gRPC SDK (Unary)	~33x SQL
OTLP Logs	~29x SQL
InfluxDB Line Protocol	~27x SQL
MySQL INSERT	~2x PostgreSQL
PostgreSQL INSERT	Baseline

How to choose:

• General workloads: gRPC SDK — best balance of simplicity and performance, with schemaless support.
• Bulk operations (migrations, backfills): gRPC Bulk — maximum throughput, requires pre-created tables.
• Continuous streams (IoT, monitoring collectors): gRPC Stream — sustained high throughput over persistent connections.
• Ecosystem integration: InfluxDB Line Protocol (Telegraf-compatible) or OTLP (OpenTelemetry-compatible) — good throughput with broad tool support.
• Development / debugging: SQL protocols (MySQL / PostgreSQL) — lower throughput but easier to inspect and debug.

For the full benchmark details and methodology, see the Ingestion Protocol Benchmark blog post.

How do I connect Grafana to GreptimeDB?

GreptimeDB works with Grafana through three data source options:

• GreptimeDB plugin: Official plugin with full SQL and PromQL support.
• Prometheus data source: Use GreptimeDB's Prometheus-compatible endpoint for PromQL dashboards.
• MySQL data source: Use the built-in MySQL data source with GreptimeDB's MySQL protocol endpoint.

See Grafana Integration for setup instructions.

How can I migrate from other databases?

GreptimeDB provides migration guides for:

• From InfluxDB: Line protocol and data migration
• From Prometheus: Remote write and historical data migration
• From ClickHouse: Table schema and data migration
• From MySQL/PostgreSQL: SQL-based migration

For detailed instructions, see Migration Overview.

Deployment & Operations

What are the deployment options?

Cluster deployment (production):

• Minimum 3 nodes for high availability
• Three components: metasrv, frontend, and datanode
• Components can be co-located or separated depending on scale
• See Capacity Planning Guide

Standalone (development / edge / IoT):

• Single binary, all components in one process
• Runs on Linux, macOS, Android ARM64, Raspberry Pi
• See Installation Guide

Storage backends: S3, GCS, Azure Blob (recommended for production); local disk (development, testing, or small-scale). Metadata: RDS or etcd (cluster), local storage (standalone).

For a full overview, see Deployments & Administration.

Which metadata storage backend should I use for metasrv?

GreptimeDB supports etcd, MySQL, and PostgreSQL as metadata storage backends for the metasrv component.

For production deployments, PostgreSQL or MySQL (including cloud RDS services) is generally recommended — most teams already have operational experience, monitoring, backup, and disaster recovery strategies for relational databases.

That said, etcd remains fully supported and actively maintained. It is not deprecated. If your team has strong etcd expertise and operational tooling, it is a perfectly valid choice.

The decision ultimately comes down to your team's skill set and existing infrastructure. See Metadata Storage Configuration for setup instructions for each backend.

How do I manage GreptimeDB?

GreptimeDB uses standard SQL as its management interface. You can create tables, alter schemas, set TTL policies, and configure indexes — all through SQL. No config files to write, no proprietary APIs to call.

For configuration beyond SQL (e.g., node-level settings), see the Configuration Guide.

How do I upgrade GreptimeDB?

See the Upgrade Guide for version-specific instructions, compatibility notes, and breaking changes.

How do I back up and restore data?

GreptimeDB provides export and import tools for full database backup and restoration, including schema-only operations and S3 export support.

See Data Export & Import.

Can I migrate data between standalone and cluster mode?

Yes. Use COPY TO to export tables from standalone mode, then COPY FROM to import them into a cluster (or vice versa). Data is exported in Parquet format and can be staged locally or in object storage (S3, GCS).

My WAL directory is growing large. Is this normal?

WAL (Write-Ahead Log) space is cyclically reused after data is flushed to persistent storage. If the WAL directory appears large, it usually means data has not been flushed yet, or the WAL retention settings need tuning. WAL space is temporary — when measuring storage consumption, measure only the data directory (data).

For WAL configuration options, see the Configuration Guide.

What are GreptimeDB's scalability characteristics?

• No strict limitations on table or column count; performance scales with primary key design rather than table count.
• Automatic time-based organization within regions.
• Manual distributed sharding via PARTITION clause — see Table Sharding Guide.
• Multi-tiered caching (write cache + LRU read cache) for optimal performance.
• Object storage backend (S3/GCS/Azure Blob) provides virtually unlimited storage capacity.
• Distributed query execution with MPP for large datasets.

How does data distribution work?

• Manual partitioning via PARTITION clause during table creation — see Table Sharding Guide.
• Time-based automatic organization within regions.
• Manual region migration for load balancing — see Region Migration Guide.
• Automatic region failover for disaster recovery — see Region Failover.

What disaster recovery options are available?

GreptimeDB offers multiple disaster recovery strategies:

• Standalone DR: Remote WAL + object storage, RPO=0, RTO in minutes.
• Region Failover: Automatic failover for individual regions with minimal downtime.
• Active-Active Failover (Enterprise): Synchronous request replication between two nodes.
• Cross-Region Single Cluster: Spans three regions with zero RPO and region-level fault tolerance.
• Backup and Restore: Periodic data backups with RPO depending on backup frequency.

See Disaster Recovery Overview.

How do I monitor and troubleshoot GreptimeDB?

GreptimeDB exposes Prometheus-compatible metrics and provides health check endpoints. For monitoring setup and troubleshooting guides, see Monitoring Overview.

Open Source vs Enterprise vs Cloud

What are the differences between GreptimeDB versions?

• Open Source: Full distributed system, multiple protocol support, basic authentication.
• Enterprise: Adds cost-based query optimizer, active-active failover, automatic scaling/indexing, RBAC/LDAP, and 24/7 support.
• GreptimeCloud: Fully managed with resource and performance guarantees for production workloads, predictable pricing, and SLA guarantees.

For a detailed feature comparison, see Pricing & Features.

Does the GreptimeDB Dashboard have authentication?

The open-source GreptimeDB Dashboard does not include built-in authentication. To restrict access, you can:

• Place a reverse proxy (e.g., Nginx, Caddy) in front of the dashboard and configure HTTP Basic Auth or other authentication mechanisms.
• Host the dashboard behind your organization's internal authentication system.

GreptimeDB Enterprise provides a management console with built-in authentication and access control.

What security features are available?

Open Source:

• Basic username/password authentication
• User-level read/write access control
• TLS/SSL support for connections

Enterprise / Cloud:

• Role-based access control (RBAC)
• LDAP support
• Team management and API keys
• Data encryption at rest
• Audit logging for compliance