Drift · Backbone: NoSQL

Backbone NoSQL

JSON document collections. A write is an upsert on the document's own _id, and the platform assigns the storage key.

A collection has to exist on the slice before you can write to it.

A write naming a collection the slice does not have is refused with 400, rather than creating one. A collection's existence and size are part of the slice's shape, set with drift slice create or drift slice resize, not the Driftfile. The Driftfile references an existing collection by slot: to seed it, give it a ttl, or declare a unique constraint; see the Driftfile reference. The refusal is the same for blobs and SQL databases.

Document identity: `_key` and `_id`

_key is the platform's. It is injected into every document as it is stored, formatted <counter>_<unix-nanos>, and it is what read and delete address. Nothing returns it at write time, so read it out of a list result.

_id is yours. Supply one and a second write with the same _id replaces the first. Omit it and every write adds a row. An _id over 255 bytes is not indexed, so the upsert silently becomes an append; the value carries no charset restriction otherwise, so an email address or a path works as an _id.

Method	Takes
`Insert(doc)`	The document. Returns an empty string on a deployed slice, because the write endpoint answers with text, not a key.
`Read(key)`	A `_key`.
`Delete(key)`	A `_key`.
`Get(id)`	An `_id`, resolved through the index.
`List(filter)`	One field/value pair. See below.
`Drop()`	Nothing. Deletes the collection and every document in it.

// _id makes the write idempotent; Get resolves it through the index
drift.Backbone.NoSQL.Collection("users").Insert(map[string]any{
    "_id":  "alice",
    "name": "Alice",
    "role": "admin",
})
alice,  _ := drift.Backbone.NoSQL.Collection("users").Get("alice")
admins, _ := drift.Backbone.NoSQL.Collection("users").List(map[string]string{"role": "admin"})

Unique fields

Declare unique: on a collection in the Driftfile and a write carrying a value another document already holds in one of those fields is rejected with 409, inside the same transaction as the write, so it is a constraint rather than a check you could race. Use it for an email, a username, or an external reference.

A document that omits a unique field is written anyway: absence is not a value, so the constraint does not make the field required. Removing unique: from the Driftfile and redeploying stops enforcing it.

Filtering

A filter reaches only what the blind index holds. At write time the platform indexes top-level scalar fields: strings, numbers, booleans. Maps, arrays and nulls are skipped, so a nested field cannot be filtered at all.

The field name must match [A-Za-z0-9_][A-Za-z0-9._-]{0,254} with no .., because it is written into the index key as plaintext; filtering on a name outside that shape answers 400 invalid field name. The value carries no such restriction, because it is hashed before it ever reaches a key: an email address, an ISO timestamp, a value with a space, all index and filter normally. Only its length is bounded, at 255 bytes; a longer value is never indexed, and filtering on one finds nothing rather than raising an error.

One pair is honoured.

List sends every entry of the map, and the slice reads the first field and the first value and ignores the rest. There is no AND across fields, and map iteration order decides which one wins. Filter on one indexed field and narrow the rest in your own code.

Result limits

list returns 100 documents when no limit is given and clamps any limit to 1–1000. The SDKs' List sends no limit at all, so a collection of 5,000 documents yields the first 100 with nothing in the response to signal the truncation. The CLI's --limit defaults to 100 and obeys the same ceiling; pass --all to page through the whole collection instead, or --after to resume from a specific _key.

NoSQL from the CLI

Shell

drift backbone nosql write --collection users --data '{"_id":"alice","name":"Alice","role":"admin"}'
drift backbone nosql list  --collection users --field role --value admin --limit 500
drift backbone nosql read  --collection users --key 7_1754308800000000000   # a _key taken from `list`
drift backbone nosql drop  users

Collections can be seeded at deploy time from a JSONL file; see the Driftfile.

Give a collection a ttl in the Driftfile and the platform reaps documents whose last write is older than it. The clock resets on every write, so only stale documents are deleted. There is no undo. Omit it and documents are kept forever.