Skip to content

Commit c4e486a

Browse files
rmlovelandrmloveland
committed
Add docs on INSPECT statement for v26.1
Fixes: - DOC-14957 - DOC-11405 - DOC-15189 - DOC-14628 - DOC-15695 - DOC-15046 Summary of changes: - Add docs for `INSPECT` statement - Add docs for `SHOW INSPECT ERRORS` statement - Add the above to the list of SQL statements - Update various privileges- and jobs-related docs
1 parent 2f74c6d commit c4e486a

6 files changed

Lines changed: 216 additions & 2 deletions

File tree

‎src/current/_includes/v26.1/sql/privileges.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ Privilege | Levels | Description
1717
`EXTERNALCONNECTION` | System | Grants the ability to connect to external systems such as object stores, key management systems, Kafka feeds, or external file systems. Often used in conjunction with the `BACKUP`, `RESTORE`, and `CHANGEFEED` privilege.
1818
`EXTERNALIOIMPLICITACCESS` | System | Grants the ability to interact with external resources that require implicit access.
1919
`INSERT` | Table, Sequence | Grants the ability to insert objects at the table or sequence level.
20+
<a id="inspect"></a> `INSPECT` | System | Grants the ability to run the [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) statement and view results with [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %}).
2021
<a id="modifyclustersetting"></a>`MODIFYCLUSTERSETTING` | System | Grants the ability to modify [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}).
2122
`MODIFYSQLCLUSTERSETTING` | System | Grants the ability to modify SQL [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}) (cluster settings prefixed with `sql.`).
2223
`NOSQLLOGIN` | System | Prevents roles from connecting to the SQL interface of a cluster.

