consolidate guidance on avoiding full scans; update session vars (#18338

)

* consolidate guidance on avoiding full scans; update session vars

src/current/_includes/v22.2/misc/session-vars.md

@@ -14,7 +14,7 @@
 | <a name="default-transaction-quality-of-service"></a> `default_transaction_quality_of_service` | The default transaction quality of service for the current session. The supported options are `regular`, `critical`, and `background`. See [Set quality of service level](admission-control.html#set-quality-of-service-level-for-a-session). | `regular` | Yes | Yes |
 | <a name="default-transaction-read-only"></a> `default_transaction_read_only` | The default transaction access mode for the current session. <br/>If set to `on`, only read operations are allowed in transactions in the current session; if set to `off`, both read and write operations are allowed. See [`SET TRANSACTION`](set-transaction.html) for more details. | `off` | Yes | Yes |
 | <a name="default-transaction-use-follower-reads"></a> `default_transaction_use_follower_reads` | If set to on, all read-only transactions use [`AS OF SYSTEM TIME follower_read_timestamp()`](as-of-system-time.html) to allow the transaction to use follower reads. <br/>If set to `off`, read-only transactions will only use follower reads if an `AS OF SYSTEM TIME` clause is specified in the statement, with an interval of at least 4.8 seconds. | `off` | Yes | Yes |
-| <a name="disallow-full-table-scans"></a> `disallow_full_table_scans` | If set to `on`, all queries that have planned a full table or full secondary index scan will return an error message. This setting does not apply to internal queries, which may plan full table or index scans without checking the session variable. | `off` | Yes | Yes |
+| <a id="disallow-full-table-scans"></a> `disallow_full_table_scans` | If set to `on`, queries on "large" tables with a row count greater than [`large_full_scan_rows`](#large-full-scan-rows) will not use full table or index scans. If no other query plan is possible, queries will return an error message. This setting does not apply to internal queries, which may plan full table or index scans without checking the session variable. | `off` | Yes | Yes |
 | <a name="distsql"></a> `distsql` | The query distribution mode for the session. By default, CockroachDB determines which queries are faster to execute if distributed across multiple nodes, and all other queries are run through the gateway node. | `auto` | Yes | Yes |
 | <a name="enable-auto-rehoming"></a> `enable_auto_rehoming` | When enabled, the [home regions](alter-table.html#crdb_region) of rows in [`REGIONAL BY ROW`](alter-table.html#set-the-table-locality-to-regional-by-row) tables are automatically set to the region of the [gateway node](ui-sessions-page.html#session-details-gateway-node) from which any [`UPDATE`](update.html) or [`UPSERT`](upsert.html) statements that operate on those rows originate. | `off` | Yes | Yes |
 | <a name="enable-implicit-select-for-update"></a> `enable_implicit_select_for_update` | Indicates whether [`UPDATE`](update.html) and [`UPSERT`](upsert.html) statements acquire locks using the `FOR UPDATE` locking mode during their initial row scan, which improves performance for contended workloads.<br/><br/>For more information about how `FOR UPDATE` locking works, see the documentation for [`SELECT FOR UPDATE`](select-for-update.html). | `on` | Yes | Yes |
@@ -31,7 +31,7 @@
 | <a name="inject-retry-errors-enabled"></a> `inject_retry_errors_enabled` | If `true`, any statement executed inside of an explicit transaction (with the exception of [`SET`](set-vars.html) statements) will return a transaction retry error. If the client retries the transaction using the special [`cockroach_restart SAVEPOINT` name](savepoint.html#savepoints-for-client-side-transaction-retries), after the 3rd retry error, the transaction will proceed as normal. Otherwise, the errors will continue until `inject_retry_errors_enabled` is set to `false`. For more details, see [Testing transaction retry logic](transactions.html#testing-transaction-retry-logic). | `false` | Yes | Yes |
 | <a name="intervalstyle"></a> `intervalstyle` | The input string format for [`INTERVAL`](interval.html) values. Accepted values include `postgres`, `iso_8601`, and `sql_standard`. | The value set by the `sql.defaults.intervalstyle` [cluster setting](cluster-settings.html) (`postgres`, by default). | Yes | Yes |
 | <a name="is-superuser"></a> `is_superuser` | If `on` or `true`, the current user is a member of the [`admin` role](security-reference/authorization.html#admin-role). | User-dependent | No | Yes |
-| <a name="large-full-scan-rows"></a> `large_full_scan_rows` | Determines which tables are considered "large" such that `disallow_full_table_scans` rejects full table or index scans of "large" tables. The default value is `1000`. To reject all full table or index scans, set to `0`. | User-dependent | No | Yes |
+| <a id="large-full-scan-rows"></a> `large_full_scan_rows` | Determines which tables are considered "large" such that `disallow_full_table_scans` prevents queries from performing full table or index scans on those tables. The default value is `1000`. To prevent all full table or index scans, set to `0`. | User-dependent | No | Yes |
 | <a name="locality"></a> `locality` | The location of the node.<br/></br>For more information, see [Locality](cockroach-start.html#locality). | Node-dependent | No | Yes |
 | <a name="lock-timeout"></a> `lock_timeout` | The amount of time a query can spend acquiring or waiting for a single [row-level lock](architecture/transaction-layer.html#concurrency-control). <br/>In CockroachDB, unlike in PostgreSQL, non-locking reads wait for conflicting locks to be released. As a result, the `lock_timeout` configuration applies to writes, and to locking and non-locking reads in read-write and read-only transactions. <br/>If `lock_timeout = 0`, queries do not timeout due to lock acquisitions. | The value set by the `sql.defaults.lock_timeout` [cluster setting](cluster-settings.html) (`0`, by default) | Yes | Yes |
 | <a name="node-id"></a> `node_id` | The ID of the node currently connected to. <br/><br/>This variable is particularly useful for verifying load balanced connections. | Node-dependent | No | Yes |

src/current/_includes/v23.1/misc/session-vars.md

@@ -15,7 +15,7 @@
 | <a id="default-transaction-quality-of-service"></a> `default_transaction_quality_of_service` | The default transaction quality of service for the current session. The supported options are `regular`, `critical`, and `background`. See [Set quality of service level]({% link {{ page.version.version }}/admission-control.md %}#set-quality-of-service-level-for-a-session). | `regular` | Yes | Yes |
 | <a id="default-transaction-read-only"></a> `default_transaction_read_only` | The default transaction access mode for the current session. <br/>If set to `on`, only read operations are allowed in transactions in the current session; if set to `off`, both read and write operations are allowed. See [`SET TRANSACTION`]({% link {{ page.version.version }}/set-transaction.md %}) for more details. | `off` | Yes | Yes |
 | <a id="default-transaction-use-follower-reads"></a> `default_transaction_use_follower_reads` | If set to on, all read-only transactions use [`AS OF SYSTEM TIME follower_read_timestamp()`]({% link {{ page.version.version }}/as-of-system-time.md %}) to allow the transaction to use follower reads. <br/>If set to `off`, read-only transactions will only use follower reads if an `AS OF SYSTEM TIME` clause is specified in the statement, with an interval of at least 4.8 seconds. | `off` | Yes | Yes |
-| <a id="disallow-full-table-scans"></a> `disallow_full_table_scans` | If set to `on`, all queries that have planned a full table or full secondary index scan will return an error message. This setting does not apply to internal queries, which may plan full table or index scans without checking the session variable. | `off` | Yes | Yes |
+| <a id="disallow-full-table-scans"></a> `disallow_full_table_scans` | If set to `on`, queries on "large" tables with a row count greater than [`large_full_scan_rows`](#large-full-scan-rows) will not use full table or index scans. If no other query plan is possible, queries will return an error message. This setting does not apply to internal queries, which may plan full table or index scans without checking the session variable. | `off` | Yes | Yes |
 | <a id="distsql"></a> `distsql` | The query distribution mode for the session. By default, CockroachDB determines which queries are faster to execute if distributed across multiple nodes, and all other queries are run through the gateway node. | `auto` | Yes | Yes |
 | <a id="enable-auto-rehoming"></a> `enable_auto_rehoming` | When enabled, the [home regions]({% link {{ page.version.version }}/alter-table.md %}#crdb_region) of rows in [`REGIONAL BY ROW`]({% link {{ page.version.version }}/alter-table.md %}#set-the-table-locality-to-regional-by-row) tables are automatically set to the region of the [gateway node]({% link {{ page.version.version }}/ui-sessions-page.md %}#session-details-gateway-node) from which any [`UPDATE`]({% link {{ page.version.version }}/update.md %}) or [`UPSERT`]({% link {{ page.version.version }}/upsert.md %}) statements that operate on those rows originate. | `off` | Yes | Yes |
 | <a id="enable-implicit-select-for-update"></a> `enable_implicit_select_for_update` | Indicates whether [`UPDATE`]({% link {{ page.version.version }}/update.md %}) and [`UPSERT`]({% link {{ page.version.version }}/upsert.md %}) statements acquire locks using the `FOR UPDATE` locking mode during their initial row scan, which improves performance for contended workloads.<br/><br/>For more information about how `FOR UPDATE` locking works, see the documentation for [`SELECT FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}). | `on` | Yes | Yes |
@@ -35,7 +35,7 @@
 | <a id="inject-retry-errors-enabled"></a> `inject_retry_errors_enabled` | If `true`, any statement executed inside of an explicit transaction (with the exception of [`SET`]({% link {{ page.version.version }}/set-vars.md %}) statements) will return a transaction retry error. If the client retries the transaction using the special [`cockroach_restart SAVEPOINT` name]({% link {{ page.version.version }}/savepoint.md %}#savepoints-for-client-side-transaction-retries), after the 3rd retry error, the transaction will proceed as normal. Otherwise, the errors will continue until `inject_retry_errors_enabled` is set to `false`. For more details, see [Test transaction retry logic]({% link {{ page.version.version }}/transaction-retry-error-example.md %}#test-transaction-retry-logic). | `false` | Yes | Yes |
 | <a id="intervalstyle"></a> `intervalstyle` | The input string format for [`INTERVAL`]({% link {{ page.version.version }}/interval.md %}) values. Accepted values include `postgres`, `iso_8601`, and `sql_standard`. | The value set by the `sql.defaults.intervalstyle` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) (`postgres`, by default). | Yes | Yes |
 | <a id="is-superuser"></a> `is_superuser` | If `on` or `true`, the current user is a member of the [`admin` role]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role). | User-dependent | No | Yes |
-| <a id="large-full-scan-rows"></a> `large_full_scan_rows` | Determines which tables are considered "large" such that `disallow_full_table_scans` rejects full table or index scans of "large" tables. The default value is `1000`. To reject all full table or index scans, set to `0`. | User-dependent | No | Yes |
+| <a id="large-full-scan-rows"></a> `large_full_scan_rows` | Determines which tables are considered "large" such that `disallow_full_table_scans` prevents queries from performing full table or index scans on those tables. The default value is `1000`. To prevent all full table or index scans, set to `0`. | User-dependent | No | Yes |
 | <a id="locality"></a> `locality` | The location of the node.<br/></br>For more information, see [Locality]({% link {{ page.version.version }}/cockroach-start.md %}#locality). | Node-dependent | No | Yes |
 | <a id="lock-timeout"></a> `lock_timeout` | The amount of time a query can spend acquiring or waiting for a single [row-level lock]({% link {{ page.version.version }}/architecture/transaction-layer.md %}#concurrency-control). <br/>In CockroachDB, unlike in PostgreSQL, non-locking reads wait for conflicting locks to be released. As a result, the `lock_timeout` configuration applies to writes, and to locking and non-locking reads in read-write and read-only transactions. <br/>If `lock_timeout = 0`, queries do not timeout due to lock acquisitions. | The value set by the `sql.defaults.lock_timeout` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) (`0`, by default) | Yes | Yes |
 | <a id="multiple-active-portals-enabled"></a> `multiple_active_portals_enabled` | Whether to enable the [multiple active portals]({% link {{ page.version.version }}/postgresql-compatibility.md %}#multiple-active-portals) pgwire feature. | `false` | Yes | Yes |

src/current/_includes/v23.2/misc/force-index-selection.md

@@ -135,11 +135,8 @@ Time: 1ms total (execution 1ms / network 0ms)
 
 ##### Prevent full scan
 
-To prevent the optimizer from planning a full scan for a table, specify the `NO_FULL_SCAN` index hint. For example:
+{% include {{ page.version.version }}/sql/no-full-scan.md %}
 
-~~~sql
-SELECT * FROM table_name@{NO_FULL_SCAN};
-~~~
-
-To prevent a full scan of a [partial index](#force-partial-index-scan), you must specify `NO_FULL_SCAN` _in combination with_ the partial index using `FORCE_INDEX=index_name`.
-If you specify only `NO_FULL_SCAN`, a full scan of a partial index may be planned.
+{{site.data.alerts.callout_success}}
+For other ways to prevent full table scans, refer to [Prevent the optimizer from planning full scans]({% link {{ page.version.version }}/performance-best-practices-overview.md %}#prevent-the-optimizer-from-planning-full-scans).
+{{site.data.alerts.end}}