Skip to content

Clarify TTL storage parameter defaults #20040

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 4, 2025
Merged

Clarify TTL storage parameter defaults #20040

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions src/current/v23.2/row-level-ttl.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,10 +147,10 @@ The settings that control the behavior of Row-Level TTL are provided using [stor
| `ttl_expiration_expression` <a name="param-ttl-expiration-expression"></a> | **Recommended**. SQL expression that defines the TTL expiration. Must evaluate to a [`TIMESTAMPTZ`]({% link {{ page.version.version }}/timestamp.md %}). This and/or [`ttl_expire_after`](#param-ttl-expire-after) are required to enable TTL. This parameter is useful when you want to set the TTL for individual rows in the table. For an example, see [Create a table with a `ttl_expiration_expression`](#create-a-table-with-a-ttl_expiration_expression). | N/A |
| `ttl_expire_after` <a name="param-ttl-expire-after"></a> | The [interval]({% link {{ page.version.version }}/interval.md %}) when a TTL will expire. This and/or [`ttl_expiration_expression`](#param-ttl-expiration-expression) are required to enable TTL. Minimum value: `'1 microsecond'`. | N/A |
| `ttl` <a name="param-ttl"></a> | Signifies if a TTL is active. Automatically set. | N/A |
| `ttl_select_batch_size` | How many rows to [select]({% link {{ page.version.version }}/select-clause.md %}) at one time during the row expiration check. Default: 500. Minimum: 1. | `sql.ttl.default_select_batch_size` |
| `ttl_delete_batch_size` <a name="param-ttl-delete-batch-size"></a> | How many rows to [delete]({% link {{ page.version.version }}/delete.md %}) at a time. Default: 100. Minimum: 1. | `sql.ttl.default_delete_batch_size` |
| `ttl_select_rate_limit` | Maximum number of rows to be selected per second (rate limit). Default: 0 (no limit). <br/><br/> Note: The rate limit is applied per leaseholder per table. In practice, it will vary based on the number of [ranges]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-range) and [leaseholders]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-leaseholder). <br/> For example, if this variable is set to 500, and a table `public.foo` has its ranges spread across 3 leaseholders, then the cluster-wide rate limit for `public.foo` is 500 x 3 = 1500. <br/> To determine the number of leaseholders for some table `public.bar` on CockroachDB v23.1+, issue the following query against the output of [`SHOW RANGES ... WITH DETAILS`]({% link {{ page.version.version }}/show-ranges.md %}#show-ranges-for-a-table-with-details): <br/> `SELECT count(DISTINCT lease_holder) FROM [SHOW RANGES FROM TABLE public.bar WITH DETAILS];` | `sql.ttl.default_select_rate_limit` |
| `ttl_delete_rate_limit` | Maximum number of rows to be deleted per second (rate limit). Default: 100 (Set to 0 for no limit). <br/><br/> Note: The rate limit is applied per leaseholder per table. In practice, it will vary based on the number of [ranges]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-range) and [leaseholders]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-leaseholder). <br/> For example, if this variable is set to 500, and a table `public.foo` has its ranges spread across 3 leaseholders, then the cluster-wide rate limit for `public.foo` is 500 x 3 = 1500. <br/> To determine the number of leaseholders for some table `public.bar` on CockroachDB v23.1+, issue the following query against the output of [`SHOW RANGES ... WITH DETAILS`]({% link {{ page.version.version }}/show-ranges.md %}#show-ranges-for-a-table-with-details): <br/> `SELECT count(DISTINCT lease_holder) FROM [SHOW RANGES FROM TABLE public.bar WITH DETAILS];` | `sql.ttl.default_delete_rate_limit` |
| `ttl_select_batch_size` | How many rows to [select]({% link {{ page.version.version }}/select-clause.md %}) at one time during the row expiration check. Defaults to the value of the associated cluster setting if unset. | `sql.ttl.default_select_batch_size` <br/> Default: 500. Minimum: 1. |
| `ttl_delete_batch_size` <a name="param-ttl-delete-batch-size"></a> | How many rows to [delete]({% link {{ page.version.version }}/delete.md %}) at a time. Defaults to the value of the associated cluster setting if unset.| `sql.ttl.default_delete_batch_size` <br/> Default: 100. Minimum: 1. |
| `ttl_select_rate_limit` | Maximum number of rows to be selected per second (rate limit). Defaults to the value of the associated cluster setting if unset. <br/><br/> Note: The rate limit is applied per leaseholder per table. In practice, it will vary based on the number of [ranges]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-range) and [leaseholders]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-leaseholder). <br/> For example, if this variable is set to 500, and a table `public.foo` has its ranges spread across 3 leaseholders, then the cluster-wide rate limit for `public.foo` is 500 x 3 = 1500. <br/> To determine the number of leaseholders for some table `public.bar` on CockroachDB v23.1+, issue the following query against the output of [`SHOW RANGES ... WITH DETAILS`]({% link {{ page.version.version }}/show-ranges.md %}#show-ranges-for-a-table-with-details): <br/> `SELECT count(DISTINCT lease_holder) FROM [SHOW RANGES FROM TABLE public.bar WITH DETAILS];` | `sql.ttl.default_select_rate_limit` <br/> Default: 0. Minimum: 0 (unlimited).|
| `ttl_delete_rate_limit` | Maximum number of rows to be deleted per second (rate limit). Defaults to the value of the associated cluster setting if unset. <br/><br/> Note: The rate limit is applied per leaseholder per table. In practice, it will vary based on the number of [ranges]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-range) and [leaseholders]({% link {{ page.version.version }}/architecture/overview.md %}#architecture-leaseholder). <br/> For example, if this variable is set to 500, and a table `public.foo` has its ranges spread across 3 leaseholders, then the cluster-wide rate limit for `public.foo` is 500 x 3 = 1500. <br/> To determine the number of leaseholders for some table `public.bar` on CockroachDB v23.1+, issue the following query against the output of [`SHOW RANGES ... WITH DETAILS`]({% link {{ page.version.version }}/show-ranges.md %}#show-ranges-for-a-table-with-details): <br/> `SELECT count(DISTINCT lease_holder) FROM [SHOW RANGES FROM TABLE public.bar WITH DETAILS];` | `sql.ttl.default_delete_rate_limit` <br/> Default: 100. Minimum: 0 (unlimited).|
| `ttl_row_stats_poll_interval` | If set, counts rows and expired rows on the table to report as Prometheus metrics while the TTL job is running. Unset by default, meaning no stats are fetched and reported. | N/A |
| `ttl_pause` <a name="param-ttl-pause"></a> | If set, stops the TTL job from executing. | N/A |
| `ttl_job_cron` <a name="param-ttl-job-cron"></a> | Frequency at which the TTL job runs, specified using [CRON syntax](https://cron.help). <span class="version-tag">New in v23.2:</span> Default: `'@daily'` (was `'@hourly'`). | N/A |
Expand Down Expand Up @@ -516,8 +516,9 @@ WITH x AS (SHOW CLUSTER SETTINGS) SELECT * FROM x WHERE variable LIKE 'sql.ttl.%
sql.ttl.default_delete_batch_size | 100 | i | default amount of rows to delete in a single query during a TTL job
sql.ttl.default_delete_rate_limit | 100 | i | default delete rate limit for all TTL jobs. Use 0 to signify no rate limit.
sql.ttl.default_select_batch_size | 500 | i | default amount of rows to select in a single query during a TTL job
sql.ttl.default_select_rate_limit | 0 | i | default select rate limit for all TTL jobs. Use 0 to signify no rate limit.
sql.ttl.job.enabled | false | b | whether the TTL job is enabled
(5 rows)
(6 rows)
~~~

## Common errors
Expand Down
Loading
Loading