Tutorial: Building with CleaveDB
Query Diagnostics (PEER) — Overview
In high-scale production databases, diagnosing slow queries, avoiding accidental full scans, and verifying neural hardware acceleration are critical for reliability. CleaveDB provides PEER—a built-in diagnostic and profiling engine that analyzes query plans and AI telemetry without executing mutations.
The Diagnostic Toolkit
1. PEER INTO COST
Profile query execution costs, inspect scan types (FULL_BUCKET_SCAN vs. INDEX_SCAN), and receive automated index recommendations.
2. PEER INTO ATTENTION
Inspect neural search status, ONNX runtime providers, Transformer model health, and 384-dimensional vector embedding telemetry.
3. Performance Tuning
Follow the canonical 4-step workflow to verify query bottlenecks, generate missing B-tree indexes, and eliminate in-memory sorting.
Calibrated I/O + CPU Cost Model
CleaveDB evaluates query cost using a calibrated NVMe SSD performance model:
- Page I/O: Estimates 16KB page reads across B+Tree traversals and sequential storage sweeps.
- CPU Evaluation: Accounts for deserialization, predicate comparisons, and in-memory sort penalties (
O(N log N)). - Automated Remediation: Emits ready-to-run
INDEXstatements when queries lack index coverage.
Explore Diagnostic Guides
Choose a topic below to inspect and tune CleaveDB query execution:
- PEER INTO COST: estimate I/O latency, selectivity, and scan modes before running expensive queries.
- PEER INTO ATTENTION: inspect neural Transformer embedding status and hardware acceleration.
- Performance tuning workflow: practical guide to converting slow full scans into sub-millisecond index lookups.