Batch Writes

What you'll learn

Write many records atomically, understand the GroupCommitter, and measure the throughput difference.

Single-agent batch

curl -s -X POST http://localhost:7475/v1/agents/events/write/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{
    "records": [
      {"payload": {"type": "click", "element": "hero_cta"}},
      {"payload": {"type": "scroll", "depth": 50}},
      {"payload": {"type": "click", "element": "pricing_link"}},
      {"payload": {"type": "page_exit", "time_on_page_ms": 12400}}
    ]
  }' | python3 -m json.tool

All four records are written in one fsync. Sequences are contiguous. If the process crashes mid-batch, the WAL ensures full recovery.

Batch response

{
  "written": 4,
  "records": [
    {"content_hash": "...", "sequence": 1, "ts_hlc": ...},
    {"content_hash": "...", "sequence": 2, "ts_hlc": ...},
    {"content_hash": "...", "sequence": 3, "ts_hlc": ...},
    {"content_hash": "...", "sequence": 4, "ts_hlc": ...}
  ]
}

Throughput difference

Use batch writes whenever you are ingesting events, logs, or sensor data.

Batch with mixed TTLs

curl -s -X POST http://localhost:7475/v1/agents/sessions/write/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{
    "records": [
      {"payload": {"token": "a"}, "ttl_ms": 3600000},
      {"payload": {"token": "b"}, "ttl_ms": 7200000},
      {"payload": {"token": "c"}}
    ]
  }' | python3 -m json.tool

Each record in a batch can have its own TTL.

Challenge

Write a Python or shell script that generates 100 event records and sends them in a single batch call. Measure wall time vs. 100 individual writes.

---