From 7cda139851a08063dadb34110c042e685f7a0593 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 10 Oct 2025 17:53:47 -0500 Subject: [PATCH] docs(influxdb3): clarify retention period constraints and zero-duration behavior - Add retention period constraints warning (minimum 1h, zero-duration behavior, infinite retention) - Restructure databases/create.md and tables/create.md with retention examples in tool sections - Add Explorer preface instructions to delete.md and list.md - Distinguish Enterprise (table-level) vs Core (database-level) retention capabilities - Update data-retention.md internals documentation with constraints --- content/shared/influxdb3-admin/databases/_index.md | 8 ++++---- content/shared/influxdb3-admin/databases/create.md | 10 +++++++++- content/shared/influxdb3-admin/tables/create.md | 12 ++++++++++-- content/shared/influxdb3-cli/create/database.md | 11 +++++++++-- content/shared/influxdb3-internals/data-retention.md | 12 +----------- 5 files changed, 33 insertions(+), 20 deletions(-) diff --git a/content/shared/influxdb3-admin/databases/_index.md b/content/shared/influxdb3-admin/databases/_index.md index 5e0e05f5e..282f6e88d 100644 --- a/content/shared/influxdb3-admin/databases/_index.md +++ b/content/shared/influxdb3-admin/databases/_index.md @@ -23,8 +23,8 @@ point is marked for deletion and is removed from the database the next time the retention enforcement service runs. By default, data does not expire. When you [create a database](/influxdb3/version/admin/databases/create/), -you can optionally set a retention period. Retention periods can be as short as an hour -or infinite (`none`). +you can optionally set a retention period. +The minimum practical retention period is 1 hour (`1h`). Database retention periods can be [updated after creation](/influxdb3/version/reference/cli/influxdb3/update/database/). For tables within a database, you can [set table-specific retention periods](/influxdb3/version/admin/tables/create/#create-a-table-with-a-retention-period) @@ -44,8 +44,8 @@ When a point's timestamp is beyond the retention period (relative to now), the point is not queryable and will be deleted. By default, data does not expire. When you [create a database](/influxdb3/version/admin/databases/create/), -you can optionally set a retention period. Retention periods can be as short as one hour -(`1h`) or infinite (`none`). +you can optionally set a retention period. +The minimum practical retention period is 1 hour (`1h`). For complete details about retention periods, including duration formats and limitations, see [Data retention in {{< product-name >}}](/influxdb3/version/reference/internals/data-retention/). diff --git a/content/shared/influxdb3-admin/databases/create.md b/content/shared/influxdb3-admin/databases/create.md index 76083457f..d0499b043 100644 --- a/content/shared/influxdb3-admin/databases/create.md +++ b/content/shared/influxdb3-admin/databases/create.md @@ -148,7 +148,6 @@ By default, data does not expire. When creating a database, set a _retention per The retention period value is a time duration value made up of a numeric value plus a duration unit. For example, `30d` means 30 days. -A zero duration (`0d`) retention period is infinite and data won't expire. The retention period value cannot be negative or contain whitespace. #### Valid durations units include @@ -160,6 +159,15 @@ The retention period value cannot be negative or contain whitespace. - **mo**: month - **y**: year +> [!Warning] +> #### Retention period constraints +> +> - **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`). +> - **Zero-duration periods**: Setting a retention period to `0` (for example, +> `0d` or `0h`) is allowed but marks all data for immediate deletion at query time. +> _This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention._ +> - **Infinite retention**: Use `none` to set an infinite retention period. + For more information about retention periods, see [Data retention](/influxdb3/version/reference/internals/data-retention/). {{% show-in "core" %}} diff --git a/content/shared/influxdb3-admin/tables/create.md b/content/shared/influxdb3-admin/tables/create.md index 456875f9c..0c12e0c2d 100644 --- a/content/shared/influxdb3-admin/tables/create.md +++ b/content/shared/influxdb3-admin/tables/create.md @@ -178,7 +178,6 @@ This allows you to maintain different retention policies for different types of The retention period value is a time duration value made up of a numeric value plus a duration unit. For example, `7d` means 7 days. -A zero duration (`0d`) retention period is infinite and data won't expire. The retention period value cannot be negative or contain whitespace. #### Valid durations units include @@ -190,6 +189,15 @@ The retention period value cannot be negative or contain whitespace. - **mo**: month - **y**: year +> [!Warning] +> #### Retention period constraints +> +> - **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`). +> - **Zero-duration periods**: Setting a retention period to `0` (for example, +> `0d` or `0h`) is allowed but marks all data for immediate deletion at query time. +> _This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention._ +> - **Infinite retention**: Use `none` to set an infinite retention period. + ### Retention period precedence When both a database and a table have retention periods defined, the **table retention @@ -213,7 +221,7 @@ For complete details about retention period precedence and behavior, see In {{< product-name >}}, tables use the database retention period. -When data in a table exceeds the database retention period, it is no longer queryable. +Points with timestamps outside of the database's retention period are no longer queryable and are marked for deletion. To control data retention for your tables, set a retention period when [creating the database](/influxdb3/version/admin/databases/create/#retention-period). For more information, see [Data retention in {{% product-name %}}](/influxdb3/version/reference/internals/data-retention/). diff --git a/content/shared/influxdb3-cli/create/database.md b/content/shared/influxdb3-cli/create/database.md index fa9331d30..82378dd33 100644 --- a/content/shared/influxdb3-cli/create/database.md +++ b/content/shared/influxdb3-cli/create/database.md @@ -142,9 +142,16 @@ values using a numeric value plus a duration unit. | `y` | year (365 days) | > [!Note] +> Minute (`m`) and second (`s`) units are not supported for retention periods. + +> [!Warning] +> #### Retention period constraints +> > - **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`). -> Setting `0` (for example, `0d`) marks all data for immediate deletion. -> - **Unsupported units**: Minute (`m`) and second (`s`) units are not supported. +> - **Zero-duration periods**: Setting a retention period to `0` (for example, +> `0d` or `0h`) is allowed but marks all data for immediate deletion at query time. +> _This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention._ +> - **Infinite retention**: Use `none` to set an infinite retention period. ### Example duration values diff --git a/content/shared/influxdb3-internals/data-retention.md b/content/shared/influxdb3-internals/data-retention.md index 65a8e8770..c29e15b95 100644 --- a/content/shared/influxdb3-internals/data-retention.md +++ b/content/shared/influxdb3-internals/data-retention.md @@ -76,7 +76,7 @@ be negative or contain whitespace. > - **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`). > - **Zero-duration periods**: Setting a retention period to `0` (for example, > `0d` or `0h`) is allowed but marks all data for immediate deletion at query time. -> This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention. +> _This differs from InfluxDB 1.x and 2.x where `0d` meant infinite retention._ > - **Infinite retention**: Use `none` to set an infinite retention period. ### Example retention period values @@ -163,17 +163,7 @@ Replace the following: - {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} {{% show-in "core" %}} -## Retention period limitations -{{< product-name >}} has the following limitations for retention periods: - -- **Immutable**: Retention periods cannot be changed after a database is created. - To change the retention period, you must create a new database and migrate your data. -- **Database-only**: Retention periods apply to entire databases. -- **Minimum for data retention**: The practical minimum retention period is 1 hour (`1h`). - Setting `0` is allowed but marks all data for immediate deletion. -- **Query-time enforcement**: Data beyond the retention period is filtered from queries - but may still exist in storage until the retention enforcement service runs. > [!Note] > #### Retention periods are immutable in Core