From f83f1be70415c50c2f417968c2e5c079712698b1 Mon Sep 17 00:00:00 2001 From: Semyon Yentsov Date: Mon, 18 Nov 2024 11:46:50 +0000 Subject: [PATCH 1/4] include tiering configuration in ttl docs --- ydb/docs/en/core/concepts/_includes/ttl.md | 59 ++++++++++++++++- .../concepts/datamodel/_includes/table.md | 2 +- ydb/docs/ru/core/concepts/_includes/ttl.md | 63 +++++++++++++++++-- .../concepts/datamodel/_includes/table.md | 2 +- 4 files changed, 116 insertions(+), 10 deletions(-) diff --git a/ydb/docs/en/core/concepts/_includes/ttl.md b/ydb/docs/en/core/concepts/_includes/ttl.md index 32c7782c2c23..0b1a0e40cdb2 100644 --- a/ydb/docs/en/core/concepts/_includes/ttl.md +++ b/ydb/docs/en/core/concepts/_includes/ttl.md @@ -4,7 +4,21 @@ This section describes how the TTL mechanism works and what its limits are. It a ## How it works {#how-it-works} -{{ ydb-short-name }} allows you to specify a TTL column in both [row-oriented](../datamodel/table.md#row-oriented-tables) and [column-oriented](../datamodel/table.md#column-oriented-tables) tables. Values in TTL columns determine the table rows lifetime. +The table's TTL is defined by a sequence of storage tiers. For each tier in the sequence, an expression is specified; when the expression triggers, the row is assigned that tier. TTL automatically performs the specified action when a tier is assigned to a row: it moves the row to external storage or deletes it. External storage is represented by the external data source object. Deletion can only be specified for the last tier. + +{% note info %} + +Currently, only an Object Storage is available as external storage. + +{% endnote %} + +{{ ydb-short-name }} allows you to specify, for both row-oriented and columnar tables, a column (TTL column) whose values are used in TTL expressions. The expression triggers when the specified number of seconds have passed since the time recorded in the TTL column. + +{% note info %} + +Automatic data eviction to external storage is available only for column-oriented tables. For row-oriented tables, this functionality is under development. + +{% endnote %} {% note warning %} @@ -15,12 +29,12 @@ An item with the `NULL` value in the TTL column is never deleted. The timestamp for deleting a table item is determined by the formula: ```text -expiration_time = valueof(ttl_column) + expire_after_seconds +eviction_time = valueof(ttl_column) + evict_after_seconds ``` {% note info %} -TTL doesn't guarantee that the item will be deleted exactly at `expiration_time`, it might happen later. If it's important to exclude logically obsolete but not yet physically deleted items from the selection, use query-level filtering. +TTL doesn't guarantee that the item will be deleted exactly at `eviction_time`, it might happen later. If it's important to exclude logically obsolete but not yet physically deleted items from the selection, use query-level filtering. {% endnote %} @@ -176,6 +190,45 @@ The example below shows how to use the `modified_at` column with a numeric type {% endlist %} +### Enabling eviction to Object Storage for an existing table {#enable-tiering-on-existing-tables} + +{% note info %} + +This functionality is only available for column-oriented tables. For row-oriented tables, this functionality is under development. + +{% endnote %} + +In the following example, rows of the table `mytable` will be moved to the bucket described in the external data source `/Root/s3_cold_data` one hour after the time recorded in the column `created_at`, and will be deleted after 24 hours: + +{% list tabs group=tool %} + +- YQL + + ```yql + ALTER TABLE `mytable` SET (TTL = Interval("PT1H") TO EXTERNAL DATA SOURCE `/Root/s3_cold_data`, Interval(PT24H) DELETE ON modified_at AS SECONDS); + ``` + +{% if oss == true %} + +- C++ + + ```c++ + session.AlterTable( + "mytable", + TAlterTableSettings() + .BeginAlterTtlSettings() + .Set("created_at", { + TTtlTierSettings(TDuration::Hours(1), TTtlEvictToExternalStorageAction("/Root/s3_cold_data")), + TTtlTierSettings(TDuration::Hours(24), TTtlDeleteAction("/Root/s3_cold_data")) + }) + .EndAlterTtlSettings() + ); + ``` + +{% endif %} + +{% endlist %} + ### Enabling TTL for a newly created table {#enable-for-new-table} For a newly created table, you can pass TTL settings along with the table description: diff --git a/ydb/docs/en/core/concepts/datamodel/_includes/table.md b/ydb/docs/en/core/concepts/datamodel/_includes/table.md index 2c0fb6f79ccf..5abd4dbdb9e4 100644 --- a/ydb/docs/en/core/concepts/datamodel/_includes/table.md +++ b/ydb/docs/en/core/concepts/datamodel/_includes/table.md @@ -134,7 +134,7 @@ If there are multiple followers, their delay from the leader may vary: although | Parameter name | Type | Acceptable values | Update capability | Reset capability | | ------------- | --- | ------------------- | --------------------- | ------------------ | -| `TTL` | Expression | `Interval("") ON [AS ]` | Yes | Yes | +| `TTL` | Expression | `, ..., ON [AS ]`, где `` — `Inteval("") TO EXTERNAL DATA SOURCE ` или `Inteval("") TO DELETE`. Краткая форма: `Interval("") ON [AS ]` — задаёт удаление данных | Да | Да | Where `` is a unit of measurement, specified only for column with a [numeric type](../../../concepts/ttl.md#restrictions): diff --git a/ydb/docs/ru/core/concepts/_includes/ttl.md b/ydb/docs/ru/core/concepts/_includes/ttl.md index 24600bbd6a01..6a799c707331 100644 --- a/ydb/docs/ru/core/concepts/_includes/ttl.md +++ b/ydb/docs/ru/core/concepts/_includes/ttl.md @@ -4,23 +4,37 @@ ## Принцип работы {#how-it-works} -{{ ydb-short-name }} позволяет указать для строковых и колоночных таблиц колонку (TTL-колонка), значения которой будут использоваться для определения времени жизни строк. TTL автоматически удаляет из таблицы строки, когда проходит указанное количество секунд от времени, записанного в TTL-колонку. +TTL таблицы задаётся последовательностью тиров хранения. Для каждого тира в последовательности задаётся выражение, при срабатывании которого строке присваивается данный тир. TTL автоматически выполнит заданное действие, когда строке будет присвоен тир: перенесёт строку во внешнее хранилище или удалит её. Внешние хранилища представляются объектом [external data source](https://ydb.tech/docs/ru/concepts/datamodel/external_data_source). Удаление может быть задано только для последнего тира. + +{% note info %} + +На данный момент, в качестве внешнего хранилища доступен только Object Storage. + +{% endnote %} + +{{ ydb-short-name }} позволяет указать для строковых и колоночных таблиц колонку (TTL-колонка), значения которой будут использоваться в TTL-выражениях. Выражение срабатывает, когда проходит указанное количество секунд от времени, записанного в TTL-колонку. + +{% note info %} + +Автоматическое перемещение данных во внешние хранилища доступно только для колоночных таблиц. Для строчных таблиц функциональность находится в разработке. + +{% endnote %} {% note warning %} -Строка с `NULL` в TTL-колонке никогда не будет удалена. +Строка с `NULL` в TTL-колонке никогда не сменит тир хранения. {% endnote %} -Момент времени, когда строка таблицы может быть удалена, определяется по следующей формуле: +Момент времени, когда срабатывает TTL-выражение, определяется по следующей формуле: ```text -expiration_time = valueof(ttl_column) + expire_after_seconds +eviction_time = valueof(ttl_column) + evict_after_seconds ``` {% note info %} -Не гарантируется, что удаление произойдет именно в `expiration_time` — оно может случиться позже. Если важно исключить из выборки логически устаревшие, но пока еще физически не удаленные строки, нужно использовать фильтрацию уровня запроса. +Не гарантируется, что удаление произойдет именно в `eviction_time` — оно может случиться позже. Если важно исключить из выборки логически устаревшие, но пока еще физически не удаленные строки, нужно использовать фильтрацию уровня запроса. {% endnote %} @@ -176,6 +190,45 @@ expiration_time = valueof(ttl_column) + expire_after_seconds {% endlist %} +### Включение вытеснения в Object Storage для существующих таблиц {#enable-tiering-on-existing-tables} + +{% note info %} + +Данная функциональность доступна только для колоночных таблиц. Для строчных таблиц функциональность находится в разработке. + +{% endnote %} + +В следующем примере строки таблицы `mytable` будут переноситься в бакет, описанный во внешнем источнике данных `/Root/s3_cold_data`, спустя час после наступления времени, записанного в колонке `created_at`, а спустя 24 часа будут удаляться: + +{% list tabs group=tool %} + +- YQL + + ```yql + ALTER TABLE `mytable` SET (TTL = Interval("PT1H") TO EXTERNAL DATA SOURCE `/Root/s3_cold_data`, Interval(PT24H) DELETE ON modified_at AS SECONDS); + ``` + +{% if oss == true %} + +- C++ + + ```c++ + session.AlterTable( + "mytable", + TAlterTableSettings() + .BeginAlterTtlSettings() + .Set("created_at", { + TTtlTierSettings(TDuration::Hours(1), TTtlEvictToExternalStorageAction("/Root/s3_cold_data")), + TTtlTierSettings(TDuration::Hours(24), TTtlDeleteAction("/Root/s3_cold_data")) + }) + .EndAlterTtlSettings() + ); + ``` + +{% endif %} + +{% endlist %} + ### Включение TTL для вновь создаваемой таблицы {#enable-for-new-table} Для вновь создаваемой таблицы можно передать настройки TTL вместе с ее описанием: diff --git a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md index def326f6acfa..c5373fe7e6e2 100644 --- a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md +++ b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md @@ -135,7 +135,7 @@ CREATE TABLE article ( | Имя параметра | Тип | Допустимые значения | Возможность
изменения | Возможность
сброса | | ------------- | --- | ------------------- | --------------------- | ------------------ | -| `TTL` | Expression | `Interval("") ON [AS ]` | Да | Да | +| `TTL` | Expression | `, ..., ON [AS ]`, где `` — `Inteval("") TO EXTERNAL DATA SOURCE ` или `Inteval("") TO DELETE`. Краткая форма: `Interval("") ON [AS ]` — задаёт удаление данных | Да | Да | Где `` — единица измерения, указывается только для колонок с [числовым типом](../../../concepts/ttl.md#restrictions): From 7c9755297b910ed6a9c1da4d208244b2caedc2b4 Mon Sep 17 00:00:00 2001 From: Semyon Date: Tue, 19 Nov 2024 15:23:37 +0300 Subject: [PATCH 2/4] Update ttl.md --- ydb/docs/ru/core/concepts/_includes/ttl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/ru/core/concepts/_includes/ttl.md b/ydb/docs/ru/core/concepts/_includes/ttl.md index 6a799c707331..1cb290938004 100644 --- a/ydb/docs/ru/core/concepts/_includes/ttl.md +++ b/ydb/docs/ru/core/concepts/_includes/ttl.md @@ -4,7 +4,7 @@ ## Принцип работы {#how-it-works} -TTL таблицы задаётся последовательностью тиров хранения. Для каждого тира в последовательности задаётся выражение, при срабатывании которого строке присваивается данный тир. TTL автоматически выполнит заданное действие, когда строке будет присвоен тир: перенесёт строку во внешнее хранилище или удалит её. Внешние хранилища представляются объектом [external data source](https://ydb.tech/docs/ru/concepts/datamodel/external_data_source). Удаление может быть задано только для последнего тира. +TTL таблицы задаётся последовательностью тиров хранения. Для каждого тира задаётся выражение, при срабатывании которого строке присваивается данный тир. Когда строке будет присвоен тир, TTL автоматически выполнит заданное действие: перенесёт строку во внешнее хранилище или удалит её. Внешние хранилища представляются объектом [external data source](https://ydb.tech/docs/ru/concepts/datamodel/external_data_source). Удаление может быть задано только для последнего тира. {% note info %} From 7fc09855422c4569951fddad77635112df9661cc Mon Sep 17 00:00:00 2001 From: Semyon Date: Tue, 19 Nov 2024 15:33:35 +0300 Subject: [PATCH 3/4] Update ttl.md --- ydb/docs/en/core/concepts/_includes/ttl.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/concepts/_includes/ttl.md b/ydb/docs/en/core/concepts/_includes/ttl.md index 0b1a0e40cdb2..d3fbdb955e4b 100644 --- a/ydb/docs/en/core/concepts/_includes/ttl.md +++ b/ydb/docs/en/core/concepts/_includes/ttl.md @@ -4,7 +4,7 @@ This section describes how the TTL mechanism works and what its limits are. It a ## How it works {#how-it-works} -The table's TTL is defined by a sequence of storage tiers. For each tier in the sequence, an expression is specified; when the expression triggers, the row is assigned that tier. TTL automatically performs the specified action when a tier is assigned to a row: it moves the row to external storage or deletes it. External storage is represented by the external data source object. Deletion can only be specified for the last tier. +The table's TTL is a sequence of storage tiers. For each tier, an expression is specified; when the expression triggers, that tier is assigned to the row. When a tier is assigned to a row, TTL automatically performs the specified action: move the row to an external storage or delete it. External storage is represented by the [external data source](https://ydb.tech/docs/en/concepts/datamodel/external_data_source) object. Deletion can only be specified for the last tier. {% note info %} From d8320af3051d4c13e24fa1f43416155de739c4b7 Mon Sep 17 00:00:00 2001 From: Semyon Date: Tue, 26 Nov 2024 11:44:10 +0300 Subject: [PATCH 4/4] paraphrase english docs --- ydb/docs/en/core/concepts/_includes/ttl.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/ydb/docs/en/core/concepts/_includes/ttl.md b/ydb/docs/en/core/concepts/_includes/ttl.md index d3fbdb955e4b..94d000574d87 100644 --- a/ydb/docs/en/core/concepts/_includes/ttl.md +++ b/ydb/docs/en/core/concepts/_includes/ttl.md @@ -4,7 +4,7 @@ This section describes how the TTL mechanism works and what its limits are. It a ## How it works {#how-it-works} -The table's TTL is a sequence of storage tiers. For each tier, an expression is specified; when the expression triggers, that tier is assigned to the row. When a tier is assigned to a row, TTL automatically performs the specified action: move the row to an external storage or delete it. External storage is represented by the [external data source](https://ydb.tech/docs/en/concepts/datamodel/external_data_source) object. Deletion can only be specified for the last tier. +The table's TTL is a sequence of storage tiers. Each tier contains an expression (TTL expression) and an action. When the expression triggers, that tier is assigned to the row. When a tier is assigned to a row, the specified action is automatically performed: moving the row to an external storage or deleting it. External storage is represented by the [external data source](https://ydb.tech/docs/en/concepts/datamodel/external_data_source) object. Deleting action can only be specified for the last tier. {% note info %} @@ -12,7 +12,7 @@ Currently, only an Object Storage is available as external storage. {% endnote %} -{{ ydb-short-name }} allows you to specify, for both row-oriented and columnar tables, a column (TTL column) whose values are used in TTL expressions. The expression triggers when the specified number of seconds have passed since the time recorded in the TTL column. +{{ ydb-short-name }} allows you to specify a column (TTL column) whose values are used in TTL expressions. The expression triggers when the specified number of seconds have passed since the time recorded in the TTL column. {% note info %}