Time to live (TTL)

Time-to-live (TTL) allows you to set an expiration time for objects in a collection.

Expired objects are periodically removed from the collection by Weaviate's background processes, helping you manage data lifecycle and storage.

TTLs are currently defined at the collection level. They can be set relative to an object's creation time, the last update time, or a specific DATE property within the object.

With all TTL definitions, you can optionally set whether to exclude expired, but not yet deleted, objects from query results. This can prevent erroneous data retrieval before the background deletion process runs.

Relative to a creation time

Set a TTL to count forward from the object's creation time metadata. The value must be positive.

Python

from weaviate.classes.config import Configure, Property, DataType
import datetime

client.collections.create(
    name="CollectionWithTTL",
    properties=[
        Property(name="referenceDate", data_type=DataType.DATE),
    ],
    object_ttl_config=Configure.ObjectTTL.delete_by_creation_time(
        time_to_live=datetime.timedelta(hours=1),  # Or set 3600 for seconds
        filter_expired_objects=True,  # Optional: automatically filter out expired objects from queries
    ),
)

TypeScript

await client.collections.create({
  name: 'CollectionWithTTL',
  properties: [
    { name: 'referenceDate', dataType: dataType.DATE },
  ],
  objectTTL: configure.objectTTL.deleteByCreationTime({
    defaultTTLSeconds: 3600,  // 1 hour
    filterExpiredObjects: true,  // Optional: automatically filter out expired objects from queries
  }),
});

Java

client.collections.create("CollectionWithTTL",
    c -> c.properties(Property.date("referenceDate"))
        .objectTtl(ttl -> ttl
            .deleteByCreationTime()
            .defaultTtlSeconds(3600)  // 1 hour
            .filterExpiredObjects(true)  // Optional: automatically filter out expired objects from queries
        ));

Relative to a last update time

Set a TTL to count forward from the object's last updated time metadata. The value must be positive.

Python

from weaviate.classes.config import Configure, Property, DataType
import datetime

client.collections.create(
    name="CollectionWithTTL",
    properties=[
        Property(name="referenceDate", data_type=DataType.DATE),
    ],
    object_ttl_config=Configure.ObjectTTL.delete_by_update_time(
        time_to_live=datetime.timedelta(days=10),  # Or set 864000 for seconds
        filter_expired_objects=True,  # Optional: automatically filter out expired objects from queries
    ),
)

TypeScript

await client.collections.create({
  name: 'CollectionWithTTL',
  properties: [
    { name: 'referenceDate', dataType: dataType.DATE },
  ],
  objectTTL: configure.objectTTL.deleteByUpdateTime({
    defaultTTLSeconds: 864000,  // 10 days
    filterExpiredObjects: true,  // Optional: automatically filter out expired objects from queries
  }),
});

Java

client.collections.create("CollectionWithTTL",
    c -> c.properties(Property.date("referenceDate"))
        .objectTtl(ttl -> ttl
            .deleteByUpdateTime()
            .defaultTtlSeconds(864000)  // 10 days
            .filterExpiredObjects(true)  // Optional: automatically filter out expired objects from queries
        ));

Relative to a specific DATE property

Set a TTL to a relative value from a specific DATE property within the object. The value can be positive or negative.

Python

from weaviate.classes.config import Configure, Property, DataType
import datetime

client.collections.create(
    name="CollectionWithTTL",
    properties=[
        Property(name="referenceDate", data_type=DataType.DATE),
    ],
    object_ttl_config=Configure.ObjectTTL.delete_by_date_property(
        property_name="referenceDate",
        ttl_offset=datetime.timedelta(minutes=5),
    ),
)

TypeScript

await client.collections.create({
  name: 'CollectionWithTTL',
  properties: [
    { name: 'referenceDate', dataType: dataType.DATE },
  ],
  objectTTL: configure.objectTTL.deleteByDateProperty({
    property: 'referenceDate',
    defaultTTLSeconds: 300,  // 5 minutes offset
  }),
});

Java

client.collections.create("CollectionWithTTL",
    c -> c.properties(Property.date("referenceDate"))
        .objectTtl(ttl -> ttl
            .deleteByDateProperty("referenceDate")
            .defaultTtlSeconds(300)  // 5 minutes offset
        ));

Further resources

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.