drift Docs
Start
What is Drift?
The tour, if you are new here.
Use cases
Whether Drift does your thing.
Getting started
Nothing to deployed, in one command.
Architecture
How a slice is put together.
What it costs
The free grant, four unit prices, two rules.
Build
Canvas
Static sites, same origin as your API.
Tools
Operate
Auth
Route gates, API keys and your account.
Teams
More than one person on one account.
Security
Boundaries, sandboxing and hardening.
Troubleshooting
Error codes
What went wrong, and what to do about it.
Legal
Acceptable use
What a slice may not be used for.
Data processing
The DPA, and every sub-processor.

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 declared in the Driftfile, with a nosql block whose size is required; drift apply creates it. The same block seeds the collection, gives it a ttl, or declares a unique constraint; see the Driftfile reference. The refusal is the same for blobs.
Driftfile
slice "accounts" {}

backbone {
  nosql "users" {
    size   = "64MiB"
    seed   = "backbone/users.jsonl"
    ttl    = "30d"
    unique = ["email", "username"]
  }
}

size is both what the collection is billed at and the limit it enforces: a write past it is refused with 413.

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)Field/value pairs, all of which must match. See below.
Drop()Nothing. Deletes the collection and every document in it.
Go
// _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 = ["email"] on a nosql block 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.

Several pairs combine with AND: List({"group_id": "g1", "status": "open"}) returns only the documents where both match. Each is still an exact match on a top-level scalar; there are no ranges and no OR. A filter holds at most 8 fields, and it cannot be combined with ListInOrder.

Put a selective field in the filter.

The platform walks whichever field matches the fewest documents and checks the others against it, so a combination costs about as much as its most selective field. A page that still is not full after 100,000 candidates is refused with 422 rather than returned short. When every field matches a large share of the collection and their combination is rare, add a more selective field, or keep that subset in its own collection.

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 with seed, a JSONL file with one document per line, each carrying an _id and upserted on every deploy; see the Driftfile.

Give a collection a ttl in the Driftfile (a duration such as "30d") 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.