Tutorial: Building with CleaveDB
Updating Documents — Overview
CHANGE and UPDATE are CleaveDB’s commands for modifying existing documents. If you are used to SQL, they operate directly on flexible JSON documents within buckets rather than fixed table columns. An update statement targets one or more documents and updates specified fields in place while leaving the rest of the document untouched.
Unlike replacing an entire record with a fresh write, these commands apply targeted mutations. You specify which bucket and document to modify, identify the fields that should be altered using SET, and supply the new values. This makes it straightforward to update a user's email address, adjust an inventory balance, or update a status flag without transmitting or rewriting the entire JSON payload.
CleaveQL supports several forms of document updates depending on your workload: targeting an explicit document ID, mutating multiple attributes simultaneously, matching a group of records with WHERE or WHOSE conditions, using the familiar UPDATE command, or injecting dynamic values computed from nested SCOOP sub-queries.
How CleaveDB processes updates
When an update executes, CleaveDB evaluates the statement through its multi-stage pipeline:
- Security and Tenant Boundaries: Document-Level Security (DLS) policies and Graph-Based Access Control (GBAC) verify that the authenticated session has permission to mutate the matched records within their tenant namespace.
- WAL & Buffer Pool: Changes are written to the Write-Ahead Log (WAL) and committed into the CLOCK-sweep buffer pool, guaranteeing ACID durability.
- Index Synchronization: If an updated field is covered by a B+Tree index, the index is refreshed immediately.
- Background Semantic Re-indexing: If text fields configured for semantic search are altered, CleaveDB queues the updated text for background vector re-embedding using the built-in ONNX Transformer model.
Use POUR when you first insert records, FIND or SCOOP to query them, CHANGE or UPDATE to evolve their data over time, and DRAIN when records should be safely soft-deleted. The lessons below cover each updating pattern with clear CleaveQL examples.
Explore the updating topics
Each lesson provides practical examples and best practices for updating data in CleaveDB:
- Updating single fields: modify a specific attribute on an identified document or condition match.
- Updating multiple fields: update several properties or nested paths in a single atomic operation.
- Sub-query injection: compute dynamic update values or target sets using nested SCOOP statements.
- The UPDATE: use the SQL-compatible UPDATE command for modifying documents.