Add docs on INSPECT statement for v26.1

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": [

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.

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.

src/current/v26.1/inspect.md

@@ -0,0 +1,142 @@
+---
+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 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 %}).
+
+{{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.
+`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 %}).
+
+## Considerations
+
+- `INSPECT` always runs as a [background job]({% link {{ page.version.version }}/show-jobs.md %}).
+- 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).
+- `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).
+- `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 %})
+  - [Hash-sharded indexes]({% link {{ page.version.version }}/hash-sharded-indexes.md %})
+  - [Inverted indexes]({% link {{ page.version.version }}/inverted-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` a table without waiting for completion
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+INSPECT TABLE movr.public.vehicles WITH OPTIONS DETACHED;
+~~~
+
+~~~
+NOTICE:  INSPECT job 1141773037670301697 running 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)

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

@@ -0,0 +1,117 @@
+---
+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 errors recorded by an [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) job.
+
+`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}`.
+
+## 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
+----------|---------
+`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 %}).
+`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 %}).
+`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 %}).
+
+## 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)