> ## Documentation Index
> Fetch the complete documentation index at: https://planetscale.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PlanetScale CLI commands: insights

Vitess, Neki, and Postgres

## Getting Started

Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup.md). Once you've installed the `pscale` CLI, you can interact with PlanetScale and manage your databases straight from the command line.

## The `insights` command

Surface PlanetScale's server-side analysis of a database: aggregated query statistics, failing query patterns, resource anomalies, and schema recommendations, all computed from production traffic.

For live, connection-level diagnostics (table sizes, locks, running queries), use [`pscale inspect`](/docs/cli/inspect) instead.

Query insights require Query Insights to be enabled for the database. See [Postgres](/docs/postgres/monitoring/query-insights.md), [Vitess](/docs/vitess/monitoring/query-insights.md), or [Neki](/docs/neki/monitoring/query-insights.md).

**Usage:**

```bash theme={null}
pscale insights <sub-command> <database> [<branch>] --org <org> <FLAG>
```

Place **positional arguments first**, then flags. **`--org` is required.**

### Available sub-commands

| **Sub-command** | **Product** | **Description** |
| :- | :- | :- |
| `queries` | Postgres, Vitess, Neki | List top queries ranked by a performance metric |
| `queries samples` | Postgres, Vitess, Neki | List recent executions for a query fingerprint |
| `queries show` | Postgres, Vitess, Neki | Show one query execution by sample ID |
| `queries summary` | Postgres, Vitess, Neki | Show aggregate statistics for a query fingerprint |
| `queries traffic-budgets` | Postgres, Vitess | List traffic budgets that affect a query fingerprint |
| `errors` | Postgres, Vitess, Neki | List queries that are failing with errors |
| `errors show` | Postgres, Vitess, Neki | List the individual query executions that failed with an error fingerprint |
| `anomalies` | Postgres, Vitess, Neki | List detected resource anomalies (CPU, memory, IOPS, rows read/written) |
| `anomalies show` | Postgres, Vitess, Neki | Show one anomaly and the queries correlated with it |
| `tags` | Postgres, Vitess, Neki | List query tag keys (sqlcommenter / system) |
| `tags show` | Postgres, Vitess, Neki | Show a query tag key and its values |
| `tags summaries` | Postgres, Vitess, Neki | List query statistics grouped by tag keys |
| `recommendations` | Postgres, Vitess, Neki | List schema recommendations with ready-to-apply DDL |
| `recommendations show` | Postgres, Vitess, Neki | Show one schema recommendation and its full DDL |
| `recommendations dismiss` | Postgres, Vitess, Neki | Dismiss a schema recommendation |

### Available flags

| **Flag** | **Description** |
| - | - |
| `--org <org>` | Organization name **(required)** |
| `-f`, `--format <FORMAT>` | Show output in a specific format. Possible values: `human` (default), `json`, `csv`. |
| `-h`, `--help` | Help for `insights` |

## Examples

### The `queries` sub-command

List the top queries for a branch, ranked by cumulative execution time (default).

**Usage:**

```bash theme={null}
pscale insights queries <database> <branch> --org <org> <FLAG>
```

**Available flags:**

| **Flag** | **Description** |
| - | - |
| `--sort <metric>` | Metric to rank by. One of: `totalTime`, `count`, `errorCount`, `rowsRead`, `rowsReturned`, `rowsAffected`, `rowsReadPerReturned`, `p50Latency`, `p99Latency`, `maxLatency`, `cpuTime`, `ioTime`, `lastRun`. Default: `totalTime`. |
| `--dir <direction>` | Sort direction: `asc` or `desc`. Default: `desc`. |
| `--limit <n>` | Number of queries to return. Default: `15`. |
| `--period <duration>` | Time period to aggregate over (for example `1h`, `24h`). |

**Examples:**

```bash theme={null}
pscale insights queries <database> <branch> --org <org>
pscale insights queries <database> <branch> --org <org> --sort rowsReadPerReturned
pscale insights queries <database> <branch> --org <org> --sort p99Latency --period 1h --format json
```

### The `queries samples` sub-command

List recent executions for a specific query fingerprint. Use the fingerprint from `pscale insights queries`. `--keyspace` is required.

**Usage:**

```bash theme={null}
pscale insights queries samples <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> <FLAG>
```

**Available flags:**

| **Flag** | **Description** |
| - | - |
| `--keyspace <name>` | Keyspace for the fingerprint (required; from `insights queries`) |
| `--limit <n>` | Number of samples to return. Default: `25`. |
| `--period <duration>` | Time period to look back (for example `1h`, `1d`). |

**Example:**

```bash theme={null}
pscale insights queries samples <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> --format json
```

`queries show` takes an individual execution/sample `id` from `queries samples`. `queries samples` and `queries summary` take a query `fingerprint`. These identifiers are not interchangeable.

### The `queries show` sub-command

Show one query execution using an ID returned by `pscale insights queries samples`.

```bash theme={null}
pscale insights queries show <database> <branch> <query-id> --org <org>
```

### The `queries summary` sub-command

Show aggregate statistics for a fingerprint from `pscale insights queries`. `--keyspace` is required (use the keyspace column from the queries list).

**Available flags:**

| **Flag** | **Description** |
| - | - |
| `--keyspace <name>` | Keyspace for the fingerprint (required; from `insights queries`) |
| `--period <duration>` | Named time period to summarize (for example `1h`, `12h`, or `1d`) |
| `--from <timestamp>` | Start of a custom time range as an ISO 8601 timestamp (use with `--to`) |
| `--to <timestamp>` | End of a custom time range as an ISO 8601 timestamp (use with `--from`) |

