From aa1a5437325db336fbcfaa31132060895167fc01 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Thu, 5 Jun 2025 22:37:14 +0300 Subject: [PATCH 01/18] Initial commit --- .../export-import/_includes/tools_dump.md | 2 +- .../yql/reference/syntax/alter-sequence.md | 55 ++++++++++ .../reference/syntax/create_table/index.md | 4 +- .../en/core/yql/reference/syntax/index.md | 6 ++ .../en/core/yql/reference/syntax/toc_i.yaml | 1 + ydb/docs/en/core/yql/reference/types/index.md | 1 + .../en/core/yql/reference/types/serial.md | 88 +++++++++++++++ .../en/core/yql/reference/types/toc_i.yaml | 3 + .../yql/reference/syntax/alter-sequence.md | 51 +++++++++ .../reference/syntax/create_table/index.md | 12 +-- .../ru/core/yql/reference/syntax/index.md | 6 ++ .../ru/core/yql/reference/syntax/toc_i.yaml | 1 + .../ru/core/yql/reference/types/serial.md | 100 +++++++++++------- 13 files changed, 281 insertions(+), 49 deletions(-) create mode 100644 ydb/docs/en/core/yql/reference/syntax/alter-sequence.md create mode 100644 ydb/docs/en/core/yql/reference/types/serial.md create mode 100644 ydb/docs/ru/core/yql/reference/syntax/alter-sequence.md diff --git a/ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md b/ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md index 81f69880854b..c6db1f44708f 100644 --- a/ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md +++ b/ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md @@ -51,7 +51,7 @@ The `tools dump` command dumps the schema objects to the client file system in t - `database`: A fully consistent dump, with one snapshot taken before starting the dump. Applied by default. - `table`: Consistency within each dumped table, taking individual independent snapshots for each table. Might run faster and have less impact on the current workload processing in the database. -- `--avoid-copy`: Do not create a snapshot before dumping. The default consistency snapshot might be inapplicable in some cases (for example, for tables with external blobs). +- `--avoid-copy`: Do not create a snapshot before dumping. The default consistency snapshot might be inapplicable in some cases (for example, for tables with external blobs).{% if feature_serial %} For correct export of tables with [serial](../../../../yql/reference/types/serial.md) types, this parameter should not be set. Otherwise, the current value of the sequence generator will not be copied, and new values will start from the initial value, which may lead to primary key conflicts.{% endif %} - `--save-partial-result`: Retain the result of a partial dump. Without this option, dumps that terminate with an error are deleted. diff --git a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md new file mode 100644 index 000000000000..c772a9ad3a4b --- /dev/null +++ b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md @@ -0,0 +1,55 @@ +# ALTER SEQUENCE + +Modifies the parameters of an existing `Sequence` object associated with a [Serial](../types/serial.md) column. + +## Syntax + +```yql +ALTER SEQUENCE [ IF EXISTS ] path_to_sequence + [ INCREMENT [ BY ] increment ] + [ START [ WITH ] start_value ] + [ RESTART [ [ WITH ] restart_value ]]; +``` + +## Parameters + +* `path_to_sequence` — the absolute path to the `Sequence` object. + + The path is constructed as `/_serial_column_{column_name}`, + where `` is the absolute path to the table, and `{column_name}` is the name of the `Serial` column. + For example, for a table at `/local/users` and a column `user_id`, the corresponding `Sequence` path will be `/local/users/_serial_column_user_id`. + +* `IF EXISTS` — if used, the statement does not return an error if the `Sequence` does not exist at the specified path. + +* `INCREMENT [ BY ] increment` — sets the increment step for the sequence. Default: 1. + +* `START [ WITH ] start_value` — sets a new start value for the sequence. Changing this parameter with `ALTER SEQUENCE` does not affect the current value, but it will be used with `ALTER SEQUENCE RESTART` if no value is specified. Default: 1. + +* `RESTART [ [ WITH ] restart_value ]` — sets the current value of the sequence to the specified `restart_value`. If the value is not specified, the current value will be set to the current start value. + +## Examples + +```yql +CREATE TABLE users ( + user_hash Uint64, + user_id Serial, + name Utf8, + email Utf8, + PRIMARY KEY (user_hash, user_id) +); +``` + +Change the increment step for `user_id` and set the current value to 1000: + +```yql +ALTER SEQUENCE `/Root/users/_serial_column_user_id` + INCREMENT BY 5 + RESTART 1000; +``` + +An alternative way to achieve the same result is to first change the start value, and then `RESTART` the `Sequence`. After this, subsequent calls to `RESTART` without an explicit value will set the current value to 1000: + +```yql +ALTER SEQUENCE `/Root/users/_serial_column_user_id` INCREMENT BY 5 START WITH 1000; +ALTER SEQUENCE `/Root/users/_serial_column_user_id` RESTART; +``` \ No newline at end of file diff --git a/ydb/docs/en/core/yql/reference/syntax/create_table/index.md b/ydb/docs/en/core/yql/reference/syntax/create_table/index.md index 9988199ae81e..eb4fed6881ff 100644 --- a/ydb/docs/en/core/yql/reference/syntax/create_table/index.md +++ b/ydb/docs/en/core/yql/reference/syntax/create_table/index.md @@ -95,11 +95,11 @@ By default, if the `STORE` parameter is not specified, a row-oriented table is c {% if feature_column_container_type == true %} - For non-key columns, any data types are allowed, whereas for key columns only [primitive](../../types/primitive.md) types are permitted. When specifying complex types (for example, List), the type should be enclosed in double quotes. + For non-key columns, any data types are allowed, whereas for key columns only [primitive](../../types/primitive.md){% if feature_serial %} and [serial](../../types/serial.md){% endif %} types are permitted. When specifying complex types (for example, List), the type should be enclosed in double quotes. {% else %} - For both key and non-key columns, only [primitive](../../types/primitive.md) data types are allowed. + For both key and non-key columns, only [primitive](../../types/primitive.md){% if feature_serial %} and [serial](../../types/serial.md){% endif %} data types are allowed. {% endif %} diff --git a/ydb/docs/en/core/yql/reference/syntax/index.md b/ydb/docs/en/core/yql/reference/syntax/index.md index c792f5acb3ff..78dc5e38d68f 100644 --- a/ydb/docs/en/core/yql/reference/syntax/index.md +++ b/ydb/docs/en/core/yql/reference/syntax/index.md @@ -98,3 +98,9 @@ {% endif %} +{% if feature_serial %} + +* [ALTER SEQUENCE](alter-sequence.md) + +{% endif %} + diff --git a/ydb/docs/en/core/yql/reference/syntax/toc_i.yaml b/ydb/docs/en/core/yql/reference/syntax/toc_i.yaml index 5863cee93d6f..6a4bcd284651 100644 --- a/ydb/docs/en/core/yql/reference/syntax/toc_i.yaml +++ b/ydb/docs/en/core/yql/reference/syntax/toc_i.yaml @@ -9,6 +9,7 @@ items: - { name: ALTER VIEW, href: alter-view.md, when: feature_view } - { name: ALTER TOPIC, href: alter-topic.md, when: feature_topic_control_plane } - { name: ALTER USER, href: alter-user.md, when: feature_user_and_group } +- { name: ALTER SEQUENCE, href: alter-sequence.md, when: feature_serial } - { name: ANALYZE, href: analyze.md, when: backend_name == "YDB" } - { name: CREATE ASYNC REPLICATION, href: create-async-replication.md, when: feature_async_replication } - { name: CREATE GROUP, href: create-group.md, when: feature_user_and_group } diff --git a/ydb/docs/en/core/yql/reference/types/index.md b/ydb/docs/en/core/yql/reference/types/index.md index f1c2fbab3b20..95e4d1c7d217 100644 --- a/ydb/docs/en/core/yql/reference/types/index.md +++ b/ydb/docs/en/core/yql/reference/types/index.md @@ -3,6 +3,7 @@ This section contains articles on YQL data types: - [Simple/Primitive types](primitive.md) +{% if feature_serial %}- [Serial types](serial.md){% endif %} - [Optional types](optional.md) - [Containers](containers.md) - [Special types](special.md) diff --git a/ydb/docs/en/core/yql/reference/types/serial.md b/ydb/docs/en/core/yql/reference/types/serial.md new file mode 100644 index 000000000000..b24e98b923cb --- /dev/null +++ b/ydb/docs/en/core/yql/reference/types/serial.md @@ -0,0 +1,88 @@ +# Serial Types + +Serial types are integer types with an associated value-generation mechanism. These types are used to create auto-increment columns: for each new row inserted into a table, a unique value for this column is generated automatically (similar to the [SERIAL](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL) type in PostgreSQL or the [AUTO_INCREMENT](https://dev.mysql.com/doc/refman/9.0/en/example-auto-increment.html) property in MySQL). + +## Description + +When a column of a serial type is defined, a separate schema object called a `Sequence` is created and bound to this column. This object is a private sequence generator and is hidden from the user. The `Sequence` will be destroyed together with the table. + +At present, the `Sequence` object supports several parameters that determine its behavior. These parameters can be altered after creation using the [ALTER SEQUENCE](../syntax/alter-sequence.md) command. + +By default, values generated by the `Sequence` start from one, are incremented by one with each new value, and are limited according to the chosen type. + +> **Note:** +> Serial columns are supported both for columns included in the primary key and for non-key columns. +> +> However, such columns cannot be [altered](../syntax/alter_table/family#mod-column-groups) or [dropped](../syntax/alter_table/columns.md) from the table — +> attempting to perform these operations will result in an error. + +| Type | Maximum Value | YDB Type | +|-------------|----------------------|----------| +| SmallSerial | 2^15–1 | Int16 | +| Serial2 | 2^15–1 | Int16 | +| Serial | 2^31–1 | Int32 | +| Serial4 | 2^31–1 | Int32 | +| Serial8 | 2^63–1 | Int64 | +| BigSerial | 2^63–1 | Int64 | + +If the sequence reaches its maximum value, insertion will result in an error: + +```text +Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_id, status: SCHEME_ERROR +
: Error: sequence [OwnerId: , LocalPathId: ] doesn't have any more values available, code: 200503 +``` + +**Note:** The next value is allocated by the generator before the actual insertion into the table and is considered used even if the row is not successfully inserted (for example, in case of transaction rollback). +As a result, the values in such a column may have gaps and may not form a continuous sequence. + +Tables with `Serial` columns support [copy](../../../reference/ydb-cli/tools-copy.md), [rename](../../../reference/ydb-cli/commands/tools/rename.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md), and [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md) operations. + +## Usage Example + +You should carefully choose the columns for your [PRIMARY KEY](../../../dev/primary-key/row-oriented.md). For scalability and high performance, you should avoid writing rows with monotonically increasing primary keys. In this case, all records will go to the last partition, and all the load will target a single server. + +As a recommended approach, use a hash (for example, from the whole or a part of the primary key) as the first key element, which will help evenly distribute data across cluster partitions. + +```yql +CREATE TABLE users ( + user_hash Uint64, + user_id Serial, + name Utf8, + email Utf8, + PRIMARY KEY (user_hash, user_id) +); + +The `user_hash` field can be calculated on the application side, for example, by applying a hash function to the `email`. + +``` yql +UPSERT INTO users (user_hash, name, email) VALUES (123456789, 'Alice', 'alice@example.com'); +INSERT INTO users (user_hash, name, email) VALUES (987654321, 'Bob', 'bob@example.com'); +REPLACE INTO users (user_hash, name, email) VALUES (111111111, 'John', 'john@example.com'); +``` + +Result (example `user_hash` values are used): + +| user_hash | email | name | user_id | +|-------------|-----------------------|-------|---------| +| 123456789 | `alice@example.com` | Alice | 1 | +| 987654321 | `bob@example.com` | Bob | 2 | +| 111111111 | `john@example.com` | John | 3 | + +You can also explicitly specify a value for the `Serial` column during insertion, for example, when restoring data. In this case, the insertion will work like with a regular integer column, and the `Sequence` will not be affected: + +``` yql +UPSERT INTO users (user_hash, user_id, name, email) VALUES (222222222, 10, 'Peter', 'peter@example.com'); +``` + +### Suboptimal Schema Example + +```yql +CREATE TABLE users_bad ( + user_id Serial, + name Utf8, + email Utf8, + PRIMARY KEY (user_id) +); +``` + +In this example, the auto-increment column is the first and only element of the primary key. This leads to an uneven load and a bottleneck on the last partition. diff --git a/ydb/docs/en/core/yql/reference/types/toc_i.yaml b/ydb/docs/en/core/yql/reference/types/toc_i.yaml index 060dd02891fa..ca05b3f8c400 100644 --- a/ydb/docs/en/core/yql/reference/types/toc_i.yaml +++ b/ydb/docs/en/core/yql/reference/types/toc_i.yaml @@ -3,6 +3,9 @@ items: href: index.md - name: Simple href: primitive.md +- name: Serial + href: serial.md + when: feature_serial - name: Optional href: optional.md - name: Containers diff --git a/ydb/docs/ru/core/yql/reference/syntax/alter-sequence.md b/ydb/docs/ru/core/yql/reference/syntax/alter-sequence.md new file mode 100644 index 000000000000..8e23e9b6c946 --- /dev/null +++ b/ydb/docs/ru/core/yql/reference/syntax/alter-sequence.md @@ -0,0 +1,51 @@ +# ALTER SEQUENCE + +Изменяет параметры уже существующего объекта `Sequence`, привязанного к колонке [Serial](../types/serial.md) типа. + +## Синтаксис + +```yql +ALTER SEQUENCE [ IF EXISTS ] path_to_sequence + [ INCREMENT [ BY ] increment ] + [ START [ WITH ] start_value ] + [ RESTART [ [ WITH ] restart_value ]]; +``` + +## Параметры + +* `path_to_sequence` - абсолютный путь до объекта `Sequence`. + + Путь формируется как `/_serial_column_{column_name}`, + где `` — абсолютный путь до таблицы, a `{column_name}` — имя колонки типа `Serial`. + Например, для таблицы с путём `/local/users` и колонки `user_id` путь к соответствующему `Sequence` будет `/local/users/_serial_column_user_id`. +* `IF EXISTS` - при использовании этой конструкции, выражение не возвращает ошибку, если не существует `Sequence` по указаному пути. +* `INCREMENT [ BY ] increment` - задает шаг изменения последовательности. Значение по умолчанию: 1. +* `START [ WITH ] start_value` - устанавливает новое стартовое значение для последовательности. Изменение этого параметра через `ALTER SEQUENCE` не влияет на текущее значение последовательности, но будет использовано, если выполнить `ALTER SEQUENCE RESTART` без указания значения. Значение по умолчанию: 1. +* `RESTART [ [ WITH ] restart_value ]` - изменяет текущее значение последовательности на указанное в `restart_value`. Если значение не указано, текущее значение последовательности будет установлено в текущее стартовое значение. + +## Примеры + +``` yql +CREATE TABLE users ( + user_hash Uint64, + user_id Serial, + name Utf8, + email Utf8, + PRIMARY KEY (user_hash, user_id) +); +``` + +Изменить шаг последовательности для `user_id` и установить текущее значение равным 1000: + +```yql +ALTER SEQUENCE `/Root/users/_serial_column_user_id` + INCREMENT BY 5 + RESTART 1000; +``` + +Альтернативный способ изменить текущее значение — сначала изменить стартовое значение, а затем выполнить `RESTART` (после этого последующие сбросы через `RESTART` без указания `restart_value` будут устанавливать текущее значение в 1000): + +```yql +ALTER SEQUENCE `/Root/users/_serial_column_user_id` INCREMENT BY 5 START WITH 1000; +ALTER SEQUENCE `/Root/users/_serial_column_user_id` RESTART; +``` diff --git a/ydb/docs/ru/core/yql/reference/syntax/create_table/index.md b/ydb/docs/ru/core/yql/reference/syntax/create_table/index.md index e9b19453590b..dc170515d519 100644 --- a/ydb/docs/ru/core/yql/reference/syntax/create_table/index.md +++ b/ydb/docs/ru/core/yql/reference/syntax/create_table/index.md @@ -96,19 +96,11 @@ WITH ( {% if feature_column_container_type == true %} - Для неключевых колонок допускаются любые типы данных{% if feature_serial %} , кроме [серийных](../../types/serial.md) {% endif %}, для ключевых - только [примитивные](../../types/primitive.md){% if feature_serial %} и [серийные](../../types/serial.md){% endif %}. При указании сложных типов (например, `List`) тип заключается в двойные кавычки. + Для неключевых колонок допускаются любые типы данных, для ключевых - только [примитивные](../../types/primitive.md){% if feature_serial %} и [серийные](../../types/serial.md){% endif %}. При указании сложных типов (например, `List`) тип заключается в двойные кавычки. {% else %} - {% if feature_serial %} - - Для ключевых колонок допускаются только [примитивные](../../types/primitive.md) и [серийные](../../types/serial.md) типы данных, для неключевых колонок допускаются только [примитивные](../../types/primitive.md). - - {% else %} - - Для ключевых и неключевых колонок допускаются только [примитивные](../../types/primitive.md) типы данных. - - {% endif %} + Для ключевых и неключевых колонок допускаются только [примитивные](../../types/primitive.md){% if feature_serial %}и [серийные](../../types/serial.md){% endif %} типы данных. {% endif %} diff --git a/ydb/docs/ru/core/yql/reference/syntax/index.md b/ydb/docs/ru/core/yql/reference/syntax/index.md index 5fe9236db3ec..dc29e7502387 100644 --- a/ydb/docs/ru/core/yql/reference/syntax/index.md +++ b/ydb/docs/ru/core/yql/reference/syntax/index.md @@ -105,3 +105,9 @@ * [DROP ASYNC REPLICATION](drop-async-replication.md) {% endif %} + +{% if feature_serial %} + +* [ALTER SEQUENCE](alter-sequence.md) + +{% endif %} \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/syntax/toc_i.yaml b/ydb/docs/ru/core/yql/reference/syntax/toc_i.yaml index 2359ee677d1d..c50a019258a3 100644 --- a/ydb/docs/ru/core/yql/reference/syntax/toc_i.yaml +++ b/ydb/docs/ru/core/yql/reference/syntax/toc_i.yaml @@ -11,6 +11,7 @@ items: - { name: ALTER RESOURCE POOL CLASSIFIER, href: alter-resource-pool-classifier.md, when: feature_resource_pool_classifier } - { name: ALTER TOPIC, href: alter-topic.md, when: feature_topic_control_plane } - { name: ALTER USER, href: alter-user.md, when: feature_user_and_group } +- { name: ALTER SEQUENCE, href: alter-sequence.md, when: feature_serial } - { name: ANALYZE, href: analyze.md, when: backend_name == "YDB" } - { name: CREATE ASYNC REPLICATION, href: create-async-replication.md, when: feature_async_replication } - { name: CREATE GROUP, href: create-group.md, when: feature_user_and_group } diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index 64b6b1e7fcd9..6dfd811c2c8d 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -1,66 +1,94 @@ # Серийные типы данных -Серийные типы данных представляют собой целые числа, но с дополнительным механизмом генерации значений. Эти типы данных используются для создания автоинкрементных колонок, а именно для каждой новой строки, добавляемой в таблицу, будет автоматически генерироваться уникальное значение для такой колонки (подобно типу [SERIAL](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL) в PostgreSQL или свойству [AUTO_INCREMENT](https://dev.mysql.com/doc/refman/9.0/en/example-auto-increment.html) в MySQL). +Серийные типы данных представляют собой целые числа, но с дополнительным механизмом генерации значений. Эти типы данных используются для создания автоинкрементных колонок, а именно - для каждой новой строки, добавляемой в таблицу, будет автоматически генерироваться уникальное значение для такой колонки (подобно типу [SERIAL](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL) в PostgreSQL или свойству [AUTO_INCREMENT](https://dev.mysql.com/doc/refman/9.0/en/example-auto-increment.html) в MySQL). + +## Описание + +При определении такого типа для колонки создаётся отдельный схемный объект `Sequence`, привязанный к этой колонке и являющийся генератором последовательности, из которого извлекаются значения. Этот объект является приватным и скрыт от пользователя. `Sequence` будет уничтожен вместе с таблицей. + +На текущий момент объект `Sequence` поддерживает ряд параметров, определяющих его поведение, которые можно изменить после создания `Sequence` с помощью команды [ALTER SEQUENCE](../syntax/alter-sequence.md). + +По умолчанию генерируемые значения начинаются с единицы, увеличиваются на один при каждом новом значении и ограничены в соответствии с выбранным типом. + +> **Примечание:** +> Колонки типа `Serial` поддерживаются как для колонок, входящих в состав первичного ключа, так и для неключевых колонок. +> +> Однако такие колонки нельзя [изменить](../syntax/alter_table/family#mod-column-groups) или [удалить](../syntax/alter_table/columns.md) из таблицы — +> при попытке выполнить эти операции будет возвращена ошибка. + +| Тип | Максимальное значение | Тип значения | +|---------------|-----------------------|--------------| +| `SmallSerial` | $2^{15}–1$ | `Int16` | +| `Serial2` | $2^{15}–1$ | `Int16` | +| `Serial` | $2^{31}–1$ | `Int32` | +| `Serial4` | $2^{31}–1$ | `Int32` | +| `Serial8` | $2^{63}–1$ | `Int64` | +| `BigSerial` | $2^{63}–1$ | `Int64` | + +При переполнении `Sequence` на вставке будет возвращаться ошибка: + +```text +Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_id, status: SCHEME_ERROR +
: Error: sequence [OwnerId: , LocalPathId: ] doesn't have any more values available, code: 200503 +``` + +Отметим, что следующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена, например, при откате транзакции. Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. + +Для таблиц с автоинкрементными колонками поддержаны операции [copy](../../../reference/ydb-cli/tools-copy.md), [rename](../../../reference/ydb-cli/commands/tools/rename.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md) и [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md). ## Пример использования +Cледует обратить внимание на правильный выбор колонок для [PRIMARY KEY](../../../dev/primary-key/row-oriented.md). Для масштабируемости нагрузки и высокой производительности стоит избегать записи строк с монотонно возрастающими первичными ключами. В этом случае все записи будут попадать в последнюю партицию, и вся нагрузка будет приходиться на один сервер. + +Например, в качестве первого элемента ключа использовать можно хеш от всего первичного ключа либо его части, чтобы равномерно распределять данные по партициям кластера. + ``` yql CREATE TABLE users ( + user_hash Uint64, user_id Serial, name Utf8, email Utf8, - PRIMARY KEY (user_id) + PRIMARY KEY (user_hash, user_id) ); ``` +Хеш для поля `user_hash` можно рассчитать на стороне приложения, например, используя хеш-функцию от `email`. + ``` yql -UPSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com'); -INSERT INTO users (name, email) VALUES ('Bob', 'bob@example.com'); -REPLACE INTO users (name, email) VALUES ('John', 'john@example.com'); +UPSERT INTO users (user_hash, name, email) VALUES (123456789, 'Alice', 'alice@example.com'); +INSERT INTO users (user_hash, name, email) VALUES (987654321, 'Bob', 'bob@example.com'); +REPLACE INTO users (user_hash, name, email) VALUES (111111111, 'John', 'john@example.com'); ``` ``` yql SELECT * FROM users; ``` -| email | name | user_id | -|---------------------|-------|---------| -| `alice@example.com` | Alice | 1 | -| `bob@example.com` | Bob | 2 | -| `john@example.com` | John | 3 | +Результат (значения `user_hash` приведены для примера): + +| user_hash | email | name | user_id | +|-------------|-----------------------|-------|---------| +| 123456789 | `alice@example.com` | Alice | 1 | +| 987654321 | `bob@example.com` | Bob | 2 | +| 111111111 | `john@example.com` | John | 3 | -Можно самостоятельно указать значение `Serial` колонки при вставке, в этом случае вставка будет выполняться, как с обычной целочисленной колонкой, и `Sequence` затрагиваться при таком запросе никак не будет: +Можно самостоятельно указать значение `Serial`-колонки при вставке, например для восстановления данных. В этом случае вставка будет выполняться, как с обычной целочисленной колонкой, и `Sequence` затрагиваться при таком запросе никак не будет: ``` yql -UPSERT INTO users (user_id, name, email) VALUES (4, 'Peter', 'peter@example.com'); +UPSERT INTO users (user_hash, user_id, name, email) VALUES (222222222, 10, 'Peter', 'peter@example.com'); ``` -## Описание - -Только колонки, участвующие в первичном ключе таблиц, могут иметь тип `Serial`. +### Пример неудачной схемы -При определении такого типа для колонки создаётся отдельный схемный объект `Sequence`, привязанный к этой колонке и являющийся генератором последовательности, из которого извлекаются значения. Этот объект является приватным и скрыт от пользователя. `Sequence` будет уничтожен вместе с таблицей. - -Значения последовательности начинаются с единицы, выдаются с шагом, равным единице, и ограничены в зависимости от используемого типа. - -| Тип | Максимальное значение | Тип значения | -|---------------|-----------------------|--------------| -| `SmallSerial` | $2^{15}–1$ | `Int16` | -| `Serial2` | $2^{15}–1$ | `Int16` | -| `Serial` | $2^{31}–1$ | `Int32` | -| `Serial4` | $2^{31}–1$ | `Int32` | -| `Serial8` | $2^{63}–1$ | `Int64` | -| `BigSerial` | $2^{63}–1$ | `Int64` | - -При переполнении `Sequence` на вставке будет возвращаться ошибка: - -```text -Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_id, status: SCHEME_ERROR -
: Error: sequence [OwnerId: , LocalPathId: ] doesn't have any more values available, code: 200503 +``` yql +CREATE TABLE users_bad ( + user_id Serial, + name Utf8, + email Utf8, + PRIMARY KEY (user_id) +); ``` -Отметим, что следующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена, например, при откате транзакции. Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. - -Для таблиц с автоинкрементными колонками поддержаны операции [copy](../../../reference/ydb-cli/tools-copy.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md) и [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md). +В следующем примере автоинкрементная колонка является единственным и первым элементом ключа — это приведёт к неравномерной нагрузке и узкому месту на последней партиции. From 0b0c5d21708e709682a7b4cc4554697be280e179 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 10 Jun 2025 01:23:31 +0300 Subject: [PATCH 02/18] Fixes --- .../core/yql/reference/syntax/alter-sequence.md | 2 +- ydb/docs/en/core/yql/reference/types/serial.md | 14 ++++++++------ ydb/docs/ru/core/yql/reference/types/serial.md | 16 +++++++++------- 3 files changed, 18 insertions(+), 14 deletions(-) diff --git a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md index c772a9ad3a4b..d3f2039851d4 100644 --- a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md +++ b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md @@ -47,7 +47,7 @@ ALTER SEQUENCE `/Root/users/_serial_column_user_id` RESTART 1000; ``` -An alternative way to achieve the same result is to first change the start value, and then `RESTART` the `Sequence`. After this, subsequent calls to `RESTART` without an explicit value will set the current value to 1000: +An alternative way to change the current value is to first set a new start value, and then `RESTART` the `Sequence`. After this, subsequent calls to `RESTART` without an explicit value will set the current value to 1000: ```yql ALTER SEQUENCE `/Root/users/_serial_column_user_id` INCREMENT BY 5 START WITH 1000; diff --git a/ydb/docs/en/core/yql/reference/types/serial.md b/ydb/docs/en/core/yql/reference/types/serial.md index b24e98b923cb..a67f1a3e4520 100644 --- a/ydb/docs/en/core/yql/reference/types/serial.md +++ b/ydb/docs/en/core/yql/reference/types/serial.md @@ -10,11 +10,11 @@ At present, the `Sequence` object supports several parameters that determine its By default, values generated by the `Sequence` start from one, are incremented by one with each new value, and are limited according to the chosen type. -> **Note:** -> Serial columns are supported both for columns included in the primary key and for non-key columns. -> -> However, such columns cannot be [altered](../syntax/alter_table/family#mod-column-groups) or [dropped](../syntax/alter_table/columns.md) from the table — -> attempting to perform these operations will result in an error. +{% note info %} +Serial columns are supported both for columns included in the primary key and for non-key columns. + +However, such columns cannot be [altered](../syntax/alter_table/family#mod-column-groups) or [dropped](../syntax/alter_table/columns.md) from the table — attempting to perform these operations will result in an error. +{% endnote %} | Type | Maximum Value | YDB Type | |-------------|----------------------|----------| @@ -32,8 +32,10 @@ Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_
: Error: sequence [OwnerId: , LocalPathId: ] doesn't have any more values available, code: 200503 ``` -**Note:** The next value is allocated by the generator before the actual insertion into the table and is considered used even if the row is not successfully inserted (for example, in case of transaction rollback). +{% note info %} +The next value is allocated by the generator before the actual insertion into the table and is considered used even if the row is not successfully inserted (for example, in case of transaction rollback). As a result, the values in such a column may have gaps and may not form a continuous sequence. +{% endnote %} Tables with `Serial` columns support [copy](../../../reference/ydb-cli/tools-copy.md), [rename](../../../reference/ydb-cli/commands/tools/rename.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md), and [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md) operations. diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index 6dfd811c2c8d..cc2e1cfb9930 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -11,11 +11,11 @@ По умолчанию генерируемые значения начинаются с единицы, увеличиваются на один при каждом новом значении и ограничены в соответствии с выбранным типом. -> **Примечание:** -> Колонки типа `Serial` поддерживаются как для колонок, входящих в состав первичного ключа, так и для неключевых колонок. -> -> Однако такие колонки нельзя [изменить](../syntax/alter_table/family#mod-column-groups) или [удалить](../syntax/alter_table/columns.md) из таблицы — -> при попытке выполнить эти операции будет возвращена ошибка. +{% note info %} +Колонки типа `Serial` поддерживаются как для колонок, входящих в состав первичного ключа, так и для неключевых колонок. + +Однако такие колонки нельзя [изменить](../syntax/alter_table/family#mod-column-groups) или [удалить](../syntax/alter_table/columns.md) из таблицы — при попытке выполнить эти операции будет возвращена ошибка. +{% endnote %} | Тип | Максимальное значение | Тип значения | |---------------|-----------------------|--------------| @@ -33,7 +33,9 @@ Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_
: Error: sequence [OwnerId: , LocalPathId: ] doesn't have any more values available, code: 200503 ``` -Отметим, что следующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена, например, при откате транзакции. Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. +{% note info %} +Cледующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена, например, при откате транзакции. Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. +{% endnote %} Для таблиц с автоинкрементными колонками поддержаны операции [copy](../../../reference/ydb-cli/tools-copy.md), [rename](../../../reference/ydb-cli/commands/tools/rename.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md) и [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md). @@ -90,5 +92,5 @@ CREATE TABLE users_bad ( ); ``` -В следующем примере автоинкрементная колонка является единственным и первым элементом ключа — это приведёт к неравномерной нагрузке и узкому месту на последней партиции. +В этом примере автоинкрементная колонка является единственным и первым элементом ключа — это приведёт к неравномерной нагрузке и узкому месту на последней партиции. From 6474d649dc3a8118f7e745ee87518cdac8e94c77 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Fri, 6 Jun 2025 19:01:31 +0300 Subject: [PATCH 03/18] Update ydb/docs/ru/core/yql/reference/types/serial.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ydb/docs/ru/core/yql/reference/types/serial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index cc2e1cfb9930..4493af3155e4 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -41,7 +41,7 @@ Cледующее значение выдаётся генератором до ## Пример использования -Cледует обратить внимание на правильный выбор колонок для [PRIMARY KEY](../../../dev/primary-key/row-oriented.md). Для масштабируемости нагрузки и высокой производительности стоит избегать записи строк с монотонно возрастающими первичными ключами. В этом случае все записи будут попадать в последнюю партицию, и вся нагрузка будет приходиться на один сервер. +Следует обратить внимание на правильный выбор колонок для [PRIMARY KEY](../../../dev/primary-key/row-oriented.md). Для масштабируемости нагрузки и высокой производительности стоит избегать записи строк с монотонно возрастающими первичными ключами. В этом случае все записи будут попадать в последнюю партицию, и вся нагрузка будет приходиться на один сервер. Например, в качестве первого элемента ключа использовать можно хеш от всего первичного ключа либо его части, чтобы равномерно распределять данные по партициям кластера. From d6036b90e21a8ac1cfb78b898741f7f872b26c39 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Fri, 6 Jun 2025 19:02:08 +0300 Subject: [PATCH 04/18] Update ydb/docs/ru/core/yql/reference/syntax/create_table/index.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- ydb/docs/ru/core/yql/reference/syntax/create_table/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/ru/core/yql/reference/syntax/create_table/index.md b/ydb/docs/ru/core/yql/reference/syntax/create_table/index.md index dc170515d519..0edc250e01b1 100644 --- a/ydb/docs/ru/core/yql/reference/syntax/create_table/index.md +++ b/ydb/docs/ru/core/yql/reference/syntax/create_table/index.md @@ -100,7 +100,7 @@ WITH ( {% else %} - Для ключевых и неключевых колонок допускаются только [примитивные](../../types/primitive.md){% if feature_serial %}и [серийные](../../types/serial.md){% endif %} типы данных. + Для ключевых и неключевых колонок допускаются только [примитивные](../../types/primitive.md){% if feature_serial %} и [серийные](../../types/serial.md){% endif %} типы данных. {% endif %} From 08e0fe262e7db47a0751b088e946fe4a017769be Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 16:39:02 +0300 Subject: [PATCH 05/18] Update ydb/docs/en/core/yql/reference/syntax/alter-sequence.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/en/core/yql/reference/syntax/alter-sequence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md index d3f2039851d4..1c54aa965f63 100644 --- a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md +++ b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md @@ -1,6 +1,6 @@ # ALTER SEQUENCE -Modifies the parameters of an existing `Sequence` object associated with a [Serial](../types/serial.md) column. +Modifies parameters of an existing `Sequence` object associated with a [Serial](../types/serial.md) column. ## Syntax From 1d34b3825f989cf6ea8247f8e7676aaa36149cde Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 16:39:21 +0300 Subject: [PATCH 06/18] Update ydb/docs/en/core/yql/reference/syntax/alter-sequence.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/en/core/yql/reference/syntax/alter-sequence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md index 1c54aa965f63..10a82b798ea3 100644 --- a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md +++ b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md @@ -17,7 +17,7 @@ ALTER SEQUENCE [ IF EXISTS ] path_to_sequence The path is constructed as `/_serial_column_{column_name}`, where `` is the absolute path to the table, and `{column_name}` is the name of the `Serial` column. - For example, for a table at `/local/users` and a column `user_id`, the corresponding `Sequence` path will be `/local/users/_serial_column_user_id`. + For example, for the column `user_id` in the table `/local/users`, the corresponding `Sequence` path will be `/local/users/_serial_column_user_id`. * `IF EXISTS` — if used, the statement does not return an error if the `Sequence` does not exist at the specified path. From 49b425964e481a6db5e89694f94044608543032f Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 16:39:35 +0300 Subject: [PATCH 07/18] Update ydb/docs/en/core/yql/reference/syntax/alter-sequence.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/en/core/yql/reference/syntax/alter-sequence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md index 10a82b798ea3..8a84edc9c1ef 100644 --- a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md +++ b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md @@ -23,7 +23,7 @@ ALTER SEQUENCE [ IF EXISTS ] path_to_sequence * `INCREMENT [ BY ] increment` — sets the increment step for the sequence. Default: 1. -* `START [ WITH ] start_value` — sets a new start value for the sequence. Changing this parameter with `ALTER SEQUENCE` does not affect the current value, but it will be used with `ALTER SEQUENCE RESTART` if no value is specified. Default: 1. +* `START [ WITH ] start_value` — sets a new start value for the sequence. Changing this parameter with `ALTER SEQUENCE` does not affect the current value, but new start value will be used with `ALTER SEQUENCE RESTART` if no value is specified. Default: 1. * `RESTART [ [ WITH ] restart_value ]` — sets the current value of the sequence to the specified `restart_value`. If the value is not specified, the current value will be set to the current start value. From c7afda88b3b8cbce3ea096b767b9aab81b117db2 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 16:55:23 +0300 Subject: [PATCH 08/18] Update ydb/docs/ru/core/yql/reference/types/serial.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/ru/core/yql/reference/types/serial.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index 4493af3155e4..29ac33a39701 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -34,7 +34,9 @@ Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_ ``` {% note info %} + Cледующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена, например, при откате транзакции. Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. + {% endnote %} Для таблиц с автоинкрементными колонками поддержаны операции [copy](../../../reference/ydb-cli/tools-copy.md), [rename](../../../reference/ydb-cli/commands/tools/rename.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md) и [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md). From 3cff74a0b40c7f67dddf4d9d366226fed967b63d Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 17:01:27 +0300 Subject: [PATCH 09/18] Update ydb/docs/en/core/yql/reference/types/serial.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/en/core/yql/reference/types/serial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/yql/reference/types/serial.md b/ydb/docs/en/core/yql/reference/types/serial.md index a67f1a3e4520..fab4631b4448 100644 --- a/ydb/docs/en/core/yql/reference/types/serial.md +++ b/ydb/docs/en/core/yql/reference/types/serial.md @@ -4,7 +4,7 @@ Serial types are integer types with an associated value-generation mechanism. Th ## Description -When a column of a serial type is defined, a separate schema object called a `Sequence` is created and bound to this column. This object is a private sequence generator and is hidden from the user. The `Sequence` will be destroyed together with the table. +When a column of a serial type is defined, a separate schema object called a `Sequence` is created and bound to this column. This object is a private sequence generator and it is hidden from the user. The `Sequence` will be destroyed together with the table. At present, the `Sequence` object supports several parameters that determine its behavior. These parameters can be altered after creation using the [ALTER SEQUENCE](../syntax/alter-sequence.md) command. From fef196fce1c4c67c892418393fccd5cfd5655c67 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 17:05:46 +0300 Subject: [PATCH 10/18] Update ydb/docs/ru/core/yql/reference/types/serial.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/ru/core/yql/reference/types/serial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index 29ac33a39701..aa3fd4680267 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -7,7 +7,7 @@ При определении такого типа для колонки создаётся отдельный схемный объект `Sequence`, привязанный к этой колонке и являющийся генератором последовательности, из которого извлекаются значения. Этот объект является приватным и скрыт от пользователя. `Sequence` будет уничтожен вместе с таблицей. -На текущий момент объект `Sequence` поддерживает ряд параметров, определяющих его поведение, которые можно изменить после создания `Sequence` с помощью команды [ALTER SEQUENCE](../syntax/alter-sequence.md). +Объект `Sequence` поддерживает ряд параметров, определяющих его поведение, которые можно изменить после создания `Sequence` с помощью команды [ALTER SEQUENCE](../syntax/alter-sequence.md). По умолчанию генерируемые значения начинаются с единицы, увеличиваются на один при каждом новом значении и ограничены в соответствии с выбранным типом. From 2ecba8bb8e1d44961c5c5084e4e6e8082607a39a Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 17:15:26 +0300 Subject: [PATCH 11/18] Update ydb/docs/ru/core/yql/reference/types/serial.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/ru/core/yql/reference/types/serial.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index aa3fd4680267..4cb9895bf928 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -12,9 +12,11 @@ По умолчанию генерируемые значения начинаются с единицы, увеличиваются на один при каждом новом значении и ограничены в соответствии с выбранным типом. {% note info %} + Колонки типа `Serial` поддерживаются как для колонок, входящих в состав первичного ключа, так и для неключевых колонок. Однако такие колонки нельзя [изменить](../syntax/alter_table/family#mod-column-groups) или [удалить](../syntax/alter_table/columns.md) из таблицы — при попытке выполнить эти операции будет возвращена ошибка. + {% endnote %} | Тип | Максимальное значение | Тип значения | From 48c58b9cdac0f50dfd81cb1465cb3634684c497d Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 9 Jun 2025 17:16:35 +0300 Subject: [PATCH 12/18] Update ydb/docs/en/core/yql/reference/types/serial.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/en/core/yql/reference/types/serial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/yql/reference/types/serial.md b/ydb/docs/en/core/yql/reference/types/serial.md index fab4631b4448..789cf89aa327 100644 --- a/ydb/docs/en/core/yql/reference/types/serial.md +++ b/ydb/docs/en/core/yql/reference/types/serial.md @@ -6,7 +6,7 @@ Serial types are integer types with an associated value-generation mechanism. Th When a column of a serial type is defined, a separate schema object called a `Sequence` is created and bound to this column. This object is a private sequence generator and it is hidden from the user. The `Sequence` will be destroyed together with the table. -At present, the `Sequence` object supports several parameters that determine its behavior. These parameters can be altered after creation using the [ALTER SEQUENCE](../syntax/alter-sequence.md) command. +The `Sequence` object supports several parameters that determine its behavior. These parameters can be altered after creation using the [ALTER SEQUENCE](../syntax/alter-sequence.md) command. By default, values generated by the `Sequence` start from one, are incremented by one with each new value, and are limited according to the chosen type. From 65d655e6eb8350caa25376c8515f24ee78117a70 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 10 Jun 2025 01:20:08 +0300 Subject: [PATCH 13/18] Update ydb/docs/ru/core/yql/reference/types/serial.md Co-authored-by: ElenaAfina <144937430+ElenaAfina@users.noreply.github.com> --- ydb/docs/ru/core/yql/reference/types/serial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index 4cb9895bf928..88de59a65fb5 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -1,7 +1,7 @@ # Серийные типы данных -Серийные типы данных представляют собой целые числа, но с дополнительным механизмом генерации значений. Эти типы данных используются для создания автоинкрементных колонок, а именно - для каждой новой строки, добавляемой в таблицу, будет автоматически генерироваться уникальное значение для такой колонки (подобно типу [SERIAL](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL) в PostgreSQL или свойству [AUTO_INCREMENT](https://dev.mysql.com/doc/refman/9.0/en/example-auto-increment.html) в MySQL). +Серийные типы данных представляют собой целые числа, но с дополнительным механизмом генерации значений. Эти типы данных используются для создания автоинкрементных колонок, а именно: для каждой новой строки, добавляемой в таблицу, будет автоматически генерироваться уникальное значение для такой колонки (подобно типу [SERIAL](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL) в PostgreSQL или свойству [AUTO_INCREMENT](https://dev.mysql.com/doc/refman/9.0/en/example-auto-increment.html) в MySQL). ## Описание From fd2639296a98c5f5e5799375d37824aacff9c909 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 10 Jun 2025 01:49:21 +0300 Subject: [PATCH 14/18] Fixes --- ydb/docs/en/core/yql/reference/types/serial.md | 5 +++++ ydb/docs/ru/core/yql/reference/types/serial.md | 6 +++++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/ydb/docs/en/core/yql/reference/types/serial.md b/ydb/docs/en/core/yql/reference/types/serial.md index 789cf89aa327..86489196f191 100644 --- a/ydb/docs/en/core/yql/reference/types/serial.md +++ b/ydb/docs/en/core/yql/reference/types/serial.md @@ -11,9 +11,11 @@ The `Sequence` object supports several parameters that determine its behavior. T By default, values generated by the `Sequence` start from one, are incremented by one with each new value, and are limited according to the chosen type. {% note info %} + Serial columns are supported both for columns included in the primary key and for non-key columns. However, such columns cannot be [altered](../syntax/alter_table/family#mod-column-groups) or [dropped](../syntax/alter_table/columns.md) from the table — attempting to perform these operations will result in an error. + {% endnote %} | Type | Maximum Value | YDB Type | @@ -33,8 +35,10 @@ Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_ ``` {% note info %} + The next value is allocated by the generator before the actual insertion into the table and is considered used even if the row is not successfully inserted (for example, in case of transaction rollback). As a result, the values in such a column may have gaps and may not form a continuous sequence. + {% endnote %} Tables with `Serial` columns support [copy](../../../reference/ydb-cli/tools-copy.md), [rename](../../../reference/ydb-cli/commands/tools/rename.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md), and [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md) operations. @@ -53,6 +57,7 @@ CREATE TABLE users ( email Utf8, PRIMARY KEY (user_hash, user_id) ); +``` The `user_hash` field can be calculated on the application side, for example, by applying a hash function to the `email`. diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index 88de59a65fb5..67545abde273 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -13,7 +13,7 @@ {% note info %} -Колонки типа `Serial` поддерживаются как для колонок, входящих в состав первичного ключа, так и для неключевых колонок. +Столбцы типа `Serial` поддерживаются как для колонок, входящих в состав первичного ключа, так и для неключевых колонок. Однако такие колонки нельзя [изменить](../syntax/alter_table/family#mod-column-groups) или [удалить](../syntax/alter_table/columns.md) из таблицы — при попытке выполнить эти операции будет возвращена ошибка. @@ -37,7 +37,11 @@ Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_ {% note info %} +<<<<<<< HEAD Cледующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена, например, при откате транзакции. Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. +======= +Следующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена (например, при откате транзакции). Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. +>>>>>>> Fixes {% endnote %} From 5dfe15b8b087fc3eb3fa8094f64a2ef90c8a4e75 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Tue, 17 Jun 2025 21:53:26 +0300 Subject: [PATCH 15/18] Apply suggestions from code review Co-authored-by: Ivan Blinkov --- .../export-import/_includes/tools_dump.md | 2 +- .../yql/reference/syntax/alter-sequence.md | 21 ++++++++----- .../en/core/yql/reference/types/serial.md | 30 +++++++++---------- 3 files changed, 29 insertions(+), 24 deletions(-) diff --git a/ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md b/ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md index c6db1f44708f..02f8494ab270 100644 --- a/ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md +++ b/ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md @@ -51,7 +51,7 @@ The `tools dump` command dumps the schema objects to the client file system in t - `database`: A fully consistent dump, with one snapshot taken before starting the dump. Applied by default. - `table`: Consistency within each dumped table, taking individual independent snapshots for each table. Might run faster and have less impact on the current workload processing in the database. -- `--avoid-copy`: Do not create a snapshot before dumping. The default consistency snapshot might be inapplicable in some cases (for example, for tables with external blobs).{% if feature_serial %} For correct export of tables with [serial](../../../../yql/reference/types/serial.md) types, this parameter should not be set. Otherwise, the current value of the sequence generator will not be copied, and new values will start from the initial value, which may lead to primary key conflicts.{% endif %} +- `--avoid-copy`: Do not create a snapshot before dumping. The default consistency snapshot might be inapplicable in some cases (for example, for tables with external blobs).{% if feature_serial %} For correct export of tables with [serial](../../../../yql/reference/types/serial.md) types, this parameter must not be set. Otherwise, the current value of the sequence generator will not be copied, and new values will start from the initial value, which may lead to primary key conflicts.{% endif %} - `--save-partial-result`: Retain the result of a partial dump. Without this option, dumps that terminate with an error are deleted. diff --git a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md index 8a84edc9c1ef..695aa3e988f3 100644 --- a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md +++ b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md @@ -1,6 +1,6 @@ # ALTER SEQUENCE -Modifies parameters of an existing `Sequence` object associated with a [Serial](../types/serial.md) column. +Modifies the parameters of an existing `Sequence` object associated with a [Serial](../types/serial.md) column. ## Syntax @@ -13,19 +13,19 @@ ALTER SEQUENCE [ IF EXISTS ] path_to_sequence ## Parameters -* `path_to_sequence` — the absolute path to the `Sequence` object. +* `path_to_sequence` — the absolute path to the sequence object. - The path is constructed as `/_serial_column_{column_name}`, - where `` is the absolute path to the table, and `{column_name}` is the name of the `Serial` column. + The path is constructed as `/_serial_column_`, + where `` is the absolute path to the table, and `` is the name of the column with the `Serial` data type. For example, for the column `user_id` in the table `/local/users`, the corresponding `Sequence` path will be `/local/users/_serial_column_user_id`. -* `IF EXISTS` — if used, the statement does not return an error if the `Sequence` does not exist at the specified path. +* `IF EXISTS` — when used, the statement does not return an error if the sequence does not exist at the specified path. * `INCREMENT [ BY ] increment` — sets the increment step for the sequence. Default: 1. -* `START [ WITH ] start_value` — sets a new start value for the sequence. Changing this parameter with `ALTER SEQUENCE` does not affect the current value, but new start value will be used with `ALTER SEQUENCE RESTART` if no value is specified. Default: 1. +* `START [ WITH ] start_value` — sets a new start value for the sequence. Changing this parameter with `ALTER SEQUENCE` does not affect the current value; the new start value is used with `ALTER SEQUENCE RESTART` if no value is specified. Default: 1. -* `RESTART [ [ WITH ] restart_value ]` — sets the current value of the sequence to the specified `restart_value`. If the value is not specified, the current value will be set to the current start value. +* `RESTART [ [ WITH ] restart_value ]` — sets the current sequence value to the specified `restart_value`. If no value is specified, it sets the current value to the start value. ## Examples @@ -52,4 +52,9 @@ An alternative way to change the current value is to first set a new start value ```yql ALTER SEQUENCE `/Root/users/_serial_column_user_id` INCREMENT BY 5 START WITH 1000; ALTER SEQUENCE `/Root/users/_serial_column_user_id` RESTART; -``` \ No newline at end of file +``` + +## See also + +* [{#T}](create-table.md) +* [{#T}](../types/serial.md) \ No newline at end of file diff --git a/ydb/docs/en/core/yql/reference/types/serial.md b/ydb/docs/en/core/yql/reference/types/serial.md index 86489196f191..61a0b5b9ccfc 100644 --- a/ydb/docs/en/core/yql/reference/types/serial.md +++ b/ydb/docs/en/core/yql/reference/types/serial.md @@ -1,6 +1,6 @@ # Serial Types -Serial types are integer types with an associated value-generation mechanism. These types are used to create auto-increment columns: for each new row inserted into a table, a unique value for this column is generated automatically (similar to the [SERIAL](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL) type in PostgreSQL or the [AUTO_INCREMENT](https://dev.mysql.com/doc/refman/9.0/en/example-auto-increment.html) property in MySQL). +Serial types are integer data types with an associated value-generation mechanism. They create auto-increment columns: each new row inserted into a table automatically generates a unique value for this column (similar to the [SERIAL](https://www.postgresql.org/docs/current/datatype-numeric.html#DATATYPE-SERIAL) type in PostgreSQL or the [AUTO_INCREMENT](https://dev.mysql.com/doc/refman/9.0/en/example-auto-increment.html) property in MySQL). ## Description @@ -18,16 +18,16 @@ However, such columns cannot be [altered](../syntax/alter_table/family#mod-colum {% endnote %} -| Type | Maximum Value | YDB Type | +| Type | Maximum Value | Underlying Type | |-------------|----------------------|----------| -| SmallSerial | 2^15–1 | Int16 | -| Serial2 | 2^15–1 | Int16 | -| Serial | 2^31–1 | Int32 | -| Serial4 | 2^31–1 | Int32 | -| Serial8 | 2^63–1 | Int64 | -| BigSerial | 2^63–1 | Int64 | +| `SmallSerial` | $2^15–1$ | `Int16` | +| `Serial2` | $2^15–1$ | `Int16` | +| `Serial` | $2^31–1$ | `Int32` | +| `Serial4` | $2^31–1$ | `Int32` | +| `Serial8` | $2^63–1$ | `Int64` | +| `BigSerial` | $2^63–1$ | `Int64` | -If the sequence reaches its maximum value, insertion will result in an error: +If a sequence reaches its maximum value, insertion results in an error: ```text Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_id, status: SCHEME_ERROR @@ -41,13 +41,13 @@ As a result, the values in such a column may have gaps and may not form a contin {% endnote %} -Tables with `Serial` columns support [copy](../../../reference/ydb-cli/tools-copy.md), [rename](../../../reference/ydb-cli/commands/tools/rename.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md), and [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md) operations. +Tables with `Serial` columns support [copy](../../../reference/ydb-cli/tools-copy.md), [rename](../../../reference/ydb-cli/commands/tools/rename.md), [dump](../../../reference/ydb-cli/export-import/tools-dump.md), [restore](../../../reference/ydb-cli/export-import/import-file.md), and [import](../../../reference/ydb-cli/export-import/import-s3.md)/[export](../../../reference/ydb-cli/export-import/export-s3.md) CLI operations. ## Usage Example -You should carefully choose the columns for your [PRIMARY KEY](../../../dev/primary-key/row-oriented.md). For scalability and high performance, you should avoid writing rows with monotonically increasing primary keys. In this case, all records will go to the last partition, and all the load will target a single server. +Carefully choose the columns for your [PRIMARY KEY](../../../dev/primary-key/row-oriented.md). To ensure scalability and high performance, avoid using monotonically increasing primary keys; this pattern directs all inserts to the last partition, concentrating load on a single server. -As a recommended approach, use a hash (for example, from the whole or a part of the primary key) as the first key element, which will help evenly distribute data across cluster partitions. +Instead, use a hash of the entire primary key (or a portion of it) as the first key element to distribute data evenly across cluster partitions. ```yql CREATE TABLE users ( @@ -59,7 +59,7 @@ CREATE TABLE users ( ); ``` -The `user_hash` field can be calculated on the application side, for example, by applying a hash function to the `email`. +The `user_hash` field can be calculated on the application side, for example, by applying a hash function to the `email` column. ``` yql UPSERT INTO users (user_hash, name, email) VALUES (123456789, 'Alice', 'alice@example.com'); @@ -75,7 +75,7 @@ Result (example `user_hash` values are used): | 987654321 | `bob@example.com` | Bob | 2 | | 111111111 | `john@example.com` | John | 3 | -You can also explicitly specify a value for the `Serial` column during insertion, for example, when restoring data. In this case, the insertion will work like with a regular integer column, and the `Sequence` will not be affected: +You can also explicitly specify a value for a column of type `Serial` during insertion, for example, when restoring data. In this case, the insertion behaves like a regular integer column, and the sequence remains unaffected: ``` yql UPSERT INTO users (user_hash, user_id, name, email) VALUES (222222222, 10, 'Peter', 'peter@example.com'); @@ -92,4 +92,4 @@ CREATE TABLE users_bad ( ); ``` -In this example, the auto-increment column is the first and only element of the primary key. This leads to an uneven load and a bottleneck on the last partition. +In this example, the auto-increment column is the sole component of the primary key, resulting in an uneven load and creating a bottleneck on the last partition. From ed1b214eaafaaae31f00e15d8cdc98070eae7bc5 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 30 Jun 2025 17:01:15 +0300 Subject: [PATCH 16/18] Fixes --- ydb/docs/en/core/yql/reference/syntax/alter-sequence.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md index 695aa3e988f3..0be90f9c76e2 100644 --- a/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md +++ b/ydb/docs/en/core/yql/reference/syntax/alter-sequence.md @@ -56,5 +56,5 @@ ALTER SEQUENCE `/Root/users/_serial_column_user_id` RESTART; ## See also -* [{#T}](create-table.md) +* [{#T}](create_table/index.md) * [{#T}](../types/serial.md) \ No newline at end of file From df88c9f504a6ac51446d7bbbb7e3ccce814de713 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 30 Jun 2025 17:08:24 +0300 Subject: [PATCH 17/18] Fixes --- ydb/docs/en/core/yql/reference/syntax/show_create.md | 2 +- ydb/docs/ru/core/yql/reference/syntax/show_create.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/ydb/docs/en/core/yql/reference/syntax/show_create.md b/ydb/docs/en/core/yql/reference/syntax/show_create.md index 8479ae57b265..d43c3ec67504 100644 --- a/ydb/docs/en/core/yql/reference/syntax/show_create.md +++ b/ydb/docs/en/core/yql/reference/syntax/show_create.md @@ -27,7 +27,7 @@ The command always returns **exactly one row** with three columns: - For tables: the main [CREATE TABLE](create_table/index.md) statement (with the path relative to the database root), plus any additional statements describing the current configuration, such as: - [ALTER TABLE ... ALTER INDEX](alter_table/secondary_index#alter-index) — for index partitioning settings. - [ALTER TABLE ... ADD CHANGEFEED](alter_table/changefeed.md) — for adding a changefeed. - - `ALTER SEQUENCE` — for restoring a `Sequence` state for `Serial` columns. + - [ALTER SEQUENCE](alter-sequence.md) — for restoring a `Sequence` state for [Serial](../types/serial.md) columns. - For views: the definition via [CREATE VIEW](create-view.md), and, if necessary, the statements the view has captured from the creation context, for example, [PRAGMA TablePathPrefix](pragma#table-path-prefix). diff --git a/ydb/docs/ru/core/yql/reference/syntax/show_create.md b/ydb/docs/ru/core/yql/reference/syntax/show_create.md index b4c0874e9d2c..1cce8e31d7d0 100644 --- a/ydb/docs/ru/core/yql/reference/syntax/show_create.md +++ b/ydb/docs/ru/core/yql/reference/syntax/show_create.md @@ -30,7 +30,7 @@ SHOW CREATE [TABLE|VIEW] ; - [ALTER TABLE ... ADD CHANGEFEED](alter_table/changefeed.md)— для добавления потока изменений. {% endif %} {% if feature_serial %} - - `ALTER SEQUENCE` — для восстановления состояния `Sequence` у колонок типа [Serial](../../../yql/reference/types/serial.md). + - [ALTER SEQUENCE](alter-sequence.md) — для восстановления состояния `Sequence` у колонок типа [Serial](../types/serial.md). {% endif %} {% if feature_view %} - Для представлений: определение посредством команды [CREATE VIEW](create-view.md), а также, если необходимо, выражения, которые были зафиксированы представлением из контекста создания, например, [PRAGMA TablePathPrefix](pragma#table-path-prefix). From b3610ab7605c9df4d6ece46efed0995531417614 Mon Sep 17 00:00:00 2001 From: Nikolay Shumkov Date: Mon, 30 Jun 2025 17:27:26 +0300 Subject: [PATCH 18/18] Fixes --- ydb/docs/ru/core/yql/reference/types/serial.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/ydb/docs/ru/core/yql/reference/types/serial.md b/ydb/docs/ru/core/yql/reference/types/serial.md index 67545abde273..aa13d8cdc409 100644 --- a/ydb/docs/ru/core/yql/reference/types/serial.md +++ b/ydb/docs/ru/core/yql/reference/types/serial.md @@ -37,11 +37,7 @@ Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_ {% note info %} -<<<<<<< HEAD Cледующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена, например, при откате транзакции. Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. -======= -Следующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена (например, при откате транзакции). Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков. ->>>>>>> Fixes {% endnote %}