Expiring Items

Deta Base supports storing items with an expiration timestamp. Items with an expired timestamp will be automatically deleted from your Base.

Storing#

Items specify the expiration timestamp value in a field name __expires in the item itself. The value is a Unix time, a number.

For e.g.

{
  "key": "item_key",
  "msg": "this will be deleted",
  "__expires": 1672531200
}

The item above will be deleted automatically on 2023-01-01 00:00:00 GMT (the equivalent date of the timestamp above).

You can use the Base SDK to put, put_many or insert items with an expiration timestamp (or the HTTP API directly).

warning

Storing an item with an already expired timestamp will not fail but the item will be immediately deleted.

info

Base SDKs might offer higher level methods with easier APIs to specify the expiration timestamp. If they do so, they still store the timestamp in the item itself as mentioned above.

Examples#

JavaScript
Python
Go
HTTP

const Deta = require('deta');
const db = Deta("project_key").Base('examples');

const item = {'value': 'temp'};

// expire in 300 seconds
await db.put(item, 'temp_key', {expireIn:300})

// expire at date
await db.put(item, 'temp_key', {expireAt: new Date('2023-01-01T00:00:00')})

Retrieving#

When you retrieve items with an expiration timestamp, the timestamp value will be present in the __expires field. The value is a Unix time.

Get and Query operations will not retrieve already expired items.

Examples#

JavaScript
Python
Go
HTTP

const { __expires } = await db.get("temp_key");

Updating#

You can update the expiration timestamp with a new timestamp by updating the value of the __expires as long as the item has not already expired.

Updating other fields of the item does not update (or renew) the expiration timestamp. You must update the value of __expires field.

You can use the Base SDK to update the expiration timestamp (or the HTTP API directly).

Examples#

JavaScript
Python
Go
HTTP

// update item to expire in 300 seconds from now 
await db.update(null, "temp_key", {expireIn: 300})

// update item to expire at date
await db.update(null, "temp_key", {expireAt: new Date('2023-01-01T00:00:00')})

Issues#

If you run into any issues, consider reporting them in our Github Discussions.