---
title: Data retention in InfluxDB 3 Core
description: InfluxDB 3 Core enforces database retention periods at query time. Retention periods are set when creating a database and cannot be changed afterward.
url: https://docs.influxdata.com/influxdb3/core/reference/internals/data-retention/
estimated_tokens: 3571
product: InfluxDB 3 Core
version: core
---

# 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](#database-retention-period)
    
-   [Retention period duration formats](#retention-period-duration-formats)
    
-   [Set database retention period](#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](/influxdb3/core/admin/databases/create/), you can optionally set a retention period. Retention periods can be as short as an hour or infinite (`none`).

[Points](/influxdb3/core/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 fully deleted by the retention enforcement service

.

## Retention period duration formats

Retention periods are specified as [duration](/influxdb3/core/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) |

Minute (`m`) and second (`s`) units are not supported for retention periods.

#### 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/core/reference/cli/influxdb3/create/database/) or the [/api/v3/configure/database](/influxdb3/core/api/database/#operation/PostConfigureDatabase) HTTP API endpoint to create a database with a retention period:

<!-- Tabbed content: Select one of the following options -->

**influxdb3 CLI:**

```bash
# 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
```

**HTTP API:**

```bash
# 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"
  }'
```

<!-- End tabbed content -->

Replace the following:

-   `DATABASE_NAME`: the name of the database
-   `AUTH_TOKEN`: your [admin token](/influxdb3/core/admin/tokens/)

#### Retention periods are immutable in Core

In InfluxDB 3 Core, 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/).

#### Related

-   [Create a database](/influxdb3/core/admin/databases/create/)
-   [influxdb3 create database](/influxdb3/core/reference/cli/influxdb3/create/database/)
-   [Create database API](/influxdb3/core/api/database/#operation/PostConfigureDatabase)

[internals](/influxdb3/core/tags/internals/) [retention](/influxdb3/core/tags/retention/)