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

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

ℹ️ 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

import (
  "log"
  "time"

  "github.com/deta/deta-go/deta"
  "github.com/deta/deta-go/service/base"
)

type TmpData struct {
  Key string `json: "key"`
  Value string `json:"value"`
  // json struct tag `__expires` for expiration timestamp
  // 'omitempty' to prevent default 0 value
  Expires int64 `json:"__expires,omitempty"`
}

func main() {
  // errors ignored for brevity
  d, _ := deta.New(deta.WithProjectKey("project_key"))
  db, _ := base.New(d, "examples")

  tmp := &TmpData{
    Key: "temp_key",
    Value: "temp",
    Expires: time.Date(2023, 1, 1, 0, 0, 0, 0, time.UTC).Unix(),
  }
  _, err := db.Put(tmp)
  if err != nil {
    log.Fatal("failed to put item:", err) 
  }
}

curl -X PUT "https://database.deta.sh/v1/test_project_id/examples/items" \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: test_project_key" \
    -d {"items":[{"key": "temp_key", "value": "temp", "__expires": 1672531200}]}

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')})

import datetime
from deta import Deta

db = Deta("project_key").Base("examples")

item = {"key": "temp_key", "value": "temp"}

# expire in 300 seconds
db.put(item, expire_in=300)

# expire at date
expire_at = datetime.datetime.fromisoformat("2023-01-01T00:00:00")
db.put(item, expire_at=expire_at)

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

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

expires = db.get("temp_key").get("__expires")

dest := struct{
  Key     string `json:"key"`
  Expires int64  `json:"__expires,omitempty"`
}{}

if err := db.Get("temp_key", &dest); err != nil {
  log.Fatal("failed to get item:", err)
}

expires := dest.Expires

curl "https://database.deta.sh/v1/test_project_id/examples/items/temp_key" \
    -H "X-Api-Key: test_project_key"

{"key": "temp_key", "value": "temp", "__expires": 1672531200}

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

updates := base.Updates{
  "__expires": 1672531200,
}
if err := db.Update("temp_key", updates); err != nil {
  log.Fatal("failed to update item:", err)
}

curl -X PATCH "https://database.data.sh/v1/test_project_id/examples/items/temp_key" \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: test_project_key" \
    -d {"set": {"__expires": 1672531200}}

// 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')})

# update item to expire in 300 seconds from now
db.update(None, "temp_key", expire_in=300)

# update item to expire at date
expire_at = datetime.datetime.fromisoformat("2023-01-01T00:00:00")
db.update(None, "temp_key", expire_at=expire_at)