Skip to main content

# kater query label

Sets the label of one column that a saved query returns.

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

Kater writes the label into the query's SQL, such as `AS "Spend"`, and compiles the query again. The query's numbers do not change.

## Examples

```bash
# See the columns of spend_by_platform, each with its reference, and the query's revision
echo '{"source": {"model_type": "query", "namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "name": "spend_by_platform"}}' | kater chart describe --request-file -
# Set the label of one column, with the request in label.json
kater query label --request-file label.json
```

## 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

| Key | What it holds |
| --- | --- |
| `source` | The query, such as `{"model_type": "query", "namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "name": "spend_by_platform"}`. |
| `field` | The column, as the `reference` that [`kater chart describe`](https://kater.ai/docs/cli-reference/chart/describe/) gives for it. Copy it as it is. |
| `label` | The new label, from 1 to 256 characters. |
| `expected_revision` | The query's `sourceRevision` from `kater chart describe`. |
| `inputs` | Parameter values and the filters to turn on, as in a run's inputs: `parameters` and `filters`. |
| `snapshot_id` | The id of rows already read for the query. The answer gives those rows back with the new label. |

## When Kater refuses it

- The query changed since `kater chart describe` gave its revision.
- The query has edits in an editor that are not saved.
- The label cannot be written without a change to the query's compiled SQL.

## 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
When Kater refuses it
See also

Kater CLI Build an analysis query

kater query label

Sets the label of one column that a saved query returns.

Kater writes the label into the query’s SQL, such as AS "Spend", and compiles the query again. The query’s numbers do not change.

Examples

# See the columns of spend_by_platform, each with its reference, and the query's revision
echo '{"source": {"model_type": "query", "namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "name": "spend_by_platform"}}' | kater chart describe --request-file -
# Set the label of one column, with the request in label.json
kater query label --request-file label.json

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

Key	What it holds
`source`	The query, such as `{"model_type": "query", "namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "name": "spend_by_platform"}`.
`field`	The column, as the `reference` that `kater chart describe` gives for it. Copy it as it is.
`label`	The new label, from 1 to 256 characters.
`expected_revision`	The query’s `sourceRevision` from `kater chart describe`.
`inputs`	Parameter values and the filters to turn on, as in a run’s inputs: `parameters` and `filters`.
`snapshot_id`	The id of rows already read for the query. The answer gives those rows back with the new label.

When Kater refuses it

The query changed since kater chart describe gave its revision.
The query has edits in an editor that are not saved.
The label cannot be written without a change to the query’s compiled SQL.

See also