Skip to content

docs: tighten the Recall investigation on the homepage and Recall page #1172

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kvlonge merged 4 commits into from
Oct 20, 2026
Merged

docs: tighten the Recall investigation on the homepage and Recall page #1172

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0d721e5
docs: show Recall step 09 with SQL queries only
kvlonge Oct 20, 2026
bd973bc
docs: shorten the warehouse query in Recall step 09
kvlonge Oct 20, 2026
12a41df
docs: restore sqb recall output in Recall step 09
kvlonge Oct 20, 2026
de28bc6
docs: restore the original step 09 intro sentence
kvlonge Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
39 changes: 20 additions & 19 deletions ...lbuild/.agents/skills/sqlbuild/references/docs/concepts/observability/recall.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,25 +29,28 @@ The waffle shop example's `daily_revenue` model has an audit, `revenue_is_non_ne
severity. One night the payments feed starts recording a refund as a negative payment. The unit tests
still pass, because they run on mocked data. The build finishes with a warning that nobody reads.

The next morning, ask when the audit started failing:
The next morning, ask when the audit started failing, and what each of those builds reported:

```bash
sqb recall query --format table \
"SELECT invocation_started_at AS run, outcome, violation_count FROM audit_results
WHERE audit_name = 'revenue_is_non_negative' ORDER BY run DESC LIMIT 3"
"SELECT a.invocation_started_at AS run, a.outcome, a.violation_count, i.status, i.exit_code
FROM audit_results a JOIN invocations i USING (invocation_id)
WHERE a.audit_name = 'revenue_is_non_negative' ORDER BY run DESC LIMIT 3"
```

```
run | outcome | violation_count
--------------------------- | ------- | ---------------
2026-10-20T00:01:44.784683Z | warn | 1
2026-10-20T00:00:34.652468Z | pass | 0
2026-10-19T23:59:23.827831Z | pass | 0
run | outcome | violation_count | status | exit_code
--------------------------- | ------- | --------------- | --------- | ---------
2026-10-20T00:01:44.784683Z | warn | 1 | completed | 0
2026-10-20T00:00:34.652468Z | pass | 0 | completed | 0
2026-10-19T23:59:23.827831Z | pass | 0 | completed | 0

3 rows
```

See what that run printed, exactly as the scheduler saw it:
The audit started warning on the latest build, and that build still exited 0, so nothing alerted.

See what that build printed, exactly as the scheduler saw it:

```bash
sqb recall output last --tail 4
Expand All @@ -60,26 +63,24 @@ sqb recall output last --tail 4
✓ Completed with warnings PASS=89 WARN=1 FAIL=0 INSUFFICIENT=0 SKIP=0 TOTAL=90 (3.08s)
```

Then check what is true in the warehouse now, with the same command:
Then check what is true in the warehouse now, with `sqb recall query` again:

```bash
sqb recall query --backend warehouse --format table \
"SELECT r.revenue_date, r.total_revenue_cents, p.payment_id, p.amount_cents
FROM prod.daily_revenue r JOIN prod.stg_payments p
ON CAST(p.paid_at AS DATE) = r.revenue_date
WHERE p.amount_cents < 0"
"SELECT payment_id, order_id, amount_cents, paid_at FROM prod.stg_payments WHERE amount_cents < 0"
```

```
revenue_date | total_revenue_cents | payment_id | amount_cents
------------ | ------------------- | ---------- | ------------
2026-04-03 | -1250 | 9 | -2200
payment_id | order_id | amount_cents | paid_at
---------- | -------- | ------------ | -------------------
9 | 8 | -2200 | 2026-04-03 15:42:00

1 row
```

