Tutorial: Building with CleaveDB

Virtual fields

Virtual fields allow you to inject calculated properties into documents at query time without altering the stored JSON records on disk. Once declared with ENRICH, virtual attributes behave exactly like stored fields across reads, filters, and aggregations.

Declaration syntax

Bind one or more computed expressions to a target bucket using WITH ... AS:

ENRICH <bucket> WITH <field_name> AS <expression>

-- Multiple fields in a single statement
ENRICH items WITH margin AS price - cost, status AS "active"

Enrichment rules persist in the system catalog and immediately apply to all existing and future documents in that bucket.

Querying enriched documents

When you run FIND, the database engine computes the virtual attributes during document retrieval:

-- 1. Store a user with separate name fields
POUR INTO users "u1" {"first": "Jane", "last": "Doe"}

-- 2. Define the virtual full_name field
ENRICH users WITH full_name AS CONCAT(first, " ", last)

-- 3. Query the document
FIND users "u1"

The output document transparently includes the synthesized attribute:

{
  "first": "Jane",
  "last": "Doe",
  "full_name": "Jane Doe"
}

Notice that full_name was never persisted to the raw database files, saving storage and preventing synchronization bugs when names are updated.

Filtering with WHERE

You can use computed fields directly in filter conditions:

FIND users WHERE full_name = "Jane Doe"

The query engine evaluates the formula for each candidate record and applies the comparison predicate seamlessly.

Aggregating enriched attributes (DISTILL)

Virtual fields can be passed into aggregate functions:

ENRICH sales WITH tax AS price * 0.20
DISTILL FROM sales TOTAL tax

The aggregation pipeline streams through the computed tax values, calculating the grand total without requiring a dedicated tax column in the database table.