Subscriptions

{
  "name": "urgent-enterprise",
  "filters": ["And", [
    ["answers.urgency.p", "Gt", 0.8],
    ["attributes.plan", "Eq", "enterprise"]
  ]],
  "events": ["entered", "exited"],
  "include": {"attributes": ["account_id"]},
  "bulk": "summary"
}

​

Create, list and query

from vainona import And

ns = db.namespace("acme/prod")
ns.subscriptions.create(
    name="urgent-enterprise",
    filters=And(("answers.urgency.p", "Gt", 0.8), ("attributes.plan", "Eq", "enterprise")),
    events=["entered", "exited"],
    include={"attributes": ["account_id"]},
    endpoint=endpoint["id"],  # or leave it out for the events feed only
)

for sub in ns.subscriptions.list()["subscriptions"]:
    print(sub["name"], sub["status"], sub.get("template"))

# The documents that match now, as a query.
page = ns.subscriptions.query("urgent-enterprise", top_k=100)

const ns = db.namespace("acme/prod");
await ns.subscriptions.create({
  name: "urgent-enterprise",
  filters: ["And", [["answers.urgency.p", "Gt", 0.8], ["attributes.plan", "Eq", "enterprise"]]],
  events: ["entered", "exited"],
  include: { attributes: ["account_id"] },
  endpoint: endpoint.id, // or leave it out for the events feed only
});

const { subscriptions } = await ns.subscriptions.list();
for (const sub of subscriptions) console.log(sub.name, sub.status, sub.template);

// The documents that match now, as a query.
const page = await ns.subscriptions.query("urgent-enterprise", { top_k: 100 });

• events defaults to ["entered"]. Add exited if you keep a list of the matching documents, or you will never hear that one left.
• endpoint defaults to none: the events go to the events feed only. An endpoint’s namespace_prefix must cover the namespace, or every namespace of a template.
• include names the attributes and answers to send with each event. The attributes and answers the filter reads are always sent. state never is.
• bulk is summary (the default) or deliver. See bulk changes.
• name is 1 to 128 letters, digits, _ and -. Creating a subscription again with the same name and the same settings returns the existing one, so a retried create is safe.
• status is syncing until the subscription’s first evaluation in the namespace, then live, with live_at.
• lag_ms is how long the oldest change the subscription hasn’t evaluated has waited. It is accurate only to about a minute: a quiet subscription records its progress about once a minute, so lag_ms reads 0 until a change has waited longer than that. It tells you the subscription is stuck, not that it is a few seconds behind. It is null while the subscription is syncing.
• warnings lists problems such as judgment_inactive: a judgment the subscription reads or includes was deactivated or deleted. Its answers stop changing, so the subscription sees nothing new from it. The subscription is never paused or deleted for that.
• update changes events, include, endpoint and bulk for the changes evaluated after it. It can’t change filters.
• delete removes the definition, and the next evaluation drops the subscription’s matching set. Events recorded before then, and deliveries already queued, still go out.
• The query runs the saved filter with your own rank_by, top_k, cursor and include, and is billed like any query. It takes a namespace, never a template prefix, and its body can’t have filters. Use it to seed a receiver, and after subscription.synced.

​

What is refused

• invalid_request: a filter on freshness, or on state; a judgment that doesn’t exist or is computed on read (on_read), in the filter or in include; state in include; empty or repeated events; more than 24 fields, counting those the filter reads; a name the namespace already has or inherits; an endpoint that doesn’t exist or doesn’t cover the namespace; a 101st subscription in a namespace, counting those it inherits; and an update that sends filters. See limits.
• plan_required: a subscription on a template prefix below the Team plan, as for templates.
• unavailable (503, with Retry-After): a create or update that names an endpoint while the endpoint can’t be checked. Nothing was changed, so retry it.

​

Events are edges, not states

• subscription, with its id, name and defined_on, the namespace or template prefix it was created on;
• namespace, the namespace the document is in;
• document, with its id, revision, incarnation and updated_at;
• attributes and answers: those the filter reads and those named in include, as a get returns them;
• cause: change for a write or a new answer, fanout, periodic, or, for bulk changes you asked to receive, backfill (with the backfill’s job_id) or resync;
• sequence, below;
• url, the document’s get, to fetch the rest with your own key;
• truncated: a body is at most 64 KB, so past that attributes and answers are left out, truncated is true, and url has them.

​

Only settled answers count

​

Bulk changes

{"subscription": {...}, "namespace": "acme/prod", "reason": "backfill",
 "job_ids": ["job_01j9..."], "entered": 1204, "exited": 37}

• created, once the subscription’s first evaluation in the namespace is done;
• backfill, sent once an evaluation finds no more of the backfill’s answers, or 10 minutes after the first one, whichever comes first. Backfills that overlap share one synced, with all their job_ids;
• thresholds_changed, when a threshold the filter reads is edited, or a new version changes it;
• weights_changed, when a composite judgment the filter reads gets new calibration fits.

​

A new subscription starts from now

​

Templates

• Per tenant. Each tenant has its own matching set, and its events name the tenant in namespace. subscription.defined_on names the prefix the subscription was created on, so a platform routes events without a lookup.
• Lazy start. A tenant starts evaluating a template’s subscription at its next change after the subscription exists, so idle tenants cost nothing. Until then the subscription reads syncing in that tenant.
• No opting out. Tenants can’t change, delete or detach a template’s subscription. To leave one out, add a condition on id or an attribute to the filter.
• Names. A tenant can’t create a subscription with the name of one it inherits. A template can create a name a tenant already has; both run, and the tenant’s own is listed first.

​

Limits