The bad row is still in prod, and payment 9 explains it. A coding agent can follow the same steps:
every answer is a SQL query over the [views](#querying-history), with the same output in `--json`.
Payment 9 is a refund recorded as a negative payment, and it is still in prod. A coding agent can
follow the same steps: the history is SQL over the [views](#querying-history), and every query can
return `--json`.

## What is recorded

Expand Down
28 changes: 14 additions & 14 deletions website/public/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -371,31 +371,31 @@ <h3>Find out what happened, then check what's true now</h3>
Every run is recorded: what ran, the SQL it executed, audit results and everything it printed. Agents and people ask in SQL, then check live state with the same command.
</p>
</div>
<pre class="terminal"><span class="cmd">sqb recall query &quot;SELECT substr(invocation_started_at, 1, 16) AS run, outcome,
violation_count FROM audit_results WHERE audit_name = 'revenue_is_non_negative'
ORDER BY run DESC LIMIT 3&quot;</span>
run <span class="dim">|</span> outcome <span class="dim">|</span> violation_count
2026-10-20T00:01 <span class="dim">|</span> <span class="warn">warn</span> <span class="dim">|</span> <span class="warn">1</span>
2026-10-20T00:00 <span class="dim">|</span> <span class="ok">pass</span> <span class="dim">|</span> 0
2026-10-19T23:59 <span class="dim">|</span> <span class="ok">pass</span> <span class="dim">|</span> 0
<pre class="terminal"><span class="cmd">sqb recall query &quot;SELECT substr(a.invocation_started_at, 1, 16) AS run,
a.outcome, a.violation_count, i.status, i.exit_code FROM audit_results a
JOIN invocations i USING (invocation_id)
WHERE a.audit_name = 'revenue_is_non_negative' ORDER BY run DESC LIMIT 3&quot;</span>
run <span class="dim">|</span> outcome <span class="dim">|</span> violation_count <span class="dim">|</span> status <span class="dim">|</span> exit_code
2026-10-20T00:01 <span class="dim">|</span> <span class="warn">warn</span> <span class="dim">|</span> <span class="warn">1</span> <span class="dim">|</span> completed <span class="dim">|</span> 0
2026-10-20T00:00 <span class="dim">|</span> <span class="ok">pass</span> <span class="dim">|</span> 0 <span class="dim">|</span> completed <span class="dim">|</span> 0
2026-10-19T23:59 <span class="dim">|</span> <span class="ok">pass</span> <span class="dim">|</span> 0 <span class="dim">|</span> completed <span class="dim">|</span> 0

<span class="cmd">sqb recall output last --tail 4</span>
daily_revenue
audit revenue_is_non_negative returned 1 row
<span class="warn strong">✓ Completed with warnings</span> PASS=89 WARN=1 FAIL=0 <span class="dim">…</span>

<span class="cmd">sqb recall query --backend warehouse &quot;SELECT r.revenue_date, r.total_revenue_cents,
p.payment_id, p.amount_cents FROM prod.daily_revenue r JOIN prod.stg_payments p
ON CAST(p.paid_at AS DATE) = r.revenue_date WHERE p.amount_cents &lt; 0&quot;</span>
revenue_date <span class="dim">|</span> total_revenue_cents <span class="dim">|</span> payment_id <span class="dim">|</span> amount_cents
2026-04-03 <span class="dim">|</span> <span class="warn">-1250</span> <span class="dim">|</span> 9 <span class="dim">|</span> <span class="warn">-2200</span></pre>
<span class="cmd">sqb recall query --backend warehouse &quot;SELECT payment_id, order_id, amount_cents, paid_at
FROM prod.stg_payments WHERE amount_cents &lt; 0&quot;</span>
payment_id <span class="dim">|</span> order_id <span class="dim">|</span> amount_cents <span class="dim">|</span> paid_at
9 <span class="dim">|</span> 8 <span class="dim">|</span> <span class="warn">-2200</span> <span class="dim">|</span> 2026-04-03 15:42:00</pre>
</div>
</div>
<p class="caption">
Real output from SQLBuild's example project, trimmed to the relevant lines. During a migration the old
table is never modified, archives can be renamed back until they expire, and every move is recorded.
In step 09 the audit started warning on the latest run, the build still finished, and the bad
row is still in prod: a refund recorded as a negative payment. Three queries, no log digging.
In step 09 the audit started warning on the latest run, the build still exited 0, and the cause
is still in prod: a refund recorded as a negative payment. Three commands, no log digging.
History stays in a SQLite file in your project, or in ClickHouse for a team. No service, no
account, no paid tier.
<a href="/docs/concepts/models/migrations/">How migrations work</a> ·
Expand Down
39 changes: 20 additions & 19 deletions website/src/content/docs/docs/concepts/observability/recall.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,25 +13,28 @@ The waffle shop example's `daily_revenue` model has an audit, `revenue_is_non_ne
severity. One night the payments feed starts recording a refund as a negative payment. The unit tests
still pass, because they run on mocked data. The build finishes with a warning that nobody reads.

The next morning, ask when the audit started failing:
The next morning, ask when the audit started failing, and what each of those builds reported:

```bash
sqb recall query --format table \
"SELECT invocation_started_at AS run, outcome, violation_count FROM audit_results
WHERE audit_name = 'revenue_is_non_negative' ORDER BY run DESC LIMIT 3"
"SELECT a.invocation_started_at AS run, a.outcome, a.violation_count, i.status, i.exit_code
FROM audit_results a JOIN invocations i USING (invocation_id)
WHERE a.audit_name = 'revenue_is_non_negative' ORDER BY run DESC LIMIT 3"
```

```
run | outcome | violation_count
--------------------------- | ------- | ---------------
2026-10-20T00:01:44.784683Z | warn | 1
2026-10-20T00:00:34.652468Z | pass | 0
2026-10-19T23:59:23.827831Z | pass | 0
run | outcome | violation_count | status | exit_code
--------------------------- | ------- | --------------- | --------- | ---------
2026-10-20T00:01:44.784683Z | warn | 1 | completed | 0
2026-10-20T00:00:34.652468Z | pass | 0 | completed | 0
2026-10-19T23:59:23.827831Z | pass | 0 | completed | 0

3 rows
```

See what that run printed, exactly as the scheduler saw it:
The audit started warning on the latest build, and that build still exited 0, so nothing alerted.

See what that build printed, exactly as the scheduler saw it:

```bash
sqb recall output last --tail 4
Expand All @@ -44,26 +47,24 @@ sqb recall output last --tail 4
✓ Completed with warnings PASS=89 WARN=1 FAIL=0 INSUFFICIENT=0 SKIP=0 TOTAL=90 (3.08s)
```

Then check what is true in the warehouse now, with the same command:
Then check what is true in the warehouse now, with `sqb recall query` again:

```bash
sqb recall query --backend warehouse --format table \
"SELECT r.revenue_date, r.total_revenue_cents, p.payment_id, p.amount_cents
FROM prod.daily_revenue r JOIN prod.stg_payments p
ON CAST(p.paid_at AS DATE) = r.revenue_date
WHERE p.amount_cents < 0"
"SELECT payment_id, order_id, amount_cents, paid_at FROM prod.stg_payments WHERE amount_cents < 0"
```

```
revenue_date | total_revenue_cents | payment_id | amount_cents
------------ | ------------------- | ---------- | ------------
2026-04-03 | -1250 | 9 | -2200
payment_id | order_id | amount_cents | paid_at
---------- | -------- | ------------ | -------------------
9 | 8 | -2200 | 2026-04-03 15:42:00

1 row
```

The bad row is still in prod, and payment 9 explains it. A coding agent can follow the same steps:
every answer is a SQL query over the [views](#querying-history), with the same output in `--json`.
Payment 9 is a refund recorded as a negative payment, and it is still in prod. A coding agent can
follow the same steps: the history is SQL over the [views](#querying-history), and every query can
return `--json`.

## What is recorded

Expand Down
Loading