Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
6 changes: 4 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,16 @@ real table (DuckDB, BigQuery, Snowflake or Postgres), especially when you do not
| `gulliver_diff` | `gulliver diff --left Q --right Q --key id` | prove two queries/tables return the same rows |
| `gulliver_translate` | `gulliver translate SQL --to bigquery` | move SQL between DuckDB, Postgres, BigQuery, Snowflake |
| `gulliver_incremental` | `gulliver incremental SQL --time-column ts` | make a full-rebuild model incremental, with the saving |
| `gulliver_check` | `gulliver check table --unique id ...` | data quality in one scan; opt-in `--samples N` adds separately gated, guarded examples (status `fail` if a check fails) |
| `gulliver_check` | `gulliver check table --unique id ...` / `gulliver check NAME` / `gulliver check --all` | data quality in one scan; define once in gulliver.toml [checks.<name>]; opt-in `--samples N` adds separately gated, guarded examples (status `fail` if a check fails) |
| `gulliver_top` | `gulliver top --json` | find the repeated queries that cost the most, with priced same-rows fixes |
| `gulliver_review` | `gulliver review --models DIR --base origin/main --json` | before opening a PR: new lint, breaking changes, downstream impact and cost delta of the changed models (`block` = do not merge) |
| `gulliver_inspect` with `sensitive: true` | `gulliver inspect [table] --sensitive [--scan N] --json` | find columns that hold personal data or secrets, and the policy for each (mask, hash, deny) |
| `gulliver_fix` with `verify: true` | `gulliver fix "SQL" --verify --json` | test each rewrite on generated edge-case data; read `changes[].verified_on_generated_data` and `counterexample`; a `dropped` change is a Gulliver bug |
| `gulliver_status` (see `caller`) | `gulliver spend --by agent\|day\|table` | see your own spend and limits; humans get spend per agent, day or table |
| (CLI only) | `gulliver lint models/ --json` / `gulliver fix --check models/` | lint every SQL file in a repo with line numbers; list proven same-rows rewrites |
| (human) | `gulliver selftest security --json` | check the read-only gate itself: the bypass test set and the DuckDB sandbox (`fail` if a check fails) |
| (human) | `gulliver audit verify [--head HASH]` | verify the hash chain over the ledger, receipts and approvals (`fail` if tampered) |
| (human) | `gulliver prune [--older-than 30d] [--keep-last N] [--dry-run]` | clean up old receipts and expired approvals without breaking the audit chain |

