Tutorial: Building with CleaveDB

MIGRATE — reshape documents

The MIGRATE command rewrites every document matching a FROM template into a new TO template across an entire bucket. By capturing attributes with placeholder variables ($1, $2), you can rename fields, duplicate values, or upgrade schemas without locking the database.

Basic syntax and pattern capturing

Define the source JSON structure and target JSON layout:

MIGRATE <bucket> FROM <src_pattern> TO <dst_pattern>

Values matched by $1, $2 in the FROM object are reused in the corresponding positions of the TO object.

Common migration patterns

Here are the standard schema reshaping workflows supported by CleaveDB:

-- 1. Rename a field from 'fname' to 'first'
MIGRATE users FROM {"fname":"$1"} TO {"first":"$1"}

-- 2. Copy a single field into two separate attributes
MIGRATE users FROM {"lname":"$1"} TO {"last":"$1", "surname":"$1"}

-- 3. Add a schema version tag to all existing profiles
MIGRATE users FROM {"first":"$1"} TO {"first":"$1", "tag":"v2"}

Unmentioned fields in the documents (such as age, email, or nested sub-documents) are preserved untouched.

Selective status migrations

You can also use MIGRATE to transition records matching specific literal values:

-- Migrate legacy accounts to stale status
MIGRATE users FROM {"status":"old"} TO {"status":"stale"}

Only documents where status === "old" are updated. Documents with any other status value remain unmodified.

Composing migrations with queries & distill

Because MIGRATE maintains full document and graph integrity, queries and aggregations immediately reflect the transformed structure:

-- Insert a test profile
POUR INTO users "u1" {"fname":"Al", "lname":"Bo", "age":32}

-- Reshape the name field
MIGRATE users FROM {"fname":"$1"} TO {"first":"$1"}

-- Verify the new field
FIND users
-- Output: {"first": "Al", "lname": "Bo", "age": 32, "_version": 2}

-- Distill aggregations remain fully operational
DISTILL FROM users TOTAL age

Each migrated document has its _version counter bumped by 1.