Time to live (TTL)

Added in v1.36

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.

Prerequisites

TTL requires the OBJECTS_TTL_DELETE_SCHEDULE environment variable to be set on the Weaviate instance. This variable defines the cron schedule for the background deletion process. If it is not set, expired objects will not be deleted.

The minimum TTL value is 60 seconds.

Relative to a creation time

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

PythonJavaScript/TypeScriptJava v6

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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
    ),
)

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
  }),
});

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.

PythonJavaScript/TypeScriptJava v6

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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
    ),
)

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
  }),
});

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.

PythonJavaScript/TypeScriptJava v6

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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),
    ),
)

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

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

Further resources

• Concepts: Data | Time to live
• References: Environment variables

Questions and feedback

If you have any questions or feedback, let us know in the user forum.

Technical questions

If you have questions feel free to post on our Community forum.

Documentation feedback

Leave feedback by opening a GitHub issue.