Data retention in InfluxDB 3 Core

InfluxDB 3 Core enforces database 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

• Retention period duration formats

• Set database retention period

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 fully deleted by the retention enforcement service.

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

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:

# 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

# Create a database with a 30-day retention period
curl --request POST "localhost:8181/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 "localhost:8181/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 "localhost:8181/api/v3/configure/database" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer 
AUTH_TOKEN
" \
  --data '{
    "db": "
DATABASE_NAME
",
    "retention_period": "90d"
  }'

Replace the following:

• DATABASE_NAME: the name of the database
• AUTH_TOKEN: your admin token