Hint injection docs by taroface · Pull Request #20830 · cockroachdb/docs

taroface · 2025-10-28T20:46:25Z

DOC-15510
DOC-15833
DOC-15834
DOC-15838
DOC-15836
DOC-15276
DOC-15422

Document hint injection
Document SHOW STATEMENT HINTS, using a SQL diagram to be updated in docgen: update SHOW STATEMENT HINTS and EXPLAIN diagrams cockroach#161545

netlify · 2025-10-28T20:46:46Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`a2bcebe`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-api-docs/deploys/697ba0ecc201a00008ad2440

netlify · 2025-10-28T20:46:47Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`a2bcebe`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-interactivetutorials-docs/deploys/697ba0ecd604df0008a3b2d4

github-actions · 2025-10-28T20:46:50Z

Files changed:

src/current/_includes/v26.1/misc/force-index-selection.md:

src/current/_includes/v26.1/sidebar-data/sql.json
src/current/v26.1/cost-based-optimizer.md
src/current/v26.1/explain-analyze.md
src/current/v26.1/explain.md
src/current/v26.1/show-statement-hints.md
src/current/v26.1/sql-statements.md

netlify · 2025-10-28T21:01:41Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`a2bcebe`
🔍 Latest deploy log	https://app.netlify.com/projects/cockroachdb-docs/deploys/697ba0ec48047c00087d06ba
😎 Deploy Preview	https://deploy-preview-20830--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

github-actions · 2026-01-21T23:42:57Z

✅ Cross-Version Link Check Passed

All cross-version link issues have been resolved. Good job!

michae2

These docs are great! Just a couple corrections.

michae2 · 2026-01-22T07:35:39Z

+{{site.data.alerts.callout_info}}
+The `statement hints count` field shows the number of individual hints applied. A single row in `system.statement_hints` can contain multiple hints (such as an index hint and a join hint).
+{{site.data.alerts.end}}
+


As of cockroachdb/cockroach#161043 there's also a new metric, sql.query.with_statement_hints.count, which counts the number of statement executions that used statement hints.

I see the issue to document this metric. However, apparently metrics.yaml now has a visibility field that (separately from the presence of a release note) determines whether these metrics are supposed to be documented. Since this metric doesn't appear to have that field, and I'm not clear on this metrics policy right now, I'll have to defer this for now. Let me know if it's meant to have visibility though.

I see. Let's skip documenting it for now.

taroface · 2026-01-22T21:48:42Z

@michae2 Updated per your comments. PTAL!

michae2

LGTM! Thanks!

michae2 · 2026-01-26T23:21:42Z

+);
+~~~
+
+Fingerprints distinguish between queries with different inline hints. For example, the fingerprint `SELECT * FROM users WHERE city = _` does **not** match the statement `SELECT * FROM users@users_pkey WHERE city = 'new york'` (which matches the fingerprint `SELECT * FROM users@users_pkey WHERE city = _`). As a result, you can use `information_schema.crdb_rewrite_inline_hints()` to remove inline hints:


This is great! Thank you!

michae2 · 2026-01-26T23:25:23Z

+{{site.data.alerts.callout_info}}
+The `statement hints count` field shows the number of individual hints applied. A single row in `system.statement_hints` can contain multiple hints (such as an index hint and a join hint).
+{{site.data.alerts.end}}
+


I see. Let's skip documenting it for now.

michae2 · 2026-01-26T23:40:05Z

