Getting Started

Tutorial: Building with CleaveDB

SCATTER writes

In a multi-node deployment, writing data to a single node requires synchronization so other shards reflect the new state. CleaveDB provides the SCATTER command keyword to broadcast document creations and updates across cluster shards through the Go Coordinator.

Broadcasting document writes

Prefix any standard mutation statement with SCATTER to dispatch it across all configured cluster shards:

CleaveQLExample · Scatter write statement

SCATTER POUR INTO products "item_42" {"name": "Widget", "price": 99.95}

The coordinator sends the mutation concurrently to every active shard node, ensuring data availability across the entire cluster topology.

Scattering document modifications

You can also broadcast document property modifications, virtual field recalibrations, or graph links:

CleaveQLExample · Scatter update statement

SCATTER CHANGE products "item_42" SET price TO 89.95

CleaveQLExample · Scatter relationship bonding

SCATTER BOND "users:1" TO "products:item_42" AS "purchased"

All shards apply the modification simultaneously, keeping read replicas and edge graph indexes synchronized.

Sharding and partitioning models

CleaveDB supports two primary deployment topologies for distributed writes:

Broadcast Replication

Every shard maintains a full copy of the dataset. SCATTER POUR ensures all nodes persist the document. Read queries can execute against any node with zero network hops.

Hash Partitioning (gid % N)

For datasets larger than a single machine's NVMe capacity, documents are partitioned by hashing the global ID (gid_of(key) % N_shards). Reads fan out via CLUSTER SCOOP and assemble in the coordinator.

Verifying cluster writes

After executing a scattered write, verify that the document is accessible across the cluster using CLUSTER SCOOP:

CleaveQLExample · Verify scattered write

CLUSTER SCOOP FROM products WHERE price < 100

The coordinator queries all shards, deduplicates the document by its unique gid, and returns the unified state:

CleaveQLExample · Deduplicated response

[
  {
    "status": "ok",
    "count": 1,
    "documents": [
      {
        "gid": "products:item_42",
        "name": "Widget",
        "price": 89.95
      }
    ]
  }
]