Skip to main content

# kater explore card preview

Runs one card on the warehouse and waits for its chart.

{/* Written by apps/landing-page/scripts/docs/write_cli_reference.py from the kater CLI's own help and scripts/docs/cli-reference.md. Do not edit it by hand: change those, then run the script. */}

While it waits, it reports each change of state. Then it gives the chart's rows and what they show.

## Examples

```bash
# Run the card in card.json and wait for its chart
kater explore card preview --request-file card.json
# Run several cards at once, from cards.json
kater explore card preview-all --request-file cards.json
```

## Options

<div class="cli-options">

| Option | Description |
| --- | --- |
| `--request-file <file>` | Required. The card as JSON, from a file. `-` reads stdin. It holds `namespace` and `card`, as [Cards](https://kater.ai/docs/cli-reference/explore/#cards) says. Add `"refresh": true` to run the card again, even when its rows are fresh in the result store. |

</div>

It also takes the [global options](https://kater.ai/docs/cli-reference/global-options/) `--json`, `--kater-root`, `--scope` and `--help`.

## Where the rows come from

A preview reads the result store first. When anyone ran the same query with the same inputs and its rows are still fresh, those rows come back. Otherwise, the card runs on the warehouse. `"refresh": true` always runs it again.

## States and failures

The progress lines print as the command works, each as the card's id and its state: `queued`, `compiling`, `waiting` or `running`. The answer ends as `complete`, `failed` or `cancelled`. A failed preview gives `failure`, whose `code` says what went wrong:

- **`compile_refused`.** The compiler refused the card's query or chart. `diagnostics` gives its reasons.
- **`preview_capacity` and `snapshot_cache_full`.** The server is busy. Preview the card again shortly.
- **`preview_expired`.** The result was released before it was read. Preview the card again.
- **`preview_timeout`.** The warehouse ran past the preview's time limit.
- **`dependency_changed`.** The model changed while the preview ran. Preview the card again.

## See also

- [`kater explore card`](https://kater.ai/docs/cli-reference/explore/card/)
- [All commands](https://kater.ai/docs/cli-reference/kater/)

On this page

Examples
Options
Where the rows come from
States and failures
See also

Kater CLI Explore and try ideas explore card

kater explore card preview

Runs one card on the warehouse and waits for its chart.

While it waits, it reports each change of state. Then it gives the chart’s rows and what they show.

Examples

# Run the card in card.json and wait for its chart
kater explore card preview --request-file card.json
# Run several cards at once, from cards.json
kater explore card preview-all --request-file cards.json

Options

Option	Description
`--request-file <file>`	Required. The card as JSON, from a file. `-` reads stdin. It holds `namespace` and `card`, as Cards says. Add `"refresh": true` to run the card again, even when its rows are fresh in the result store.

It also takes the global options --json, --kater-root, --scope and --help.

Where the rows come from

A preview reads the result store first. When anyone ran the same query with the same inputs and its rows are still fresh, those rows come back. Otherwise, the card runs on the warehouse. "refresh": true always runs it again.

States and failures

The progress lines print as the command works, each as the card’s id and its state: queued, compiling, waiting or running. The answer ends as complete, failed or cancelled. A failed preview gives failure, whose code says what went wrong:

compile_refused. The compiler refused the card’s query or chart. diagnostics gives its reasons.
preview_capacity and snapshot_cache_full. The server is busy. Preview the card again shortly.
preview_expired. The result was released before it was read. Preview the card again.
preview_timeout. The warehouse ran past the preview’s time limit.
dependency_changed. The model changed while the preview ran. Preview the card again.

See also