From 7fcdff5d67c5086876af4aa1454b3cc06da195dd Mon Sep 17 00:00:00 2001 From: "Lei, HUANG" Date: Wed, 29 Jul 2026 23:04:25 +0800 Subject: [PATCH 1/2] docs: add manual compaction time range Signed-off-by: Lei, HUANG --- docs/reference/sql/admin.md | 6 ++++ .../manage-data/compaction.md | 28 +++++++++++++++++++ .../current/reference/sql/admin.md | 6 ++++ .../manage-data/compaction.md | 28 +++++++++++++++++++ 4 files changed, 68 insertions(+) diff --git a/docs/reference/sql/admin.md b/docs/reference/sql/admin.md index ecd6b74bc0..be16490068 100644 --- a/docs/reference/sql/admin.md +++ b/docs/reference/sql/admin.md @@ -47,6 +47,12 @@ admin compact_table("test", "swcs", "parallelism=2"); -- Schedule an SWCS compaction with custom time window and parallelism -- admin compact_table("test", "swcs", "window=1800,parallelism=2"); +-- Schedule a regular compaction for the half-open time range [start_time, end_time) -- +admin compact_table("test", "regular", "start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z"); + +-- Schedule an SWCS compaction for a time range -- +admin compact_table("test", "strict_window", "window=3600,start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z"); + -- Garbage collect orphaned SST files for a dropped table -- admin gc_table("test"); diff --git a/docs/user-guide/deployments-administration/manage-data/compaction.md b/docs/user-guide/deployments-administration/manage-data/compaction.md index 37ba6a7f5c..1a86076acc 100644 --- a/docs/user-guide/deployments-administration/manage-data/compaction.md +++ b/docs/user-guide/deployments-administration/manage-data/compaction.md @@ -174,6 +174,34 @@ The `parallelism` parameter is also available for regular compaction: ADMIN COMPACT_TABLE("monitor", "regular", "parallelism=2"); ``` +### Limit manual compaction to a time range + +Both regular and SWCS manual compactions can be limited to a time range by setting `start_time` and `end_time` in the options string: + +```sql +-- Regular compaction for a time range +ADMIN COMPACT_TABLE( + "monitor", + "regular", + "parallelism=2,start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z" +); + +-- SWCS compaction for a time range +ADMIN COMPACT_TABLE( + "monitor", + "strict_window", + "window=3600,start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z" +); +``` + +The time range has the following rules and behavior: + +- `start_time` and `end_time` must be specified together, and `start_time` must be earlier than `end_time`. +- The range is half-open: `[start_time, end_time)`. It selects compaction windows that overlap the range rather than filtering individual rows. +- A timestamp with an explicit time zone or UTC offset uses that zone. A timestamp without one uses the current query session time zone. +- Regular compaction keeps the existing TWCS trigger rules and only considers candidate windows that overlap the range. Specifying a range does not force an otherwise ineligible window to be compacted. +- SWCS preserves its forced-compaction behavior. If an SST file in a selected window also spans other windows, GreptimeDB transitively includes those dependent windows. The actual compacted windows can therefore extend beyond the requested range; this ensures that all rows from shared input SST files are retained. + The following diagram shows the process of strict window compression: In Figure A, there are 3 overlapping SST files: `[0, 3]` (which includes timestamps 0, 1, 2, and 3), `[3, 8]`, and `[8, 10]`. diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/admin.md b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/admin.md index 837e6e96a6..feb62ced3d 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/admin.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/reference/sql/admin.md @@ -46,6 +46,12 @@ admin compact_table("test", "swcs", "parallelism=2"); -- 启动 SWCS compaction，自定义时间窗口和并行度 -- admin compact_table("test", "swcs", "window=1800,parallelism=2"); +-- 对左闭右开的时间范围 [start_time, end_time) 启动常规 compaction -- +admin compact_table("test", "regular", "start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z"); + +-- 对指定时间范围启动 SWCS compaction -- +admin compact_table("test", "strict_window", "window=3600,start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z"); + -- 对已删除的表进行垃圾回收 -- admin gc_table("test"); diff --git a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/compaction.md b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/compaction.md index 67cf5bc92d..94a54f8f69 100644 --- a/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/compaction.md +++ b/i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/manage-data/compaction.md @@ -171,6 +171,34 @@ ADMIN COMPACT_TABLE("monitor", "swcs", "window=1800,parallelism=2"); ADMIN COMPACT_TABLE("monitor", "regular", "parallelism=2"); ``` +### 限定手动压缩的时间范围 + +常规压缩和 SWCS 手动压缩都可以通过在选项字符串中设置 `start_time` 和 `end_time` 来限定时间范围： + +```sql +-- 对指定时间范围执行常规压缩 +ADMIN COMPACT_TABLE( + "monitor", + "regular", + "parallelism=2,start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z" +); + +-- 对指定时间范围执行 SWCS 压缩 +ADMIN COMPACT_TABLE( + "monitor", + "strict_window", + "window=3600,start_time=2026-01-01T00:00:00Z,end_time=2026-02-01T00:00:00Z" +); +``` + +时间范围遵循以下规则和行为： + +- `start_time` 和 `end_time` 必须同时指定，并且 `start_time` 必须早于 `end_time`。 +- 时间范围是左闭右开的 `[start_time, end_time)`。它用于选择与该范围重叠的压缩窗口，而不是过滤单独的数据行。 +- 带有明确时区或 UTC 偏移量的时间戳使用指定的时区；未指定时区的时间戳使用当前查询会话的时区。 +- 常规压缩保留已有的 TWCS 触发规则，并且只考虑与该范围重叠的候选窗口。指定时间范围不会强制压缩不满足触发条件的窗口。 +- SWCS 保留强制压缩语义。如果选中窗口中的 SST 文件还跨越其他窗口，GreptimeDB 会递归包含这些依赖窗口。因此，实际压缩的窗口可能超出请求的时间范围；这可以确保共享输入 SST 文件中的所有数据行都被保留。 + 下图展示了一次 SWCS 压缩的过程： 在图 A 中，有 3 个重叠的 SST 文件，分别是 `[0, 3]`（也就是包含 0、1、2、3 的时间戳）、`[3, 8]` 和 `[8, 10]`。 From 5d42d6f9f11a1e3deadba2579fdbf1e899e4bee3 Mon Sep 17 00:00:00 2001 From: "Lei, HUANG" Date: Wed, 29 Jul 2026 23:17:02 +0800 Subject: [PATCH 2/2] docs: use compaction terminology consistently Signed-off-by: Lei, HUANG --- .../deployments-administration/manage-data/compaction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/deployments-administration/manage-data/compaction.md b/docs/user-guide/deployments-administration/manage-data/compaction.md index 1a86076acc..fec9919410 100644 --- a/docs/user-guide/deployments-administration/manage-data/compaction.md +++ b/docs/user-guide/deployments-administration/manage-data/compaction.md @@ -202,7 +202,7 @@ The time range has the following rules and behavior: - Regular compaction keeps the existing TWCS trigger rules and only considers candidate windows that overlap the range. Specifying a range does not force an otherwise ineligible window to be compacted. - SWCS preserves its forced-compaction behavior. If an SST file in a selected window also spans other windows, GreptimeDB transitively includes those dependent windows. The actual compacted windows can therefore extend beyond the requested range; this ensures that all rows from shared input SST files are retained. -The following diagram shows the process of strict window compression: +The following diagram shows the process of strict window compaction: In Figure A, there are 3 overlapping SST files: `[0, 3]` (which includes timestamps 0, 1, 2, and 3), `[3, 8]`, and `[8, 10]`. The strict window compaction strategy will assign the file `[3, 8]` that covers windows 0, 4, and 8 to three separate windows respectively. This allows it to merge with `[0, 3]` and `[8, 10]` separately.