Tutorial: Building with CleaveDB

PEER INTO COST

Before running an expensive analytical query or write operation against a massive bucket, PEER INTO COST predicts execution overhead, analyzes scan selectivity, and provides automated indexing suggestions.

Syntax and usage

Wrap any target query inside parentheses after PEER INTO COST:

PEER INTO COST ( FIND logs WHERE level = "error" ARRANGED BY timestamp )

The database parses and analyzes the statement without executing the scan or returning raw document payloads.

Structured cost breakdown

The engine returns a detailed JSON diagnostic report:

{
  "status": "ok",
  "cost": {
    "scan_type": "FULL_BUCKET_SCAN",
    "estimated_docs_scanned": 50000,
    "filter_selectivity": 0.12,
    "docs_after_filter": 6000,
    "sort_in_memory": true,
    "has_applicable_index": false,
    "estimated_ms": 65,
    "suggestions": [
      "Create INDEX logs ON (level, timestamp) to avoid full scan and eliminate in-memory sort",
      "Add LIMIT to cap memory usage"
    ]
  }
}

The diagnostic immediately highlights whether the query requires a sequential scan or suffers from in-memory sorting penalties.

Key metrics explained

Profiling write operations

You can also profile document insertions and bulk writes:

PEER INTO COST ( POUR {"name": "Test", "role": "engineer"} INTO users )

Reveals indexing and validation overhead prior to committing large transactional writes.