@@ -39,15 +39,16 @@ The user requires the appropriate [privileges]({% link {{ page.version.version }

 Parameter         | Description


Not sure how helpful this is, but just noting here that there are two "levels" to EXPLAIN parameters: "modes" and "flags". There has to be 1 mode, and then 0 or more flags for that mode.

Modes:

PLAN (the default if no modes are provided)

OPT

DISTSQL

DDL

VEC

DEBUG

GIST

FINGERPRINT (new)

Flags:

VERBOSE

TYPES

ENV

CATALOG

JSON

MEMO

SHAPE

VIZ

REDACT

It confuses things a little bit to document them all together, because they work a bit differently.

Thank you! I will file this into a separate ticket.

https://cockroachlabs.atlassian.net/browse/DOC-15982

161545: docgen: update SHOW STATEMENT HINTS and EXPLAIN diagrams r=michae2 a=taroface Updated the diagram for `SHOW STATEMENT HINTS` (exposing the `DETAILS` option). Diagram looks like: <img width="547" height="274" alt="image" src="https://github.com/user-attachments/assets/1c66f39b-30b1-4dbf-a32b-893e4222db75" /> Also updated the `EXPLAIN` diagram to include the `FINGERPRINT` option: <img width="605" height="453" alt="image" src="https://github.com/user-attachments/assets/1f9d9b27-b8b4-4c60-b1d2-3b4ad6aafb87" /> This is related to the docs PR cockroachdb/docs#20830 Epic: none Release note: none Release justification: non-production code change Co-authored-by: Ryan Kuo <ryank@cockroachlabs.com>

peachdawnleach

Just a couple of small comments; otherwise LGTM. Very thorough and clear

peachdawnleach · 2026-01-28T22:50:17Z

+-------|------|------------
+`row_id` | `INT` | A unique ID.
+`fingerprint` | `STRING` | The SQL statement fingerprint that the hint applies to.
+`hint_type` | `STRING` | `rewrite_inline_hints`, indicating an injected hint.


Not sure I understand this one- is rewrite_inline_hints the only possible value here? If not, it might be good to make that more clear.

Yes, eventually there will be other hint types! I clarified this but somewhat more indirectly.

161545: docgen: update SHOW STATEMENT HINTS and EXPLAIN diagrams r=michae2 a=taroface Updated the diagram for `SHOW STATEMENT HINTS` (exposing the `DETAILS` option). Diagram looks like: <img width="547" height="274" alt="image" src="https://github.com/user-attachments/assets/1c66f39b-30b1-4dbf-a32b-893e4222db75" /> Also updated the `EXPLAIN` diagram to include the `FINGERPRINT` option: <img width="605" height="453" alt="image" src="https://github.com/user-attachments/assets/1f9d9b27-b8b4-4c60-b1d2-3b4ad6aafb87" /> This is related to the docs PR cockroachdb/docs#20830 Epic: none Release note: none Release justification: non-production code change Co-authored-by: Ryan Kuo <ryank@cockroachlabs.com>

taroface added the DO NOT MERGE label Oct 28, 2025

taroface force-pushed the hint-injection branch 2 times, most recently from 95d85db to 73b7928 Compare January 21, 2026 23:42

taroface force-pushed the hint-injection branch from 73b7928 to 774dc87 Compare January 21, 2026 23:43

update hint injection docs for 26.1; add SHOW STATEMENT HINTS page

919fc5a

taroface force-pushed the hint-injection branch from 774dc87 to 919fc5a Compare January 21, 2026 23:44

taroface requested review from DrewKimball and michae2 January 21, 2026 23:46

taroface changed the title ~~[WIP] hint injection docs~~ Hint injection docs Jan 21, 2026

taroface removed the DO NOT MERGE label Jan 21, 2026

fix image paths

5ea6f9e

taroface mentioned this pull request Jan 22, 2026

docgen: update SHOW STATEMENT HINTS and EXPLAIN diagrams cockroachdb/cockroach#161545

Merged

michae2 reviewed Jan 22, 2026

View reviewed changes

address review comments

372f4f8

taroface force-pushed the hint-injection branch from d0153eb to 372f4f8 Compare January 22, 2026 21:48

taroface requested a review from michae2 January 22, 2026 21:48

Merge branch 'main' into hint-injection

c345162

michae2 approved these changes Jan 26, 2026

View reviewed changes

michae2 reviewed Jan 26, 2026

View reviewed changes

Comment thread src/current/v26.1/show-statement-hints.md Outdated

Merge branch 'main' into hint-injection

e9d9124

address review comments

904b5e8

peachdawnleach self-requested a review January 28, 2026 21:36

peachdawnleach approved these changes Jan 28, 2026

View reviewed changes

taroface and others added 2 commits January 29, 2026 12:27

address review comments

1a2480d

Merge branch 'main' into hint-injection

a2bcebe

taroface enabled auto-merge (squash) January 29, 2026 18:03

taroface merged commit 7519047 into main Jan 29, 2026
7 checks passed

taroface deleted the hint-injection branch January 29, 2026 18:12

blathers-crl Bot mentioned this pull request Jan 29, 2026

release-26.1: docgen: update SHOW STATEMENT HINTS and EXPLAIN diagrams cockroachdb/cockroach#162052

Merged

		@@ -39,15 +39,16 @@ The user requires the appropriate [privileges]({% link {{ page.version.version }

		Parameter \| Description

Conversation

taroface commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

netlify Bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

github-actions Bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

netlify Bot commented Oct 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

github-actions Bot commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

michae2 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

taroface commented Jan 22, 2026

Uh oh!

michae2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

peachdawnleach left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

taroface commented Oct 28, 2025 •

edited

Loading

netlify Bot commented Oct 28, 2025 •

edited

Loading

netlify Bot commented Oct 28, 2025 •

edited

Loading

github-actions Bot commented Oct 28, 2025 •

edited

Loading

netlify Bot commented Oct 28, 2025 •

edited

Loading

github-actions Bot commented Jan 21, 2026 •

edited

Loading