KV Fields

Any Model may have any number of Cloudflare KV hydrated fields.

KV fields reference templates defined in a KV bindings or Durable Object bindings.

Defining a KV Field

A field in a Model can be hydrated from KV by referencing a binding defined on a kv namespace:

kv MyNamespace {
    settings -> json { }
}

model User {
    kv MyNamespace::settings {
        settings
    }
}

The above snippet defines a Model User with a KV field settings that is sourced from the namespace MyNamespace under the static key "settings".

The value in the template is typed as json, and Cloesce will automatically handle the serialization and deserialization of this field when reading from and writing to KV.

Note

To use a Durable Object’s KV field, shard fields must be provided in the kv field:

durable MyDurableObject {
    shard {
        tenant: string
    }

    settings -> json { }
}

model User for MyDurableObject::tenant {
    kv MyDurableObject::{settings, tenant} {
        settings
    }
}

Key Interpolation

A common pattern is to format a key such that any number of related values can be stored under that template. For example:

kv MyNamespace {
    profile -> json {
        userId: int

        "profile/{userId}"
    }

    profileImplicitKey -> json {
        userId: int
    }
}

Here, profile accepts one parameter, userId. The key for this field in KV is defined as "profile/{userId}", where {userId} is a placeholder replaced with the actual value of the userId parameter when accessing KV.

In the profileImplicitKey field, the key is not explicitly defined, so Cloesce will automatically generate a key based on the field name and its parameters. In this case, the key will be "profileImplicitKey/userId/{userId}".

Any column or route field on a Model can be used to populate the parameters of a KV field, as long as the types match. For example:

model User for MyDb {
    primary {
        id: int
    }

    column {
        friendId: int
    }

    kv MyNamespace::profile(id) {
        profile
    }

    kv MyNamespace::profile(friendId) {
        friendProfile
    }
}