Initial commit

Author: shnikd

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.
 

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 `<path_to_table>/_serial_column_{column_name}`,
+    where `<path_to_table>` 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;
+```

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<String>), 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<String>), 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 %}
 

ydb/docs/en/core/yql/reference/syntax/index.md

@@ -97,3 +97,9 @@
 
 {% endif %}
 
+{% if feature_serial %}
+
+* [ALTER SEQUENCE](alter-sequence.md)
+
+{% endif %}
+

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 }

ydb/docs/en/core/yql/reference/types/serial.md

@@ -6,7 +6,9 @@ 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 is hidden from the user. The `Sequence` will be destroyed together with the table.
 
-Values generated by the sequence start from one, are incremented by one with each new value, and are limited according to the chosen type.
+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.

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`.
+
+    Путь формируется как `<path_to_table>/_serial_column_{column_name}`,
+    где `<path_to_table>` — абсолютный путь до таблицы, 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;
+```

ydb/docs/ru/core/yql/reference/syntax/create_table/index.md

@@ -96,17 +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<String>`) тип заключается в двойные кавычки.
+  Для неключевых колонок допускаются любые типы данных, для ключевых - только [примитивные](../../types/primitive.md){% if feature_serial %} и [серийные](../../types/serial.md){% endif %}. При указании сложных типов (например, `List<String>`) тип заключается в двойные кавычки.
 
   {% else %}
 
-  {% if feature_serial %}
-
-  Для ключевых колонок допускаются только [примитивные](../../types/primitive.md) и [серийные](../../types/serial.md) типы данных, для неключевых колонок допускаются только [примитивные](../../types/primitive.md).
-
-  {% else %}
-
-  Для ключевых и неключевых колонок допускаются только [примитивные](../../types/primitive.md) типы данных.
+  Для ключевых и неключевых колонок допускаются только [примитивные](../../types/primitive.md){% if feature_serial %}и [серийные](../../types/serial.md){% endif %} типы данных.
 
   {% endif %}
 

ydb/docs/ru/core/yql/reference/syntax/index.md

@@ -104,3 +104,9 @@
 * [DROP ASYNC REPLICATION](drop-async-replication.md)
 
 {% endif %}
+
+{% if feature_serial %}
+
+* [ALTER SEQUENCE](alter-sequence.md)
+
+{% endif %}

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 }

ydb/docs/ru/core/yql/reference/types/serial.md

@@ -7,7 +7,9 @@
 
 При определении такого типа для колонки создаётся отдельный схемный объект `Sequence`, привязанный к этой колонке и являющийся генератором последовательности, из которого извлекаются значения. Этот объект является приватным и скрыт от пользователя. `Sequence` будет уничтожен вместе с таблицей.
 
-Значения последовательности начинаются с единицы, выдаются с шагом, равным единице, и ограничены в зависимости от используемого типа.
+На текущий момент объект `Sequence` поддерживает ряд параметров, определяющих его поведение, которые можно изменить после создания `Sequence` с помощью команды [ALTER SEQUENCE](../syntax/alter-sequence.md).
+
+По умолчанию генерируемые значения начинаются с единицы, увеличиваются на один при каждом новом значении и ограничены в соответствии с выбранным типом.
 
 > **Примечание:**
 > Колонки типа `Serial` поддерживаются как для колонок, входящих в состав первичного ключа, так и для неключевых колонок.