Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge pull request #6459 from influxdata/jts/chore-explorer-server-name 

Core and Enterprise: Retention periods and Explorer server name
pull/6457/head^2
Jason Stirnaman 2025-10-10 18:11:41 -05:00 committed by GitHub
parent cea4016b35 65b2763049
commit e11cd3096e
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
34 changed files with 1224 additions and 221 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
compose.yaml
View File

@ -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

4
content/influxdb3/core/admin/databases/_index.md
View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/_index.md
//SOURCE - content/shared/influxdb3-admin/databases/_index.md
-->

24
content/influxdb3/core/admin/databases/create.md
View File

@ -1,8 +1,8 @@
---
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
@ -10,14 +10,26 @@ weight: 201
list_code_example: |
<!--pytest.mark.skip-->
{{% 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
---

17
content/influxdb3/core/admin/databases/delete.md
View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/delete.md
//SOURCE - content/shared/influxdb3-admin/databases/delete.md
-->

13
content/influxdb3/core/admin/databases/list.md
View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/list.md
//SOURCE - content/shared/influxdb3-admin/databases/list.md
-->

19
content/influxdb3/core/admin/tables/create.md
View File

@ -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 <DATABASE_NAME> \
--token <AUTH_TOKEN> \
<TABLE_NAME>
--database DATABASE_NAME \
--token AUTH_TOKEN \
TABLE_NAME
# HTTP API
curl -X POST "http://localhost:8181/api/v3/configure/table" \
--header "Authorization: Bearer <AUTH_TOKEN>" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{"db": "<DATABASE_NAME>", "table": "<TABLE_NAME>", "tags": ["tag1", "tag2", "tag3"]}'
--data '{"db": "DATABASE_NAME", "table": "TABLE_NAME", "tags": ["tag1", "tag2", "tag3"]}'
```
related:
- /influxdb3/core/reference/cli/influxdb3/create/table/

16
content/influxdb3/core/admin/tables/list.md
View File

@ -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 <DATABASE_NAME> \
--token <AUTH_TOKEN> \
--database DATABASE_NAME \
--token AUTH_TOKEN \
"SHOW TABLES"
# HTTP API
curl --get "http://localhost:8181/api/v3/query_sql" \
--header "Authorization: Bearer <AUTH_TOKEN>" \
--data-urlencode "db=<DATABASE_NAME>" \
--header "Authorization: Bearer AUTH_TOKEN" \
--data-urlencode "db=DATABASE_NAME" \
--data-urlencode "q=SHOW TABLES"
```
related:

4
content/influxdb3/core/reference/cli/influxdb3/create/database.md
View File

@ -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
---

22
content/influxdb3/core/reference/internals/data-retention.md Normal file
View File

@ -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
---
<!--
//SOURCE content/shared/influxdb3-internals/data-retention.md
-->

2
content/influxdb3/enterprise/admin/_index.md
View File

@ -11,5 +11,5 @@ source: /shared/influxdb3-admin/_index.md
---
<!--
The content of this file is located at content/shared/influxdb3-admin/_index.md
//SOURCE - content/shared/influxdb3-admin/_index.md
-->

2
content/influxdb3/enterprise/admin/databases/_index.md
View File

@ -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/

25
content/influxdb3/enterprise/admin/databases/create.md
View File

@ -1,8 +1,8 @@
---
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
@ -10,14 +10,27 @@ weight: 201
list_code_example: |
<!--pytest.mark.skip-->
{{% 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
---

17
content/influxdb3/enterprise/admin/databases/delete.md
View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/delete.md
//SOURCE - content/shared/influxdb3-admin/databases/delete.md
-->

13
content/influxdb3/enterprise/admin/databases/list.md
View File

@ -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
---
<!--
The content of this file is located at content/shared/influxdb3-admin/databases/list.md
//SOURCE - content/shared/influxdb3-admin/databases/list.md
-->

2
content/influxdb3/enterprise/admin/tables/_index.md
View File

@ -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
---

30
content/influxdb3/enterprise/admin/tables/create.md
View File

@ -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 <DATABASE_NAME> \
--token <AUTH_TOKEN> \
<TABLE_NAME>
--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 <AUTH_TOKEN>" \
curl --request POST "http://localhost:8181/api/v3/configure/table" \
--header "Content-Type: application/json" \
--data '{"db": "<DATABASE_NAME>", "table": "<TABLE_NAME>", "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
---

4
content/influxdb3/enterprise/admin/tables/delete.md
View File

@ -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
---

18
content/influxdb3/enterprise/admin/tables/list.md
View File

@ -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 <DATABASE_NAME> \
--token <AUTH_TOKEN> \
--database DATABASE_NAME \
--token AUTH_TOKEN \
"SHOW TABLES"
# HTTP API
curl --get "http://localhost:8181/api/v3/query_sql" \
--header "Authorization: Bearer <AUTH_TOKEN>" \
--data-urlencode "db=<DATABASE_NAME>" \
--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
---

4
content/influxdb3/enterprise/reference/cli/influxdb3/create/database.md
View File

@ -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
---

4
content/influxdb3/enterprise/reference/cli/influxdb3/create/table.md
View File

@ -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
---

3
content/influxdb3/enterprise/reference/cli/influxdb3/update/database.md
View File

@ -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
---

27
content/influxdb3/enterprise/reference/internals/data-retention.md Normal file
View File

@ -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
---
<!--
//SOURCE content/shared/influxdb3-internals/data-retention.md
-->

21
content/influxdb3/explorer/get-started.md
View File

@ -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

12
content/influxdb3/explorer/install.md
View File

@ -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:**

29
content/shared/influxdb3-admin/databases/_index.md
View File

@ -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.
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)
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 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.
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/).
{{% /show-in %}}
## Database, table, and column limits

209
content/shared/influxdb3-admin/databases/create.md
View File

@ -1,42 +1,156 @@
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" %}}
<!--Allow fail for database create and delete: namespaces aren't reusable-->
<!--pytest.mark.skip-->
{{% 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)
<!--
## Retention period syntax
## Create a database using the influxdb3 CLI
Use the [`influxdb3 create database` command](/influxdb3/version/reference/cli/influxdb3/create/database/)
to create a database. Provide the following:
- Database name _(see [Database naming restrictions](#database-naming-restrictions))_
- {{< product-name >}} {{% token-link "admin" "admin" %}}
- _(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 %}}
<!--pytest.mark.skip-->
```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 +159,39 @@ The retention period value cannot be negative or contain whitespace.
- **mo**: month
- **y**: year
{{% /flex-content %}}
{{% flex-content "half" %}}
> [!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<unit>` (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
For more information about retention periods, see [Data retention](/influxdb3/version/reference/internals/data-retention/).
- `0d`: infinite/none
- `3d`: 3 days
- `6w`: 6 weeks
- `1mo`: 1 month (30 days)
- `1y`: 1 year
- `30d30d`: 60 days
- `2.5d`: 60 hours
{{% 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 %}}
{{% /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

61
content/shared/influxdb3-admin/databases/delete.md
View File

@ -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/).

70
content/shared/influxdb3-admin/databases/list.md
View File

@ -1,10 +1,17 @@
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
- _(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
@ -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/).
<!-- ### Output to a Parquet file
To output your list of databases to a Parquet file, provide the following

169
content/shared/influxdb3-admin/tables/create.md
View File

@ -8,20 +8,24 @@ However, you can manually create tables to define a custom schema or apply custo
- [Create a table using the influxdb3 CLI](#create-a-table-using-the-influxdb3-cli)
- [Create a table using the HTTP API](#create-a-table-using-the-http-api)
{{% show-in "enterprise" %}}
- [Retention period](#retention-period)
{{% /show-in %}}
{{% show-in "core" %}}
- [Data retention](#data-retention)
{{% /show-in %}}
- [Table naming restrictions](#table-naming-restrictions)
## Create a table using the influxdb3 CLI
1. If you haven't already, [download and install the `influxdb3` CLI](/influxdb3/version/reference/cli/influxdb3/#download-and-install-the-influxdb3-cli).
2. Run the `influxdb3 create table` command and provide the following:
Use the `influxdb3 create table` command and provide the following:
- _Required_: The name of the database to create the table in
- _Required_: The name of the table to create (see [Table naming restrictions](#table-naming-restrictions))
- _Required_: Tag columns to include in the table (must have at least one tag column)
- _Optional_: Field columns and their data types to include in the table
{{% show-in "enterprise" %}}
- _Optional_: A retention period for the table
- _Optional_: [Retention period](#retention-period). If omitted, uses database retention period.
{{% /show-in %}}
> [!Note]
@ -36,28 +40,15 @@ However, you can manually create tables to define a custom schema or apply custo
>
> For more information, see [Optimize writes](/influxdb3/version/write-data/best-practices/optimize-writes/#sort-tags-by-query-priority).
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
```bash{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
# Create a table with tag columns
influxdb3 create table \
--tags tag1,tag2,tag3 \
--database DATABASE_NAME \
--token AUTH_TOKEN \
TABLE_NAME
```
{{% /code-placeholders %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the table in
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
### Create a table with field columns
To define specific field columns and their data types when creating the table, use the `--fields` flag:
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```sh
# Create a table with tag and field columns
influxdb3 create table \
--tags room,sensor_id \
--fields temp:float64,hum:float64,co:int64 \
@ -65,15 +56,10 @@ influxdb3 create table \
--token AUTH_TOKEN \
TABLE_NAME
```
{{% /code-placeholders %}}
{{% show-in "enterprise" %}}
### Create a table with a retention period
To set a specific retention period for the table, use the `--retention-period` flag:
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```sh
```bash{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
# Create a table with a 7-day retention period
influxdb3 create table \
--tags room,sensor_id \
--fields temp:float64,hum:float64 \
@ -81,10 +67,22 @@ influxdb3 create table \
--database DATABASE_NAME \
--token AUTH_TOKEN \
TABLE_NAME
# Create a table with database default retention (omit --retention-period)
influxdb3 create table \
--tags room,sensor_id \
--database DATABASE_NAME \
--token AUTH_TOKEN \
TABLE_NAME
```
{{% /code-placeholders %}}
{{% /show-in %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the table in
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
## Create a table using the HTTP API
To create a table using the HTTP API, send a `POST` request to the `/api/v3/configure/table` endpoint:
@ -97,10 +95,17 @@ Include the following in your request:
- `Authorization: Bearer` with your authentication token
- `Content-Type: application/json`
- **Request body**: JSON object with table configuration
- `db` _(string, required)_: Database name
- `table` _(string, required)_: Table name
- `tags` _(array, required)_: Tag column names
- `fields` _(array, optional)_: Field definitions with name and type
{{% show-in "enterprise" %}}
- `retention_period` _(string, optional)_: [Retention period](#retention-period). If omitted, uses database retention period.
{{% /show-in %}}
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/table" \
```bash{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
# Create a table with tag columns
curl -X POST "{{< influxdb/host >}}/api/v3/configure/table" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
@ -108,13 +113,8 @@ curl -X POST "http://{{< influxdb/host >}}/api/v3/configure/table" \
"table": "TABLE_NAME",
"tags": ["tag1", "tag2", "tag3"]
}'
```
{{% /code-placeholders %}}
### Create a table with field columns using the API
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
# Create a table with tag and field columns
curl -X POST "{{< influxdb/host >}}/api/v3/configure/table" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
@ -129,13 +129,10 @@ curl -X POST "{{< influxdb/host >}}/api/v3/configure/table" \
]
}'
```
{{% /code-placeholders %}}
{{% show-in "enterprise" %}}
### Create a table with a retention period using the API
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
```bash{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
# Create a table with a 7-day retention period
curl -X POST "{{< influxdb/host >}}/api/v3/configure/table" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
@ -149,8 +146,94 @@ curl -X POST "{{< influxdb/host >}}/api/v3/configure/table" \
],
"retention_period": "7d"
}'
# Create a table with database default retention (omit retention_period)
curl -X POST "{{< influxdb/host >}}/api/v3/configure/table" \
--header "Authorization: Bearer AUTH_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"db": "DATABASE_NAME",
"table": "TABLE_NAME",
"tags": ["room", "sensor_id"]
}'
```
{{% /code-placeholders %}}
{{% /show-in %}}
Replace the following:
- {{% code-placeholder-key %}}`DATABASE_NAME`{{% /code-placeholder-key %}}: the name of the database to create the table in
- {{% code-placeholder-key %}}`TABLE_NAME`{{% /code-placeholder-key %}}: the name of the table to create
- {{% code-placeholder-key %}}`AUTH_TOKEN`{{% /code-placeholder-key %}}: your {{% token-link "admin" %}}
{{% show-in "enterprise" %}}
## Retention period
By default, tables use the database retention period. When creating a table, set a table-specific _retention period_ to automatically delete expired data and optimize storage for that table.
A table retention period overrides the database retention period for that specific table.
This allows you to maintain different retention policies for different types of data within the same database.
### Retention period syntax
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.
The retention period value cannot be negative or contain whitespace.
#### Valid durations units include
- **m**: minute
- **h**: hour
- **d**: day
- **w**: week
- **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<unit>` (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
period takes precedence** for that specific table.
**Example scenarios:**
- **Short-term data in long-term database**: Store high-volume sensor data with 7-day
retention in a database with 90-day retention
- **Long-term data in short-term database**: Store audit logs with 1-year retention in
a database with 30-day retention
- **Mixed retention requirements**: Maintain both real-time metrics (7 days) and
aggregated metrics (1 year) in the same database
For complete details about retention period precedence and behavior, see
[Data retention in {{< product-name >}}](/influxdb3/version/reference/internals/data-retention/#retention-period-precedence).
{{% /show-in %}}
{{% show-in "core" %}}
## Data retention
In {{< product-name >}}, tables use the database retention period.
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/).
> [!Note]
> #### Upgrade to Enterprise for table-specific retention
>
> With InfluxDB 3 Enterprise, you can set table-level retention periods that override
> the database retention period. This allows you to maintain different retention policies
> for different types of data within the same database.
>
> For more information, see [InfluxDB 3 Enterprise](/influxdb3/enterprise/).
{{% /show-in %}}
## Table naming restrictions

23
content/shared/influxdb3-admin/tables/delete.md
View File

@ -16,18 +16,15 @@ You can also schedule a hard deletion to permanently remove the table and its da
## Delete a table using the influxdb3 CLI
1. If you haven't already, [download and install the `influxdb3` CLI](/influxdb3/version/reference/cli/influxdb3/#download-and-install-the-influxdb3-cli).
2. Use the `influxdb3 delete table` command to delete a table:
Use the `influxdb3 delete table` command to delete a table:
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```sh
```sh{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
influxdb3 delete table \
--database DATABASE_NAME \
--token AUTH_TOKEN \
TABLE_NAME
```
{{% /code-placeholders %}}
Replace the following:
@ -39,29 +36,25 @@ Replace the following:
To permanently delete a table and its data immediately, use the `--hard-delete now` flag:
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```sh
```sh{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
influxdb3 delete table \
--database DATABASE_NAME \
--token AUTH_TOKEN \
--hard-delete now \
TABLE_NAME
```
{{% /code-placeholders %}}
### Schedule a hard deletion
To schedule a table for hard deletion at a specific time, use the `--hard-delete` flag with a timestamp:
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```sh
```sh{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
influxdb3 delete table \
--database DATABASE_NAME \
--token AUTH_TOKEN \
--hard-delete "2025-12-31T23:59:59Z" \
TABLE_NAME
```
{{% /code-placeholders %}}
## Delete a table using the HTTP API
@ -80,12 +73,10 @@ Include the following in your request:
### Soft delete a table
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
```bash{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
curl -X DELETE "{{< influxdb/host >}}/api/v3/configure/table?db=DATABASE_NAME&table=TABLE_NAME" \
--header "Authorization: Bearer AUTH_TOKEN"
```
{{% /code-placeholders %}}
Replace the following:
@ -97,12 +88,10 @@ Replace the following:
To schedule a hard deletion at a specific time, include the `hard_delete_at` parameter with an ISO 8601 timestamp:
{{% code-placeholders "DATABASE_NAME|TABLE_NAME|AUTH_TOKEN" %}}
```bash
```bash{placeholders="DATABASE_NAME|TABLE_NAME|AUTH_TOKEN"}
curl -X DELETE "{{< influxdb/host >}}/api/v3/configure/table?db=DATABASE_NAME&table=TABLE_NAME&hard_delete_at=2025-12-31T23:59:59Z" \
--header "Authorization: Bearer AUTH_TOKEN"
```
{{% /code-placeholders %}}
### Response

4
content/shared/influxdb3-admin/tables/list.md
View File

@ -9,9 +9,7 @@ This guide shows how to retrieve a list of all tables (measurements) in a databa
## List tables using the influxdb3 CLI
1. If you haven't already, [download and install the `influxdb3` CLI](/influxdb3/version/reference/cli/influxdb3/#download-and-install-the-influxdb3-cli).
2. Use the `influxdb3 query` command with the `SHOW TABLES` SQL statement:
Use the `influxdb3 query` command with the `SHOW TABLES` SQL statement:
{{% code-placeholders "DATABASE_NAME|AUTH_TOKEN" %}}
```sh

90
content/shared/influxdb3-cli/create/database.md
View File

@ -72,7 +72,8 @@ influxdb3 create database --token AUTH_TOKEN DATABASE_NAME
### Create a database with a retention period
Creates a database with a specific retention period.
Creates a database with a 30-day retention period.
Data older than 30 days will not be queryable.
<!--pytest.mark.skip-->
@ -80,4 +81,91 @@ 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).
<!--pytest.mark.skip-->
```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.
<!--pytest.mark.skip-->
```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.
<!--pytest.mark.skip-->
```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.
<!--pytest.mark.skip-->
```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]
> 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<unit>` (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
- `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/).

32
content/shared/influxdb3-cli/update/database/_index.md
View File

@ -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.
@ -49,7 +72,6 @@ In your commands replace the following:
- {{% 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.
<!--pytest.mark.skip-->
```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`.
<!--pytest.mark.skip-->
```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.
<!--pytest.mark.skip-->
```bash
```bash{placeholders="DATABASE_NAME|AUTH_TOKEN"}
influxdb3 update database --token AUTH_TOKEN --retention-period 7d DATABASE_NAME
```
{{% /code-placeholders %}}
{{% /show-in %}}

403
content/shared/influxdb3-internals/data-retention.md Normal file
View File

@ -0,0 +1,403 @@
<!-- Allow beginning shortcode -->
{{< 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)
- [Set database retention period](#set-database-retention-period)
{{% show-in "enterprise" %}}
- [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<unit>` (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" %}}
> [!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 %}}