From c34e051d9a53c84e9e19cc54a594ab1710d618e2 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Mon, 5 Jan 2026 16:32:14 -0500 Subject: [PATCH 1/5] 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 --- .../_includes/v26.1/sidebar-data/sql.json | 12 ++ src/current/_includes/v26.1/sql/privileges.md | 1 + src/current/_includes/v26.1/ui/jobs.md | 2 +- src/current/v26.1/inspect.md | 127 ++++++++++++++++++ src/current/v26.1/show-inspect-errors.md | 116 ++++++++++++++++ src/current/v26.1/show-jobs.md | 2 +- src/current/v26.1/sql-statements.md | 9 ++ 7 files changed, 267 insertions(+), 2 deletions(-) create mode 100644 src/current/v26.1/inspect.md create mode 100644 src/current/v26.1/show-inspect-errors.md diff --git a/src/current/_includes/v26.1/sidebar-data/sql.json b/src/current/_includes/v26.1/sidebar-data/sql.json index 4591796a8e6..cad254696d3 100644 --- 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": "INSPECT", + "urls": [ + "/${VERSION}/inspect.html" + ] + }, { "title": "JOIN", "urls": [ @@ -700,6 +706,12 @@ "/${VERSION}/show-index.html" ] }, + { + "title": "SHOW INSPECT ERRORS", + "urls": [ + "/${VERSION}/show-inspect-errors.html" + ] + }, { "title": "SHOW JOBS", "urls": [ diff --git a/src/current/_includes/v26.1/sql/privileges.md b/src/current/_includes/v26.1/sql/privileges.md index 12062b5e194..8d828216fd8 100644 --- 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. + `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 %}). `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 index c67c55d9a0c..e01a0173310 100644 --- 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 new file mode 100644 index 00000000000..2486205d1bc --- /dev/null +++ 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 + +
+ {% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/inspect_table.html %} +
+ +
+ {% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/inspect_database.html %} +
+ +## 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 new file mode 100644 index 00000000000..5be168ccd5d --- /dev/null +++ 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 + +
+{% remote_include https://raw.githubusercontent.com/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/show_inspect_errors.html %} +
+ +## 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 index 8fc02539608..1a8a2f1ebad 100644 --- 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 %}).

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 %}).

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 %}).

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 index 9efb6365296..5a137cd6408 100644 --- a/src/current/v26.1/sql-statements.md +++ b/src/current/v26.1/sql-statements.md @@ -113,6 +113,15 @@ Statement | Usage [`SHOW USERS`]({% link {{ page.version.version }}/show-users.md %}) | Lists the users for all databases. [`SHOW DEFAULT PRIVILEGES`]({% link {{ page.version.version }}/show-default-privileges.md %}) | Show the default privileges for objects created by specific roles/users in the current database. + + +## Data consistency statements + +Statement | Usage +----------|------------ +[`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) | Run data consistency validation checks against tables or databases. +[`SHOW INSPECT ERRORS`]({% link {{ page.version.version }}/show-inspect-errors.md %}) | View issues detected by [`INSPECT`]({% link {{ page.version.version }}/inspect.md %}) data consistency validation jobs. + ## Transaction control statements From b172f4e30f324245550252a866c2388a4be661fe Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 15 Jan 2026 16:50:11 -0500 Subject: [PATCH 2/5] Update with spilchen feedback (1) --- src/current/v26.1/inspect.md | 24 +++++++++++++++++++----- src/current/v26.1/show-inspect-errors.md | 9 +++++---- 2 files changed, 24 insertions(+), 9 deletions(-) diff --git a/src/current/v26.1/inspect.md b/src/current/v26.1/inspect.md index 2486205d1bc..b5fa8ede20d 100644 --- a/src/current/v26.1/inspect.md +++ b/src/current/v26.1/inspect.md @@ -5,7 +5,7 @@ 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 %}). +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. @@ -16,7 +16,7 @@ The `INSPECT` [statement]({% link {{ page.version.version }}/sql-statements.md % 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 %})). +- 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 @@ -34,8 +34,8 @@ 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). +`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 @@ -43,16 +43,19 @@ 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 the inspection job in the background. For an example, see [`INSPECT` a table and run the job in the background](#inspect-a-table-and-run-the-job-in-the-background). This option allows `INSPECT` to run inside a [multi-statement transaction]({% link {{ page.version.version }}/run-multi-statement-transactions.md %}). ## 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` can be run inside a [multi-statement transaction]({% link {{ page.version.version }}/run-multi-statement-transactions.md %}) if the [`DETACHED` option](#options) is used. Otherwise, it needs to be run in an [implicit transaction]({% link {{ page.version.version }}/transactions.md %}#individual-statements). - `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 %}) + - [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 @@ -81,6 +84,17 @@ NOTICE: waiting for INSPECT job to complete: 1141477560713150465 If the statement is canceled, the job will continue in the background. ~~~ +### `INSPECT` a table and run the job in the background + +{% 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 %} diff --git a/src/current/v26.1/show-inspect-errors.md b/src/current/v26.1/show-inspect-errors.md index 5be168ccd5d..fbaa13b901c 100644 --- a/src/current/v26.1/show-inspect-errors.md +++ b/src/current/v26.1/show-inspect-errors.md @@ -5,9 +5,9 @@ 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. +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. -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}`. +`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 @@ -51,8 +51,9 @@ 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. +`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 %}). +`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. +`internal_error` | An internal error (for example, data corruption or encoding issues) prevented the check from completing normally. These errors can indicate data corruption or other serious issues that require investigation. If you see this error, please [contact Support]({% link {{ page.version.version }}/support-resources.md %}). ## Examples From eb312abf4a30e7dfe09eb1fa91f99b8688b064ee Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 16 Jan 2026 11:19:03 -0500 Subject: [PATCH 3/5] Update with spilchen feedback (2) --- src/current/v26.1/inspect.md | 7 ++++--- src/current/v26.1/show-inspect-errors.md | 6 +++--- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/src/current/v26.1/inspect.md b/src/current/v26.1/inspect.md index b5fa8ede20d..59a185a3e97 100644 --- a/src/current/v26.1/inspect.md +++ b/src/current/v26.1/inspect.md @@ -43,12 +43,13 @@ 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 the inspection job in the background. For an example, see [`INSPECT` a table and run the job in the background](#inspect-a-table-and-run-the-job-in-the-background). This option allows `INSPECT` to run inside a [multi-statement transaction]({% link {{ page.version.version }}/run-multi-statement-transactions.md %}). +`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` can be run inside a [multi-statement transaction]({% link {{ page.version.version }}/run-multi-statement-transactions.md %}) if the [`DETACHED` option](#options) is used. Otherwise, it needs to be run in an [implicit transaction]({% link {{ page.version.version }}/transactions.md %}#individual-statements). - `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 %}) @@ -84,7 +85,7 @@ NOTICE: waiting for INSPECT job to complete: 1141477560713150465 If the statement is canceled, the job will continue in the background. ~~~ -### `INSPECT` a table and run the job in the background +### `INSPECT` a table without waiting for completion {% include_cached copy-clipboard.html %} ~~~ sql diff --git a/src/current/v26.1/show-inspect-errors.md b/src/current/v26.1/show-inspect-errors.md index fbaa13b901c..9a3f3e62f77 100644 --- a/src/current/v26.1/show-inspect-errors.md +++ b/src/current/v26.1/show-inspect-errors.md @@ -51,9 +51,9 @@ 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 %}). -`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. -`internal_error` | An internal error (for example, data corruption or encoding issues) prevented the check from completing normally. These errors can indicate data corruption or other serious issues that require investigation. If you see this error, please [contact Support]({% link {{ page.version.version }}/support-resources.md %}). +`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 From 963c591ccb30328578cf45bf9352d9ea701edb71 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 22 Jan 2026 14:57:03 -0500 Subject: [PATCH 4/5] Add bsanchez-the-roach, rafiss, spilchen feedback --- src/current/v26.1/inspect.md | 5 ++--- src/current/v26.1/show-inspect-errors.md | 3 ++- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/current/v26.1/inspect.md b/src/current/v26.1/inspect.md index 59a185a3e97..dbbfc698d42 100644 --- a/src/current/v26.1/inspect.md +++ b/src/current/v26.1/inspect.md @@ -15,8 +15,7 @@ The `INSPECT` [statement]({% link {{ page.version.version }}/sql-statements.md % 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 %}). +- The `INSPECT` system-level [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges), which is required to run the `INSPECT` statement. ## Synopsis @@ -117,7 +116,7 @@ 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: +You can check the status of the `INSPECT` [job]({% link {{ page.version.version }}/show-jobs.md %}) using a statement like the following: {% include_cached copy-clipboard.html %} ~~~ sql diff --git a/src/current/v26.1/show-inspect-errors.md b/src/current/v26.1/show-inspect-errors.md index 9a3f3e62f77..ba239239c3f 100644 --- a/src/current/v26.1/show-inspect-errors.md +++ b/src/current/v26.1/show-inspect-errors.md @@ -14,7 +14,6 @@ The `SHOW INSPECT ERRORS` [statement]({% link {{ page.version.version }}/sql-sta 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 @@ -59,6 +58,8 @@ Error type | Meaning ### Show the latest errors for a table +To see the errors found by the most recent `INSPECT` job, issue the following statement: + {% include_cached copy-clipboard.html %} ~~~ sql SHOW INSPECT ERRORS FOR TABLE movr.public.users; From 61c65f4c9dc79ee7ca99d928c2855a4fd05eb0b2 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Thu, 22 Jan 2026 15:13:29 -0500 Subject: [PATCH 5/5] Satisfy x-version link linter --- src/current/_includes/v26.1/ui/jobs.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/current/_includes/v26.1/ui/jobs.md b/src/current/_includes/v26.1/ui/jobs.md index e01a0173310..60ca27a6bc4 100644 --- a/src/current/_includes/v26.1/ui/jobs.md +++ b/src/current/_includes/v26.1/ui/jobs.md @@ -8,7 +8,7 @@ The Jobs list is designed for you to manage pending work. It is not intended to Use the **Jobs** table to see recently created and completed jobs. -DB Console Jobs Page +DB Console Jobs Page ### Filter jobs @@ -66,7 +66,7 @@ The details show: - **User Name** - error messages (if any) -DB Console Jobs Page +DB Console Jobs Page ## See also