From 3a8b0d862b0294ce255af161409260e108830fc0 Mon Sep 17 00:00:00 2001
From: Ryan Kuo <8740013+taroface@users.noreply.github.com>
Date: Tue, 4 Jun 2024 09:34:14 -0400
Subject: [PATCH] set COPY QoS for admission control (#18614)
---
.../_includes/v23.2/misc/session-vars.md | 1 +
.../_includes/v24.1/misc/session-vars.md | 1 +
src/current/v23.2/admission-control.md | 19 ++++++++++++++++---
src/current/v24.1/admission-control.md | 19 ++++++++++++++++---
4 files changed, 34 insertions(+), 6 deletions(-)
diff --git a/src/current/_includes/v23.2/misc/session-vars.md b/src/current/_includes/v23.2/misc/session-vars.md
index 7d978c32894..7bc46843661 100644
--- a/src/current/_includes/v23.2/misc/session-vars.md
+++ b/src/current/_includes/v23.2/misc/session-vars.md
@@ -4,6 +4,7 @@
| `bytea_output` | The [mode for conversions from `STRING` to `BYTES`]({% link {{ page.version.version }}/bytes.md %}#supported-conversions). | hex | Yes | Yes |
| `client_min_messages` | The severity level of notices displayed in the [SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}). Accepted values include `debug5`, `debug4`, `debug3`, `debug2`, `debug1`, `log`, `notice`, `warning`, and `error`. | `notice` | Yes | Yes |
| `copy_from_atomic_enabled` | If set to `on`, [`COPY FROM`]({% link {{ page.version.version }}/copy-from.md %}) statements are committed atomically, matching PostgreSQL behavior. If set to `off`, `COPY FROM` statements are segmented into batches of 100 rows unless issued within an explicit transaction, matching the CockroachDB behavior in versions prior to v22.2. | `on` | Yes | Yes |
+| `copy_transaction_quality_of_service` | The default quality of service for [`COPY`]({% link {{ page.version.version }}/copy-from.md %}) statements in the current session. The supported options are `regular`, `critical`, and `background`. See [Set quality of service level]({% link {{ page.version.version }}/admission-control.md %}#copy-qos). | `background` | Yes | Yes |
| `cost_scans_with_default_col_size` | Whether to prevent the optimizer from considering column size when costing plans. | `false` | Yes | Yes |
| `crdb_version` | The version of CockroachDB. | CockroachDB OSS version
| No | Yes |
| `database` | The [current database]({% link {{ page.version.version }}/sql-name-resolution.md %}#current-database). | Database in connection string, or empty if not specified. | Yes | Yes |
diff --git a/src/current/_includes/v24.1/misc/session-vars.md b/src/current/_includes/v24.1/misc/session-vars.md
index 7b0e8441a9d..5d7c7c80248 100644
--- a/src/current/_includes/v24.1/misc/session-vars.md
+++ b/src/current/_includes/v24.1/misc/session-vars.md
@@ -5,6 +5,7 @@
| `bytea_output` | The [mode for conversions from `STRING` to `BYTES`]({% link {{ page.version.version }}/bytes.md %}#supported-conversions). | hex | Yes | Yes |
| `client_min_messages` | The severity level of notices displayed in the [SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}). Accepted values include `debug5`, `debug4`, `debug3`, `debug2`, `debug1`, `log`, `notice`, `warning`, and `error`. | `notice` | Yes | Yes |
| `copy_from_atomic_enabled` | If set to `on`, [`COPY FROM`]({% link {{ page.version.version }}/copy-from.md %}) statements are committed atomically, matching PostgreSQL behavior. If set to `off`, `COPY FROM` statements are segmented into batches of 100 rows unless issued within an explicit transaction, matching the CockroachDB behavior in versions prior to v22.2. | `on` | Yes | Yes |
+| `copy_transaction_quality_of_service` | The default quality of service for [`COPY`]({% link {{ page.version.version }}/copy-from.md %}) statements in the current session. The supported options are `regular`, `critical`, and `background`. See [Set quality of service level]({% link {{ page.version.version }}/admission-control.md %}#copy-qos). | `background` | Yes | Yes |
| `cost_scans_with_default_col_size` | Whether to prevent the optimizer from considering column size when costing plans. | `false` | Yes | Yes |
| `crdb_version` | The version of CockroachDB. | CockroachDB OSS version
| No | Yes |
| `database` | The [current database]({% link {{ page.version.version }}/sql-name-resolution.md %}#current-database). | Database in connection string, or empty if not specified. | Yes | Yes |
diff --git a/src/current/v23.2/admission-control.md b/src/current/v23.2/admission-control.md
index 48181aaf1c5..c4f9a6f07c4 100644
--- a/src/current/v23.2/admission-control.md
+++ b/src/current/v23.2/admission-control.md
@@ -46,6 +46,7 @@ Almost all database operations that use CPU or perform storage IO are controlled
- [Bulk data imports]({% link {{ page.version.version }}/import-into.md %}).
- [Backups]({% link {{ page.version.version }}/backup-and-restore-overview.md %}).
- [Schema changes]({% link {{ page.version.version }}/online-schema-changes.md %}), including index and column backfills (on both the [leaseholder replica]({% link {{ page.version.version }}/architecture/replication-layer.md %}#leases) and [follower replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#raft)).
+- [`COPY`]({% link {{ page.version.version }}/copy-from.md %}) statements.
- [Deletes]({% link {{ page.version.version }}/delete-data.md %}) (including deletes initiated by [row-level TTL jobs]({% link {{ page.version.version }}/row-level-ttl.md %}); the [selection queries]({% link {{ page.version.version }}/selection-queries.md %}) performed by TTL jobs are also subject to CPU admission control).
- [Follower replication work]({% link {{ page.version.version }}/architecture/replication-layer.md %}#raft).
- [Raft log entries being written to disk]({% link {{ page.version.version }}/architecture/replication-layer.md %}#raft).
@@ -80,7 +81,7 @@ The transaction start time is used within the priority queue and gives preferenc
### Set quality of service level for a session
-In an overload scenario where CockroachDB cannot service all requests, you can identify which requests should be prioritized. This is often referred to as _quality of service_ (QoS). Admission control queues work throughout the system. To set the quality of service level on the admission control queues on behalf of SQL requests submitted in a session, use the `default_transaction_quality_of_service` [session variable]({% link {{ page.version.version }}/set-vars.md %}#default-transaction-quality-of-service). The valid values are `critical`, `background`, and `regular`. Admission control must be enabled for this setting to have an effect.
+In an overload scenario where CockroachDB cannot service all requests, you can identify which requests should be prioritized. This is often referred to as _quality of service_ (QoS). Admission control queues work throughout the system. To set the quality of service level on the admission control queues on behalf of SQL requests submitted in a session, use the [`default_transaction_quality_of_service`]({% link {{ page.version.version }}/set-vars.md %}#default-transaction-quality-of-service) session variable. The valid values are `critical`, `background`, and `regular`. Admission control must be enabled for this setting to have an effect.
To increase the priority of subsequent SQL requests, run:
@@ -103,14 +104,26 @@ To reset the priority to the default session setting (in between background and
SET default_transaction_quality_of_service=regular;
~~~
+
+
+The quality of service for [`COPY`]({% link {{ page.version.version }}/copy-from.md %}) statements is configured separately with the [`copy_transaction_quality_of_service`]({% link {{ page.version.version }}/set-vars.md %}#copy-transaction-quality-of-service) session variable, which defaults to `background`.
+
+To increase the priority of subsequent `COPY` statements, run:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SET copy_transaction_quality_of_service=critical;
+~~~
+
### Set quality of service level for a transaction
-To set the quality of service level for a single [transaction]({% link {{ page.version.version }}/transactions.md %}), set the [`default_transaction_quality_of_service` session variable]({% link {{ page.version.version }}/set-vars.md %}#default-transaction-quality-of-service) for just that transaction using the [`SET LOCAL`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction) statement inside a [`BEGIN`]({% link {{ page.version.version }}/begin-transaction.md %}) ... [`COMMIT`]({% link {{ page.version.version }}/commit-transaction.md %}) block as shown below. The valid values are `critical`, `background`, and `regular`.
+To set the quality of service level for a single [transaction]({% link {{ page.version.version }}/transactions.md %}), set the [`default_transaction_quality_of_service`]({% link {{ page.version.version }}/set-vars.md %}#default-transaction-quality-of-service) and/or [`copy_transaction_quality_of_service`]({% link {{ page.version.version }}/set-vars.md %}#copy-transaction-quality-of-service) session variable for just that transaction using the [`SET LOCAL`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction) statement inside a [`BEGIN`]({% link {{ page.version.version }}/begin-transaction.md %}) ... [`COMMIT`]({% link {{ page.version.version }}/commit-transaction.md %}) block, as shown in the following example. The valid values are `critical`, `background`, and `regular`.
{% include_cached copy-clipboard.html %}
~~~ sql
BEGIN;
-SET LOCAL default_transaction_quality_of_service = 'regular'; -- Edit to desired level
+SET LOCAL default_transaction_quality_of_service = 'regular'; -- Edit transaction QoS to desired level
+SET LOCAL copy_transaction_quality_of_service = 'regular'; -- Edit COPY QoS to desired level
-- Statements to run in this transaction go here
COMMIT;
~~~
diff --git a/src/current/v24.1/admission-control.md b/src/current/v24.1/admission-control.md
index 98a7b70acb3..b7678ec4ac0 100644
--- a/src/current/v24.1/admission-control.md
+++ b/src/current/v24.1/admission-control.md
@@ -46,6 +46,7 @@ Almost all database operations that use CPU or perform storage IO are controlled
- [Bulk data imports]({% link {{ page.version.version }}/import-into.md %}).
- [Backups]({% link {{ page.version.version }}/backup-and-restore-overview.md %}).
- [Schema changes]({% link {{ page.version.version }}/online-schema-changes.md %}), including index and column backfills (on both the [leaseholder replica]({% link {{ page.version.version }}/architecture/replication-layer.md %}#leases) and [follower replicas]({% link {{ page.version.version }}/architecture/replication-layer.md %}#raft)).
+- [`COPY`]({% link {{ page.version.version }}/copy-from.md %}) statements.
- [Deletes]({% link {{ page.version.version }}/delete-data.md %}) (including deletes initiated by [row-level TTL jobs]({% link {{ page.version.version }}/row-level-ttl.md %}); the [selection queries]({% link {{ page.version.version }}/selection-queries.md %}) performed by TTL jobs are also subject to CPU admission control).
- [Follower replication work]({% link {{ page.version.version }}/architecture/replication-layer.md %}#raft).
- [Raft log entries being written to disk]({% link {{ page.version.version }}/architecture/replication-layer.md %}#raft).
@@ -80,7 +81,7 @@ The transaction start time is used within the priority queue and gives preferenc
### Set quality of service level for a session
-In an overload scenario where CockroachDB cannot service all requests, you can identify which requests should be prioritized. This is often referred to as _quality of service_ (QoS). Admission control queues work throughout the system. To set the quality of service level on the admission control queues on behalf of SQL requests submitted in a session, use the `default_transaction_quality_of_service` [session variable]({% link {{ page.version.version }}/set-vars.md %}#default-transaction-quality-of-service). The valid values are `critical`, `background`, and `regular`. Admission control must be enabled for this setting to have an effect.
+In an overload scenario where CockroachDB cannot service all requests, you can identify which requests should be prioritized. This is often referred to as _quality of service_ (QoS). Admission control queues work throughout the system. To set the quality of service level on the admission control queues on behalf of SQL requests submitted in a session, use the [`default_transaction_quality_of_service`]({% link {{ page.version.version }}/set-vars.md %}#default-transaction-quality-of-service) session variable. The valid values are `critical`, `background`, and `regular`. Admission control must be enabled for this setting to have an effect.
To increase the priority of subsequent SQL requests, run:
@@ -103,14 +104,26 @@ To reset the priority to the default session setting (in between background and
SET default_transaction_quality_of_service=regular;
~~~
+
+
+The quality of service for [`COPY`]({% link {{ page.version.version }}/copy-from.md %}) statements is configured separately with the [`copy_transaction_quality_of_service`]({% link {{ page.version.version }}/set-vars.md %}#copy-transaction-quality-of-service) session variable, which defaults to `background`.
+
+To increase the priority of subsequent `COPY` statements, run:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SET copy_transaction_quality_of_service=critical;
+~~~
+
### Set quality of service level for a transaction
-To set the quality of service level for a single [transaction]({% link {{ page.version.version }}/transactions.md %}), set the [`default_transaction_quality_of_service` session variable]({% link {{ page.version.version }}/set-vars.md %}#default-transaction-quality-of-service) for just that transaction using the [`SET LOCAL`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction) statement inside a [`BEGIN`]({% link {{ page.version.version }}/begin-transaction.md %}) ... [`COMMIT`]({% link {{ page.version.version }}/commit-transaction.md %}) block as shown below. The valid values are `critical`, `background`, and `regular`.
+To set the quality of service level for a single [transaction]({% link {{ page.version.version }}/transactions.md %}), set the [`default_transaction_quality_of_service`]({% link {{ page.version.version }}/set-vars.md %}#default-transaction-quality-of-service) and/or [`copy_transaction_quality_of_service`]({% link {{ page.version.version }}/set-vars.md %}#copy-transaction-quality-of-service) session variable for just that transaction using the [`SET LOCAL`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction) statement inside a [`BEGIN`]({% link {{ page.version.version }}/begin-transaction.md %}) ... [`COMMIT`]({% link {{ page.version.version }}/commit-transaction.md %}) block, as shown in the following example. The valid values are `critical`, `background`, and `regular`.
{% include_cached copy-clipboard.html %}
~~~ sql
BEGIN;
-SET LOCAL default_transaction_quality_of_service = 'regular'; -- Edit to desired level
+SET LOCAL default_transaction_quality_of_service = 'regular'; -- Edit transaction QoS to desired level
+SET LOCAL copy_transaction_quality_of_service = 'regular'; -- Edit COPY QoS to desired level
-- Statements to run in this transaction go here
COMMIT;
~~~