greptimeteam/greptimedb-trigger

GreptimeDB Trigger Guide

Enterprise only. Triggers are available only in GreptimeDB Enterprise. For open-source deployments, fall back to Prometheus Alertmanager or an external scheduler.

Create GreptimeDB trigger definition as an alternative to Prometheus alerting rules. A trigger periodically runs a query — a SQL SELECT or a TQL EVAL block wrapping a PromQL expression — and turns each result row into an alert instance. Most concepts from Prometheus alerting rules map directly onto trigger DDL, and existing PromQL rules can be hosted as-is through TQL EVAL.

The workflow

To create a GreptimeDB trigger, we should follow these phases:

Phase 1. Understanding GreptimeDB Trigger

First, we should read the trigger reference from the documentation.

There are pages available, use WebFetch to load and understand them:

1. High-level overview and a worked example https://docs.greptime.com/enterprise/trigger/
2. Full trigger syntax reference https://docs.greptime.com/reference/sql/trigger-syntax/

Phase 2. Syntax essentials

The ON clause accepts either:

• a plain SQL SELECT (typical for GreptimeDB-native queries), or
• a TQL EVAL expression that embeds a PromQL-style query — this is the migration path for users porting Prometheus alerting rules.

TQL EVAL syntax inside ON:

ON (TQL EVAL (<start>, <end>, <step>[, <lookback>]) <promql_expression>)

See the TQL reference for the start / end / step semantics.

Example:

CREATE TRIGGER cpu_monitor
ON (
    TQL EVAL (now(), now(), '1m')
    avg_over_time(cpu_usage_total[1m])
) EVERY '1 minute'::INTERVAL
NOTIFY (
    WEBHOOK alert_manager URL 'http://127.0.0.1:9093' WITH (timeout='1m')
);

When the user starts from a PromQL alert rule, keep it as TQL EVAL — do not rewrite it to SQL aggregation just to fit the trigger. For cases where the rule is natively SQL, write a regular SELECT with a time window filter (e.g. WHERE ts >= NOW() - '1 minutes'::INTERVAL) and GROUP BY for per-series evaluation.

Skeleton:

CREATE TRIGGER [IF NOT EXISTS] <trigger_name>
  ON (<SELECT ...>) EVERY <interval>
  [LABELS (<k>=<v>, ...)]
  [ANNOTATIONS (<k>=<v>, ...)]
  [FOR <interval>]
  [KEEP FIRING FOR <interval>]
  NOTIFY (
    WEBHOOK <notify_name> URL '<url>' [WITH (<k>=<v>, ...)]
  );

Key clauses:

• ON (<SELECT>) EVERY <interval> — the query runs on the given cadence. Each returned row produces one alert instance, keyed by its label set. Columns whose name or alias starts with label_ are extracted as dynamic labels (the label_ prefix is stripped); all other columns become annotations. Rows with the same label set collapse into a single alert.
• LABELS (...) — static labels merged into every alert instance. These are what Alertmanager routes / groups / silences on.
• ANNOTATIONS (...) — static annotations for human-readable context.
• FOR <interval> — how long the condition must keep matching before the alert transitions from Pending to Firing (and fires a notification). Without FOR, an alert fires on first appearance.
• KEEP FIRING FOR <interval> — sets a minimum firing duration. Once an alert enters Firing, it remains firing for at least this long, even if the condition later stops matching. After that duration has elapsed, it can be marked resolved on a subsequent evaluation where the condition is absent.
• NOTIFY (WEBHOOK ...) — currently only the WEBHOOK channel is supported, with an optional WITH (timeout='1m') parameter. Payload is compatible with Prometheus Alertmanager, so an existing Alertmanager can receive trigger alerts without glue code.

Interval notes: INTERVAL expressions may not use years or months (variable-length). Minimum granularity is 1 second.

Worked SQL example:

CREATE TRIGGER IF NOT EXISTS `load1_monitor`
  ON (
    SELECT
      host          AS label_host,
      avg(load1)    AS avg_load1,
      max(ts)       AS ts
    FROM public.load1
    WHERE ts >= NOW() - '1 minutes'::INTERVAL
    GROUP BY host
    HAVING avg(load1) > 10
  ) EVERY '1 minutes'::INTERVAL
  FOR '3 minutes'::INTERVAL
  KEEP FIRING FOR '3 minutes'::INTERVAL
  LABELS (severity=warning)
  ANNOTATIONS (comment='Your computer is smoking, should take a break.')
  NOTIFY (
    WEBHOOK alert_manager URL 'http://localhost:9093' WITH (timeout='1m')
  );

Lifecycle: SHOW TRIGGERS [LIKE ... | WHERE ...], SHOW CREATE TRIGGER <name>, DROP TRIGGER [IF EXISTS] <name>.

Phase 3. Configure webhook for trigger

Return a complete CREATE TRIGGER SQL statement. If the user did not provide webhook details, use a placeholder Alertmanager URL (e.g. http://localhost:9093) and tell them what to swap in.

If the user already runs a Prometheus Alertmanager, point the trigger webhook at the same Alertmanager — the alert payload is Alertmanager-native, so routing / grouping / inhibition / silencing all work unchanged.

Reference

Prometheus Alertmanager

Alertmanager is typically configured in prometheus.yml like this:

# Alerting specifies settings related to the Alertmanager
alerting:
  alertmanagers:
    - static_configs:
      - targets:
        # Alertmanager's default port is 9093
        - localhost:9093

We can use this target as our webhook destination.

Step-by-step guide

https://greptime.com/blogs/2025-12-23-trigger-quick-start