> For the complete documentation index, see [llms.txt](https://bucketdb.sullux.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bucketdb.sullux.com/usage/batching.md).

# Batching & Transactions

All write operations in BucketDB (inserts, updates, deletes) are performed through a **Batch**. A Batch acts as an isolated, in-memory workspace. It ensures that multiple related operations can be staged and committed together as a single atomic unit to the distributed Write-Forward Log.

## Why Batching?

Because BucketDB relies on object storage (which is highly durable but suffers from network latency and eventual consistency), it is too slow to write every single row individually to S3. Instead, BucketDB buffers writes locally in memory. When you are ready, you flush the entire batch as a single, highly compressed JSON payload to the `committed/` prefix.

## The Batch Workflow

```javascript
// 1. Create a new batch workspace
const batch = db.batch();

// 2. Perform synchronous, in-memory operations
batch.insert('users', { id: 'u_1', name: 'Alice', age: 30 });
batch.update('users', { id: 'u_2', name: 'Bob', age: 31 });
batch.delete('users', 'u_3'); // Delete by primary key

// 3. Flush the batch asynchronously
await batch.flush();
```

All `insert`, `update`, and `delete` operations inside a batch are strictly synchronous. They merely encode the JavaScript objects into binary representations based on your schemas and append them to an internal write log.

The only asynchronous operation is `flush()`, which uploads the encoded write log to the underlying storage driver.

## Sub-Batches (Nested Contexts)

In complex applications, you often have a primary logical operation (like creating a user profile) that triggers secondary operations (like logging an audit event or sending a welcome email). You want the secondary operations to succeed or fail alongside the primary one, without passing a giant `batch` object through every layer of your application.

BucketDB supports nested sub-batches.

```javascript
const rootBatch = db.batch();
rootBatch.insert('users', { id: 'u_1', name: 'Alice' });

// Create a child batch
const auditBatch = rootBatch.subBatch();
auditBatch.insert('audit_logs', { id: 'log_1', action: 'CREATE_USER', userId: 'u_1' });

// You do NOT flush the sub-batch.
// When you flush the root batch, it recursively flushes all its children.
await rootBatch.flush();
```

This allows discrete functions in your codebase to accept an optional parent `batch` context, create their own sub-batch, and append their work, ensuring everything is committed atomically.

## Read-After-Write Consistency (The Overlay)

A common challenge in distributed, eventually-consistent databases is "Read-After-Write" consistency. If you write a record and immediately query for it, the query might hit an older data block that hasn't been updated yet.

BucketDB solves this brilliantly through **Batch Overlays**.

You can pass a batch object into the `.overlay()` method of the `QueryBuilder`. The query engine will load the immutable data blocks from S3, and then intelligently merge the pending, unflushed operations from your local batch memory *on top* of the results before returning them to you.

```javascript
const batch = db.batch();
batch.insert('users', { id: 'u_99', name: 'Zane' });

// Zane has NOT been flushed to S3 yet.
// However, by overlaying the batch, the query engine knows about him.
const results = await db.query('users')
  .overlay(batch)
  .where('id', '=', 'u_99')
  .execute();

console.log(results[0].name); // "Zane"
```

This is incredibly powerful for complex multi-step workflows. You can insert data, query that same data a few lines of code later to make a business decision, and then flush the entire operation at the very end.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://bucketdb.sullux.com/usage/batching.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.