Scheduled Compaction

Scheduled Compaction is a GreptimeDB Enterprise feature that periodically submits regular compaction requests for all physical Regions that have a leader in a cluster. It runs on the leader Metasrv, uses a cron expression and an IANA time zone to determine the schedule, and stores recent job reports in the Metasrv KV backend.

This feature complements GreptimeDB's automatic and manual compaction. Use it when you want to compact all Regions regularly during a predictable maintenance window.

Configure the plugin

Add the compaction_cronjob plugin to the Metasrv configuration:

[[plugins]]
[plugins.compaction_cronjob]
enable = true
timezone = "Asia/Shanghai"
cron = "0 0 0 * * *"
max_concurrent_regions = 4
compact_parallelism = 1
manual_trigger_cooldown_secs = 3600
max_history_jobs = 100

The cron expression includes seconds. For example, 0 0 0 * * * runs at midnight every day in the configured time zone.

Option	Default	Description
enable	false	Enables scheduled compaction.
timezone	Local IANA time zone, or UTC if it cannot be detected	The time zone used to evaluate cron, for example Asia/Shanghai.
cron	0 0 0 * * *	The compaction schedule.
max_concurrent_regions	4	The maximum number of Region compaction requests submitted concurrently by one job. Must be greater than 0.
compact_parallelism	1	The compaction parallelism passed to each Region request. Must be greater than 0.
manual_trigger_cooldown_secs	3600	The minimum interval between a manual trigger and the most recent job, whether that job was scheduled or manually triggered. Set it to 0 to disable the cooldown. Scheduled jobs are not delayed by this option.
max_history_jobs	100	The maximum number of terminal job reports retained after history pruning runs when a job completes. Must be greater than 0.

Only the leader Metasrv runs the scheduler. After leadership changes, the new leader continues scheduling future jobs from the configured cron expression.

Before starting the scheduler, a new leader marks jobs left in running state as cancelled and writes a warning log. This status change does not cancel Region requests that were already submitted by the previous leader. Cancelled jobs are terminal and participate in history pruning the next time a job completes.

HTTP endpoints

The plugin adds the following endpoints to the Metasrv HTTP server. Replace <metasrv-http-address> with the configured Metasrv HTTP address.

Trigger a job

curl -X POST \
  "http://<metasrv-http-address>/admin/compaction_cronjob/trigger"

Send this request to the leader Metasrv. The request waits for the job to finish submitting Region compaction requests and returns its report.

• Returns 409 Conflict when sent to a follower Metasrv.
• Returns 429 Too Many Requests when the manual trigger is still within manual_trigger_cooldown_secs of the most recent scheduled or manual job.
• Returns 500 Internal Server Error for other failures.

Get a job

curl --get \
  --data-urlencode "job_id=2026-06-16T00:00:00+00:00" \
  "http://<metasrv-http-address>/admin/compaction_cronjob/job"

The job_id is returned by the trigger and job-list endpoints. It is an RFC 3339 timestamp and should be URL encoded. The endpoint returns 404 Not Found when the job does not exist.

List recent jobs

curl --get \
  --data-urlencode "limit=20" \
  "http://<metasrv-http-address>/admin/compaction_cronjob/jobs"

Jobs are ordered by scheduled time in descending order. The optional limit parameter defaults to 20.

Job report

The trigger and query endpoints return JSON job reports. A completed successful job resembles:

{
  "job_id": "2026-06-16T00:00:00+00:00",
  "scheduled_at": "2026-06-16T00:00:00Z",
  "started_at": "2026-06-16T00:00:00.010Z",
  "finished_at": "2026-06-16T00:00:01.010Z",
  "status": "succeeded",
  "execution_result": {
    "total_regions": 8,
    "submitted_regions": 8,
    "failed_regions": []
  }
}

The status field is "running", "succeeded", "partial_failed", or "cancelled". A failed job uses {"failed": "<reason>"} as the status value. The execution result records how many Region requests were attempted and submitted, together with Region-level submission failures.