Add docs on INSPECT statement for v26.1 #22023
Conversation
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
rmloveland
force-pushed
the
20260105-inspect
branch
2 times, most recently
from
c4e486a to
fb70bc1
Compare
rmloveland
force-pushed
the
20260105-inspect
branch
from
fb70bc1 to
c34e051
Compare
|
@spilchen this is a first cut at INSPECT docs. I read the eng design doc and have been testing locally with a v26.1 pre-release. Hopefully these are reasonably close to ok but please let me know if i missed anything important or something is incorrect. Happy to update as needed. Thank you! |
spilchen
left a comment
spilchen
left a comment
There was a problem hiding this comment.
Thanks for putting this together.
|
|
||
| ### Error types | ||
|
|
||
| The `INSPECT` implementation reports the following `error_type` values: |
There was a problem hiding this comment.
The errors we report are a bit different. We have these 3 currently defined (more are coming in 26.2):
// Inspect error types reported by INSPECT. Each value identifies a specific kind
// of validation failure. These values are stored in system.inspect_errors.error_type.
const (
// MissingSecondaryIndexEntry occurs when a primary index row exists
// but the corresponding entry is missing from a secondary index.
MissingSecondaryIndexEntry inspectErrorType = "missing_secondary_index_entry"
// DanglingSecondaryIndexEntry occurs when a secondary index entry exists
// but the corresponding row in the primary index is missing.
DanglingSecondaryIndexEntry inspectErrorType = "dangling_secondary_index_entry"
// InternalError occurs when an internal error (e.g., data corruption, encoding
// issues) prevents the check from completing normally. These errors indicate
// potential data corruption or other serious issues that require investigation.
InternalError inspectErrorType = "internal_error"
)
There was a problem hiding this comment.
thank you! I've updated the table as follows, let me know what you think - i also added a line about contacting support for the internal_error one - but let me know if that advice should be more general, i.e., should one contact Support for any of these errors?
Error type Meaning missing_secondary_index_entryA 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_entryA [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_errorAn 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 %}).
There was a problem hiding this comment.
The internal error ended up being a catch all for any error that occurs while INSPECT runs its queries. For example, if INSPECT hits something like a GC timeout, it will surface as an internal error. Data corruption can show up this way, but it definitely isn’t the norm. Some assessment of the underlying error is needed before deciding whether to contact support.
For the other errors, those represent actual data corruption that we’ve detected. We don’t currently tell the user how to fix those issues, so if they want them resolved, they’ll likely need to contact support.
| -------|------------ | ||
| `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 %}). |
There was a problem hiding this comment.
This kind of makes it sound like this is the only way to background the INSPECT job. But INSPECT always runs in the background. The difference is if the client waits for the job to finish or not.
|
|
||
| ### Error types | ||
|
|
||
| The `INSPECT` implementation reports the following `error_type` values: |
There was a problem hiding this comment.
The internal error ended up being a catch all for any error that occurs while INSPECT runs its queries. For example, if INSPECT hits something like a GC timeout, it will surface as an internal error. Data corruption can show up this way, but it definitely isn’t the norm. Some assessment of the underlying error is needed before deciding whether to contact support.
For the other errors, those represent actual data corruption that we’ve detected. We don’t currently tell the user how to fix those issues, so if they want them resolved, they’ll likely need to contact support.
2 participants
Fixes:
Summary of changes:
Add docs for
INSPECTstatementAdd docs for
SHOW INSPECT ERRORSstatementAdd the above to the list of SQL statements
Update various privileges- and jobs-related docs