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..59a185a3e97 --- /dev/null +++ b/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 + +
+ {% 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. +`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) 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..9a3f3e62f77 --- /dev/null +++ b/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 + +
+{% 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 +----------|--------- +`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) 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