Skip to content
Connect > Data APIs > Use Cases

Filtered live view

Goal: a blotter that shows only the orders that matter right now (say, only OPEN orders) and drops each one the moment it fills, without you polling or re-querying. This is where focus filtering (oof) earns its place.

Prerequisites

  • The WebSocket server is enabled (ami.websocket.port=3410): see Configuration.
  • An ORDERS PUBLIC table with a status column. The Insert rows and call a procedure page creates it; drive it by inserting OPEN orders and updating them to FILLED over REST.

The problem with a plain filter

Subscribe to open orders the naive way:

1
{"action":"subscribe","id":"blotter","sql":"SELECT ORDER_ID,SYM,side,qty,status FROM ORDERS WHERE status == \"OPEN\"","oof":false}

With the default oof:false, the WHERE is applied only when a row is first seen. Your snapshot correctly contains the open orders, but when O-1001 later fills and its status changes to FILLED, the Center keeps sending you updates for it (it was already in your set) and never tells you it left the filter. Your "open orders" blotter now shows a filled order. It has gone stale.

Turn on focus filtering

Set oof:true:

1
{"action":"subscribe","id":"blotter","sql":"SELECT ORDER_ID,SYM,side,qty,status FROM ORDERS WHERE status == \"OPEN\"","oof":true}

Now the Center re-checks the WHERE whenever an update changes status, the column it reads:

  • A new order inserted with status="OPEN" → you receive an add.
  • An order whose status changes from OPEN to FILLED → you receive a delete (it left the filter).
  • A change to an order that stays OPEN (e.g. a quantity amend) → a normal update.

Your client can treat the stream literally: add inserts a row, delete removes it, update merges. The blotter always holds exactly the open orders.

Client handling

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
const orders = new Map();
const ws = new WebSocket("ws://localhost:3410/center");

ws.onopen = () => ws.send(JSON.stringify({
  action: "subscribe", id: "blotter",
  sql: 'SELECT ORDER_ID,SYM,side,qty,status FROM ORDERS WHERE status == "OPEN"',
  oof: true
}));

ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type !== "updates") return;
  for (const u of msg.updates) {
    if (u.action === "delete") orders.delete(u.objectId);          // order left the filter
    else orders.set(u.objectId, { ...(orders.get(u.objectId) ?? {}), ...u.row });
  }
  renderBlotter(orders);
};

Drive it by inserting and filling orders over REST (see Insert rows and call a procedure) and watch rows appear and disappear.

Choosing oof

oof:false (default) oof:true
Filter re-checked on updates No Yes
Rows that leave the filter Stay, go stale (no delete) Removed with a delete
Newly inserted matching rows Added with an add Added with an add
Existing rows that change into the filter Never added (until re-subscribe) Added with an add
Cost Cheaper Per-update re-check on the Center

Note the distinction under oof:false: a brand-new row inserted with status="OPEN" is delivered, but an existing FILLED order that is later updated back to OPEN is not: the filter is only evaluated when a row is inserted or snapshotted, not when it changes.

Use oof:true whenever the membership of the filtered set changes over time: open orders, working quotes, anything with a lifecycle. Use oof:false when the filter just narrows a stable set (e.g. one symbol) and you don't care about rows crossing the boundary.

The limit-breach alert use case takes this one step further: the filter is the alert condition.