Execution Analysis

Understand how your query will run before executing it.

explain() — Execution Plan

The explain() function parses a query and returns a cost-annotated execution plan without running it. Each stage shows its Big-O cost, estimated record counts, and any warnings.

explain("from(orders) | filter(amount > 100)")

This returns a structured plan showing every step Liven will take, the estimated cost of each step, and the expected number of records at each stage.

Example Output

Step 1: from("orders")
  → Full segment scan
  → Estimated cost: O(N)
  → Estimated records: all records in "orders"
  Step 2: filter(amount > 100)
  → In-memory filter
  → Estimated cost: O(M) where M = upstream record count
  → Estimated records: records with amount > 100

Timestamp Index Optimization

When a time-range filter is detected, the plan shows "timestamp index scan" instead of "full segment scan":

explain("from(events) | filter(timestamp > 1700000000000)")
  // Shows: "timestamp index scan — O(log N + K)"

Using explain() for Debugging

Use explain() to:

• Identify expensive operations — queries that trigger full segment scans instead of index lookups
• Verify pipeline order — check that your most restrictive filter comes first
• Compare query strategies — test different filter arrangements to find the most efficient one
• Understand cross-stream joins — see whether a correlate() will trigger a secondary full scan

Explain an Insert

explain("from(users).insert(k1, {name: test})")

Shows the existence check (O(log n)), append (O(1)), and index update (O(log n)) costs.

Explain streams()

explain("streams()")

Confirms zero-disk reads — the streams list is served entirely from in-memory state.

status() — Live Server Metrics

The status() query returns current server metrics without any query parsing:

status()

Returns: active_connections and broadcast_subscribers.