‎src/current/_includes/v26.1/ui/jobs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Column | Description
2828
----------|------------
2929
Description | SQL statement that created the job.
3030
Status | Current [job status](#job-status) or completion progress.
31-
Job ID | Unique job ID. This value is used to [pause]({{ link_prefix }}pause-job.html), [resume]({{ link_prefix }}resume-job.html), or [cancel]({{ link_prefix }}cancel-job.html) jobs.
31+
Job ID | Unique job ID. This value is used to [pause]({{ link_prefix }}pause-job.html), [resume]({{ link_prefix }}resume-job.html), or [cancel]({{ link_prefix }}cancel-job.html) jobs. For [`INSPECT`]({{ link_prefix }}inspect.html) jobs, you can use the Job ID with [`SHOW INSPECT ERRORS FOR JOB {id}`]({{ link_prefix }}show-inspect-errors.html).
3232
User Name | User that created the job.
3333
Creation Time (UTC) | Date and time the job was created.
3434
Last Modified Time (UTC) | Date and time the job was last modified.

‎src/current/v26.1/inspect.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
title: INSPECT
3+
summary: Use the INSPECT statement to run data consistency validation checks against tables or databases.
4+
toc: true
5+
docs_area: reference.sql
6+
---
7+
8+
The `INSPECT` [statement]({% link {{ page.version.version }}/sql-statements.md %}) runs a data consistency validation job against a table or database. The initial validation checks primary-to-secondary index consistency and records any errors.
9+
10+
{{site.data.alerts.callout_info}}
11+
`INSPECT` does not automatically repair errors.
12+
{{site.data.alerts.end}}
13+
14+
## Considerations
15+
16+
[XXX](XXX): DECIDE WHICH THINGS SHOULD GO IN KNOWN LIMITATIONS
17+
18+
- `INSPECT` always runs as a [background job]({% link {{ page.version.version }}/show-jobs.md %}).
19+
- `INSPECT` must be run in an implicit transaction. It cannot be run inside a multi-statement transaction. For more information, see [Run Multi-Statement Transactions]({% link {{ page.version.version }}/run-multi-statement-transactions.md %}).
20+
- `INSPECT` runs with low priority admission control and may take time on large datasets. Plan to run during periods of lower load.
21+
- Unsupported indexes (such as vector, partial, or expression indexes) are skipped when using the default `INDEX ALL` behavior. If an unsupported index is explicitly requested using `INDEX (...)`, the statement fails before starting.
22+
23+
## Required privileges
24+
25+
To run `INSPECT` and view its results, the user must have:
26+
27+
- The `INSPECT` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges).
28+
- The `VIEWSYSTEMTABLE` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) (required to view results via [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %})).
29+
30+
## Syntax
31+
32+
[XXX](XXX): ADD SQL DIAGRAM
33+
34+
~~~ sql
35+
INSPECT TABLE <table_name> [AS OF SYSTEM TIME <expr>] [WITH OPTIONS ( <option> [, ...] )] [DETACHED]
36+
37+
INSPECT DATABASE <database_name> [AS OF SYSTEM TIME <expr>] [WITH OPTIONS ( <option> [, ...] )] [DETACHED]
38+
~~~
39+
40+
## Parameters
41+
42+
Parameter | Description
43+
----------|------------
44+
`table_name` | The table to inspect.
45+
`database_name` | The database to inspect.
46+
`AS OF SYSTEM TIME <expr>` | Optional. Run inspection against a historical read timestamp. For details, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
47+
`WITH OPTIONS (...)` | Optional. Controls which indexes are inspected. See [Options](#options).
48+
`DETACHED` | Optional. Run the inspection job asynchronously and return the job ID without waiting for completion. To monitor progress, use [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %}).
49+
50+
### Options
51+
52+
Option | Description
53+
-------|------------
54+
`INDEX ALL` | Inspect all supported indexes in the target table or database. This is the default.
55+
`INDEX (<indexname> [, ...])` | Inspect only the specified indexes. `INDEX ALL` and `INDEX (...)` are mutually exclusive.
56+
57+
## Viewing results
58+
59+
To view errors found by an inspection job, use [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %}). Errors are stored internally and may be subject to retention policies.
60+
61+
## Examples
62+
63+
### Inspect a table (all supported indexes)
64+
65+
{% include_cached copy-clipboard.html %}
66+
~~~ sql
67+
INSPECT TABLE movr.public.users;
68+
~~~
69+
70+
### Inspect a table for specific indexes
71+
72+
{% include_cached copy-clipboard.html %}
73+
~~~ sql
74+
INSPECT TABLE movr.public.users WITH OPTIONS (INDEX (users_pkey, users_name_idx));
75+
~~~
76+
77+
### Inspect at a specific timestamp
78+
79+
{% include_cached copy-clipboard.html %}
80+
~~~ sql
81+
INSPECT TABLE movr.public.users AS OF SYSTEM TIME '-10s';
82+
~~~
83+
84+
### Run an inspection job asynchronously
85+
86+
{% include_cached copy-clipboard.html %}
87+
~~~ sql
88+
INSPECT TABLE movr.public.users DETACHED;
89+
~~~
90+
91+
The job ID is returned after job creation completes:
92+
93+
~~~
94+
job_id
95+
----------------------
96+
592786066399264769
97+
(1 row)
98+
~~~
99+
100+
## Known limitations
101+
102+
[XXX](XXX): FILL IN KNOWN LIMITATIONS SECTION
103+
104+
## See also
105+
106+
- [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %})
107+
- [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %})
108+
- [Jobs page in DB Console]({% link {{ page.version.version }}/ui-jobs-page.md %})
109+
- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
110+
- [Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %})
111+
- [INSPECT privilege](XXX)