`--period` cannot be combined with `--from` and `--to`. Both range flags must be set together.

```bash theme={null}
pscale insights queries summary <database> <branch> <fingerprint> --org <org> --keyspace <keyspace>
pscale insights queries summary <database> <branch> <fingerprint> --org <org> --keyspace <keyspace> --period 1h
```

### The `queries traffic-budgets` sub-command

List traffic budgets that affect a query fingerprint. Pass `--keyspace` from the queries list. The command is paginated; pass `--page` for the next page instead of walking every page automatically.

**Available flags:**

| **Flag** | **Description** |
| - | - |
| `--keyspace <name>` | Keyspace for the fingerprint (from `insights queries`) |
| `--page <n>` | Page of results to fetch. |
| `--per-page <n>` | Number of results per page. Default: `25`. |

```bash theme={null}
pscale insights queries traffic-budgets <database> <branch> <fingerprint> --org <org> --keyspace <keyspace>
```

### The `errors` sub-command

List failing query patterns with error messages.

**Usage:**

```bash theme={null}
pscale insights errors <database> <branch> --org <org> <FLAG>
```

**Available flags:**

| **Flag** | **Description** |
| - | - |
| `--limit <n>` | Number of errors to return. Default: `15`. |
| `--period <duration>` | Time period to aggregate over (for example `1h`, `24h`). |

**Example:**

```bash theme={null}
pscale insights errors <database> <branch> --org <org> --format json
```

#### `errors show`

List the individual executions that failed with an error fingerprint, including the users, keyspaces, and
statements involved. Use the fingerprint column from `insights errors` (`error_fingerprint` in JSON), not
the truncated id.

**Available flags:**

| **Flag** | **Description** |
| - | - |
| `--limit <n>` | Number of queries to return. Default: `25`. |
| `--period <duration>` | Time period to look back (for example `1h`, `1d`). |

```bash theme={null}
pscale insights errors show <database> <branch> <fingerprint> --org <org>
pscale insights errors show <database> <branch> <fingerprint> --org <org> --period 1h --limit 50
```

### The `anomalies` sub-command

List detected resource anomalies for a branch.

**Usage:**

```bash theme={null}
pscale insights anomalies <database> <branch> --org <org> <FLAG>
```

#### `anomalies show`

Show one anomaly from `insights anomalies`, along with the queries whose activity correlates with it.

```bash theme={null}
pscale insights anomalies show <database> <branch> <anomaly-id> --org <org>
```

### The `tags` sub-command

List query tag keys from sqlcommenter / system tags on a branch.

**Usage:**

```bash theme={null}
pscale insights tags <database> <branch> --org <org> <FLAG>
```

**Available flags:**

| **Flag** | **Description** |
| - | - |
| `--period <duration>` | Time period to look back (for example `1h`, `1d`). |
| `--fingerprint <fp>` | Only tags seen on this query fingerprint. |
| `--keyspace <name>` | Filter tags to a keyspace. |
| `--limit <n>` | Number of top values to show in human output. Default: `3`. |

**Example:**

```bash theme={null}
pscale insights tags <database> <branch> --org <org> --format json
```

#### `tags show`

Show a query tag key and its values.

```bash theme={null}
pscale insights tags show <database> <branch> <tag> --org <org>
```

#### `tags summaries`

List query statistics grouped by one or more tag keys. `--tags` is required and repeatable.

```bash theme={null}
pscale insights tags summaries <database> <branch> --org <org> --tags username --tags app --format json
```

### The `recommendations` sub-command

List schema recommendations for a database: unused tables and indexes, duplicate indexes, bloated tables and indexes, missing indexes derived from production query patterns, and sequence overflow risks. Each recommendation includes ready-to-apply DDL in JSON output.

This sub-command takes a database name only (not a branch).

**Usage:**

```bash theme={null}
pscale insights recommendations <database> --org <org> <FLAG>
```

**Example:**

```bash theme={null}
pscale insights recommendations <database> --org <org> --format json
```

#### `recommendations show`

Show a single schema recommendation, including the full ready-to-apply DDL. `<number>` is the recommendation sequence number from `pscale insights recommendations`, the same value used by `recommendations dismiss`.

```bash theme={null}
pscale insights recommendations show <database> <number> --org <org>
```

#### `recommendations dismiss`

Dismiss a schema recommendation. Use the recommendation number from `pscale insights recommendations`. Interactive confirmation is required unless `--force` is passed.

```bash theme={null}
pscale insights recommendations dismiss <database> <number> --org <org> --force --reason "not applicable"
```

If the database or branch is not found, or Query Insights is not enabled, the command returns an error explaining both possible causes.

## Related documentation

> **[pscale inspect](/docs/cli/inspect.md)**

> **[Query Insights (Postgres)](/docs/postgres/monitoring/query-insights.md)**

> **[Query Insights (Vitess)](/docs/vitess/monitoring/query-insights.md)**

> **[Query Insights (Neki)](/docs/neki/monitoring/query-insights.md)**

> **[Anomalies (Neki)](/docs/neki/monitoring/anomalies.md)**

> **[Schema recommendations (Postgres)](/docs/postgres/monitoring/schema-recommendations.md)**

> **[Schema recommendations (Neki)](/docs/neki/monitoring/schema-recommendations.md)**

## Need help?

Get help from [the PlanetScale Support team](https://planetscale.com/contact?initial=support), or join our [Discord community](https://pscale.link/community) to see how others are using PlanetScale.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.