Tutorial: Building with CleaveDB

Creating ID

Every document needs two coordinates: a bucket to group it with similar records, and an ID to pick out one record from that group. A user profile might live in the users bucket under the ID jane, giving it the readable address users:jane. When you use POUR, choose an ID your application can recognize, or let CleaveDB generate one when the data arrives without a natural key.

Use an ID your application already knows

Put the ID after the bucket name when there is already a stable identifier to use—a username, an order number, or a key from another system. This is useful when you expect to look up the document by that same value later: Jane’s profile remains users:jane, easy for both the application and its developers to recognize. The bucket name may be unquoted or quoted; both forms in this example target users.

POUR INTO users "jane" {"name": "Jane", "age": 25, "city": "Manila"}
POUR INTO "users" "pedro" {"name": "Pedro"}

Read the first line in three parts: users is the destination bucket, "jane" is the chosen document ID, and the JSON object is Jane’s data. The second line does the same for Pedro, with quotation marks around the bucket name. CleaveQL uses the bucket and ID together as the document address; the ID alone is only unique within its bucket.

Let CleaveDB generate an ID

Some records arrive without a natural key. A click event, a log entry, or an incoming message still needs its own document address, even when the application has no useful ID to supply. Put RANDOM where the ID would normally go; CleaveDB generates a cryptographic 64-bit hexadecimal ID for the document. Your application can send the event it observed and leave the key creation to the database.

POUR INTO events RANDOM {"type": "click", "page": "/home"}

Here, events names the destination, RANDOM asks CleaveDB to supply the ID, and the JSON describes what happened. Use an explicit ID when it carries meaning or must match an existing key; use RANDOM when you simply need CleaveDB to give each new document its own address.

Name the bucket

The bucket follows INTO and tells CleaveDB where the document belongs. Choose a name that makes the collection’s purpose obvious: users for profiles, events for activity, or products for a catalog. You can begin writing without a setup step; if the bucket does not exist, CleaveDB creates it as part of the POUR. See the POUR overview for more about buckets and document storage.