Skip to main content

# kater insight run

Runs one insight template over the result of a workspace query, as a dashboard's key takeaways do.

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

Name the template, and match each of its columns to a column of the query. It writes nothing.

## Examples

```bash
# Find whether one platform takes most of the spend
kater insight run --request-file largest_platform.json
# Make a request that calls a platform dominant at 40 percent of spend, and send it
jq '.parameters = {"dominance_share": 0.4}' largest_platform.json > largest_platform_40.json
kater insight run --request-file largest_platform_40.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 query, the template, and how their columns match, as JSON. Give `-` to read 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

| Field | What it holds |
| --- | --- |
| `namespace` | The workspace, by its full `path`. |
| `query` | The query, by its name, such as `spend_by_platform`. |
| `insight` | The template, by its name, such as `largest_segment`. |
| `columns` | Each column of the template, matched to a column of the query. |
| `parameters` | Optional. Values for the template's own parameters, such as `dominance_share`. |
| `inputs` | Optional. The query's parameter values and filters. |
| `fresh` | Optional. True runs the query on the warehouse again. |

The `largest_segment` template takes a `segment` column and a `value` column. This file matches them to `platform` and `sum__spend`:

```json title="largest_platform.json"
{"namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "query": "spend_by_platform", "insight": "largest_segment", "columns": {"segment": "platform", "value": "sum__spend"}}
```

## Templates

Kater's templates are in the connection's `modeling/.kater/insight_templates/`. A template of your own in `modeling/kater_objects/custom_insight_templates/` takes the place of Kater's template with the same name. The query must be in a workspace, and you need permission to run it. The query's own optional filters are on.

## See also

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

On this page

Examples
Arguments
Options
The request
Templates
See also

Kater CLI Present and share insight

kater insight run

Runs one insight template over the result of a workspace query, as a dashboard's key takeaways do.

Name the template, and match each of its columns to a column of the query. It writes nothing.

Examples

# Find whether one platform takes most of the spend
kater insight run --request-file largest_platform.json
# Make a request that calls a platform dominant at 40 percent of spend, and send it
jq '.parameters = {"dominance_share": 0.4}' largest_platform.json > largest_platform_40.json
kater insight run --request-file largest_platform_40.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 query, the template, and how their columns match, as JSON. Give `-` to read it from standard input. See The request.

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

The request

Field	What it holds
`namespace`	The workspace, by its full `path`.
`query`	The query, by its name, such as `spend_by_platform`.
`insight`	The template, by its name, such as `largest_segment`.
`columns`	Each column of the template, matched to a column of the query.
`parameters`	Optional. Values for the template’s own parameters, such as `dominance_share`.
`inputs`	Optional. The query’s parameter values and filters.
`fresh`	Optional. True runs the query on the warehouse again.

The largest_segment template takes a segment column and a value column. This file matches them to platform and sum__spend:

{"namespace": {"path": "connections/snowflake_prod_connection/workspaces/ad_reporting"}, "query": "spend_by_platform", "insight": "largest_segment", "columns": {"segment": "platform", "value": "sum__spend"}}

Templates

Kater’s templates are in the connection’s modeling/.kater/insight_templates/. A template of your own in modeling/kater_objects/custom_insight_templates/ takes the place of Kater’s template with the same name. The query must be in a workspace, and you need permission to run it. The query’s own optional filters are on.

See also