Pulse Compute
The most useful questions usually span two worlds. "Which of the customers who churned last quarter opened a support ticket this week" needs last quarter's history and this week's live data — and in most stacks those live in two different systems, so answering it means building a pipeline to copy one into the other and keeping that pipeline from going stale. Compute removes the pipeline. It's the query engine over your Lakehouse data, and it speaks the same SQL you already use against your operational database — so a single query can reach both.
One query, both worlds
You point the same query call you use for raw SQL at whatever you want to ask. Compute reads the query and routes it for you:
SELECT c.name, sum(s.amount) AS ltv
FROM dataset.q2_sales AS s
JOIN pg.customers AS c ON c.id = s.customer_id
GROUP BY c.name
ORDER BY ltv DESC;
The prefixes tell Compute where each table lives. dataset.<name> is a Lakehouse dataset — read from columnar storage, fast and partition-pruned. pg.<collection> is one of your live Governed Database collections — read straight from Postgres, with row-level security still enforced, so a query can never see a row the caller couldn't see through the ordinary API. The example above joins a quarter of analytical sales history against the live customer table in one statement, no copy step in between.
Queries that touch only your operational tables run against Postgres exactly as they do today — nothing changes for existing code. It's the moment you reference a dataset. table that Compute engages. A name that doesn't resolve to anything real is a hard error, never a silent empty result, so a typo in a table name fails loudly instead of quietly returning nothing.
The platform's own telemetry is a dataset you can query: dataset.telemetry_metrics, dataset.telemetry_logs and dataset.telemetry_traces. Write the values of a dataset query into the SQL text.
Create the client once
import { createClient } from "@k9o/core";
const k9o = createClient({
orgSlug: "acme",
projectSlug: "task-app",
apiKey: process.env.K9O_API_KEY,
});Pulse Compute · C1: ask one question across two collections with a JOIN
One engine ingests, refreshes, queries and joins over your data. In the TypeScript SDK the query surface is k9o.query(sql, params): a read-only SQL statement, parameters either a list ($1, $2) or named values (:name, rewritten to positional by the SDK). Row-level security applies and the caller needs the project-editor role. A table qualified dataset.<name> reads a Pulse Dataset; C4 to C6 show the dataset surface (k9o.analytics, k9o.rollups).
Setup
// The collections this example uses (created once, by a migration):
// CREATE TABLE customers (id text PRIMARY KEY, region text);
// CREATE TABLE orders (id text PRIMARY KEY, customer_id text, total integer);
for (const [id, region] of [["c1", "eu"], ["c2", "eu"], ["c3", "us"]] as const) await k9o.from("customers").insert({ id, region });
for (const [id, customer_id, total] of [["o1", "c1", 40], ["o2", "c2", 25], ["o3", "c3", 99], ["o4", "c1", 8]] as const) {
await k9o.from("orders").insert({ id, customer_id, total });
}// A named parameter (:min) is bound by the database, never pasted into the text.
const { data: byRegion } = await k9o.query<{ region: string; orders: string; revenue: string }>(
`SELECT c.region, count(*) AS orders, sum(o.total) AS revenue
FROM orders o JOIN customers c ON c.id = o.customer_id
WHERE o.total >= :min
GROUP BY c.region
ORDER BY revenue DESC`,
{ min: 10 },
);
console.log(JSON.stringify(byRegion));[{"region":"us","orders":"1","revenue":"99"},{"region":"eu","orders":"2","revenue":"65"}]countandsumcome back as strings; convert withNumber(...)where you need arithmetic.- Read-only: a write through
k9o.queryis refused (K9O_RAW_SQL_READ_ONLY); change rows throughk9o.from(collection). One statement per call. - The tables listed in the Setup are created once by a migration (see the migrations documentation); the example starts from the data. The tab uses the website's names.
Pulse Compute · C2: a scheduled rollup is a function plus a schedule
import { readFile } from "node:fs/promises";
// Upload the built artifact, then deploy it under a name. Deploying is an operator action on the gateway tier.
const wasm = await readFile("./daily_rollup.wasm");
const { data: artifact } = await k9o.functions.uploadArtifact(wasm, "wasm");
const { data: fn } = await k9o.functions.deploy({
name: "daily_rollup",
runtime: "rust",
tier: "gateway",
artifactKey: artifact.artifactKey,
version: "1",
});
console.log(fn.name, fn.status);daily_rollup activePulse Compute · C3: join a fact table against a live stream
**No SDK call joins a stream.** k9o.query reads collections and datasets; it does not read a stream, and k9o.streams has no query. What exists is k9o.streams.subscribe (live events) and replay (history). The join below is done in your code: read the dimension side once with k9o.query, then look each event up as it arrives.
// The collections this example uses (created once, by a migration):
// CREATE TABLE customers (id text PRIMARY KEY, region text);
// The stream carries order events; customers is the collection to join against.
const { data: stream } = await k9o.streams.create({ displayName: "orders-feed", maxBytes: 10_485_760 });
const slug = stream.slug;
try {
await k9o.streams.publish(slug, { id: "o1", customerId: "c1", total: 40 });
await k9o.streams.publish(slug, { id: "o2", customerId: "c2", total: 99 });
await k9o.streams.publish(slug, { id: "o3", customerId: "c1", total: 25 });
// The dimension side: read once with the query surface.
const { data: customers } = await k9o.query<{ id: string; region: string }>("SELECT id, region FROM customers");
const regionOf = new Map(customers.map((c) => [c.id, c.region]));
// The stream side: join each event as it arrives, keep running totals per region.
const totals = new Map<string, number>();
const stop = new AbortController();
let seen = 0;
for await (const event of k9o.streams.subscribe<{ id: string; customerId: string; total: number }>(slug, {
fromSequence: 0,
signal: stop.signal,
})) {
const region = regionOf.get(event.data.customerId) ?? "unknown";
totals.set(region, (totals.get(region) ?? 0) + event.data.total);
console.log(event.sequence, event.data.id, region, JSON.stringify([...totals]));
if (++seen === 3) stop.abort();
}
} finally {
await k9o.streams.delete(slug);
}1 o1 eu [["eu",40]]
2 o2 us [["eu",40],["us",99]]
3 o3 eu [["eu",65],["us",99]]- The customer lookup is a snapshot taken before the loop; re-read it on a timer if customers change while you listen.
- Publishing needs the project admin role; subscribing and replaying need the admin or auditor role.
- The tables listed in the code block are created once by a migration (see the migrations documentation); the example starts from the data.
- The tab creates a temporary stream and deletes it at the end.
Pulse Compute · C4: list and read datasets and rollups
// What exists: datasets (an array) and rollups ({ rollups }).
const { data: datasets } = await k9o.analytics.list();
console.log(datasets.slice(0, 3).map((d) => `${d.slug} (${d.displayName})`).join(", "));
const { data: rollups } = await k9o.rollups.list();
for (const r of rollups.rollups) console.log(`rollup ${r.slug} window ${r.windowSeconds}s ${r.attestationStatus}`);events (Demo events), orders (Orders), telemetry_logs (Telemetry (logs))
rollup orders_per_hour window 60s active
rollup events_per_minute window 60s active
rollup logs_per_minute window 60s active- The calls are read-only, against datasets and rollups that already exist on the project; nothing is created, written, uploaded, materialised or re-attested. The dataset and rollup names are examples. Callers must be project members; service and extension tokens cannot call these routes.
Pulse Compute · C5: create a dataset, write, upload, create a rollup
// The dataset is created by this call; its columns are the schema (no migration involved).
await k9o.analytics.create("orders", {
displayName: "Orders",
columns: [{ name: "order_id", type: "string" }, { name: "city", type: "string" }, { name: "amount", type: "decimal(12,2)" }],
residencyClass: "shared", // or "per-subject"
});- The call creates the dataset and writes no rows; the next tab writes them.
- A slug is never reissued after
delete; a project holds at most 200 datasets.
Pulse Compute · C6: follow a rollup's closed cells
const controller = new AbortController();
for await (const event of k9o.rollups.subscribe("orders_per_hour", { signal: controller.signal })) {
const cell = event.payload;
if (event.suppressed) {
// Below the cohort threshold: no values, only the reason.
console.log(cell.cellKey, cell.status, cell.reason);
} else {
console.log(cell.cellKey, cell.bucket, JSON.stringify(cell.dims), cell.final, JSON.stringify(cell.measures));
}
controller.abort(); // stop after the first cell here
}7c1e2a 2026-10-27T17:00:00.000Z {"city":"Berlin"} true {"orders":12,"revenue":"310.40"}- The stream carries cells only when a rollup folds new data.
- A cell is
{ cellKey, bucket, dims, final, measures }; a suppressed cell hasstatus: "suppressed"and areason(cohort_below_k) instead of measures.eventIddrops a cell a resume re-sends. The SDK reconnects by itself;onResyncis called when the position is lost (re-read withrollups.read).
For the wire-level contract — the single-dataset query path, and the cost figures every query returns so you can see what a query scanned before it surprises you — see API → Data §6.3.
Why it scales the way it does
Compute is a fleet of stateless query workers, each a single embeddable engine (DuckDB) rather than a coordinator-and-workers cluster you have to size and babysit. That choice is the same self-hostable, sovereign-by-construction posture as the rest of the platform, and it has a practical payoff: because the data lives in object storage and the workers only stream it, how much you've stored and how much you query scale independently. A large dataset you rarely touch doesn't cost you query capacity, and a burst of queries doesn't require you to have provisioned a bigger warehouse in advance.
Rollups: pre-computed answers for the dashboards you refresh constantly
Some questions you ask over and over — the numbers behind a live dashboard, refreshed every few seconds. Re-scanning the raw data every time is wasteful. A rollup computes the aggregate continuously as new data arrives, so the dashboard reads a small, always-current summary instead of the full history behind it:
POST /@<projectSlug>/analytics/<datasetSlug>/rollups
{
"slug": "sign-in-volume",
"source": "auth_events",
"dimensions": ["result", "provider"],
"measures": [
{ "name": "count", "agg": "count" },
{ "name": "p95_latency", "agg": "p95", "column": "latency_ms" }
],
"windowSeconds": 60,
"nonPersonal": true
}
A rollup can fold events straight off a Pulse Stream topic into a window of at least 60 seconds. count takes no column; every other aggregation (last, sum, avg, min, max, count_distinct, p50, p95, p99) takes the column it folds. A rollup declares either a subjectField (the event field naming the data subject) or nonPersonal: true, never both. You read its current cells with GET /@<projectSlug>/rollups/<slug>/read, or subscribe to live updates with GET /@<projectSlug>/rollups/<slug>/subscribe, so a dashboard stays current without ever touching the raw event volume underneath it.
What it costs to run
Compute meters the actual work — CPU time — against a single pool that comes with your plan tier. Everything draws from that one pool: ingesting data, refreshing rollups, running queries, and the join work when a query federates back to Postgres. Each shows up separately on your bill so you can see where the time went, but there's one allowance, not four separate ones to juggle. Run past it and queries throttle with a nudge to upgrade rather than a surprise charge; paying for overflow is something you opt into. Current rates and tier allowances are on the pricing page.
See also
- Lakehouse — where the datasets Compute reads are stored.
- Stream — the event bus a rollup can fold from.
- API → Data §6 — the query wire contract in full.