Skip to main content

# kater query sandbox

Opens a saved query in a new scratch file in your brainstorm folder.

{/* 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. */}

There you can try changes, and the query stays as it is. The scratch file keeps the query's SQL, its parameters and its chart, and reads the workspace by its full path.

## Examples

```bash
# Open the spend_by_platform query in a new scratch file, with the request in sandbox.json
kater query sandbox --request-file sandbox.json
# Send the same request on standard input
echo '{"namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "document": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting/query_contracts/spend_by_platform.sql"}, "title": "Spend by platform"}' | kater query sandbox --request-file -
```

## Arguments

<div class="cli-options">

| Argument | Description |
| --- | --- |
| `<path>` | Optional. In place of `--request-file`: the workspace, the query file or the chart file the request names. |

</div>

## Options

<div class="cli-options">

| Option | Description |
| --- | --- |
| `--request-file <file>` | The JSON request. `-` reads it from standard input. See [The request](#the-request). |

</div>

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

## The request

```json title="sandbox.json"
{"namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "document": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting/query_contracts/spend_by_platform.sql"}, "title": "Spend by platform"}
```

| Key | What it holds |
| --- | --- |
| `namespace` | The query's workspace, by its path from the content root. |
| `document` | The query's file, as `{"path": ...}` from the content root. |
| `title` | The statement's title in the scratch file. |
| `chart` | The chart as the page draws it. Its fields become the scratch file's chart. |

## What it answers

The answer gives the scratch file's `path`, the `statement` that holds the query, and its `range`. Run it with [`kater show`](https://kater.ai/docs/cli-reference/show/), with the file in `--select` and `--statement`. The workspace's fields and calculations stay in the workspace, so nothing is changed into fields of the shared model.

## See also

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

On this page

Examples
Arguments
Options
The request
What it answers
See also

Kater CLI Build an analysis query

kater query sandbox

Opens a saved query in a new scratch file in your brainstorm folder.

There you can try changes, and the query stays as it is. The scratch file keeps the query’s SQL, its parameters and its chart, and reads the workspace by its full path.

Examples

# Open the spend_by_platform query in a new scratch file, with the request in sandbox.json
kater query sandbox --request-file sandbox.json
# Send the same request on standard input
echo '{"namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "document": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting/query_contracts/spend_by_platform.sql"}, "title": "Spend by platform"}' | kater query sandbox --request-file -

Arguments

Argument	Description
`<path>`	Optional. In place of `--request-file`: the workspace, the query file or the chart file the request names.

Options

Option	Description
`--request-file <file>`	The JSON request. `-` reads it from standard input. See The request.

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

The request

{"namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "document": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting/query_contracts/spend_by_platform.sql"}, "title": "Spend by platform"}

Key	What it holds
`namespace`	The query’s workspace, by its path from the content root.
`document`	The query’s file, as `{"path": ...}` from the content root.
`title`	The statement’s title in the scratch file.
`chart`	The chart as the page draws it. Its fields become the scratch file’s chart.

What it answers

The answer gives the scratch file’s path, the statement that holds the query, and its range. Run it with kater show, with the file in --select and --statement. The workspace’s fields and calculations stay in the workspace, so nothing is changed into fields of the shared model.

See also