Skip to main content
Your schema says what; routing decides which machine gets the homework.

​
1. Motivation

One logical Entity may need scalar storage, vector search, text search, and graph traversal. Routing lets those fields live on suitable Backends while application code keeps one ws.query(Entity) surface. HeavenBase plans from registered placements, Backend types, strategies, handlers, and exact capability evidence. It merges detached result frames by object_id.

​
2. Start with Automatic Placement

Workspace presets provide practical defaults. The debug preset gives local development a complete, inspectable routing setup.
Short keyword arrays can use the SQL-hosted SparseGramIndex strategy for reverse containment. The explicit gram Backend remains available for compatibility layouts.

​
3. Place Fields Explicitly

Use .store(to=..., strategy=...) when a field needs a specific Backend or physical strategy.
Built-in strategies include InlineColumn, JsonField, SideTable, VectorIndex, InvertedIndex, SparseGramIndex, GraphEdge, and ExternalRef. Most applications only need explicit placement where provider choice or performance matters.

​
4. Inspect Placement

Storage rows in MetaSchema expose the compiled plan:
object_id placement is fixed. HeavenBase replicates identity where required so split fields can hydrate into one logical row.

​
5. Inspect Execution

Each step reports the selected Backend, strategy, handler, execution mode, and fallback or unsupported reason. A matching operation, handler key, or semantic tag is not proof that a provider can execute the fragment natively.

​
6. Understand the Boundary

Backend writes are coordinated, but independently routed Backends do not form a distributed transaction. A failed fan-out may require explicit audit, repair, or application reconciliation. Keep the operating model small:
  1. Define the Entity once.
  2. Start with a preset.
  3. Add explicit placement only where it buys something measurable.
  4. Use explain() before making performance claims.

​
Summary

  • Routing separates logical schema from physical execution.
  • Presets cover common placements; .store(...) expresses deliberate exceptions.
  • MetaSchema shows placement, while explain() shows actual execution.
  • Cross-Backend transactional guarantees remain an application concern.

​
Further Exploration

Related resources:
  • Entities — Declare typed fields
  • Backends — Compare Backend roles and capabilities
  • Query — Execute and explain routed requests
  • Architecture — Follow the complete execution flow