Add docs on INSPECT statement for v26.1

rmloveland · rmloveland · commit fb70bc1a6430 · 2026-01-14T15:43:20.000-05:00
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
diff --git a/src/current/_includes/v26.1/sidebar-data/sql.json b/src/current/_includes/v26.1/sidebar-data/sql.json
@@ -484,6 +484,12 @@
                 "/${VERSION}/insert.html"
               ]
             },
+            {
+              "title": "<code>INSPECT</code>",
+              "urls": [
+                "/${VERSION}/inspect.html"
+              ]
+            },
             {
               "title": "<code>JOIN</code>",
               "urls": [
@@ -700,6 +706,12 @@
                 "/${VERSION}/show-index.html"
               ]
             },
+            {
+              "title": "<code>SHOW INSPECT ERRORS</code>",
+              "urls": [
+                "/${VERSION}/show-inspect-errors.html"
+              ]
+            },
             {
               "title": "<code>SHOW JOBS</code>",
               "urls": [
diff --git a/src/current/_includes/v26.1/sql/privileges.md b/src/current/_includes/v26.1/sql/privileges.md
@@ -17,6 +17,7 @@ Privilege | Levels | Description
 `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.
 `EXTERNALIOIMPLICITACCESS` | System | Grants the ability to interact with external resources that require implicit access.
 `INSERT` | Table, Sequence | Grants the ability to insert objects at the table or sequence level.
+<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 %}).
 <a id="modifyclustersetting"></a>`MODIFYCLUSTERSETTING` | System | Grants the ability to modify [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}).
 `MODIFYSQLCLUSTERSETTING` | System | Grants the ability to modify SQL [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}) (cluster settings prefixed with `sql.`).
 `NOSQLLOGIN` | System | Prevents roles from connecting to the SQL interface of a cluster.
diff --git a/src/current/_includes/v26.1/ui/jobs.md b/src/current/_includes/v26.1/ui/jobs.md
@@ -28,7 +28,7 @@ Column | Description
 ----------|------------
 Description | SQL statement that created the job.
 Status | Current [job status](#job-status) or completion progress.
-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.
+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).
 User Name | User that created the job.
 Creation Time (UTC) | Date and time the job was created.
 Last Modified Time (UTC) | Date and time the job was last modified.
diff --git a/src/current/v26.1/inspect.md b/src/current/v26.1/inspect.md
@@ -0,0 +1,127 @@
+---
+title: INSPECT
+summary: Use the INSPECT statement to run data consistency validation checks against tables or databases.
+toc: true
+docs_area: reference.sql
+---
+
+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. To display any errors recorded by the validation job, use [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %}).
+
+{{site.data.alerts.callout_info}}
+`INSPECT` is used to verify data integrity. It does not automatically repair errors.
+{{site.data.alerts.end}}
+
+## Required privileges
+
+To run `INSPECT` and view its results, the user must have:
+
+- The `INSPECT` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) is required to run the `INSPECT` statement.
+- The `VIEWSYSTEMTABLE` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges), which is required to view the results of [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %})).
+
+## Synopsis
+
+<div>
+  {% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/inspect_table.html %}
+</div>
+
+<div>
+  {% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/inspect_database.html %}
+</div>
+
+## Parameters
+
+Parameter | Description
+----------|------------
+`table_name` | The [table]({% link {{ page.version.version }}/create-table.md %}) to inspect.
+`db_name` | The [database]({% link {{ page.version.version }}/create-database.md %}) to inspect.
+`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 %}).
+`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).
+
+### Options
+
+Option | Description
+-------|------------
+`INDEX ALL` | Inspect all supported index types in the target table or database. This is the default.
+`INDEX ({index_name} [, ...])` | Inspect only the specified indexes. Note that `INDEX ALL` and this option are mutually exclusive.
+
+## Considerations
+
+- `INSPECT` must be run in an [implicit transaction]({% link {{ page.version.version }}/transactions.md %}#individual-statements). 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 %}).
+- `INSPECT` always runs as a [background job]({% link {{ page.version.version }}/show-jobs.md %}).
+- `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.
+- The following index types are unsupported:
+  - [Vector indexes]({% link {{ page.version.version }}/vector-indexes.md %})
+  - [Partial indexes]({% link {{ page.version.version }}/partial-indexes.md %})
+  - [Expression indexes]({% link {{ page.version.version }}/expression-indexes.md %})
+- 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.
+
+## Examples
+
+### `INSPECT` a table (all supported indexes)
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+INSPECT TABLE movr.public.users;
+~~~
+
+~~~
+NOTICE: waiting for INSPECT job to complete: 1141477630617223169
+If the statement is canceled, the job will continue in the background.
+~~~
+
+### `INSPECT` a table for specific indexes
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+INSPECT TABLE movr.public.vehicles WITH OPTIONS INDEX (vehicles_auto_index_fk_city_ref_users);
+~~~
+
+~~~
+NOTICE: waiting for INSPECT job to complete: 1141477560713150465
+If the statement is canceled, the job will continue in the background.
+~~~
+
+### `INSPECT` at a specific timestamp
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+INSPECT TABLE movr.public.users AS OF SYSTEM TIME '-10s';
+~~~
+
+~~~
+NOTICE:  waiting for INSPECT job to complete: 1141477013029322753
+If the statement is canceled, the job will continue in the background.
+~~~
+
+### Checking `INSPECT` job status
+
+When you issue the `INSPECT` statement, a `NOTICE` message is returned to the client showing the job ID:
+
+~~~
+NOTICE:  waiting for INSPECT job to complete: 1141477013029322753
+If the statement is canceled, the job will continue in the background.
+~~~
+
+You can check the status of the `INSPECT` job using a statement like the following:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT * FROM [SHOW JOBS] WHERE job_id = 1141477013029322753;
+~~~
+~~~
+        job_id        | job_type |           description           | user_name |  status   | running_status |        created         |        started         |        finished        |        modified        | fraction_completed | error | coordinator_id
+----------------------+----------+---------------------------------+-----------+-----------+----------------+------------------------+------------------------+------------------------+------------------------+--------------------+-------+-----------------
+  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
+~~~
+
+### Viewing `INSPECT` results
+
+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.
+
+## See also
+
+- [`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %})
+- [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %})
+- [Jobs page in DB Console]({% link {{ page.version.version }}/ui-jobs-page.md %})
+- [`AS OF SYSTEM TIME`]({% link {{ page.version.version }}/as-of-system-time.md %})
+- [Supported privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges)
diff --git a/src/current/v26.1/show-inspect-errors.md b/src/current/v26.1/show-inspect-errors.md
@@ -0,0 +1,116 @@
+---
+title: SHOW INSPECT ERRORS
+summary: The SHOW INSPECT ERRORS statement lists issues detected by the INSPECT data consistency checker.
+toc: true
+docs_area: reference.sql
+---
+
+The `SHOW INSPECT ERRORS` [statement]({% link {{ page.version.version }}/sql-statements.md %}) displays any issues detected by the data consistency validation jobs run by the [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) statement.
+
+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 its ID, e.g. `SHOW INSPECT ERRORS FOR JOB {id}`.
+
+## Required privileges
+
+To run `SHOW INSPECT ERRORS`, the user must have:
+
+- 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 %}).
+- The `VIEWSYSTEMTABLE` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges), which is required to view the output of `SHOW INSPECT ERRORS`.
+
+## Synopsis
+
+<div>
+{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/show_inspect_errors.html %}
+</div>
+
+## Parameters
+
+Parameter | Syntax   | Description
+----------|----------|------------
+`opt_for_table_clause` | `FOR TABLE {table_name}` | Optional. Show errors for the specified [table]({% link {{ page.version.version }}/create-table.md %}).
+`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 %}).
+`opt_with_details` | `WITH DETAILS` | Optional. Include structured error metadata from the `details` column ([JSON]({% link {{ page.version.version }}/jsonb.md %})) in the results.
+
+## Response
+
+`SHOW INSPECT ERRORS` returns the following columns, with one row per issue detected.
+
+Field | Description
+------|------------
+`job_id` | The ID of the [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) job that detected the issue.
+`error_type` | The type of inconsistency detected. For more information, see [Error types](#error-types).
+`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).
+`database_name` | The [database]({% link {{ page.version.version }}/create-database.md %}) containing the schema object with an issue.
+`schema_name` | The [schema]({% link {{ page.version.version }}/schema-design-overview.md %}) containing the object with an issue.
+`object_name` | The [table]({% link {{ page.version.version }}/create-table.md %}) or [index]({% link {{ page.version.version }}/indexes.md %}) with an issue.
+`primary_key` | The [primary key]({% link {{ page.version.version }}/primary-key.md %}) of the row involved in the issue, if applicable.
+`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.
+
+### Error types
+
+The `INSPECT` implementation reports the following `error_type` values:
+
+Error type | Meaning
+----------|---------
+`secondary_index_missing` | 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 %}).
+`secondary_index_dangling` | 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.
+
+## Examples
+
+### Show the latest errors for a table
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SHOW INSPECT ERRORS FOR TABLE movr.public.users;
+~~~
+
+### Show errors for a specific inspection job
+
+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.,
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+INSPECT TABLE movr.public.users AS OF SYSTEM TIME '-10s';
+~~~
+
+~~~
+NOTICE:  waiting for INSPECT job to complete: 1141477013029322753
+If the statement is canceled, the job will continue in the background.
+~~~
+
+To show errors for a job, issue the following statement:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SHOW INSPECT ERRORS FOR JOB 1141477013029322753;
+~~~
+
+If there are no errors associated with that job ID, the output is:
+
+~~~
+SHOW INSPECT ERRORS 0
+~~~
+
+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:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SHOW INSPECT ERRORS FOR JOB 0;
+~~~
+
+~~~
+SHOW INSPECT ERRORS 0
+~~~
+
+### Show errors with details
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SHOW INSPECT ERRORS FOR TABLE movr.public.users WITH DETAILS;
+~~~
+
+## See also
+
+- [`INSPECT`]({% link {{ page.version.version }}/inspect.md %})
+- [`SHOW JOBS`]({% link {{ page.version.version }}/show-jobs.md %})
+- [Jobs page in DB Console]({% link {{ page.version.version }}/ui-jobs-page.md %})
+- [Authorization]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges)
diff --git a/src/current/v26.1/show-jobs.md b/src/current/v26.1/show-jobs.md
@@ -61,7 +61,7 @@ The following fields are returned for each job:
 Field | Description
 ------|------------
 `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).
-`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).
+`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).
 `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}`.
 `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.
 `user_name` | The name of the [user]({% link {{ page.version.version }}/security-reference/authorization.md %}#create-and-manage-users) who started the job.
diff --git a/src/current/v26.1/sql-statements.md b/src/current/v26.1/sql-statements.md
