Skip to main content
Version: 1.0

Frequently Asked Questions

Looking for introductory information?

General​

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:

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.

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:

How do I connect Grafana to GreptimeDB?​

GreptimeDB works with Grafana through three data source options:

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.

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.

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