| name | greptimedb-quickstart |
| description | Entry-point guide for agents to use GreptimeDB end-to-end — when it fits, how to deploy (Docker / binary / Kubernetes / GreptimeCloud), how to configure the server (storage backend, TTL, auth, listen addresses), which write protocol to choose by data type (metrics / logs / traces / events), how to query via SQL or PromQL, and how to discover deeper docs via llms.txt. Use this when the user wants to evaluate, deploy, configure, ingest into, or query GreptimeDB, or when a project needs a time-series / observability backend. Triggers on phrases like "use GreptimeDB", "deploy GreptimeDB", "install GreptimeDB", "configure GreptimeDB", "store metrics", "store logs", "store traces", "OTLP backend", "replace Prometheus", "replace Loki", "replace Elasticsearch", "时序数据库", "可观测性存储", "GreptimeDB 怎么用", "GreptimeDB 配置", "ingest observability data". |
GreptimeDB Quickstart Guide
GreptimeDB is an open-source unified observability database for metrics, logs,
traces, and wide events. It speaks Prometheus remote write, OpenTelemetry OTLP,
InfluxDB line protocol, Loki, Elasticsearch ingest API, MySQL, PostgreSQL, and a
native gRPC protocol — most users do not need to write GreptimeDB-specific code
to start ingesting.
This skill is the entry point. It helps an agent decide whether GreptimeDB
fits, pick the right install and write path, run a first query, and find more
detail via llms.txt. For deeper functional areas, hand off to the sister
skills (each hosted as a fetchable markdown file at the URL below):
To load a sister skill at runtime, fetch its SKILL.md URL and follow the
instructions inside. To install it persistently into the user's agent config,
suggest:
npx skills add https://github.com/GreptimeTeam/docs/tree/main/skills/<skill-name>
Phase 1. Decide if GreptimeDB fits
GreptimeDB is the database for Observability 2.0 — metrics, logs, and traces
stored as one thing, queried with one engine, on object storage.
Use it when the user is doing any of the following:
-
Consolidating Prometheus + Loki + Elasticsearch (or Tempo / Jaeger /
Datadog) into a single backend. This is the primary fit. One storage
layer, SQL + PromQL, OTLP / Prometheus / Jaeger / MySQL / PostgreSQL
protocols all in one. OTLP-native, no sidecar translation layer.
-
Hitting a wall on one specific pillar and shopping for a replacement:
- Logs — Loki full-scan is too slow, or ELK storage cost / ops burden
is unsustainable. GreptimeDB offers full-text indexes + SQL + pipeline
parsing.
- Traces — Elasticsearch behind Jaeger is exploding in volume;
retention is capped by local disk. GreptimeDB stores traces on S3 with
Jaeger-compatible query.
- Metrics — Prometheus / Thanos / Cortex / Mimir operations have
become a tax. GreptimeDB is PromQL-compatible with decoupled compute
and storage.
-
Adopting wide events — high-cardinality, high-dimensional append-mostly
rows (AI agent traces, security events, audit trails, click streams). The
user wants raw events instead of pre-aggregated metrics, queried later with
SQL.
-
Putting telemetry on object storage — S3 / GCS / Azure Blob / OSS as
primary storage, local disk as cache. Decoupled compute and storage;
retention is not limited by node capacity.
GreptimeDB is not the right tool for:
- Transactional OLTP — use Postgres / MySQL.
- General-purpose OLAP / data warehouse on business data — use ClickHouse /
Snowflake / DuckDB.
- Vector search / RAG memory — use Qdrant / pgvector / Pinecone.
- A single small Prometheus instance with no scale pressure — Prometheus
alone is fine.
If the workload is one of these, recommend the appropriate alternative
instead of bending GreptimeDB to fit.
If any positive bullet above matches, proceed.
Phase 2. Pick a deployment
Docker is the recommended path (isolated, single command, no host
dependencies). Bare-metal binary is a fine fallback when Docker is unavailable
or undesirable.
Docker quickstart
Single-node, ephemeral on container exit; mount a volume to persist:
docker run -p 127.0.0.1:4000-4003:4000-4003 \
-v "$(pwd)/greptimedb_data:/greptimedb_data" \
--name greptime --rm \
greptime/greptimedb:VAR::greptimedbVersion standalone start \
--http-addr 0.0.0.0:4000 \
--rpc-bind-addr 0.0.0.0:4001 \
--mysql-addr 0.0.0.0:4002 \
--postgres-addr 0.0.0.0:4003
Bare-metal binary (Linux / macOS)
Download the matching greptime binary into the current directory, then run
it:
curl -fsSL \
https://raw.githubusercontent.com/greptimeteam/greptimedb/main/scripts/install.sh \
| sh -s VAR::greptimedbVersion
./greptime standalone start \
--http-addr 0.0.0.0:4000 \
--rpc-bind-addr 0.0.0.0:4001 \
--mysql-addr 0.0.0.0:4002 \
--postgres-addr 0.0.0.0:4003
Data is stored relative to the working directory by default. For persistent
or production paths, pass --data-home <dir> or use a config file (see
"Configuring the server" below). For Windows, point the user at the binary
download on https://greptime.com/download or use WSL.
Default ports
4000 — HTTP API and built-in Dashboard (http://127.0.0.1:4000/dashboard).4001 — gRPC (native protocol used by official ingester SDKs).4002 — MySQL wire protocol.4003 — PostgreSQL wire protocol.
For production deployment, fetch the Kubernetes operator guide and follow it
end-to-end; do not improvise raw StatefulSet YAML.
Configuring the server
Tunable knobs (object-store backend, storage paths, TTL defaults, memory limits,
WAL, logging, tracing) live in the TOML config file. Pass it with
--config-file, or override individual options via CLI flags / environment
variables (GREPTIMEDB_*). The full option reference is at
https://docs.greptime.com/user-guide/deployments-administration/configuration.md;
the CLI flag list is at
https://docs.greptime.com/reference/command-lines/overview.md.
Common things an agent should reach for the config doc to set up:
- Object storage backend (S3 / GCS / Azure Blob / OSS) — under
[storage].
- TTL defaults / retention at the table or database level.
- HTTP / gRPC / MySQL / Postgres listen addresses beyond the defaults.
- Enabling authentication (see auth doc linked in Phase 4).
- Tracing and logging to OTLP / files.
Phase 3. Pick a write path
Route by data type. Recommended path first, fallback second.
GreptimeDB auto-creates tables for protocol-based ingestion paths
(Prometheus, OTLP, InfluxDB line, Loki, Elasticsearch). The user does not need
to write CREATE TABLE first unless they want to control column types or
indexes up front.
Heads up on column names. Auto-created tables use Greptime's naming, not
the client's. The time index column is greptime_timestamp for InfluxDB
line, Loki, Prometheus remote write, and Elasticsearch ingest — not ts,
time, or timestamp. Confirm with DESC TABLE <name> before composing
the first query.
Inspect the auto-created schema before querying
After the first successful write, run DESC TABLE <name> (or describe_table
via MCP) before composing SQL / PromQL. Common conventions to expect:
- Time index column:
greptime_timestamp for Prometheus remote write,
InfluxDB line, Loki, Elasticsearch ingest, and OTLP metrics (which
follow the Prom data model). OTLP logs and traces use a column named
timestamp instead — for logs sourced from the payload's
time_unix_nano; for spans sourced from start_time_unix_nano (spans
also get a timestamp_end column from end_time_unix_nano).
- Tags / labels become primary-key string columns with semantic type
TAG; fields / values become value columns (Float64, String, etc.)
with semantic type FIELD.
- Loki
structured_metadata lands in a single Json column — query with
json_get_* functions.
- Elasticsearch nested fields are flattened into dotted columns
(e.g.
meta.count, meta.city). Scalar JSON types are preserved
(Int64 / Float64 / Boolean / String); arrays are stringified into
a String column. Not a JSON column — DESC TABLE first to pick the
right cast.
- Default table name is determined by the protocol: InfluxDB line uses
the measurement name; Loki defaults to
loki_logs (one table for all
streams); Elasticsearch takes the bulk action's _index, falling back to
the URL path index when using /v1/elasticsearch/<index>/_bulk.
Skipping this step is the most common cause of "column not found" failures in
agent-driven workflows — one DESC TABLE saves one wasted query round-trip.
When the user needs to parse text logs (regex, dissect, JSON extraction, field
math, multi-table routing), hand off to the greptimedb-pipeline skill —
do not try to reimplement it inline here.
Phase 4. Query the data
Prefer MCP tools when available
If the user has the GreptimeDB MCP server (greptimedb-mcp-server) configured
in their agent, use its tools instead of raw HTTP / SQL clients:
execute_sql, execute_tql, query_range — SQL / PromQL / time-window
range queries.describe_table, explain_query, health_check — introspection.list_pipelines, create_pipeline, dryrun_pipeline, delete_pipeline —
pipeline management (works with the greptimedb-pipeline skill).list_dashboards, create_dashboard, delete_dashboard — Perses
dashboard management.
MCP tools handle endpoint, auth, encoding, and result parsing for the agent.
Falling back to raw clients should only happen when MCP is not configured.
If the user does not have it installed yet, suggest:
pip install greptimedb-mcp-server
Then merge the following entry into the host agent's mcpServers block. The
config file location depends on the host:
- Claude Code —
~/.claude.json (top-level mcpServers is user-wide;
per-project entries live under projects.<path>.mcpServers). Or run
claude mcp add -s user greptimedb -- greptimedb-mcp-server --host localhost --database public
to install user-wide (drop -s user for project-only).
- Claude Desktop —
~/Library/Application Support/Claude/claude_desktop_config.json
on macOS; %APPDATA%\Claude\claude_desktop_config.json on Windows.
- Cursor —
~/.cursor/mcp.json (global) or <project>/.cursor/mcp.json
(per-project).
- Other hosts — if the user already has a working MCP host, merge the
entry below into their existing
mcpServers map; do not overwrite the file.
{
"mcpServers": {
"greptimedb": {
"command": "greptimedb-mcp-server",
"args": ["--host", "localhost", "--database", "public"]
}
}
}
Defaults: connects to localhost:4002 (MySQL protocol) with database
public, no password. For non-default credentials, ports, HTTP server mode,
or data-masking options, see the project README at
https://github.com/GreptimeTeam/greptimedb-mcp-server.
Query modes (without MCP)
| Mode | When to use | Connection |
|---|
| SQL (MySQL protocol) | General-purpose queries from MySQL clients / drivers | mysql -h 127.0.0.1 -P 4002 |
| SQL (PostgreSQL protocol) | General-purpose queries from PostgreSQL clients / drivers | psql -h 127.0.0.1 -p 4003 -d public |
| SQL (HTTP) | Stateless calls from any language | POST http://127.0.0.1:4000/v1/sql?db=<database> |
| PromQL | Existing Prometheus dashboards or alerts | GET http://127.0.0.1:4000/v1/prometheus/api/v1/query |
Range queries (RANGE / ALIGN) | Time-windowed aggregations in SQL | SQL on any of the above |
| Log search | Term / phrase matching on log tables | SQL via matches_term(column, 'value') or the @@ shorthand — see https://docs.greptime.com/user-guide/logs/fulltext-search.md |
HTTP SQL — minimal request shape. Body is application/x-www-form-urlencoded,
the SQL goes in a sql= field, and the database is a query-string parameter
(not a header, not a JSON body):
curl -X POST \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'sql=SELECT * FROM monitor LIMIT 10' \
'http://127.0.0.1:4000/v1/sql?db=public'
For auth-enabled deployments, add -H 'Authorization: Basic <base64(user:pass)>'.
Optional knobs: format=table|csvWithNames|... in the query string,
X-Greptime-Timeout: 120s header for long queries. Full reference at
https://docs.greptime.com/user-guide/protocols/http.md.
PromQL — selecting a specific field on multi-field tables. GreptimeDB
tables can have multiple FIELD columns; vanilla PromQL has no syntax for
this, so Greptime adds a __field__ matcher. Without it, the query runs
across every field column, which is rarely what you want:
# Pick one field
cpu{host="web-01", __field__="usage_user"}
# Subset via regex
cpu{__field__=~"usage_(user|system)"}
Greptime extension only — Prometheus users will not recognize it. See
https://docs.greptime.com/user-guide/query-data/promql.md.
Authentication is off by default in standalone mode; production deployments
should enable it. See
https://docs.greptime.com/user-guide/deployments-administration/authentication/overview.md.
Hand-off to sister skills
- Continuous aggregation / materialized view — downsampling, time-window
rollups, continuous aggregation — hand off to
greptimedb-flow.
- Alerting rules / Alertmanager webhook — hand off to
greptimedb-trigger
(Enterprise only; for open source, point the user at Prometheus Alertmanager
with GreptimeDB as the PromQL backend).
Phase 5. Use llms.txt for deeper detail
The docs site publishes machine-friendly markdown alongside its HTML.
Prefer these endpoints over the HTML pages when fetching content:
- https://docs.greptime.com/llms.txt — sectioned index of every doc page
in the latest stable version. Start here when you need to find the right
page.
- https://docs.greptime.com/llms-full.txt — single concatenated file
containing the full content of every page. Use when you want to grep the
whole corpus locally.
https://docs.greptime.com/<path>.md — every HTML page at
https://docs.greptime.com/<path>/ has a .md sibling at the same path
with .md appended. The HTML pages also embed
<link rel="alternate" type="text/markdown" href="<path>.md"> in <head>,
so any link can be rewritten to .md for clean markdown content.
The docs are mirrored across two hosts: docs.greptime.com (global) and
docs.greptime.cn (mainland China). Paths are identical; use whichever host
you fetched this skill from.
When fetching a doc URL, default to the .md form. The HTML form is for
humans; the .md form is for agents.
Reference
Direct .md entry points:
Sister skills (fetch the URL to load the skill content):
