Skip to content

Commit cd3d914

Browse files
rmlovelandrmloveland
authored
Add docs on INSPECT statement for v26.1 (#22023)
* 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 927b971 commit cd3d914

7 files changed

Lines changed: 285 additions & 4 deletions

File tree

‎src/current/_includes/v26.1/sidebar-data/sql.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -484,6 +484,12 @@
484484
"/${VERSION}/insert.html"
485485
]
486486
},
487+
{
488+
"title": "<code>INSPECT</code>",
489+
"urls": [
490+
"/${VERSION}/inspect.html"
491+
]
492+
},
487493
{
488494
"title": "<code>JOIN</code>",
489495
"urls": [
@@ -700,6 +706,12 @@
700706
"/${VERSION}/show-index.html"
701707
]
702708
},
709+
{
710+
"title": "<code>SHOW INSPECT ERRORS</code>",
711+
"urls": [
712+
"/${VERSION}/show-inspect-errors.html"
713+
]
714+
},
703715
{
704716
"title": "<code>SHOW JOBS</code>",
705717
"urls": [

‎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: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ The Jobs list is designed for you to manage pending work. It is not intended to
88

99
Use the **Jobs** table to see recently created and completed jobs.
1010

11-
<img src="{{ 'images/v24.2/ui-jobs-page.png' | relative_url }}" alt="DB Console Jobs Page" style="border:1px solid #eee;max-width:100%" />
11+
<img src="{{ 'images/v26.1/ui-jobs-page.png' | relative_url }}" alt="DB Console Jobs Page" style="border:1px solid #eee;max-width:100%" />
1212

1313
### Filter jobs
1414

@@ -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.
@@ -66,7 +66,7 @@ The details show:
6666
- **User Name**
6767
- error messages (if any)
6868

69-
<img src="{{ 'images/v24.2/ui_jobs_page_details.png' | relative_url }}" alt="DB Console Jobs Page" style="border:1px solid #eee;max-width:100%" />
69+
<img src="{{ 'images/v26.1/ui_jobs_page_details.png' | relative_url }}" alt="DB Console Jobs Page" style="border:1px solid #eee;max-width:100%" />
7070

7171
## See also
7272

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

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
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 and records any errors it finds. To display errors recorded by an inspection job, use [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %}).
9+
10+
{{site.data.alerts.callout_info}}
11+
`INSPECT` is used to verify data integrity. It does not automatically repair errors.
12+
{{site.data.alerts.end}}
13+
14+
## Required privileges
15+
16+
To run `INSPECT` and view its results, the user must have:
17+
18+
- The `INSPECT` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges), which is required to run the `INSPECT` statement.
19+
20+
## Synopsis
21+
22+
<div>
23+
{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/inspect_table.html %}
24+
</div>
25+
26+
<div>
27+
{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/inspect_database.html %}
28+
</div>
29+
30+
## Parameters
31+
32+
Parameter | Description
33+
----------|------------
34+
`table_name` | The [table]({% link {{ page.version.version }}/create-table.md %}) to inspect.
35+
`db_name` | The [database]({% link {{ page.version.version }}/create-database.md %}) to inspect.
36+
`opt_as_of_clause` | Optional. Run the inspection against a historical read timestamp using `INSPECT ... AS OF SYSTEM TIME {expr}`. For an example, see [`INSPECT` at a specific timestamp](#inspect-at-a-specific-timestamp). For more information about historical reads, see [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}).
37+
`opt_inspect_options_clause` | Optional. Control which [indexes]({% link {{ page.version.version }}/indexes.md %}) are inspected using `INSPECT ... WITH OPTIONS (...)`. For an example, see [`INSPECT` a table for specific indexes](#inspect-a-table-for-specific-indexes). See [Options](#options).
38+
39+
### Options
40+
41+
Option | Description
42+
-------|------------
43+
`INDEX ALL` | Inspect all supported index types in the target table or database. This is the default.
44+
`INDEX ({index_name} [, ...])` | Inspect only the specified indexes. Note that `INDEX ALL` and this option are mutually exclusive.
45+
`DETACHED` | Run `INSPECT` in detached mode so the statement returns to the SQL client after the job is created (instead of waiting for the job to complete). For an example, see [`INSPECT` a table without waiting for completion](#inspect-a-table-without-waiting-for-completion). This option allows `INSPECT` to run inside a [multi-statement transaction]({% link {{ page.version.version }}/run-multi-statement-transactions.md %}).
46+
47+
## Considerations
48+
49+
- `INSPECT` always runs as a [background job]({% link {{ page.version.version }}/show-jobs.md %}).
50+
- By default, `INSPECT` causes the SQL client to wait for the background job to complete and returns a `NOTICE` with the job ID. To return to the client as soon as the job is created (without waiting for it to finish), use the [`DETACHED` option](#options).
51+
- `INSPECT` can be run inside a [multi-statement transaction]({% link {{ page.version.version }}/run-multi-statement-transactions.md %}) if the `DETACHED` option is used. Otherwise, it needs to be run in an [implicit transaction]({% link {{ page.version.version }}/transactions.md %}#individual-statements).
52+
- `INSPECT` runs with low priority under the [admission control]({% link {{ page.version.version }}/admission-control.md %}) subsystem and may take time on large datasets. Plan to run it during periods of lower system load.
53+
- The following index types are unsupported:
54+
- [Vector indexes]({% link {{ page.version.version }}/vector-indexes.md %})
55+
- [Partial indexes]({% link {{ page.version.version }}/partial-indexes.md %})
56+
- [Expression indexes]({% link {{ page.version.version }}/expression-indexes.md %})
57+
- [Hash-sharded indexes]({% link {{ page.version.version }}/hash-sharded-indexes.md %})
58+
- [Inverted indexes]({% link {{ page.version.version }}/inverted-indexes.md %})
59+
- Unsupported index types are automatically skipped when using the default `INDEX ALL` behavior. If an unsupported index type is directly requested using `INDEX {index_name}`, the statement will fail before starting.
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+
~~~
71+
NOTICE: waiting for INSPECT job to complete: 1141477630617223169
72+
If the statement is canceled, the job will continue in the background.
73+
~~~
74+
75+
### `INSPECT` a table for specific indexes
76+
77+
{% include_cached copy-clipboard.html %}
78+
~~~ sql
79+
INSPECT TABLE movr.public.vehicles WITH OPTIONS INDEX (vehicles_auto_index_fk_city_ref_users);
80+
~~~
81+
82+
~~~
83+
NOTICE: waiting for INSPECT job to complete: 1141477560713150465
84+
If the statement is canceled, the job will continue in the background.
85+
~~~
86+
87+
### `INSPECT` a table without waiting for completion
88+
89+
{% include_cached copy-clipboard.html %}
90+
~~~ sql
91+
INSPECT TABLE movr.public.vehicles WITH OPTIONS DETACHED;
92+
~~~
93+
94+
~~~
95+
NOTICE: INSPECT job 1141773037670301697 running in the background
96+
~~~
97+
98+
### `INSPECT` at a specific timestamp
99+
100+
{% include_cached copy-clipboard.html %}
101+
~~~ sql
102+
INSPECT TABLE movr.public.users AS OF SYSTEM TIME '-10s';
103+
~~~
104+
105+
~~~
106+
NOTICE: waiting for INSPECT job to complete: 1141477013029322753
107+
If the statement is canceled, the job will continue in the background.
108+
~~~
109+
110+
### Checking `INSPECT` job status
111+
112+
When you issue the `INSPECT` statement, a `NOTICE` message is returned to the client showing the job ID:
113+
114+
~~~
115+
NOTICE: waiting for INSPECT job to complete: 1141477013029322753
116+
If the statement is canceled, the job will continue in the background.
117+
~~~
118+
119+
You can check the status of the `INSPECT` [job]({% link {{ page.version.version }}/show-jobs.md %}) using a statement like the following:
120+
121+
{% include_cached copy-clipboard.html %}
122+
~~~ sql
123+
SELECT * FROM [SHOW JOBS] WHERE job_id = 1141477013029322753;
124+
~~~
125+
~~~
126+
job_id | job_type | description | user_name | status | running_status | created | started | finished | modified | fraction_completed | error | coordinator_id
127+
----------------------+----------+---------------------------------+-----------+-----------+----------------+------------------------+------------------------+------------------------+------------------------+--------------------+-------+-----------------
128+
1141477013029322753 | INSPECT | INSPECT TABLE movr.public.users | node | succeeded | NULL | 2026-01-14 20:12:19+00 | 2026-01-14 20:12:19+00 | 2026-01-14 20:12:19+00 | 2026-01-14 20:12:19+00 | 1 | | 1
129+
~~~
130+
131+
### Viewing `INSPECT` results
132+
133+
To view errors found by an inspection job, use [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %}). Errors are stored in an internal system table and are subject to a 90 day retention policy.
134+
135+
## See also
136+
137+
- [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %})
138+
- [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %})
139+
- [Jobs page in DB Console]({% link {{ page.version.version }}/ui-jobs-page.md %})
140+
- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
141+
- [Supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges)

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

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
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 errors recorded by an [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) job.
9+
10+
`SHOW INSPECT ERRORS` shows results for a single `INSPECT` job at a time; it does not aggregate results across jobs. By default, it returns errors from the most recent completed, successful `INSPECT` job for the specified table. To view errors from a specific job, use `SHOW INSPECT ERRORS FOR JOB {job_id}`.
11+
12+
## Required privileges
13+
14+
To run `SHOW INSPECT ERRORS`, the user must have:
15+
16+
- The `INSPECT` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges), which is required to run the [`INSPECT` statement]({% link {{ page.version.version }}/inspect.md %}).
17+
18+
## Synopsis
19+
20+
<div>
21+
{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/show_inspect_errors.html %}
22+
</div>
23+
24+
## Parameters
25+
26+
Parameter | Syntax | Description
27+
----------|----------|------------
28+
`opt_for_table_clause` | `FOR TABLE {table_name}` | Optional. Show errors for the specified [table]({% link {{ page.version.version }}/create-table.md %}).
29+
`opt_for_job_clause` | `FOR JOB {job_id}` | Optional. Show errors produced by the job ID returned by the [`INSPECT` statement]({% link {{ page.version.version }}/inspect.md %}).
30+
`opt_with_details` | `WITH DETAILS` | Optional. Include structured error metadata from the `details` column ([JSON]({% link {{ page.version.version }}/jsonb.md %})) in the results.
31+
32+
## Response
33+
34+
`SHOW INSPECT ERRORS` returns the following columns, with one row per issue detected.
35+
36+
Field | Description
37+
------|------------
38+
`job_id` | The ID of the [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) job that detected the issue.
39+
`error_type` | The type of inconsistency detected. For more information, see [Error types](#error-types).
40+
`aost` | The [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %}) timestamp used by the validation [job]({% link {{ page.version.version }}/show-jobs.md %}) (if any).
41+
`database_name` | The [database]({% link {{ page.version.version }}/create-database.md %}) containing the schema object with an issue.
42+
`schema_name` | The [schema]({% link {{ page.version.version }}/schema-design-overview.md %}) containing the object with an issue.
43+
`object_name` | The [table]({% link {{ page.version.version }}/create-table.md %}) or [index]({% link {{ page.version.version }}/indexes.md %}) with an issue.
44+
`primary_key` | The [primary key]({% link {{ page.version.version }}/primary-key.md %}) of the row involved in the issue, if applicable.
45+
`details` | This column is present only if `WITH DETAILS` is specified. It contains structured metadata ([JSON]({% link {{ page.version.version }}/jsonb.md %})) describing the issue.
46+
47+
### Error types
48+
49+
The `INSPECT` implementation reports the following `error_type` values:
50+
51+
Error type | Meaning
52+
----------|---------
53+
`missing_secondary_index_entry` | A row in the [primary index]({% link {{ page.version.version }}/primary-key.md %}) is missing a corresponding entry in a [secondary index]({% link {{ page.version.version }}/indexes.md %}). If you see this error, [contact Support]({% link {{ page.version.version }}/support-resources.md %}).
54+
`dangling_secondary_index_entry` | A [secondary index]({% link {{ page.version.version }}/indexes.md %}) entry exists, but the referenced [primary index]({% link {{ page.version.version }}/primary-key.md %}) row does not. If you see this error, [contact Support]({% link {{ page.version.version }}/support-resources.md %}).
55+
`internal_error` | An error occurred while `INSPECT` was running its validation queries (for example, an [MVCC GC timeout]({% link {{ page.version.version }}/ui-queues-dashboard.md %}#mvcc-gc-queue)). The cause of this error type is usually not related to data validity. Investigate the underlying job error details and cluster logs to determine the cause before deciding whether to [contact Support]({% link {{ page.version.version }}/support-resources.md %}).
56+
57+
## Examples
58+
59+
### Show the latest errors for a table
60+
61+
To see the errors found by the most recent `INSPECT` job, issue the following statement:
62+
63+
{% include_cached copy-clipboard.html %}
64+
~~~ sql
65+
SHOW INSPECT ERRORS FOR TABLE movr.public.users;
66+
~~~
67+
68+
### Show errors for a specific inspection job
69+
70+
When you issue the [`INSPECT` statement]({% link {{ page.version.version }}/inspect.md %}), a `NOTICE` message is returned to the client showing the job ID, e.g.,
71+
72+
{% include_cached copy-clipboard.html %}
73+
~~~ sql
74+
INSPECT TABLE movr.public.users AS OF SYSTEM TIME '-10s';
75+
~~~
76+
77+
~~~
78+
NOTICE: waiting for INSPECT job to complete: 1141477013029322753
79+
If the statement is canceled, the job will continue in the background.
80+
~~~
81+
82+
To show errors for a job, issue the following statement:
83+
84+
{% include_cached copy-clipboard.html %}
85+
~~~ sql
86+
SHOW INSPECT ERRORS FOR JOB 1141477013029322753;
87+
~~~
88+
89+
If there are no errors associated with that job ID, the output is:
90+
91+
~~~
92+
SHOW INSPECT ERRORS 0
93+
~~~
94+
95+
Note that if you issue a job ID for a nonexistent job, you will see the same output as for a job with no errors:
96+
97+
{% include_cached copy-clipboard.html %}
98+
~~~ sql
99+
SHOW INSPECT ERRORS FOR JOB 0;
100+
~~~
101+
102+
~~~
103+
SHOW INSPECT ERRORS 0
104+
~~~
105+
106+
### Show errors with details
107+
108+
{% include_cached copy-clipboard.html %}
109+
~~~ sql
110+
SHOW INSPECT ERRORS FOR TABLE movr.public.users WITH DETAILS;
111+
~~~
112+
113+
## See also
114+
115+
- [`INSPECT`]({% link {{ page.version.version }}/inspect.md %})
116+
- [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %})
117+
- [Jobs page in DB Console]({% link {{ page.version.version }}/ui-jobs-page.md %})
118+
- [Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges)

0 commit comments

Comments
 (0)