‎src/current/v26.1/show-inspect-errors.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
title: SHOW INSPECT ERRORS
3+
summary: The SHOW INSPECT ERRORS statement lists issues detected by the INSPECT data consistency checker.
4+
toc: true
5+
docs_area: reference.sql
6+
---
7+
8+
The `SHOW INSPECT ERRORS` [statement]({% link {{ page.version.version }}/sql-statements.md %}) displays issues detected by [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) data consistency validation jobs.
9+
10+
By default, `SHOW INSPECT ERRORS` returns errors from the most recent completed and successful `INSPECT` job for the specified table. To view errors from a specific inspection job, use `FOR JOB <id>`.
11+
12+
## Syntax
13+
14+
[XXX](XXX): ADD LINK TO SQL DIAGRAM
15+
16+
~~~ sql
17+
SHOW INSPECT ERRORS
18+
[FOR TABLE <table_name>]
19+
[FOR JOB <job_id>]
20+
[WITH DETAILS]
21+
~~~
22+
23+
## Parameters
24+
25+
Parameter | Description
26+
----------|------------
27+
`FOR TABLE <table_name>` | Show errors for the specified table.
28+
`FOR JOB <job_id>` | Show errors produced by the specified `INSPECT` job ID.
29+
`WITH DETAILS` | Include structured error metadata from the `details` column (JSON) in the results.
30+
31+
## Required privileges
32+
33+
To run `SHOW INSPECT ERRORS`, the user must have:
34+
35+
- The `INSPECT` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges).
36+
- The `VIEWSYSTEMTABLE` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges).
37+
38+
## Response
39+
40+
`SHOW INSPECT ERRORS` returns one row per detected issue.
41+
42+
Field | Description
43+
------|------------
44+
`job_id` | The ID of the `INSPECT` job that detected the issue.
45+
`error_type` | The type of inconsistency detected. See [Error types](#error-types).
46+
`aost` | The [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) timestamp used by the job (if any).
47+
`database_name` | The database containing the object with an issue.
48+
`schema_name` | The schema containing the object with an issue.
49+
`object_name` | The table or index with an issue.
50+
`primary_key` | The primary key of the row involved in the issue, if applicable.
51+
`details` | Present only with `WITH DETAILS`. Structured metadata (JSON) describing the issue.
52+
53+
### Error types
54+
55+
The initial `INSPECT` implementation reports the following `error_type` values:
56+
57+
Error type | Meaning
58+
----------|---------
59+
`secondary_index_missing` | A row in the primary index is missing a corresponding entry in a secondary index.
60+
`secondary_index_dangling` | A secondary index entry exists, but the referenced primary index row does not.
61+
62+
## Examples
63+
64+
### Show the latest errors for a table
65+
66+
{% include_cached copy-clipboard.html %}
67+
~~~ sql
68+
SHOW INSPECT ERRORS FOR TABLE movr.public.users;
69+
~~~
70+
71+
### Show errors for a specific inspection job
72+
73+
First, find the job ID (for example, by using [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %})):
74+
75+
{% include_cached copy-clipboard.html %}
76+
~~~ sql
77+
SHOW JOBS;
78+
~~~
79+
80+
Then show errors for that job:
81+
82+
{% include_cached copy-clipboard.html %}
83+
~~~ sql
84+
SHOW INSPECT ERRORS FOR JOB 592786066399264769;
85+
~~~
86+
87+
### Show errors with details
88+
89+
{% include_cached copy-clipboard.html %}
90+
~~~ sql
91+
SHOW INSPECT ERRORS FOR TABLE movr.public.users WITH DETAILS;
92+
~~~
93+
94+
## See also
95+
96+
- [`INSPECT`]({% link {{ page.version.version }}/inspect.md %})
97+
- [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %})
98+
- [Jobs page in DB Console]({% link {{ page.version.version }}/ui-jobs-page.md %})
99+
- [Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %})
100+
- [XXX](XXX): LINK TO EXACT INSPECT PRIVILEGES

‎src/current/v26.1/show-jobs.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ The following fields are returned for each job:
6161
Field | Description
6262
------|------------
6363
`job_id` | A unique ID to identify each job. This value is used if you want to control jobs (i.e., [pause]({% link {{ page.version.version }}/pause-job.md %}), [resume]({% link {{ page.version.version }}/resume-job.md %}), or [cancel]({% link {{ page.version.version }}/cancel-job.md %}) it).
64-
`job_type` | The type of job: [`SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`NEW SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`KEY VISUALIZER`]({% link {{ page.version.version }}/ui-key-visualizer.md %}), [`MIGRATION`]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#overview), [`BACKUP`]({% link {{ page.version.version }}/backup.md %}), [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), [`IMPORT`]({% link {{ page.version.version }}/import-into.md %}), [`CHANGEFEED`](#show-changefeed-jobs), [`CREATE STATS`]({% link {{ page.version.version }}/create-statistics.md %}), [`ROW LEVEL TTL`]({% link {{ page.version.version }}/row-level-ttl.md %}), [`REPLICATION STREAM INGESTION`]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}), `REPLICATION STREAM PRODUCER`([physical cluster replication]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}) or [logical data replication]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %})), [`LOGICAL REPLICATION`]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %}). <br><br>For job types of automatic jobs, see [Show automatic jobs](#show-automatic-jobs).
64+
`job_type` | The type of job: [`SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`NEW SCHEMA CHANGE`]({% link {{ page.version.version }}/online-schema-changes.md %}), [`KEY VISUALIZER`]({% link {{ page.version.version }}/ui-key-visualizer.md %}), [`MIGRATION`]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#overview), [`BACKUP`]({% link {{ page.version.version }}/backup.md %}), [`RESTORE`]({% link {{ page.version.version }}/restore.md %}), [`IMPORT`]({% link {{ page.version.version }}/import-into.md %}), [`CHANGEFEED`](#show-changefeed-jobs), [`CREATE STATS`]({% link {{ page.version.version }}/create-statistics.md %}), [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}), [`ROW LEVEL TTL`]({% link {{ page.version.version }}/row-level-ttl.md %}), [`REPLICATION STREAM INGESTION`]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}), `REPLICATION STREAM PRODUCER`([physical cluster replication]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}) or [logical data replication]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %})), [`LOGICAL REPLICATION`]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %}). <br><br>For `INSPECT` jobs, you can use the `job_id` value with [`SHOW INSPECT ERRORS FOR JOB {job_id}`]({% link {{ page.version.version }}/show-inspect-errors.md %}). <br><br>For job types of automatic jobs, see [Show automatic jobs](#show-automatic-jobs).
6565
`description` | The statement that started the job, or a textual description of the job. When you run `SHOW JOBS`, the `description` field is limited to 100 characters. To view the full description for a job, run `SHOW JOB {job ID}`.
6666
`statement` | When `description` is a textual description of the job, the statement that started the job is returned in this column. Currently, this field is populated only for the automatic table statistics jobs.
6767
`user_name` | The name of the [user]({% link {{ page.version.version }}/security-reference/authorization.md %}#create-and-manage-users) who started the job.

‎src/current/v26.1/sql-statements.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,8 @@ Statement | Usage
5252
[`DROP TYPE`]({% link {{ page.version.version }}/drop-type.md %}) | Remove a user-defined, [enumerated data type]({% link {{ page.version.version }}/enum.md %}).
5353
[`DROP VIEW`]({% link {{ page.version.version }}/drop-view.md %})| Remove a view.
5454
[`REFRESH`]({% link {{ page.version.version }}/refresh.md %}) | Refresh the stored query results of a [materialized view]({% link {{ page.version.version }}/views.md %}#materialized-views).
55+
[`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) | Run data consistency validation checks against tables or databases. [XXX](XXX): CONFIRM THIS SHOULD GO HERE?
56+
[`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %}) | View issues detected by `INSPECT` data consistency validation jobs. [XXX](XXX): CONFIRM THIS SHOULD GO HERE?
5557
[`SHOW COLUMNS`]({% link {{ page.version.version }}/show-columns.md %}) | View details about columns in a table.
5658
[`SHOW CONSTRAINTS`]({% link {{ page.version.version }}/show-constraints.md %}) | List constraints on a table.
5759
[`SHOW CREATE`]({% link {{ page.version.version }}/show-create.md %}) | View the `CREATE` statement for a database, function, sequence, table, or view.

0 commit comments

Comments
 (0)