Spedo Reactive Delta Query Binding & Freshness Contracts

Since version v0.63.0

Spedo introduces Reactive Delta Query Binding (bind_query / bind_collection), transforming Spedo from a passive key-value store into an Intelligent Live In-Memory Dataflow Runtime. Instead of repeatedly querying over TCP or guessing cache TTLs, your application binds to query patterns, maintains local in-memory state, and receives differential micro-deltas in real time.

1. The Paradigm Shift: Live Query Bindings vs Passive Caches

Traditional application architectures suffer from standard caching dilemmas:

• TTL Guesswork: Short TTLs overload the database; long TTLs serve stale data.
• Cache Stampedes & Invalidation Inefficiencies: When one record in a list changes, traditional systems invalidate or re-query the entire dataset over TCP.
• High Network Overhead: Microservices waste CPU cycles and network bandwidth serializing and deserializing identical query payloads.

Spedo's Reactive Binding solves this with Live In-Memory Subscriptions & Micro-Deltas:

+-----------------------------------------------------------------------------------------+
|                    SPEDO REACTIVE DELTA QUERY ARCHITECTURE                             |
+-----------------------------------------------------------------------------------------+

  Application Worker (Python / Node / Go)
  +-------------------------------------------------------------------------------------+
  |                                                                                     |
  |   orders = db.bind_query("order:*", freshness="bounded:50ms")                       |
  |                                                                                     |
  |   +-------------------------------------------------------------------------------+ |
  |   | Local In-Memory Bound View (dict / live collection)                           | |
  |   |  - order:101 -> {"id": 101, "item": "Laptop", "status": "DELIVERED"}          | |
  |   |  - order:102 -> {"id": 102, "item": "Mouse", "status": "SHIPPED"}            | |
  |   +-------------------------------------------------------------------------------+ |
  |         ^                                                                           |
  |         |  0.0004 ms (Sub-microsecond local RAM reads)                              |
  |         |                                                                           |
  |   [ Fast App Read Operations ]                                                      |
  +-------------------------------------------------------------------------------------+
            ^
            |  Differential Delta Stream (DeltaOp: UPDATE_FIELD, SET, DEL)
            |  Only sends modified bytes over CDC ring buffer (99% bandwidth reduction)
            |
  +-------------------------------------------------------------------------------------+
  | Spedo Engine (Embedded or Standalone TCP Server)                                    |
  |   - CDC Ring Buffer / Sequence WAL Tracker                                          |
  |   - Atomic Pattern Matching & Delta Dispatcher                                     |
  +-------------------------------------------------------------------------------------+

2. Freshness Contracts (SLAs)

Every bound query accepts an explicit Freshness Contract, letting developers choose the exact trade-off between read speed and data consistency:

3. Python SDK Usage & Examples

A. Basic Query Binding & Differential Updates

import spedo
from spedo import DeltaOp

# Connect via embedded in-process engine or remote TCP cluster:
db = spedo.embedded(max_memory="256MB")

# Bind a live collection of active orders with a 50ms freshness contract:
orders = db.bind_query("order:*", freshness="bounded:50ms")

# Read operations are 100% local in-memory (0.4 µs latency):
order_101 = orders.get("order:101")
print(f"Order Count: {len(orders)}")

# Differential deltas automatically patch the local view:
orders.apply_delta(
    DeltaOp.UPDATE_FIELD,
    key="order:101",
    value="DELIVERED",
    path="status"
)

assert orders.get("order:101")["status"] == "DELIVERED"

B. Filtered Reactive Queries (Predicates)

Bind queries can filter items using custom predicates so only relevant records occupy worker memory:

# Bind only pending high-priority orders:
vip_pending = db.bind_query(
    "order:*",
    freshness="bounded:20ms",
    filter_fn=lambda k, v: isinstance(v, dict) and v.get("status") == "PENDING" and v.get("amount", 0) > 1000
)

# Iterating only evaluates matching items:
for order_id, order_data in vip_pending.items():
    print(f"Priority Order: {order_id} -> ${order_data['amount']}")

C. Reactive Subscribers & Change Notifications

Attach event callbacks to react immediately when bound data changes:

orders = db.bind_query("order:*", freshness="bounded:50ms")

def on_order_updated(key: str, op: str, value: any):
    print(f"🔔 Live Delta Received: {op} on {key} -> {value}")

# Subscribe to change stream:
orders.subscribe(on_order_updated)

# When a mutation occurs, the subscriber is invoked instantly:
orders.apply_delta(DeltaOp.SET, "order:105", {"item": "GPU", "status": "PROCESSING"})

4. Performance & Efficiency Comparison

5. Summary & Ecosystem Integration

• Embedded & Client Compatible: Works seamlessly with spedo.embedded() and standard spedo.connect() TCP clients.
• Thread-Safe & Lock-Free Read Paths: Local memory snapshots allow lock-free concurrent reads across worker coroutines.
• Comprehensive Test Suite: Fully covered in tests/test_reactive_query_binding.py.