Tutorial: Building with CleaveDB
Storing Documents (POUR) — Overview
POUR is CleaveDB’s command for creating and writing documents. If you are used to SQL, it fills a role similar to INSERT, but CleaveDB stores flexible JSON documents in named buckets rather than requiring every record to follow a fixed table schema. A POUR write places a document in a bucket and associates it with an ID.
The JSON object holds a document’s fields. Documents in the same bucket can contain different fields, so you can store the attributes that make sense for each record without forcing every kind of data into one rigid shape. CleaveDB namespaces documents by the authenticated tenant, keeping users’ data isolated according to the database’s tenant rules. That means the same bucket name can be used by different tenants while CleaveDB applies the appropriate data boundaries.
A typical write follows a simple rhythm: choose where the document belongs, decide how it should be addressed, then provide its JSON data. From there, CleaveQL gives you several variations for the job at hand: create one document, let CleaveDB choose an ID, send a batch, set an expiry, register an account secret, or write into a nested field. Each variation is still part of the POUR family, so the shape of the data workflow stays familiar even when the details change.
POUR is the start of the document’s journey, not the end of it. Use FIND to retrieve what you wrote, CHANGE to edit selected fields later, and LINK to connect that document to another one. The pages below walk through each POUR variation with examples, so you can pick the right one without memorizing the whole command reference first.
Explore the POUR options
Each option has its own page with details based on the CleaveQL command reference: