From d5866d17372d262281c0bb0b27eabc9c9e8e37b8 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 10 Oct 2025 15:00:52 -0500 Subject: [PATCH 1/6] feat(influxdb3): Data retention in Core and Enterprise: - Adds /reference/internals/data-retention/ for data retention behavior and retention period details - admin/databases and admin/tables: - Adds examples for API and retention period - Adds cautions and behavior notes for Core retention - reference/cli/influxdb3: Adds usage examples and details - Closes /influxdata/DAR/issues/548 --- .../influxdb3/core/admin/databases/_index.md | 4 +- .../influxdb3/core/admin/databases/create.md | 26 +- .../influxdb3/core/admin/databases/delete.md | 17 +- .../influxdb3/core/admin/databases/list.md | 13 +- content/influxdb3/core/admin/tables/create.md | 19 +- content/influxdb3/core/admin/tables/list.md | 16 +- .../cli/influxdb3/create/database.md | 4 + .../reference/internals/data-retention.md | 22 + content/influxdb3/enterprise/admin/_index.md | 2 +- .../enterprise/admin/databases/_index.md | 2 + .../enterprise/admin/databases/create.md | 27 +- .../enterprise/admin/databases/delete.md | 17 +- .../enterprise/admin/databases/list.md | 13 +- .../enterprise/admin/tables/_index.md | 2 + .../enterprise/admin/tables/create.md | 30 +- .../enterprise/admin/tables/delete.md | 4 +- .../influxdb3/enterprise/admin/tables/list.md | 18 +- .../cli/influxdb3/create/database.md | 4 + .../reference/cli/influxdb3/create/table.md | 4 + .../cli/influxdb3/update/database.md | 3 + .../reference/internals/data-retention.md | 27 ++ .../influxdb3-admin/databases/_index.md | 29 +- .../influxdb3-admin/databases/create.md | 201 +++++++-- .../influxdb3-admin/databases/delete.md | 61 ++- .../shared/influxdb3-admin/databases/list.md | 68 ++- .../shared/influxdb3-admin/tables/create.md | 195 +++++--- .../shared/influxdb3-admin/tables/delete.md | 23 +- content/shared/influxdb3-admin/tables/list.md | 4 +- .../shared/influxdb3-cli/create/database.md | 83 +++- .../influxdb3-cli/update/database/_index.md | 34 +- .../influxdb3-internals/data-retention.md | 417 ++++++++++++++++++ 31 files changed, 1174 insertions(+), 215 deletions(-) create mode 100644 content/influxdb3/core/reference/internals/data-retention.md create mode 100644 content/influxdb3/enterprise/reference/internals/data-retention.md create mode 100644 content/shared/influxdb3-internals/data-retention.md diff --git a/content/influxdb3/core/admin/databases/_index.md b/content/influxdb3/core/admin/databases/_index.md index 87623fd74..9ed468390 100644 --- a/content/influxdb3/core/admin/databases/_index.md +++ b/content/influxdb3/core/admin/databases/_index.md @@ -12,6 +12,8 @@ influxdb3/core/tags: [databases] related: - /influxdb3/core/write-data/best-practices/schema-design/ - /influxdb3/core/reference/cli/influxdb3/ + - /influxdb3/core/api/v3/#tag/Database, Database API reference + - /influxdb3/core/reference/internals/data-retention/ - /influxdb3/explorer/manage-databases/ alt_links: cloud: /influxdb/cloud/admin/buckets/ @@ -22,5 +24,5 @@ source: /shared/influxdb3-admin/databases/_index.md --- diff --git a/content/influxdb3/core/admin/databases/create.md b/content/influxdb3/core/admin/databases/create.md index 00431430b..784d8952e 100644 --- a/content/influxdb3/core/admin/databases/create.md +++ b/content/influxdb3/core/admin/databases/create.md @@ -1,23 +1,35 @@ --- title: Create a database description: > - Use the [`influxdb3 create database` command](/influxdb3/core/reference/cli/influxdb3/create/database/) - to create a new database in {{< product-name >}}. + Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to create a new database + in {{< product-name >}}. menu: influxdb3_core: parent: Manage databases weight: 201 list_code_example: | - - {{% code-placeholders "DATABASE_NAME" %}} - ```sh - influxdb3 create database DATABASE_NAME + + ```sh{placeholders="DATABASE_NAME|AUTH_TOKEN"} + # influxdb3 CLI + influxdb3 create database \ + --retention-period 30d \ + DATABASE_NAME + + # HTTP API + curl --request POST "http://localhost:8181/api/v3/configure/database" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "retention_period": "30d" + }' ``` - {{% /code-placeholders %}} related: - /influxdb3/core/reference/cli/influxdb3/create/database/ + - /influxdb3/core/api/v3/#operation/PostConfigureDatabase, Create database API - /influxdb3/core/reference/naming-restrictions/ + - /influxdb3/core/reference/internals/data-retention/ - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/create.md --- diff --git a/content/influxdb3/core/admin/databases/delete.md b/content/influxdb3/core/admin/databases/delete.md index 69bb8aaea..93878b9f3 100644 --- a/content/influxdb3/core/admin/databases/delete.md +++ b/content/influxdb3/core/admin/databases/delete.md @@ -1,25 +1,28 @@ --- title: Delete a database description: > - Use the [`influxdb3 delete database` command](/influxdb3/core/reference/cli/influxdb3/delete/database/) - to delete a database from {{< product-name >}}. - Provide the name of the database you want to delete. + Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to delete a database + from {{< product-name >}}. menu: influxdb3_core: parent: Manage databases weight: 203 list_code_example: | - {{% code-placeholders "DATABASE_NAME" %}} - ```sh + ```sh{placeholders="DATABASE_NAME"} + # influxdb3 CLI influxdb3 delete database DATABASE_NAME + + # HTTP API + curl --request DELETE "http://localhost:8181/api/v3/configure/database?db=DATABASE_NAME" \ + --header "Authorization: Bearer AUTH_TOKEN" ``` - {{% /code-placeholders %}} related: - /influxdb3/core/reference/cli/influxdb3/delete/database/ + - /influxdb3/core/api/v3/#operation/DeleteConfigureDatabase, Delete database API - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/delete.md --- diff --git a/content/influxdb3/core/admin/databases/list.md b/content/influxdb3/core/admin/databases/list.md index 4be161e41..ae4a0a8dd 100644 --- a/content/influxdb3/core/admin/databases/list.md +++ b/content/influxdb3/core/admin/databases/list.md @@ -1,22 +1,27 @@ --- title: List databases description: > - Use the [`influxdb3 show databases` command](/influxdb3/core/reference/cli/influxdb3/show/databases/) - to list databases in {{< product-name >}}. + Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to list databases in {{< product-name >}}. menu: influxdb3_core: parent: Manage databases weight: 202 list_code_example: | - ```sh + ```sh{placeholders="AUTH_TOKEN"} + # influxdb3 CLI influxdb3 show databases + + # HTTP API + curl --request GET "http://localhost:8181/api/v3/configure/database" \ + --header "Authorization: Bearer AUTH_TOKEN" ``` related: - /influxdb3/core/reference/cli/influxdb3/show/databases/ + - /influxdb3/core/api/v3/#operation/GetConfigureDatabase, List databases API - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/list.md --- diff --git a/content/influxdb3/core/admin/tables/create.md b/content/influxdb3/core/admin/tables/create.md index 21b73a9e8..ca998216b 100644 --- a/content/influxdb3/core/admin/tables/create.md +++ b/content/influxdb3/core/admin/tables/create.md @@ -1,27 +1,26 @@ --- title: Create a table description: > - Use the [`influxdb3 create table` command](/influxdb3/core/reference/cli/influxdb3/create/table/) - or the [HTTP API](/influxdb3/core/api/v3/) to create a new table in a specified database in InfluxDB 3 Core. - Provide the database name, table name, and tag columns. + Use the influxdb3 CLI or HTTP API to create a table in a specified database + in {{< product-name >}}. menu: influxdb3_core: parent: Manage tables weight: 201 list_code_example: | - ```sh - # CLI + ```sh{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"} + # influxdb3 CLI influxdb3 create table \ --tags tag1,tag2,tag3 \ - --database \ - --token \ - + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + TABLE_NAME # HTTP API curl -X POST "http://localhost:8181/api/v3/configure/table" \ - --header "Authorization: Bearer " \ + --header "Authorization: Bearer AUTH_TOKEN" \ --header "Content-Type: application/json" \ - --data '{"db": "", "table": "", "tags": ["tag1", "tag2", "tag3"]}' + --data '{"db": "DATABASE_NAME", "table": "TABLE_NAME", "tags": ["tag1", "tag2", "tag3"]}' ``` related: - /influxdb3/core/reference/cli/influxdb3/create/table/ diff --git a/content/influxdb3/core/admin/tables/list.md b/content/influxdb3/core/admin/tables/list.md index 3cc4ab7ac..8f34315d6 100644 --- a/content/influxdb3/core/admin/tables/list.md +++ b/content/influxdb3/core/admin/tables/list.md @@ -1,25 +1,25 @@ --- title: List tables description: > - Use the [`influxdb3 query` command](/influxdb3/core/reference/cli/influxdb3/query/) - or the [HTTP API](/influxdb3/core/api/v3/) to list tables in a specified database in {{< product-name >}}. + Use the influxdb3 CLI or HTTP API to list tables in a specified database + in {{< product-name >}}. Use SQL SHOW TABLES or InfluxQL SHOW MEASUREMENTS statements. menu: influxdb3_core: parent: Manage tables weight: 202 list_code_example: | - ```sh - # CLI + ```sh{placeholders="DATABASE_NAME|AUTH_TOKEN"} + # influxdb3 CLI influxdb3 query \ - --database \ - --token \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ "SHOW TABLES" # HTTP API curl --get "http://localhost:8181/api/v3/query_sql" \ - --header "Authorization: Bearer " \ - --data-urlencode "db=" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SHOW TABLES" ``` related: diff --git a/content/influxdb3/core/reference/cli/influxdb3/create/database.md b/content/influxdb3/core/reference/cli/influxdb3/create/database.md index 970660fb4..a957f4ac7 100644 --- a/content/influxdb3/core/reference/cli/influxdb3/create/database.md +++ b/content/influxdb3/core/reference/cli/influxdb3/create/database.md @@ -7,6 +7,10 @@ menu: parent: influxdb3 create name: influxdb3 create database weight: 400 +related: + - /influxdb3/core/admin/databases/create/ + - /influxdb3/core/api/v3/#operation/PostConfigureDatabase, Create database API + - /influxdb3/core/reference/internals/data-retention/ source: /shared/influxdb3-cli/create/database.md --- diff --git a/content/influxdb3/core/reference/internals/data-retention.md b/content/influxdb3/core/reference/internals/data-retention.md new file mode 100644 index 000000000..ffa4b98cb --- /dev/null +++ b/content/influxdb3/core/reference/internals/data-retention.md @@ -0,0 +1,22 @@ +--- +title: Data retention in {{< product-name >}} +description: > + {{% product-name %}} enforces database retention periods at query time. + Retention periods are set when creating a database and cannot be changed afterward. +weight: 103 +menu: + influxdb3_core: + name: Data retention + parent: Core internals +influxdb3/core/tags: [internals, retention] +related: + - /influxdb3/core/admin/databases/create/ + - /influxdb3/core/reference/cli/influxdb3/create/database/ + - /influxdb3/core/api/v3/#operation/PostConfigureDatabase, Create database API + - /influxdb3/core/reference/glossary/#retention-period +source: /shared/influxdb3-internals/data-retention.md +--- + + diff --git a/content/influxdb3/enterprise/admin/_index.md b/content/influxdb3/enterprise/admin/_index.md index f546ae387..3686c80aa 100644 --- a/content/influxdb3/enterprise/admin/_index.md +++ b/content/influxdb3/enterprise/admin/_index.md @@ -11,5 +11,5 @@ source: /shared/influxdb3-admin/_index.md --- diff --git a/content/influxdb3/enterprise/admin/databases/_index.md b/content/influxdb3/enterprise/admin/databases/_index.md index c93183766..6b2349a2b 100644 --- a/content/influxdb3/enterprise/admin/databases/_index.md +++ b/content/influxdb3/enterprise/admin/databases/_index.md @@ -12,6 +12,8 @@ influxdb3/enterprise/tags: [databases] related: - /influxdb3/enterprise/write-data/best-practices/schema-design/ - /influxdb3/enterprise/reference/cli/influxdb3/ + - /influxdb3/enterprise/api/v3/#tag/Database, Database API reference + - /influxdb3/enterprise/reference/internals/data-retention/ - /influxdb3/explorer/manage-databases/ alt_links: cloud: /influxdb/cloud/admin/buckets/ diff --git a/content/influxdb3/enterprise/admin/databases/create.md b/content/influxdb3/enterprise/admin/databases/create.md index 442df2032..cd3d3baa8 100644 --- a/content/influxdb3/enterprise/admin/databases/create.md +++ b/content/influxdb3/enterprise/admin/databases/create.md @@ -1,23 +1,36 @@ --- title: Create a database description: > - Use the [`influxdb3 create database` command](/influxdb3/enterprise/reference/cli/influxdb3/create/database/) - to create a new database in {{< product-name >}}. + Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to create a new database + in {{< product-name >}}. menu: influxdb3_enterprise: parent: Manage databases weight: 201 list_code_example: | - - {{% code-placeholders "DATABASE_NAME" %}} - ```sh - influxdb3 create database DATABASE_NAME + + ```sh{placeholders="DATABASE_NAME"} + + # influxdb3 CLI + influxdb3 create database \ + --retention-period 30d \ + DATABASE_NAME + + # HTTP API + curl --request POST "http://localhost:8181/api/v3/configure/database" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "retention_period": "30d" + }' ``` - {{% /code-placeholders %}} related: - /influxdb3/enterprise/reference/cli/influxdb3/create/database/ + - /influxdb3/enterprise/api/v3/#operation/PostConfigureDatabase, Create database API - /influxdb3/enterprise/reference/naming-restrictions/ + - /influxdb3/enterprise/reference/internals/data-retention/ - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/create.md --- diff --git a/content/influxdb3/enterprise/admin/databases/delete.md b/content/influxdb3/enterprise/admin/databases/delete.md index 9ae9b963e..8371ade61 100644 --- a/content/influxdb3/enterprise/admin/databases/delete.md +++ b/content/influxdb3/enterprise/admin/databases/delete.md @@ -1,25 +1,28 @@ --- title: Delete a database description: > - Use the [`influxdb3 delete database` command](/influxdb3/enterprise/reference/cli/influxdb3/delete/database/) - to delete a database from {{< product-name >}}. - Provide the name of the database you want to delete. + Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to delete a database + from {{< product-name >}}. menu: influxdb3_enterprise: parent: Manage databases weight: 203 list_code_example: | - {{% code-placeholders "DATABASE_NAME" %}} - ```sh + ```sh{placeholders="DATABASE_NAME|AUTH_TOKEN"} + # influxdb3 CLI influxdb3 delete database DATABASE_NAME + + # HTTP API + curl --request DELETE "http://localhost:8181/api/v3/configure/database?db=DATABASE_NAME" \ + --header "Authorization: Bearer AUTH_TOKEN" ``` - {{% /code-placeholders %}} related: - /influxdb3/enterprise/reference/cli/influxdb3/delete/database/ + - /influxdb3/enterprise/api/v3/#operation/DeleteConfigureDatabase, Delete database API - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/delete.md --- diff --git a/content/influxdb3/enterprise/admin/databases/list.md b/content/influxdb3/enterprise/admin/databases/list.md index e9d5cd374..ae9c4fa0b 100644 --- a/content/influxdb3/enterprise/admin/databases/list.md +++ b/content/influxdb3/enterprise/admin/databases/list.md @@ -1,22 +1,27 @@ --- title: List databases description: > - Use the [`influxdb3 show databases` command](/influxdb3/enterprise/reference/cli/influxdb3/show/databases/) - to list databases in {{< product-name >}}. + Use the influxdb3 CLI, HTTP API, or InfluxDB 3 Explorer to list databases in {{< product-name >}}. menu: influxdb3_enterprise: parent: Manage databases weight: 202 list_code_example: | - ```sh + ```sh{placeholders="AUTH_TOKEN"} + # influxdb3 CLI influxdb3 show databases + + # HTTP API + curl --request GET "http://localhost:8181/api/v3/configure/database" \ + --header "Authorization: Bearer AUTH_TOKEN" ``` related: - /influxdb3/enterprise/reference/cli/influxdb3/show/databases/ + - /influxdb3/enterprise/api/v3/#operation/GetConfigureDatabase, List databases API - /influxdb3/explorer/manage-databases/ source: /shared/influxdb3-admin/databases/list.md --- diff --git a/content/influxdb3/enterprise/admin/tables/_index.md b/content/influxdb3/enterprise/admin/tables/_index.md index 4a61775c4..eee4b13e9 100644 --- a/content/influxdb3/enterprise/admin/tables/_index.md +++ b/content/influxdb3/enterprise/admin/tables/_index.md @@ -12,7 +12,9 @@ influxdb3/enterprise/tags: [tables] related: - /influxdb3/enterprise/write-data/best-practices/schema-design/ - /influxdb3/enterprise/reference/cli/influxdb3/ + - /influxdb3/enterprise/api/v3/#tag/Table, Table API reference - /influxdb3/enterprise/reference/naming-restrictions/ + - /influxdb3/enterprise/reference/internals/data-retention/ source: /shared/influxdb3-admin/tables/_index.md --- diff --git a/content/influxdb3/enterprise/admin/tables/create.md b/content/influxdb3/enterprise/admin/tables/create.md index 70f88c530..ef786ca04 100644 --- a/content/influxdb3/enterprise/admin/tables/create.md +++ b/content/influxdb3/enterprise/admin/tables/create.md @@ -1,32 +1,38 @@ --- title: Create a table description: > - Use the [`influxdb3 create table` command](/influxdb3/enterprise/reference/cli/influxdb3/create/table/) - or the [HTTP API](/influxdb3/enterprise/api/v3/) to create a new table in a specified database - in InfluxDB 3 Enterprise. Provide the database name, table name, and tag columns. + Use the influxdb3 CLI or HTTP API to create a table in a specified database + in {{< product-name >}}. menu: influxdb3_enterprise: parent: Manage tables weight: 201 list_code_example: | - ```sh - # CLI + ```sh{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"} + # influxdb3 CLI influxdb3 create table \ --tags tag1,tag2,tag3 \ - --database \ - --token \ - + --retention-period 7d \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + TABLE_NAME # HTTP API - curl -X POST "http://localhost:8181/api/v3/configure/table" \ - --header "Authorization: Bearer " \ + curl --request POST "http://localhost:8181/api/v3/configure/table" \ --header "Content-Type: application/json" \ - --data '{"db": "", "table": "", "tags": ["tag1", "tag2", "tag3"]}' + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "table": "TABLE_NAME", + "tags": ["tag1", "tag2", "tag3"], + "retention_period": "7d" + }' ``` related: - /influxdb3/enterprise/reference/cli/influxdb3/create/table/ + - /influxdb3/enterprise/api/v3/#operation/PostConfigureTable, Create table API - /influxdb3/enterprise/reference/naming-restrictions/ - - /influxdb3/enterprise/api/v3/ + - /influxdb3/enterprise/reference/internals/data-retention/ source: /shared/influxdb3-admin/tables/create.md --- diff --git a/content/influxdb3/enterprise/admin/tables/delete.md b/content/influxdb3/enterprise/admin/tables/delete.md index 8314f7cd1..8580ca7e3 100644 --- a/content/influxdb3/enterprise/admin/tables/delete.md +++ b/content/influxdb3/enterprise/admin/tables/delete.md @@ -2,7 +2,7 @@ title: Delete a table description: > Use the [`influxdb3 delete table` command](/influxdb3/enterprise/reference/cli/influxdb3/delete/table/) - or the [HTTP API](/influxdb3/enterprise/api/v3/) to delete a table from a specified database in InfluxDB 3 Enterprise. + or the [HTTP API](/influxdb3/enterprise/api/v3/) to delete a table from a specified database in {{< product-name >}}. Supports both soft delete and hard delete operations. menu: influxdb3_enterprise: @@ -22,7 +22,7 @@ list_code_example: | ``` related: - /influxdb3/enterprise/reference/cli/influxdb3/delete/table/ - - /influxdb3/enterprise/api/v3/ + - /influxdb3/enterprise/api/v3/#operation/DeleteConfigureTable, Delete table API source: /shared/influxdb3-admin/tables/delete.md --- diff --git a/content/influxdb3/enterprise/admin/tables/list.md b/content/influxdb3/enterprise/admin/tables/list.md index e76a17a01..bc013aece 100644 --- a/content/influxdb3/enterprise/admin/tables/list.md +++ b/content/influxdb3/enterprise/admin/tables/list.md @@ -1,30 +1,30 @@ --- title: List tables description: > - Use the [`influxdb3 query` command](/influxdb3/enterprise/reference/cli/influxdb3/query/) - or the [HTTP API](/influxdb3/enterprise/api/v3/) to list tables in a specified database in {{% product-name %}}. + Use the influxdb3 CLI or HTTP API to list tables in a specified database + in {{< product-name >}}. Use SQL SHOW TABLES or InfluxQL SHOW MEASUREMENTS statements. menu: influxdb3_enterprise: parent: Manage tables weight: 202 list_code_example: | - ```sh - # CLI + ```sh{placeholders="DATABASE_NAME|AUTH_TOKEN"} + # influxdb3 CLI influxdb3 query \ - --database \ - --token \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ "SHOW TABLES" # HTTP API curl --get "http://localhost:8181/api/v3/query_sql" \ - --header "Authorization: Bearer " \ - --data-urlencode "db=" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data-urlencode "db=DATABASE_NAME" \ --data-urlencode "q=SHOW TABLES" ``` related: - /influxdb3/enterprise/reference/cli/influxdb3/query/ - - /influxdb3/enterprise/api/v3/ + - /influxdb3/enterprise/api/v3/#operation/GetQuerySql, Query API source: /shared/influxdb3-admin/tables/list.md --- diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/database.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/database.md index 1260906f9..5a1d61c7d 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/database.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/database.md @@ -7,6 +7,10 @@ menu: parent: influxdb3 create name: influxdb3 create database weight: 400 +related: + - /influxdb3/enterprise/admin/databases/create/ + - /influxdb3/enterprise/api/v3/#operation/PostConfigureDatabase, Create database API + - /influxdb3/enterprise/reference/internals/data-retention/ source: /shared/influxdb3-cli/create/database.md --- diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/create/table.md b/content/influxdb3/enterprise/reference/cli/influxdb3/create/table.md index fbfb8ed27..26c53e503 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/create/table.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/create/table.md @@ -7,6 +7,10 @@ menu: parent: influxdb3 create name: influxdb3 create table weight: 400 +related: + - /influxdb3/enterprise/admin/tables/create/ + - /influxdb3/enterprise/api/v3/#operation/PostConfigureTable, Create table API + - /influxdb3/enterprise/reference/internals/data-retention/ source: /shared/influxdb3-cli/create/table.md --- diff --git a/content/influxdb3/enterprise/reference/cli/influxdb3/update/database.md b/content/influxdb3/enterprise/reference/cli/influxdb3/update/database.md index 0a8130a62..289af5e08 100644 --- a/content/influxdb3/enterprise/reference/cli/influxdb3/update/database.md +++ b/content/influxdb3/enterprise/reference/cli/influxdb3/update/database.md @@ -7,6 +7,9 @@ menu: parent: influxdb3 update name: influxdb3 update database weight: 400 +related: + - /influxdb3/enterprise/api/v3/#operation/PatchConfigureDatabase, Update database API + - /influxdb3/enterprise/reference/internals/data-retention/ source: /shared/influxdb3-cli/update/database/_index.md --- diff --git a/content/influxdb3/enterprise/reference/internals/data-retention.md b/content/influxdb3/enterprise/reference/internals/data-retention.md new file mode 100644 index 000000000..9bae03474 --- /dev/null +++ b/content/influxdb3/enterprise/reference/internals/data-retention.md @@ -0,0 +1,27 @@ +--- +title: Data retention in {{< product-name >}} +description: > + {{% product-name %}} enforces database and table retention periods at query time + and, to optimize storage, routinely deletes expired data. +weight: 103 +menu: + influxdb3_enterprise: + name: Data retention + parent: Enterprise internals +influxdb3/enterprise/tags: [internals, retention] +related: + - /influxdb3/enterprise/admin/databases/create/ + - /influxdb3/enterprise/admin/tables/create/ + - /influxdb3/enterprise/reference/cli/influxdb3/create/database/ + - /influxdb3/enterprise/reference/cli/influxdb3/create/table/ + - /influxdb3/enterprise/reference/cli/influxdb3/update/database/ + - /influxdb3/enterprise/api/v3/#operation/PostConfigureDatabase, Create database API + - /influxdb3/enterprise/api/v3/#operation/PostConfigureTable, Create table API + - /influxdb3/enterprise/api/v3/#operation/PatchConfigureDatabase, Update database API + - /influxdb3/enterprise/reference/glossary/#retention-period +source: /shared/influxdb3-internals/data-retention.md +--- + + diff --git a/content/shared/influxdb3-admin/databases/_index.md b/content/shared/influxdb3-admin/databases/_index.md index f3f59aef7..4e6433a04 100644 --- a/content/shared/influxdb3-admin/databases/_index.md +++ b/content/shared/influxdb3-admin/databases/_index.md @@ -22,8 +22,33 @@ When a point's timestamp is beyond the retention period (relative to now), the point is marked for deletion and is removed from the database the next time the retention enforcement service runs. -The _maximum_ retention period is infinite (`none`) meaning data does not expire -and will never be removed by the retention enforcement service. +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`). + +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) +that override the database retention period. + +For complete details about retention periods, including duration formats, precedence +rules, and deletion behavior, see +[Data retention in {{< product-name >}}](/influxdb3/version/reference/internals/data-retention/). +{{% /show-in %}} + +{{% show-in "core" %}} +## Retention periods + +A database **retention period** is the maximum age of data stored in the database. +The age of data is determined by the timestamp associated with each point. +When a point's timestamp is beyond the retention period (relative to now), the +point is not queryable. + +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`). + +For complete details about retention periods, including duration formats and limitations, +see [Data retention in {{< product-name >}}](/influxdb3/version/reference/internals/data-retention/). {{% /show-in %}} ## Database, table, and column limits diff --git a/content/shared/influxdb3-admin/databases/create.md b/content/shared/influxdb3-admin/databases/create.md index fd9546174..76083457f 100644 --- a/content/shared/influxdb3-admin/databases/create.md +++ b/content/shared/influxdb3-admin/databases/create.md @@ -1,42 +1,157 @@ -Use the [`influxdb3 create database` command](/influxdb3/version/reference/cli/influxdb3/create/database/) +Use the [`influxdb3 create database` command](/influxdb3/version/reference/cli/influxdb3/create/database/), +the [HTTP API](/influxdb3/version/api/v3/), or [InfluxDB 3 Explorer](/influxdb3/explorer/) to create a database in {{< product-name >}}. -Provide the following: - -- Database name _(see [Database naming restrictions](#database-naming-restrictions))_ -- {{< product-name >}} {{% token-link "admin" "admin" %}} - - - - -{{% code-placeholders "DATABASE_NAME" %}} - -```sh -influxdb3 create database DATABASE_NAME -``` - -{{% /code-placeholders %}} +- [Create a database using the influxdb3 CLI](#create-a-database-using-the-influxdb3-cli) +- [Create a database using the HTTP API](#create-a-database-using-the-http-api) +- [Create a database using InfluxDB 3 Explorer](#create-a-database-using-influxdb-3-explorer) +- [Retention period](#retention-period) - [Database naming restrictions](#database-naming-restrictions) - [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention) - [Database limit](#database-limit) - + +```sh{placeholders="DATABASE_NAME|AUTH_TOKEN"} +# Create a database with a 30-day retention period +influxdb3 create database --retention-period 30d DATABASE_NAME + +# Create a database with a 90-day retention period using authentication +influxdb3 create database \ + --retention-period 90d \ + --token AUTH_TOKEN \ + DATABASE_NAME + +# Create a database with infinite retention (default) +influxdb3 create database DATABASE_NAME +``` + +Replace the following: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +## Create a database using the HTTP API + +To create a database using the HTTP API, send a `POST` request to the `/api/v3/configure/database` endpoint: + +{{% api-endpoint method="POST" endpoint="{{< influxdb/host >}}/api/v3/configure/database" %}} + +Include the following in your request: + +- **Headers**: + - `Content-Type: application/json` + - `Authorization: Bearer` with your {{% token-link "admin" %}} +- **Request body** (JSON object): + - `db` _(string, required)_: Database name + - `retention_period` _(string, optional)_: [Retention period](#retention-period). If omitted, data doesn't expire. + +{{% show-in "core" %}} +> [!Important] +> #### Retention periods are immutable in Core +> +> In {{< product-name >}}, retention periods can only be set when creating a database +> and cannot be changed afterward. If you need to change a retention period, you must +> create a new database with the desired retention period and migrate your data. +{{% /show-in %}} + +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} +# Create a database with a 30-day retention period +curl --request POST "{{< influxdb/host >}}/api/v3/configure/database" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "retention_period": "30d" + }' + +# Create a database with a 90-day retention period +curl --request POST "{{< influxdb/host >}}/api/v3/configure/database" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "retention_period": "90d" + }' + +# Create a database with infinite retention (default) +curl --request POST "{{< influxdb/host >}}/api/v3/configure/database" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME" + }' +``` + +Replace the following: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +### Response + +A successful request returns HTTP status `200` with the database configuration. + +## Create a database using InfluxDB 3 Explorer + +> [!Caution] +> Currently, you can't set a retention period when creating a database in Explorer. +> To create a database with a retention period, see one of the following: +> - [Create a database using the influxdb3 CLI](#create-a-database-using-the-influxdb3-cli) +> - [Create a database using the HTTP API](#create-a-database-using-the-http-api) + +{{% show-in "core" %}} +> [!Important] +> #### Retention periods are immutable in Core +> +> After creating a database in {{< product-name >}}, you cannot change its retention period. +{{% /show-in %}} + +Use the [InfluxDB 3 Explorer](/influxdb3/explorer/) web interface to create a database in {{% product-name %}}: + +1. If you haven't already, see how to [get started with Explorer and connect to your {{% product-name %}} server](/influxdb3/explorer/get-started/). +2. In Explorer, click **Manage Databases** in the left navigation. +3. Click **+ Create New**. +4. Enter a database name. +5. Click **Create Database**. + +For more information, see [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/). + +- [Retention period](#retention-period) +- [Database naming restrictions](#database-naming-restrictions) +- [InfluxQL DBRP naming convention](#influxql-dbrp-naming-convention) +- [Database limit](#database-limit) + +## Retention period + +By default, data does not expire. When creating a database, set a _retention period_ to automatically delete expired data and optimize storage. + +### Retention period syntax -Use the `--retention-period` flag to define a specific -[retention period](/influxdb3/version/admin/databases/#retention-periods) -for the database. 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. -{{< flex >}} -{{% flex-content "half" %}} - -##### Valid durations units include +#### Valid durations units include - **m**: minute - **h**: hour @@ -45,22 +160,30 @@ The retention period value cannot be negative or contain whitespace. - **mo**: month - **y**: year -{{% /flex-content %}} -{{% flex-content "half" %}} +For more information about retention periods, see [Data retention](/influxdb3/version/reference/internals/data-retention/). -##### Example retention period values +{{% show-in "core" %}} +> [!Important] +> #### Retention periods are immutable in Core +> +> In {{< product-name >}}, retention periods can only be set when creating a database +> and cannot be changed afterward. If you need to change a retention period, you must +> create a new database with the desired retention period and migrate your data. +> +> For mutable retention periods and table-level retention, consider upgrading to +> [InfluxDB 3 Enterprise](/influxdb3/enterprise/). +{{% /show-in %}} -- `0d`: infinite/none -- `3d`: 3 days -- `6w`: 6 weeks -- `1mo`: 1 month (30 days) -- `1y`: 1 year -- `30d30d`: 60 days -- `2.5d`: 60 hours - -{{% /flex-content %}} -{{< /flex >}} ---> +{{% show-in "enterprise" %}} +> [!Note] +> #### Database retention serves as default for tables +> +> The database retention period serves as the default retention period for all tables in +> the database, unless a table has its own retention period defined. Table-level retention +> periods override database retention periods. +> +> For more information, see [Retention period precedence](/influxdb3/enterprise/reference/internals/data-retention/#retention-period-precedence). +{{% /show-in %}} ## Database naming restrictions diff --git a/content/shared/influxdb3-admin/databases/delete.md b/content/shared/influxdb3-admin/databases/delete.md index 80190b2c1..bac01ccf1 100644 --- a/content/shared/influxdb3-admin/databases/delete.md +++ b/content/shared/influxdb3-admin/databases/delete.md @@ -1,6 +1,6 @@ -Use the [`influxdb3 delete database` command](/influxdb3/version/reference/cli/influxdb3/delete/database/) -to delete a database from {{< product-name >}}. +Use the [`influxdb3 delete database` command](/influxdb3/version/reference/cli/influxdb3/delete/database/), +the [HTTP API](/influxdb3/version/api/v3/), or [InfluxDB 3 Explorer](/influxdb3/explorer/) to delete a database from {{< product-name >}}. > [!Caution] > #### Deleting a database cannot be undone @@ -8,15 +8,66 @@ to delete a database from {{< product-name >}}. > Deleting a database is a destructive action. > Once a database is deleted, data stored in that database cannot be recovered. +- [Delete a database using the influxdb3 CLI](#delete-a-database-using-the-influxdb3-cli) +- [Delete a database using the HTTP API](#delete-a-database-using-the-http-api) +- [Delete a database using InfluxDB 3 Explorer](#delete-a-database-using-influxdb-3-explorer) + +## Delete a database using the influxdb3 CLI + Provide the following: - Name of the database to delete - - {{< product-name >}} {{% token-link "admin" "admin" %}} -{{% code-placeholders "DATABASE_NAME" %}} -```sh +```sh{placeholders="DATABASE_NAME"} influxdb3 delete database DATABASE_NAME ``` -{{% /code-placeholders %}} + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to delete Enter `yes` to confirm that you want to delete the database. + +## Delete a database using the HTTP API + +To delete a database using the HTTP API, send a `DELETE` request to the `/api/v3/configure/database` endpoint: + +{{% api-endpoint method="DELETE" endpoint="{{< influxdb/host >}}/api/v3/configure/database" %}} + +Include the following in your request: + +- **Query parameters**: + - `db`: Database name to delete +- **Headers**: + - `Authorization: Bearer` with your {{% token-link "admin" %}} + +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} +curl --request DELETE "{{< influxdb/host >}}/api/v3/configure/database?db=DATABASE_NAME" \ + --header "Authorization: Bearer AUTH_TOKEN" +``` + +Replace the following: + +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to delete +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +### Response + +A successful deletion returns HTTP status `200` with no content body. + +## Delete a database using InfluxDB 3 Explorer + +You can also delete databases using the [InfluxDB 3 Explorer](/influxdb3/explorer/) web interface: + +1. If you haven't already, see how to [get started with Explorer and connect to your {{% product-name %}} server](/influxdb3/explorer/get-started/). +2. In Explorer, click **Databases** in the left navigation. +3. Find the database you want to delete in the list. +4. Click the **Delete** icon (trash can) next to the database name. +5. In the confirmation dialog, type the database name to confirm. +6. Click **Delete Database**. + +> [!Caution] +> This action cannot be undone. All data in the database will be permanently deleted. + +For more information, see [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/). diff --git a/content/shared/influxdb3-admin/databases/list.md b/content/shared/influxdb3-admin/databases/list.md index 1954dcb48..871bd406e 100644 --- a/content/shared/influxdb3-admin/databases/list.md +++ b/content/shared/influxdb3-admin/databases/list.md @@ -1,6 +1,13 @@ -Use the [`influxdb3 show databases` command](/influxdb3/version/reference/cli/influxdb3/show/databases/) -to list databases in {{< product-name >}}. +Use the [`influxdb3 show databases` command](/influxdb3/version/reference/cli/influxdb3/show/databases/), +the [`/api/v3/configure/database`](/influxdb3/version/api/v3/) HTTP API endpoint, or [InfluxDB 3 Explorer](/influxdb3/explorer/) to list databases in {{< product-name >}}. + +- [List databases using the influxdb3 CLI](#list-databases-using-the-influxdb3-cli) +- [List databases using the HTTP API](#list-databases-using-the-http-api) +- [List databases using InfluxDB 3 Explorer](#list-databases-using-influxdb-3-explorer) + +## List databases using the influxdb3 CLI + Provide the following: - _(Optional)_ [Output format](#output-formats) with the `--format` option @@ -72,7 +79,7 @@ noaa {{% /expand %}} {{< /expand-wrapper >}} -## List deleted databases +### List deleted databases To list deleted databases, include the `--show-deleted` option with your `influxdb3 show databases` command: @@ -81,6 +88,61 @@ To list deleted databases, include the `--show-deleted` option with your influxdb3 show databases --show-deleted ``` +## List databases using the HTTP API + +To list databases using the HTTP API, send a `GET` request to the `/api/v3/configure/database` endpoint: + +{{% api-endpoint method="GET" endpoint="{{< influxdb/host >}}/api/v3/configure/database" %}} + +Include the following in your request: + +- **Headers**: + - `Authorization: Bearer` with your {{% token-link %}} + +```bash{placeholders="AUTH_TOKEN"} +curl --request GET "{{< influxdb/host >}}/api/v3/configure/database" \ + --header "Authorization: Bearer AUTH_TOKEN" +``` + +Replace the following: + +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +### Response + +A successful request returns HTTP status `200` with a JSON array of database objects: + +```json +[ + { + "db": "home", + "retention_period": "30d" + }, + { + "db": "home_actions", + "retention_period": "7d" + }, + { + "db": "noaa", + "retention_period": "none" + } +] +``` + +## List databases using InfluxDB 3 Explorer + +You can also view all databases using the [InfluxDB 3 Explorer](/influxdb3/explorer/) web interface: + +1. If you haven't already, see how to [get started with Explorer and connect to your {{% product-name %}} server](/influxdb3/explorer/get-started/). +2. In Explorer, click **Databases** in the left navigation. +3. The Databases page displays a list of all databases with the following information: + - Database name + - Retention period (if configured) + - Number of tables in the database + - Creation date + +For more information, see [Manage databases with InfluxDB 3 Explorer](/influxdb3/explorer/manage-databases/). + @@ -80,4 +81,84 @@ Creates a database with a specific retention period. influxdb3 create database --retention-period 30d DATABASE_NAME ``` +### Create a database with infinite retention + +Creates a database with no retention period (data never expires). + + + +```bash +influxdb3 create database --retention-period none DATABASE_NAME +``` + +### Create a database with a 90-day retention period + +Creates a database with a 90-day retention period using an authentication token. + + + +```bash +influxdb3 create database \ + --retention-period 90d \ + --token AUTH_TOKEN \ + DATABASE_NAME +``` + +### Create a database with a 1-year retention period + +Creates a database with a 1-year retention period. + + + +```bash +influxdb3 create database --retention-period 1y DATABASE_NAME +``` + +### Create a database with a combined duration + +Creates a database with a retention period of 30 days and 12 hours. + + + +```bash +influxdb3 create database --retention-period 30d12h DATABASE_NAME +``` + {{% /code-placeholders %}} + +## Retention period duration formats + +Retention periods are specified as [duration](/influxdb3/version/reference/glossary/#duration) +values using a numeric value plus a duration unit. + +### Valid duration units + +| Unit | Description | +|:-----|:------------| +| `h` | hour | +| `d` | day | +| `w` | week | +| `mo` | month (30 days) | +| `y` | year (365 days) | + +> [!Note] +> - **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. + +### Example duration values + +- `1h` - 1 hour +- `24h` - 24 hours +- `7d` - 7 days +- `4w` - 4 weeks +- `30d` - 30 days +- `1mo` - 1 month (30 days) +- `90d` - 90 days +- `1y` - 1 year (365 days) +- `none` - infinite (data never expires) + +You can combine units: `30d12h` (30.5 days), `1y6mo` (545 days) + +For complete details about retention periods, see +[Data retention in {{< product-name >}}](/influxdb3/version/reference/internals/data-retention/). diff --git a/content/shared/influxdb3-cli/update/database/_index.md b/content/shared/influxdb3-cli/update/database/_index.md index a292283a4..d73b9ea15 100644 --- a/content/shared/influxdb3-cli/update/database/_index.md +++ b/content/shared/influxdb3-cli/update/database/_index.md @@ -1,6 +1,15 @@ The `influxdb3 update database` command updates an existing database in your {{< product-name >}} instance. +{{% show-in "enterprise" %}} Use this command to update a database's retention period. +{{% /show-in %}} + +{{% show-in "core" %}} +> [!Note] +> {{< product-name >}} does not support updating database retention periods. +> Retention periods can only be set when [creating a database](/influxdb3/core/admin/databases/create/) +> and cannot be changed afterward. +{{% /show-in %}} ## Usage @@ -18,6 +27,18 @@ You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environme ## Options +{{% hide-in "enterprise" %}} +| Option | | Description | +| :----- | :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | +| `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | +| `-d` | `--database` | The name of the database to update | +| | `--token` | Authentication token | +| | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | +| `-h` | `--help` | Print help information | +| | `--help-all` | Print detailed help information | +{{% /hide-in %}} + +{{% show-in "enterprise" %}} | Option | | Description | | :----- | :------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | | `-H` | `--host` | Host URL of the running {{< product-name >}} server (default is `http://127.0.0.1:8181`) | @@ -27,6 +48,7 @@ You can also set the database name using the `INFLUXDB3_DATABASE_NAME` environme | | `--tls-ca` | Path to a custom TLS certificate authority (for testing or self-signed certificates) | | `-h` | `--help` | Print help information | | | `--help-all` | Print detailed help information | +{{% /show-in %}} ### Option environment variables @@ -39,6 +61,7 @@ You can use the following environment variables instead of providing CLI options | `INFLUXDB3_AUTH_TOKEN` | `--token` | | `INFLUXDB3_TLS_CA` | `--tls-ca` | +{{% show-in "enterprise" %}} ## Examples The following examples show how to update a database. @@ -46,10 +69,9 @@ The following examples show how to update a database. In your commands replace the following: - {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: Database name -- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: Authentication token -{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}} ### Update a database retention period @@ -57,7 +79,7 @@ Updates a database retention period to 30 days. -```bash +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} influxdb3 update database --retention-period 30d DATABASE_NAME ``` @@ -67,7 +89,7 @@ Removes the retention period from a database by setting it to `none`. -```bash +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} influxdb3 update database --retention-period none DATABASE_NAME ``` @@ -77,8 +99,8 @@ Updates a database using an authentication token. -```bash +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} influxdb3 update database --token AUTH_TOKEN --retention-period 7d DATABASE_NAME ``` -{{% /code-placeholders %}} \ No newline at end of file +{{% /show-in %}} \ No newline at end of file diff --git a/content/shared/influxdb3-internals/data-retention.md b/content/shared/influxdb3-internals/data-retention.md new file mode 100644 index 000000000..65a8e8770 --- /dev/null +++ b/content/shared/influxdb3-internals/data-retention.md @@ -0,0 +1,417 @@ + +{{< product-name >}} enforces database{{% show-in "enterprise" %}} and table{{% /show-in %}} retention periods at query time. +Any points with timestamps beyond a retention period +are filtered out of query results, even though the data may still exist in storage. + +- [Database retention period](#database-retention-period) +{{% show-in "enterprise" %}} +- [Table retention period](#table-retention-period) +{{% /show-in %}} +- [Retention period duration formats](#retention-period-duration-formats) +{{% show-in "core" %}} +- [Set database retention period](#set-database-retention-period) +- [Retention period limitations](#retention-period-limitations) +{{% /show-in %}} +{{% show-in "enterprise" %}} +- [Set retention periods](#set-retention-periods) +- [Update retention periods](#update-retention-periods) +- [Retention period precedence](#retention-period-precedence) +- [When does data actually get deleted?](#when-does-data-actually-get-deleted) +{{% /show-in %}} + +## Database retention period + +A **database retention period** is the duration of time that a database retains data. +Retention periods are designed to automatically delete expired data and optimize +storage without any user intervention. + +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`). + +[Points](/influxdb3/version/reference/glossary/#point) in a database with +timestamps beyond the defined retention period (relative to now) are not queryable, +but may still exist in storage until {{% show-in "core" %}}fully deleted by the retention enforcement service{{% /show-in %}}{{% show-in "enterprise" %}}[fully deleted](#when-does-data-actually-get-deleted){{% /show-in %}}. + +{{% show-in "enterprise" %}} +Database retention periods serve as the default retention period for all tables in +the database, unless a table has its own retention period defined. +{{% /show-in %}} + +{{% show-in "enterprise" %}} +## Table retention period + +In addition to database-level retention periods, {{< product-name >}} supports +**table-level retention periods**. A table retention period overrides the database +retention period for that specific table. + +This allows you to: +- Keep different types of data for different durations within the same database +- Apply shorter retention periods to high-volume, low-value data +- Apply longer retention periods to critical data that needs extended retention +{{% /show-in %}} + +## Retention period duration formats + +Retention periods are specified as [duration](/influxdb3/version/reference/glossary/#duration) +values using a numeric value plus a duration unit. The retention period value cannot +be negative or contain whitespace. + +### Valid duration units + +| Unit | Description | +|:-----|:------------| +| `h` | hour | +| `d` | day | +| `w` | week | +| `mo` | month (30 days) | +| `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`). +> - **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 retention period values + +| Value | Description | +|:------|:------------| +| `1h` | 1 hour | +| `24h` | 24 hours (1 day) | +| `7d` | 7 days | +| `4w` | 4 weeks (28 days) | +| `1mo` | 1 month (30 days) | +| `90d` | 90 days | +| `1y` | 1 year (365 days) | +| `none` | Infinite - data never expires | + +You can combine multiple duration units in a single value: + +| Value | Description | +|:------|:------------| +| `30d12h` | 30 days and 12 hours (30.5 days) | +| `2w3d` | 2 weeks and 3 days (17 days) | +| `1y6mo` | 1 year and 6 months (545 days) | + +### Set database retention period + +Use the [`influxdb3 create database` command](/influxdb3/version/reference/cli/influxdb3/create/database/) or the [/api/v3/configure/database](/influxdb3/version/api/v3/#operation/PostConfigureDatabase) HTTP API endpoint to create a database with a retention period: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3 CLI](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} +# Create a database with a 30-day retention period +influxdb3 create database --retention-period 30d DATABASE_NAME + +# Create a database with infinite retention +influxdb3 create database --retention-period none DATABASE_NAME + +# Create a database with a 90-day retention period using authentication +influxdb3 create database \ + --retention-period 90d \ + --token AUTH_TOKEN \ + DATABASE_NAME +``` +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} +# Create a database with a 30-day retention period +curl --request POST "{{< influxdb/host >}}/api/v3/configure/database" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "retention_period": "30d" + }' + +# Create a database with infinite retention +curl --request POST "{{< influxdb/host >}}/api/v3/configure/database" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "retention_period": "none" + }' + +# Create a database with a 90-day retention period +curl --request POST "{{< influxdb/host >}}/api/v3/configure/database" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "retention_period": "90d" + }' +``` +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Replace the following: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database +- {{% 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 +> +> In {{< product-name >}}, retention periods can only be set when +> [creating a database](/influxdb3/core/admin/databases/create/) and cannot be +> changed afterward. If you need to change a retention period, you must create a +> new database with the desired retention period and migrate your data. +> +> #### Upgrade to InfluxDB 3 Enterprise for advanced retention features +> +> With InfluxDB 3 Enterprise, you can set table-level retention policies and update +> retention periods after creation. For more information, see +> [InfluxDB 3 Enterprise data retention](/influxdb3/enterprise/reference/internals/data-retention/). +{{% /show-in %}} + +{{% show-in "enterprise" %}} + +### Set table retention period + +Use the [`influxdb3 create table` command](/influxdb3/enterprise/reference/cli/influxdb3/create/table/) or the [/api/v3/configure/table](/influxdb3/enterprise/reference/api/v3/#operation/PostConfigureTable) HTTP API endpoint to create a table with a retention period: + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3 CLI](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"} +# Create a table with a 7-day retention period +influxdb3 create table \ + --tags sensor_id,location \ + --retention-period 7d \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + TABLE_NAME + +# Create a table with field definitions and retention period +influxdb3 create table \ + --tags room,sensor_id \ + --fields temp:float64,hum:float64 \ + --retention-period 30d \ + --database DATABASE_NAME \ + --token AUTH_TOKEN \ + TABLE_NAME +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"} +# Create a table with a 7-day retention period +curl --request POST "{{< influxdb/host >}}/api/v3/configure/table" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "table": "TABLE_NAME", + "tags": ["sensor_id", "location"], + "retention_period": "7d" + }' + +# Create a table with field definitions and retention period +curl --request POST "{{< influxdb/host >}}/api/v3/configure/table" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "db": "DATABASE_NAME", + "table": "TABLE_NAME", + "tags": ["room", "sensor_id"], + "fields": [ + {"name": "temp", "type": "float64"}, + {"name": "hum", "type": "float64"} + ], + "retention_period": "30d" + }' +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Replace the following: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database +{{% show-in "enterprise" %}} +- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create +{{% /show-in %}} +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +## Update retention periods + +{{< product-name >}} allows you to update database retention +periods after creation using the +[`influxdb3 update database` command](/influxdb3/enterprise/reference/cli/influxdb3/update/database/). + +{{< code-tabs-wrapper >}} +{{% code-tabs %}} +[influxdb3 CLI](#) +[HTTP API](#) +{{% /code-tabs %}} +{{% code-tab-content %}} + +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} +# Update a database retention period to 60 days +influxdb3 update database --retention-period 60d DATABASE_NAME + +# Clear a database retention period (set to infinite) +influxdb3 update database --retention-period none DATABASE_NAME + +# Update with authentication +influxdb3 update database \ + --retention-period 90d \ + --token AUTH_TOKEN \ + DATABASE_NAME +``` + +{{% /code-tab-content %}} +{{% code-tab-content %}} + +```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"} +# Update a database retention period to 60 days +curl --request PATCH "{{< influxdb/host >}}/api/v3/configure/database/DATABASE_NAME" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "retention_period": "60d" + }' + +# Clear a database retention period (set to infinite) +curl --request PATCH "{{< influxdb/host >}}/api/v3/configure/database/DATABASE_NAME" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "retention_period": "none" + }' + +# Update a database retention period to 90 days +curl --request PATCH "{{< influxdb/host >}}/api/v3/configure/database/DATABASE_NAME" \ + --header "Content-Type: application/json" \ + --header "Authorization: Bearer AUTH_TOKEN" \ + --data '{ + "retention_period": "90d" + }' +``` + +{{% /code-tab-content %}} +{{< /code-tabs-wrapper >}} + +Replace the following: +- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database +- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}} + +> [!Note] +> {{< product-name >}} does not currently support updating table retention periods +> after creation. Table retention periods can only be set when creating the table. + +## Retention period precedence + +When both database and table retention periods are defined, the **table retention +period takes precedence** for that specific table. This allows fine-grained control +over data retention within a database. + +### Examples + +#### Example: Table retention shorter than database retention + +```bash +# Database with 90-day retention +influxdb3 create database --retention-period 90d mydb + +# Table with 7-day retention (overrides database retention) +influxdb3 create table \ + --tags sensor_id \ + --retention-period 7d \ + --database mydb \ + metrics +``` + +In this example: +- Data in the `metrics` table expires after 7 days +- Data in other tables in `mydb` expires after 90 days + +#### Example: Table retention longer than database retention + +```bash +# Database with 30-day retention +influxdb3 create database --retention-period 30d mydb + +# Table with 1-year retention (overrides database retention) +influxdb3 create table \ + --tags device_id \ + --retention-period 1y \ + --database mydb \ + audit_logs +``` + +In this example: +- Data in the `audit_logs` table expires after 1 year +- Data in other tables in `mydb` expires after 30 days + +#### Example: Database retention updated after table creation + +```bash +# Original database with 30-day retention +influxdb3 create database --retention-period 30d mydb + +# Table with 7-day retention +influxdb3 create table \ + --tags sensor_id \ + --retention-period 7d \ + --database mydb \ + metrics + +# Update database retention to 90 days +influxdb3 update database --retention-period 90d mydb +``` + +After the update: +- Data in the `metrics` table still expires after 7 days (table retention unchanged) +- Data in other tables in `mydb` now expires after 90 days (affected by database update) + +## When does data actually get deleted? + +{{< product-name >}} routinely deletes expired data to optimize storage. +The retention enforcement service runs periodically and: + +1. **Identifies expired data**: Finds data with timestamps beyond the retention period +2. **Deletes expired files**: Permanently removes Parquet files containing only expired data +3. **Optimizes mixed files**: For files containing both expired and non-expired data, + the system may compact and rewrite files to remove expired data + +The timing of physical deletion depends on: +- The retention enforcement service schedule +- The compaction strategy configured for your installation +- The ratio of expired to non-expired data in Parquet files + +> [!Important] +> Even though expired data may still exist in storage temporarily, it will never +> appear in query results. Retention period enforcement at query time ensures +> expired data is always filtered out. +{{% /show-in %}} From bb1fc94dfd7532fd267aed2cc89f475c65c83629 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 10 Oct 2025 15:10:39 -0500 Subject: [PATCH 2/6] fix(influxdb3): link fragments --- content/shared/influxdb3-admin/databases/list.md | 2 +- content/shared/influxdb3-internals/data-retention.md | 3 +-- 2 files changed, 2 insertions(+), 3 deletions(-) diff --git a/content/shared/influxdb3-admin/databases/list.md b/content/shared/influxdb3-admin/databases/list.md index 871bd406e..4592c7fae 100644 --- a/content/shared/influxdb3-admin/databases/list.md +++ b/content/shared/influxdb3-admin/databases/list.md @@ -11,7 +11,7 @@ the [`/api/v3/configure/database`](/influxdb3/version/api/v3/) HTTP API endpoint Provide the following: - _(Optional)_ [Output format](#output-formats) with the `--format` option - - _(Optional)_ [Show deleted databases](list-deleted-databasese) with the + - _(Optional)_ [Show deleted databases](list-deleted-databases) with the `--show-deleted` option - {{< product-name >}} {{% token-link "admin" "admin" %}} with the `-t`, `--token` option diff --git a/content/shared/influxdb3-internals/data-retention.md b/content/shared/influxdb3-internals/data-retention.md index 65a8e8770..5b5aa99dd 100644 --- a/content/shared/influxdb3-internals/data-retention.md +++ b/content/shared/influxdb3-internals/data-retention.md @@ -8,12 +8,11 @@ are filtered out of query results, even though the data may still exist in stora - [Table retention period](#table-retention-period) {{% /show-in %}} - [Retention period duration formats](#retention-period-duration-formats) -{{% show-in "core" %}} - [Set database retention period](#set-database-retention-period) +{{% show-in "core" %}} - [Retention period limitations](#retention-period-limitations) {{% /show-in %}} {{% show-in "enterprise" %}} -- [Set retention periods](#set-retention-periods) - [Update retention periods](#update-retention-periods) - [Retention period precedence](#retention-period-precedence) - [When does data actually get deleted?](#when-does-data-actually-get-deleted) From da4f5e66a6dc89c702edba575fe824ae41ba2fd1 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 10 Oct 2025 15:30:27 -0500 Subject: [PATCH 3/6] fix(explorer): When to use host.docker.internal with InfluxDB 3. - Revises guidance in install and get-started. - Adds Explorer to project compose file for testing. --- compose.yaml | 12 ++++++++++++ content/influxdb3/explorer/get-started.md | 21 +++++++++++++++++++-- content/influxdb3/explorer/install.md | 12 +++++++++--- 3 files changed, 40 insertions(+), 5 deletions(-) diff --git a/compose.yaml b/compose.yaml index 612900f6a..fbeb8196c 100644 --- a/compose.yaml +++ b/compose.yaml @@ -369,6 +369,18 @@ services: target: /var/lib/influxdb3/plugins/custom secrets: - influxdb3-enterprise-admin-token + influxdb3-explorer: + container_name: influxdb3-explorer + image: influxdata/influxdb3-ui:latest + pull_policy: always + ports: + - 8888:80 + - 8889:8888 + command: + - --mode=admin + profiles: + - explorer + - influxdb3 telegraf-pytest: container_name: telegraf-pytest image: influxdata/docs-pytest diff --git a/content/influxdb3/explorer/get-started.md b/content/influxdb3/explorer/get-started.md index 0096f2da6..68bd0242c 100644 --- a/content/influxdb3/explorer/get-started.md +++ b/content/influxdb3/explorer/get-started.md @@ -36,9 +36,26 @@ InfluxDB 3 Explorer supports the following InfluxDB 3 products: - **Server name**: A name to identify the InfluxDB 3 server you're connecting to. - **Server URL**: The URL used to connect to your InfluxDB 3 server. + - The URL depends on how and where your InfluxDB 3 instance is running. See [When to use `host.docker.internal`](#when-to-use-hostdockerinternal) for more information. - Select the protocol to use (http or https). - Provide the host and, if necessary, the port. - - _If connecting to a local, non-Docker instance, use `host.docker.internal`._ For more information about host.docker.internal, see the [Docker documentation](https://docs.docker.com/desktop/features/networking). + + > [!Note] + > #### When to use `host.docker.internal` + > + > If your InfluxDB 3 instance is running in Docker (not the same container as Explorer), + > use `host.docker.internal` as your server host to allow the Explorer container to + > connect to the InfluxDB container on the host--for example: + > + > ```txt + > "DEFAULT_INFLUX_SERVER": "http://host.docker.internal:8181" + > ``` + > + > - If both Explorer and InfluxDB are in the same Docker network, use the container name instead. + > - If InfluxDB is running natively on your machine (not in Docker), use `localhost`. + > + > For more information, see the [Docker networking documentation](https://docs.docker.com/desktop/features/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). + - **Token**: The authorization token to use to connect to your InfluxDB 3 server. We recommend using an InfluxDB 3 _admin_ token. @@ -122,7 +139,7 @@ The Results pane provides three view options: > - Ensure that you query the `time` column > - Update the query to include an `ORDER BY time` clause. -Congratulations! You have successfully used {{% product-name %}} to connect to, +You have successfully used {{% product-name %}} to connect to, write data to, and query data from an InfluxDB 3 instance. ## Video walkthrough diff --git a/content/influxdb3/explorer/install.md b/content/influxdb3/explorer/install.md index e555511a2..862844609 100644 --- a/content/influxdb3/explorer/install.md +++ b/content/influxdb3/explorer/install.md @@ -240,14 +240,20 @@ Instead of configuring connections through the UI, you can pre-define connection - **`DEFAULT_SERVER_NAME`**: a display name (only used by Explorer) for your [InfluxDB 3 Core](/influxdb3/core/get-started/setup/#start-influxdb) or [Enterprise](/influxdb3/enterprise/get-started/setup/#start-influxdb) server > [!Note] - > If connecting to a local, _non-Docker_ instance, use `host.docker.internal` as your server host--for example: + > #### When to use `host.docker.internal` + > + > If your InfluxDB 3 instance is running in Docker (not the same container as Explorer), + > use `host.docker.internal` as your server host to allow the Explorer container to + > connect to the InfluxDB container on the host--for example: > > ```txt > "DEFAULT_INFLUX_SERVER": "http://host.docker.internal:8181" > ``` > - > `host.docker.internal` allows the Docker container to connect to services running on your host machine. - > For more information, see the [Docker documentation](https://docs.docker.com/desktop/features/networking). + > - If both Explorer and InfluxDB are in the same Docker network, use the container name instead. + > - If InfluxDB is running natively on your machine (not in Docker), use `localhost`. + > + > For more information, see the [Docker networking documentation](https://docs.docker.com/desktop/features/networking/#i-want-to-connect-from-a-container-to-a-service-on-the-host). 2. **Mount the configuration directory:** From 97ead36ab2f75f55de01647b0afa540c3a2e7ea2 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 10 Oct 2025 16:47:15 -0500 Subject: [PATCH 4/6] Update content/shared/influxdb3-admin/databases/_index.md Co-authored-by: Scott Anderson --- content/shared/influxdb3-admin/databases/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/shared/influxdb3-admin/databases/_index.md b/content/shared/influxdb3-admin/databases/_index.md index 4e6433a04..5e0e05f5e 100644 --- a/content/shared/influxdb3-admin/databases/_index.md +++ b/content/shared/influxdb3-admin/databases/_index.md @@ -41,7 +41,7 @@ rules, and deletion behavior, see A database **retention period** is the maximum age of data stored in the database. The age of data is determined by the timestamp associated with each point. When a point's timestamp is beyond the retention period (relative to now), the -point is not queryable. +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 From 7cda139851a08063dadb34110c042e685f7a0593 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 10 Oct 2025 17:53:47 -0500 Subject: [PATCH 5/6] 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 From 65b2763049c474debc34182691a5e01473309ff2 Mon Sep 17 00:00:00 2001 From: Jason Stirnaman Date: Fri, 10 Oct 2025 18:07:30 -0500 Subject: [PATCH 6/6] fix(influxdb3): link fragments --- content/shared/influxdb3-admin/databases/list.md | 2 +- content/shared/influxdb3-internals/data-retention.md | 3 --- 2 files changed, 1 insertion(+), 4 deletions(-) diff --git a/content/shared/influxdb3-admin/databases/list.md b/content/shared/influxdb3-admin/databases/list.md index 4592c7fae..cd40ef9dc 100644 --- a/content/shared/influxdb3-admin/databases/list.md +++ b/content/shared/influxdb3-admin/databases/list.md @@ -11,7 +11,7 @@ the [`/api/v3/configure/database`](/influxdb3/version/api/v3/) HTTP API endpoint Provide the following: - _(Optional)_ [Output format](#output-formats) with the `--format` option - - _(Optional)_ [Show deleted databases](list-deleted-databases) with the + - _(Optional)_ [Show deleted databases](#list-deleted-databases) with the `--show-deleted` option - {{< product-name >}} {{% token-link "admin" "admin" %}} with the `-t`, `--token` option diff --git a/content/shared/influxdb3-internals/data-retention.md b/content/shared/influxdb3-internals/data-retention.md index bd9d79a07..f2a9c8c2f 100644 --- a/content/shared/influxdb3-internals/data-retention.md +++ b/content/shared/influxdb3-internals/data-retention.md @@ -9,9 +9,6 @@ are filtered out of query results, even though the data may still exist in stora {{% /show-in %}} - [Retention period duration formats](#retention-period-duration-formats) - [Set database retention period](#set-database-retention-period) -{{% show-in "core" %}} -- [Retention period limitations](#retention-period-limitations) -{{% /show-in %}} {{% show-in "enterprise" %}} - [Update retention periods](#update-retention-periods) - [Retention period precedence](#retention-period-precedence)