Data Retention

{{< 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 {{% show-in "enterprise" %}}
• Table retention period {{% /show-in %}}
• Retention period duration formats
• Set database retention period {{% show-in "enterprise" %}}
• Update retention periods
• Retention period precedence
• 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, you can optionally set a retention period. Retention periods can be as short as an hour or infinite (none).

Points 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{{% /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 values using a numeric value plus a duration unit. The retention period value cannot be negative or contain whitespace.

Valid duration units

[!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

You can combine multiple duration units in a single value:

Set database retention period

Use the influxdb3 create database command or the /api/v3/configure/database 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 %}}

# 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 %}}

# 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 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. {{% /show-in %}}

{{% show-in "enterprise" %}}

Set table retention period

Use the influxdb3 create table command or the /api/v3/configure/table 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 %}}

# 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 %}}

# 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.

{{< code-tabs-wrapper >}} {{% code-tabs %}} influxdb3 CLI HTTP API {{% /code-tabs %}} {{% code-tab-content %}}

# 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 %}}

# 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

# 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

# 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

# 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 %}}