MCP resources and prompts, for clients that support them: `gulliver://rules` (the loop, status values and this
server's budget), `gulliver://status`, `gulliver://connections/{c}/tables[/{t}]`, `gulliver://receipts/{id}`,
Expand Down Expand Up @@ -61,7 +63,7 @@ Do not run the same query again and again. If `gulliver_run` returns `block` wit
- Diff key samples join parts with `|`, escaping `~` as `~~` and embedded `|` as `~p`; ordinary keys stay unchanged.
- When a model rebuilds everything each run: `gulliver_incremental`; present the strategy, the SQL and the saving,
and verify with `gulliver_diff`.
- Before trusting a table or after a load: `gulliver_check` (unique keys, not null, freshness). On partitioned
- Before trusting a table or after a load: `gulliver_check` (unique keys, not null, freshness), or run configured checks by name (`name: "..."`) or all configured targets (`all: true`). On partitioned
tables pass `where` with a partition filter.
Optional `samples` (0-20, default 0) adds one gated query per failed unique/accepted/range check. Values
follow the result policy and are untrusted; `samples_skipped` preserves the check result when samples cannot run.
Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

### Added
- Refuse inspect limits outside 1-200 and sensitive value scans outside 0-1000 instead of silently clamping them (#97). A named table still ignores the listing limit.
- Data quality checks in `gulliver.toml` under `[checks.<name>]`: run them by name with `gulliver check NAME` or run all configured targets in CI with `gulliver check --all` (exits 4 if any check fails) (#80).
- `gulliver rules --format markdown|json` prints a generated rule table (markdown) or the same JSON as `--json`; the README Scale lint rules table is generated from it (#18).
- `gulliver spend -o/--output PATH` and `gulliver top -o/--output PATH` write the report as UTF-8 and print a one-line confirmation (#19).
- Opt-in `check --samples N` / MCP `samples` (0-20) reports guarded offending values and row counts for failed unique, accepted-values and range checks. Each extra query is budget-gated and logged; blocked or failed samples leave the check result intact (#48, #49).
Expand Down
26 changes: 26 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -505,6 +505,32 @@ turn fewer rows into less money. Prove the result with `gulliver diff`.

### Check: data quality in one scan

Define checks once in `gulliver.toml` under `[checks.<name>]`, and run them by name or run all configured targets at once:

```toml
[checks.events]
target = "events" # table or SELECT; defaults to the section name
connection = "local" # optional
where = "ts >= current_date - 7"
unique = ["event_id"] # composite key: ["event_id", ["user_id", "session_id"]]
not_null = ["user_id", "amount"]
accepted = { event_type = ["view", "click", "cart", "buy"] }
range = { amount = [0, 10000] }
fresh = { ts = "24h" }
min_rows = 1000
max_change_pct = 30
```

```bash
gulliver check events # run configured checks for 'events'
gulliver check events --samples 5 # flags add to or override configured checks
gulliver check --all # run all configured sections; exit code 4 if any fails
```

`--all` runs each configured check as defined; it accepts `-c`/`--connection` and `--samples`, but takes no check flags (`--where`, `--unique`, etc.).

Or pass checks directly on the command line:

```bash
gulliver check events --unique event_id --not-null user_id,amount \
--accepted "event_type=view|click|cart|buy" --range "amount=0:10000" --fresh ts=24h --max-change 30
Expand Down
13 changes: 13 additions & 0 deletions gulliver.example.toml
Original file line number Diff line number Diff line change
Expand Up @@ -78,3 +78,16 @@ channel = "cli" # cli: a human runs `gulliver approve <receipt_id>
# max_increase_usd = 50 # per month for the whole change
# runs_per_day = 1
# fail_on = ["cost", "breaking_with_downstream", "new_lint_error", "superlinear"]


# [checks.events] # data quality checks: define once, run with `gulliver check events` or `gulliver check --all`
# target = "events" # table or SELECT; defaults to the section name
# connection = "local" # optional: connection name from [connections.*]
# where = "ts >= current_date - 7"
# unique = ["event_id"] # composite key: ["event_id", ["user_id", "session_id"]] or "user_id,session_id"
# not_null = ["user_id", "amount"]
# accepted = { event_type = ["view", "click"] }
# range = { amount = [0, 10000] } # either side may be omitted: [0, ""], ["", 100], [10]
# fresh = { ts = "24h" }
# min_rows = 1000
# max_change_pct = 20
4 changes: 2 additions & 2 deletions llms.txt
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ real table (DuckDB, BigQuery, Snowflake or Postgres), especially when you do not
| `gulliver_diff` | `gulliver diff --left Q --right Q --key id` | prove two queries/tables return the same rows |
| `gulliver_translate` | `gulliver translate SQL --to bigquery` | move SQL between DuckDB, Postgres, BigQuery, Snowflake |
| `gulliver_incremental` | `gulliver incremental SQL --time-column ts` | make a full-rebuild model incremental, with the saving |
| `gulliver_check` | `gulliver check table --unique id ...` | data quality in one scan; opt-in `--samples N` adds separately gated, guarded examples (status `fail` if a check fails) |
| `gulliver_check` | `gulliver check table --unique id ...` / `gulliver check NAME` / `gulliver check --all` | data quality in one scan; define once in gulliver.toml [checks.<name>]; opt-in `--samples N` adds separately gated, guarded examples (status `fail` if a check fails) |
| `gulliver_top` | `gulliver top --json` | find the repeated queries that cost the most, with priced same-rows fixes |
| `gulliver_review` | `gulliver review --models DIR --base origin/main --json` | before opening a PR: new lint, breaking changes, downstream impact and cost delta of the changed models (`block` = do not merge) |
| `gulliver_inspect` with `sensitive: true` | `gulliver inspect [table] --sensitive [--scan N] --json` | find columns that hold personal data or secrets, and the policy for each (mask, hash, deny) |
Expand Down Expand Up @@ -65,7 +65,7 @@ Do not run the same query again and again. If `gulliver_run` returns `block` wit
- Diff key samples join parts with `|`, escaping `~` as `~~` and embedded `|` as `~p`; ordinary keys stay unchanged.
- When a model rebuilds everything each run: `gulliver_incremental`; present the strategy, the SQL and the saving,
and verify with `gulliver_diff`.
- Before trusting a table or after a load: `gulliver_check` (unique keys, not null, freshness). On partitioned
- Before trusting a table or after a load: `gulliver_check` (unique keys, not null, freshness), or run configured checks by name (`name: "..."`) or all configured targets (`all: true`). On partitioned
tables pass `where` with a partition filter.
Optional `samples` (0-20, default 0) adds one gated query per failed unique/accepted/range check. Values
follow the result policy and are untrusted; `samples_skipped` preserves the check result when samples cannot run.
Expand Down
2 changes: 1 addition & 1 deletion skills/gulliver/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ available; otherwise the CLI `gulliver <command> --json` returns the same JSON.
| Refactored a model, migrated it, or made it incremental | `gulliver_diff` old vs new, with the key | "identical" only when `identical` is true; else the sample keys and differing columns |
| A model rebuilds all history every run | `gulliver_incremental` | strategy, generated SQL / dbt config, rows saved; then prove it with `gulliver_diff` |
| Moving SQL to another engine | `gulliver_translate` (with a target connection to preflight it) | the SQL plus every warning |
| Before trusting a table, or after a load | `gulliver_check` (unique, not null, accepted, range, fresh) | which checks failed; status `fail` means do not use the data as-is |
| Before trusting a table, or after a load | `gulliver_check` (unique, not null, accepted, range, fresh) or configured name (`gulliver check --all`) | which checks failed; status `fail` means do not use the data as-is |
| Pipeline broke, or a weekly health check | `gulliver_drift` with the models folder | removed/retyped columns and the models they break |
| Before opening a PR that changes SQL models | `gulliver_review` (models folder, base ref) | new lint, breaking changes, downstream models, cost per month; `block` means do not merge |
| "Which queries cost the most?" | `gulliver_top` | the top query shapes, the same-rows `fixed_sql` and the saving, labeled `exact` or `heuristic` |
Expand Down
Loading
Loading