YDBDOCS-819: serial types (#8956)

Co-authored-by: Ivan Blinkov <[email protected]>
Co-authored-by: Ivan Blinkov <[email protected]>

8 files changed, 82 insertions, 3 deletions

diff --git a/ydb/docs/_assets/tags.css b/ydb/docs/_assets/tags.css
index ae0c442af7d..ae0c442af7d 100644..100755
--- a/ydb/docs/_assets/tags.css
+++ b/ydb/docs/_assets/tags.css
diff --git a/ydb/docs/presets.yaml b/ydb/docs/presets.yaml
index 9c1105a617d..cc8ab528941 100644
--- a/ydb/docs/presets.yaml
+++ b/ydb/docs/presets.yaml
@@ -9,6 +9,7 @@ default:
   feature_replace: true
   feature_upsert: true
   feature_join: true
+  feature_serial: true
   feature_map_tables: true
   feature_group_by_rollup_cube: true
   feature_window_functions: true
diff --git a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/tools-dump.md b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/tools-dump.md
index 0f8dacf1513..60ad766688c 100644
--- a/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/tools-dump.md
+++ b/ydb/docs/ru/core/reference/ydb-cli/export-import/_includes/tools-dump.md
@@ -23,7 +23,7 @@
 - `database` - Полностью консистентная выгрузка, со снятием одного снапшота перед началом выгрузки. Применяется по умолчанию.
 - `table` - Консистентность в пределах каждой выгружаемой таблицы, со снятием отдельных независимых снапшотов для каждой выгружаемой таблицы. Может работать быстрее и оказывать меньшее влияние на обработку текущей нагрузки на базу данных.
 
-`--avoid-copy`: Не применять создание снапшота для выгрузки. Применяемый по умолчанию для обеспечения консистентности снапшот может быть неприменим для некоторых случаев (например, для таблиц со внешними блобами).
+`--avoid-copy`: Не применять создание снапшота для выгрузки. Применяемый по умолчанию для обеспечения консистентности снапшот может быть неприменим для некоторых случаев (например, для таблиц со внешними блобами).{% if feature_serial %} Для корректной выгрузки таблиц с [серийными](../../../../yql/reference/types/serial.md) типами требуется не выставлять этот параметр. Иначе актуальное значение генератора последовательности не будет скопировано, и новые значения будут выдаваться со стартового значения, что может привести к конфликтам по первичному ключу.{% endif %}
 
 `--save-partial-result`: Не удалять результат частично выполненной выгрузки. Без включения данной опции результат выгрузки будет удален, если в процессе её выполнения произойдет ошибка.
 
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/index.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/index.md
index 0fb38c40664..0f7e0c01bba 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/index.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/index.md
@@ -94,14 +94,22 @@ WITH (
 
   {% if feature_column_container_type == true %}
 
-  Для неключевых колонок допускаются любые типы данных, для ключевых - только [примитивные](../../types/primitive.md). При указании сложных типов (например, `List<String>`) тип заключается в двойные кавычки.
-
+  Для неключевых колонок допускаются любые типы данных{% if feature_serial %} , кроме [серийных](../../types/serial.md) {% endif %}, для ключевых - только [примитивные](../../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) типы данных.
 
   {% endif %}
 
+  {% endif %}
+
   {% if feature_not_null == true %}
 
   Без дополнительных модификаторов колонка приобретает [опциональный тип](../../types/optional.md), и допускает запись `NULL` в качестве значений. Для получения неопционального типа необходимо использовать `NOT NULL`.
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/types/_includes/serial.md b/ydb/docs/ru/core/yql/reference/yql-core/types/_includes/serial.md
new file mode 100644
index 00000000000..1313eb28cdb
--- /dev/null
+++ b/ydb/docs/ru/core/yql/reference/yql-core/types/_includes/serial.md
@@ -0,0 +1,64 @@
+# Серийные типы данных
+
+Серийные типы данных представляют собой целые числа, но с дополнительным механизмом генерации значений. Эти типы данных используются для создания автоинкрементных колонок, а именно для каждой новой строки, добавляемой в таблицу, будет автоматически генерироваться уникальное значение для такой колонки (подобно типу [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).
+
+## Пример использования
+
+``` yql
+CREATE TABLE users (
+    user_id Serial,
+    name Utf8,
+    email Utf8,
+    PRIMARY KEY (user_id)
+);
+```
+
+``` yql
+UPSERT INTO users (name, email) VALUES ('Alice', '[email protected]');
+INSERT INTO users (name, email) VALUES ('Bob', '[email protected]');
+REPLACE INTO users (name, email) VALUES ('John', '[email protected]');
+```
+
+``` yql
+SELECT * FROM users;
+```
+
+email | name | user_id
+----- | ----- | -----
+`[email protected]` | Alice | 1
+`[email protected]` | Bob | 2
+`[email protected]` | John | 3
+
+Можно самостоятельно указать значение `Serial` колонки при вставке, в этом случае вставка будет выполняться, как с обычной целочисленной колонкой и `Sequence` затрагиваться при таком запросе никак не будет:
+
+``` yql
+UPSERT INTO users (user_id, name, email) VALUES (4, 'Peter', '[email protected]');
+```
+
+## Описание
+
+Только колонки, участвующие в первичном ключе таблиц, могут иметь тип `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
+    <main>: Error: sequence [OwnerId: <some>, LocalPathId: <some>] doesn't have any more values available, code: 200503
+```
+
+Отметим, что следующее значение выдаётся генератором до непосредственной вставки в таблицу и уже будет считаться использованным, даже если строка, содержащая это значение, не была успешно вставлена, например, при откате транзакции. Поэтому множество значений такой колонки может содержать пропуски и состоять из нескольких промежутков.
+
+Для таблиц с автоинкрементными колонками поддержаны операции [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).
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/types/index.md b/ydb/docs/ru/core/yql/reference/yql-core/types/index.md
index 99dbc2fe47d..6d3fba63b0b 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/types/index.md
+++ b/ydb/docs/ru/core/yql/reference/yql-core/types/index.md
@@ -3,6 +3,7 @@
 В данном разделе размещены статьи по типам данных YQL:
 
 - [Простые/примитивные типы](primitive.md)
+{% if feature_serial %}- [Серийные типы](serial.md){% endif %}
 - [Опциональные типы](optional.md)
 - [Контейнеры](containers.md)
 - [Специальные типы](special.md)
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/types/serial.md b/ydb/docs/ru/core/yql/reference/yql-core/types/serial.md
new file mode 100644
index 00000000000..bcfe4cc06f0
--- /dev/null
+++ b/ydb/docs/ru/core/yql/reference/yql-core/types/serial.md
@@ -0,0 +1,2 @@
+
+{% include [x](_includes/serial.md) %}
diff --git a/ydb/docs/ru/core/yql/reference/yql-core/types/toc_i.yaml b/ydb/docs/ru/core/yql/reference/yql-core/types/toc_i.yaml
index af3cb084f72..aae8ebd30b1 100644
--- a/ydb/docs/ru/core/yql/reference/yql-core/types/toc_i.yaml
+++ b/ydb/docs/ru/core/yql/reference/yql-core/types/toc_i.yaml
@@ -3,6 +3,9 @@ items:
   href: index.md
 - name: Простые
   href: primitive.md
+- name: Серийные
+  href: serial.md
+  when: feature_serial
 - name: Опциональные
   href: optional.md
 - name: Контейнеры