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

Author: taroface

src/current/_includes/v25.4/misc/force-index-selection.md

@@ -1,9 +1,7 @@
-By using the explicit index annotation, you can override [CockroachDB's index selection](https://www.cockroachlabs.com/blog/index-selection-cockroachdb-2/) and use a specific [index]({% link {{ page.version.version }}/indexes.md %}) when reading from a named table. This is called an *index hint*.
+By using the explicit index annotation, you can override [CockroachDB's index selection](https://www.cockroachlabs.com/blog/index-selection-cockroachdb-2/) and use a specific [index]({% link {{ page.version.version }}/indexes.md %}) when reading from a named table.
 
+{{site.data.alerts.callout_info}}
 Index selection can impact [performance]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), but does not change the result of a query.
-
-{{site.data.alerts.callout_success}}
-You can apply index hints without modifying the original query text. Refer to [Hint injection]({% link {{ page.version.version }}/cost-based-optimizer.md %}#hint-injection).
 {{site.data.alerts.end}}
 
 ##### Force index scan

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

@@ -1,7 +1,9 @@
-By using the explicit index annotation, you can override [CockroachDB's index selection](https://www.cockroachlabs.com/blog/index-selection-cockroachdb-2/) and use a specific [index]({% link {{ page.version.version }}/indexes.md %}) when reading from a named table.
+By using the explicit index annotation, you can override [CockroachDB's index selection](https://www.cockroachlabs.com/blog/index-selection-cockroachdb-2/) and use a specific [index]({% link {{ page.version.version }}/indexes.md %}) when reading from a named table. This is called an *index hint*.
 
-{{site.data.alerts.callout_info}}
 Index selection can impact [performance]({% link {{ page.version.version }}/performance-best-practices-overview.md %}), but does not change the result of a query.
+
+{{site.data.alerts.callout_success}}
+{% include_cached new-in.html version="v26.1" %} You can use [hint injection]({% link {{ page.version.version }}/cost-based-optimizer.md %}#hint-injection) to apply index hints without modifying the original query text.
 {{site.data.alerts.end}}
 
 ##### Force index scan

src/current/_includes/v26.1/sidebar-data/sql.json

@@ -796,6 +796,12 @@
                 "/${VERSION}/show-sessions.html"
               ]
             },
+            {
+              "title": "<code>SHOW STATEMENT HINTS</code>",
+              "urls": [
+                "/${VERSION}/show-statement-hints.html"
+              ]
+            },
             {
               "title": "<code>SHOW STATEMENTS</code>",
               "urls": [

src/current/v25.4/cost-based-optimizer.md

@@ -419,10 +419,6 @@ Due to SQL's implicit `AS` syntax, you cannot specify a join hint with only the
 
 For a join hint example, see [Use the right join type]({% link {{ page.version.version }}/apply-statement-performance-rules.md %}#rule-3-use-the-right-join-type).
 
-{{site.data.alerts.callout_success}}
-You can apply join hints without modifying the original query text. Refer to [Hint injection](#hint-injection).
-{{site.data.alerts.end}}
-
 ### Supported join algorithms
 
 - `HASH`: Forces a hash join; in other words, it disables merge and lookup joins. A hash join is always possible, even if there are no equality columns: CockroachDB treats a nested loop join without an index as a special case of a hash join, where the hash table effectively has one bucket.
@@ -461,105 +457,6 @@ To make the optimizer prefer lookup joins to merge joins when performing foreign
 
 - You should reconsider hint usage with each new release of CockroachDB. Due to improvements in the optimizer, hints specified to work with an older version may cause decreased performance in a newer version.
 
-## Hint injection
-
-<span class="version-tag">New in v25.4.1:</span> *Hint injection* allows you to apply [index hints]({% link {{ page.version.version }}/table-expressions.md %}#force-index-selection) and [join hints](#join-hints) without modifying the original query text. This is useful when you cannot modify application code, need to optimize queries from ORMs or third-party applications, or want to test different hints without changing production queries.
-
-Instead of relying on inline hints (such as `SELECT * FROM table@index_name` or `INNER HASH JOIN`), hint injection stores hints in the `system.statement_hints` table and automatically applies them to statements that match a [fingerprint]({% link {{ page.version.version }}/ui-statements-page.md %}#sql-statement-fingerprints). To inject a hint, invoke the `crdb_internal.inject_hint()` function with a SQL statement fingerprint and a matching statement with hints applied:
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-SELECT crdb_internal.inject_hint(
-  '{statement fingerprint}',
-  '{statement with hints}'
-);
-~~~
-
-For example, the following invocation stores the `users_email_idx` hint in the `system.statement_hints` table:
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-SELECT crdb_internal.inject_hint(
-  'SELECT * FROM users WHERE email = _',
-  'SELECT * FROM users@users_email_idx WHERE email = _'
-);
-~~~
-
-{{site.data.alerts.callout_info}}
-The statement with hints must have the same syntactic structure as the statement fingerprint. Constants in the second parameter are ignored, and only hints are extracted and applied.
-{{site.data.alerts.end}}
-
-The function returns a unique hint ID:
-
-~~~
-  crdb_internal.inject_hint
------------------------------
-        1119388019656228865
-~~~
-
-Afterward, any query matching the `SELECT * FROM users WHERE email = _` fingerprint will use the `users_email_idx` index, regardless of the `email` value.
-
-Similarly, to force a specific join algorithm:
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-SELECT crdb_internal.inject_hint(
-  'SELECT * FROM orders AS o INNER JOIN customers AS c ON o.customer_id = c.id',
-  'SELECT * FROM orders AS o INNER HASH JOIN customers AS c ON o.customer_id = c.id'
-);
-~~~
-
-You can inject both index and join hints in a single statement:
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-SELECT crdb_internal.inject_hint(
-  'SELECT * FROM orders AS o INNER JOIN customers AS c ON o.customer_id = c.id WHERE o.status = _',
-  'SELECT * FROM orders@orders_status_idx AS o INNER LOOKUP JOIN customers@primary AS c ON o.customer_id = c.id WHERE o.status = _'
-);
-~~~
-
-Hint injection supports all inline hint types, including:
-
-- [Index hints]({% link {{ page.version.version }}/table-expressions.md %}#force-index-selection): `@index_name`, `@{FORCE_INDEX=idx}`, `@{FORCE_INDEX=idx,DESC}`, `@{NO_FULL_SCAN}`, `@{AVOID_FULL_SCAN}`, `@{NO_ZIGZAG_JOIN}`, `@{FORCE_ZIGZAG}`
-- [Join hints](#join-hints): `HASH`, `MERGE`, `LOOKUP`, `INVERTED`, `STRAIGHT`
-
-### Manage injected hints
-
-To view all injected hints, query the `system.statement_hints` table:
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-SELECT row_id, fingerprint, created_at FROM system.statement_hints;
-~~~
-
-~~~
-        row_id        |                                          fingerprint                                           |          created_at
-----------------------+------------------------------------------------------------------------------------------------+--------------------------------
-  1119388019656228865 | SELECT * FROM users WHERE email = _                                                            | 2025-10-28 19:41:53.416787+00
-  1119394099211304961 | SELECT * FROM orders AS o INNER JOIN customers AS c ON o.customer_id = c.id                    | 2025-10-28 20:12:48.75263+00
-  1119397773284343809 | SELECT * FROM orders AS o INNER JOIN customers AS c ON o.customer_id = c.id WHERE o.status = _ | 2025-10-28 20:31:29.990728+00
-(3 rows)
-~~~
-
-{{site.data.alerts.callout_success}}
-The `hint` column is stored in a format that is not human-readable. Use the `fingerprint` column to identify which hints are stored.
-{{site.data.alerts.end}}
-
-To remove a hint by its hint ID:
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-DELETE FROM system.statement_hints WHERE row_id = {hint_id};
-~~~
-
-To remove all hints for a specific query fingerprint:
-
-{% include_cached copy-clipboard.html %}
-~~~ sql
-DELETE FROM system.statement_hints WHERE fingerprint = '{statement_fingerprint}';
-~~~
-
 ## Zigzag joins
 
 The optimizer may plan a zigzag join when there are at least **two secondary indexes on the same table** and the table is filtered in a query with at least two filters constraining different attributes to a constant. A zigzag join works by "zigzagging" back and forth between two indexes and returning only rows with matching primary keys within a specified range. For example:

src/current/v26.1/cost-based-optimizer.md

@@ -419,6 +419,10 @@ Due to SQL's implicit `AS` syntax, you cannot specify a join hint with only the
 
 For a join hint example, see [Use the right join type]({% link {{ page.version.version }}/apply-statement-performance-rules.md %}#rule-3-use-the-right-join-type).
 
+{{site.data.alerts.callout_success}}
+{% include_cached new-in.html version="v26.1" %} You can use [hint injection](#hint-injection) to apply join hints without modifying the original query text.
+{{site.data.alerts.end}}
+
 ### Supported join algorithms
 
 - `HASH`: Forces a hash join; in other words, it disables merge and lookup joins. A hash join is always possible, even if there are no equality columns: CockroachDB treats a nested loop join without an index as a special case of a hash join, where the hash table effectively has one bucket.
@@ -457,6 +461,139 @@ To make the optimizer prefer lookup joins to merge joins when performing foreign
 
 - You should reconsider hint usage with each new release of CockroachDB. Due to improvements in the optimizer, hints specified to work with an older version may cause decreased performance in a newer version.
 
+## Hint injection
+
+{% include_cached new-in.html version="v26.1" %} *Hint injection* allows you to apply [index hints]({% link {{ page.version.version }}/table-expressions.md %}#force-index-selection) and [join hints](#join-hints) without modifying the original query text. This is useful when you cannot modify application code, need to optimize queries from ORMs or third-party applications, or want to test different hints without changing queries in production.
+
+Hint injection supports all inline hint types. Instead of relying on inline hints (such as `SELECT * FROM table@index_name` or `INNER HASH JOIN`), hint injection stores hints in the `system.statement_hints` table and automatically applies them to statements that match a [fingerprint]({% link {{ page.version.version }}/ui-statements-page.md %}#sql-statement-fingerprints).
+
+### Inject hints
+
+{{site.data.alerts.callout_info}}
+To inject hints using `crdb_internal.inject_hint()`, users must have the [`REPAIRCLUSTER`]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) privilege.
+{{site.data.alerts.end}}
+
+To inject a hint, invoke the `crdb_internal.inject_hint()` built-in function with two matching SQL statement fingerprints: a fingerprint identifying which queries to optimize, and a fingerprint with hints that must be applied:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT crdb_internal.inject_hint(
+  '{fingerprint}',
+  '{fingerprint with hints}'
+);
+~~~
+
+Both fingerprints in the function invocation **must** have the same syntactic structure and use underscores (`_`) as placeholders for constants. For example, use `SELECT * FROM users WHERE city = _` rather than `SELECT * FROM users WHERE city = 'new york'`.
+
+For example, the following invocation stores the `users_city_idx` index hint in the `system.statement_hints` table, returning a unique hint ID:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT crdb_internal.inject_hint(
+  'SELECT * FROM users WHERE city = _',
+  'SELECT * FROM users@users_city_idx WHERE city = _'
+);
+~~~
+
+~~~
+  crdb_internal.inject_hint
+-----------------------------
+        1143498239153340417
+~~~
+
+Afterward, any executed statement that matches the `SELECT * FROM users WHERE city = _` fingerprint will first be rewritten to use the `users_city_idx` index, regardless of the `city` value.
+
+{{site.data.alerts.callout_info}}
+If a query already contains explicit inline hints (such as `SELECT * FROM users@primary WHERE city = 'new york'`), those inline hints will take precedence over the injected hints.
+{{site.data.alerts.end}}
+
+To inject a specific [join algorithm](#supported-join-algorithms):
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT crdb_internal.inject_hint(
+  'SELECT * FROM users AS u INNER JOIN rides AS r ON u.id = r.rider_id',
+  'SELECT * FROM users AS u INNER MERGE JOIN rides AS r ON u.id = r.rider_id'
+);
+~~~
+
+{{site.data.alerts.callout_success}}
+If multiple hints exist for the same statement fingerprint, only the **most recently created hint** is applied. To replace an existing hint, you can create a new one for the same fingerprint, which will automatically take precedence.
+{{site.data.alerts.end}}
+
+### View injected hints
+
+{{site.data.alerts.callout_info}}
+To view hints using [`SHOW STATEMENT HINTS`]({% link {{ page.version.version }}/show-statement-hints.md %}), users must have the [`VIEWCLUSTERMETADATA`]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) privilege.
+{{site.data.alerts.end}}
+
+Use the [`SHOW STATEMENT HINTS`]({% link {{ page.version.version }}/show-statement-hints.md %}) statement to view hints for a specific statement fingerprint:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SHOW STATEMENT HINTS FOR 'SELECT * FROM users WHERE city = _' WITH DETAILS;
+~~~
+
+~~~
+        row_id        |            fingerprint             |      hint_type       |          created_at           |                              details
+----------------------+------------------------------------+----------------------+-------------------------------+--------------------------------------------------------------------
+  1143470380756697089 | SELECT * FROM users WHERE city = _ | rewrite_inline_hints | 2026-01-21 21:11:06.782818+00 | {"donorSql": "SELECT * FROM users@users_city_idx WHERE city = _"}
+~~~
+
+You can also query the `system.statement_hints` table directly to view all injected hints:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT row_id, fingerprint, created_at FROM system.statement_hints;
+~~~
+
+~~~
+        row_id        |                                     fingerprint                                      |          created_at
+----------------------+--------------------------------------------------------------------------------------+--------------------------------
+  1143498239153340417 | SELECT * FROM users WHERE city = _                                                   | 2026-01-21 23:32:48.490786+00
+  1143498276700913665 | SELECT * FROM users AS u INNER JOIN rides AS r ON u.id = r.rider_id                  | 2026-01-21 23:32:59.949608+00
+(2 rows)
+~~~
+
+To verify that injected hints are being applied to your queries, use [`EXPLAIN`]({% link {{ page.version.version }}/explain.md %}) or [`EXPLAIN ANALYZE`]({% link {{ page.version.version }}/explain-analyze.md %}). When hints from `system.statement_hints` are applied, the output includes a `statement hints count` field showing the number of hints applied. For example:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+EXPLAIN SELECT * FROM users WHERE city = 'new york';
+~~~
+
+~~~
+                                     info
+-------------------------------------------------------------------------------
+  distribution: local
+  statement hints count: 1
+
+  • scan
+    estimated row count: 6 (12% of the table; stats collected 22 minutes ago)
+    table: users@users_pkey
+    spans: [/'new york' - /'new york']
+~~~
+
+{{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}}
+
+### Remove injected hints
+
+To remove a hint by its hint ID:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+DELETE FROM system.statement_hints WHERE row_id = {hint_id};
+~~~
+
+To remove all hints for a specific query fingerprint:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+DELETE FROM system.statement_hints WHERE fingerprint = '{statement_fingerprint}';
+~~~
+
 ## Zigzag joins
 
 The optimizer may plan a zigzag join when there are at least **two secondary indexes on the same table** and the table is filtered in a query with at least two filters constraining different attributes to a constant. A zigzag join works by "zigzagging" back and forth between two indexes and returning only rows with matching primary keys within a specified range. For example:

src/current/v26.1/explain-analyze.md

@@ -68,6 +68,7 @@ Property        | Description
 `execution time` | The time it took for the final statement plan to complete.
 `distribution` | Whether the statement was distributed or local. If `distribution` is `full`, execution of the statement is performed by multiple nodes in parallel, then the results are returned by the gateway node. If `local`, the execution plan is performed only on the gateway node. Even if the execution plan is `local`, row data may be fetched from remote nodes, but the processing of the data is performed by the local node.
 `plan type` | The plan type used by the query: `generic, re-optimized`, `generic, reused`, or `custom`. For details, refer to [Query plan type]({% link {{ page.version.version }}/cost-based-optimizer.md %}#query-plan-type).
+`statement hints count` | <span class="version-tag">New in v26.1:</span> The number of [injected hints]({% link {{ page.version.version }}/cost-based-optimizer.md %}#hint-injection) from `system.statement_hints` applied to the statement. This field is only displayed when hints are applied.
 `vectorized` | Whether the [vectorized execution engine]({% link {{ page.version.version }}/vectorized-execution.md %}) was used in this statement.
 `rows decoded from KV` | The number of rows read from the [storage layer]({% link {{ page.version.version }}/architecture/storage-layer.md %}).
 `cumulative time spent in KV` | The total amount of time spent in the storage layer.

src/current/v26.1/explain.md

@@ -67,6 +67,7 @@ Node details | The properties, columns, and ordering details for the current sta
 |----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `distribution` | Whether the statement was distributed or local. If `distribution` is `full`, execution of the statement is performed by multiple nodes in parallel, then the results are returned by the gateway node. If `local`, the execution plan is performed only on the gateway node. Even if the execution plan is `local`, row data may be fetched from remote nodes, but the processing of the data is performed by the local node. |
 | `vectorized`   | Whether the [vectorized execution engine]({% link {{ page.version.version }}/vectorized-execution.md %}) was used in this statement.                                                                                                                                                                                                                                                                                                                              |
+| `statement hints count` | <span class="version-tag">New in v26.1:</span> The number of [injected hints]({% link {{ page.version.version }}/cost-based-optimizer.md %}#hint-injection) from `system.statement_hints` applied to the statement. This field is only displayed when hints are applied. |
 
 
 ### Statement plan tree properties