;
};
## Getting Started
Make sure to first [set up your PlanetScale developer environment](/docs/cli/planetscale-environment-setup). 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), [Vitess](/docs/vitess/monitoring/query-insights), or [Neki](/docs/neki/monitoring/query-insights).
**Usage:**
```bash theme={null}
pscale insights [] --org
```
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 ` | Organization name **(required)** |
| `-f`, `--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 --org
```
**Available flags:**
| **Flag** | **Description** |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--sort ` | Metric to rank by. One of: `totalTime`, `count`, `errorCount`, `rowsRead`, `rowsReturned`, `rowsAffected`, `rowsReadPerReturned`, `p50Latency`, `p99Latency`, `maxLatency`, `cpuTime`, `ioTime`, `lastRun`. Default: `totalTime`. |
| `--dir ` | Sort direction: `asc` or `desc`. Default: `desc`. |
| `--limit ` | Number of queries to return. Default: `15`. |
| `--period ` | Time period to aggregate over (for example `1h`, `24h`). |
**Examples:**
```bash theme={null}
pscale insights queries --org
pscale insights queries --org --sort rowsReadPerReturned
pscale insights queries --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 --org --keyspace
```
**Available flags:**
| **Flag** | **Description** |
| --------------------- | ---------------------------------------------------------------- |
| `--keyspace ` | Keyspace for the fingerprint (required; from `insights queries`) |
| `--limit ` | Number of samples to return. Default: `25`. |
| `--period ` | Time period to look back (for example `1h`, `1d`). |
**Example:**
```bash theme={null}
pscale insights queries samples --org --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 --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 ` | Keyspace for the fingerprint (required; from `insights queries`) |
| `--period ` | Named time period to summarize (for example `1h`, `12h`, or `1d`) |
| `--from ` | Start of a custom time range as an ISO 8601 timestamp (use with `--to`) |
| `--to ` | 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 --org --keyspace
pscale insights queries summary --org --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 ` | Keyspace for the fingerprint (from `insights queries`) |
| `--page ` | Page of results to fetch. |
| `--per-page ` | Number of results per page. Default: `25`. |
```bash theme={null}
pscale insights queries traffic-budgets --org --keyspace
```
### The `errors` sub-command
List failing query patterns with error messages.
**Usage:**
```bash theme={null}
pscale insights errors --org
```
**Available flags:**
| **Flag** | **Description** |
| --------------------- | -------------------------------------------------------- |
| `--limit ` | Number of errors to return. Default: `15`. |
| `--period ` | Time period to aggregate over (for example `1h`, `24h`). |
**Example:**
```bash theme={null}
pscale insights errors --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 ` | Number of queries to return. Default: `25`. |
| `--period ` | Time period to look back (for example `1h`, `1d`). |
```bash theme={null}
pscale insights errors show --org
pscale insights errors show --org --period 1h --limit 50
```
### The `anomalies` sub-command
List detected resource anomalies for a branch.
**Usage:**
```bash theme={null}
pscale insights anomalies --org
```
#### `anomalies show`
Show one anomaly from `insights anomalies`, along with the queries whose activity correlates with it.
```bash theme={null}
pscale insights anomalies show --org
```
### The `tags` sub-command
List query tag keys from sqlcommenter / system tags on a branch.
**Usage:**
```bash theme={null}
pscale insights tags --org
```
**Available flags:**
| **Flag** | **Description** |
| --------------------- | ----------------------------------------------------------- |
| `--period ` | Time period to look back (for example `1h`, `1d`). |
| `--fingerprint ` | Only tags seen on this query fingerprint. |
| `--keyspace ` | Filter tags to a keyspace. |
| `--limit ` | Number of top values to show in human output. Default: `3`. |
**Example:**
```bash theme={null}
pscale insights tags --org --format json
```
#### `tags show`
Show a query tag key and its values.
```bash theme={null}
pscale insights tags show --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 --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 --org
```
**Example:**
```bash theme={null}
pscale insights recommendations --org --format json
```
#### `recommendations show`
Show a single schema recommendation, including the full ready-to-apply DDL. `` is the recommendation sequence number from `pscale insights recommendations`, the same value used by `recommendations dismiss`.
```bash theme={null}
pscale insights recommendations show --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 --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
## 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.