Skip to content

Commit 8a3209b

Browse files
shnikdshnikd
committed
Initial commit
1 parent 3a005c7 commit 8a3209b

File tree

13 files changed

+281
-47
lines changed

13 files changed

+281
-47
lines changed

‎ydb/docs/en/core/reference/ydb-cli/export-import/_includes/tools_dump.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ The `tools dump` command dumps the schema objects to the client file system in t
5151
- `database`: A fully consistent dump, with one snapshot taken before starting the dump. Applied by default.
5252
- `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.
5353

54-
- `--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).
54+
- `--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 %}
5555

5656
- `--save-partial-result`: Retain the result of a partial dump. Without this option, dumps that terminate with an error are deleted.
5757

‎ydb/docs/en/core/yql/reference/syntax/alter-sequence.md

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# ALTER SEQUENCE
2+
3+
Modifies the parameters of an existing `Sequence` object associated with a [Serial](../types/serial.md) column.
4+
5+
## Syntax
6+
7+
```yql
8+
ALTER SEQUENCE [ IF EXISTS ] path_to_sequence
9+
[ INCREMENT [ BY ] increment ]
10+
[ START [ WITH ] start_value ]
11+
[ RESTART [ [ WITH ] restart_value ]];
12+
```
13+
14+
## Parameters
15+
16+
* `path_to_sequence` — the absolute path to the `Sequence` object.
17+
18+
The path is constructed as `<path_to_table>/_serial_column_{column_name}`,
19+
where `<path_to_table>` is the absolute path to the table, and `{column_name}` is the name of the `Serial` column.
20+
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`.
21+
22+
* `IF EXISTS` — if used, the statement does not return an error if the `Sequence` does not exist at the specified path.
23+
24+
* `INCREMENT [ BY ] increment` — sets the increment step for the sequence. Default: 1.
25+
26+
* `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.
27+
28+
* `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.
29+
30+
## Examples
31+
32+
```yql
33+
CREATE TABLE users (
34+
user_hash Uint64,
35+
user_id Serial,
36+
name Utf8,
37+
email Utf8,
38+
PRIMARY KEY (user_hash, user_id)
39+
);
40+
```
41+
42+
Change the increment step for `user_id` and set the current value to 1000:
43+
44+
```yql
45+
ALTER SEQUENCE `/Root/users/_serial_column_user_id`
46+
INCREMENT BY 5
47+
RESTART 1000;
48+
```
49+
50+
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:
51+
52+
```yql
53+
ALTER SEQUENCE `/Root/users/_serial_column_user_id` INCREMENT BY 5 START WITH 1000;
54+
ALTER SEQUENCE `/Root/users/_serial_column_user_id` RESTART;
55+
```

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -95,11 +95,11 @@ By default, if the `STORE` parameter is not specified, a row-oriented table is c
9595
9696
{% if feature_column_container_type == true %}
9797
98-
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.
98+
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.
9999
100100
{% else %}
101101
102-
For both key and non-key columns, only [primitive](../../types/primitive.md) data types are allowed.
102+
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.
103103
104104
{% endif %}
105105

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

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,3 +97,9 @@
9797

9898
{% endif %}
9999

100+
{% if feature_serial %}
101+
102+
* [ALTER SEQUENCE](alter-sequence.md)
103+
104+
{% endif %}
105+

‎ydb/docs/en/core/yql/reference/syntax/toc_i.yaml

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ items:
99
- { name: ALTER VIEW, href: alter-view.md, when: feature_view }
1010
- { name: ALTER TOPIC, href: alter-topic.md, when: feature_topic_control_plane }
1111
- { name: ALTER USER, href: alter-user.md, when: feature_user_and_group }
12+
- { name: ALTER SEQUENCE, href: alter-sequence.md, when: feature_serial }
1213
- { name: ANALYZE, href: analyze.md, when: backend_name == "YDB" }
1314
- { name: CREATE ASYNC REPLICATION, href: create-async-replication.md, when: feature_async_replication }
1415
- { name: CREATE GROUP, href: create-group.md, when: feature_user_and_group }

‎ydb/docs/en/core/yql/reference/types/index.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
This section contains articles on YQL data types:
44

55
- [Simple/Primitive types](primitive.md)
6+
{% if feature_serial %}- [Serial types](serial.md){% endif %}
67
- [Optional types](optional.md)
78
- [Containers](containers.md)
89
- [Special types](special.md)

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

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
# Serial Types
2+
3+
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).
4+
5+
## Description
6+
7+
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.
8+
9+
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.
10+
11+
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.
12+
13+
> **Note:**
14+
> Serial columns are supported both for columns included in the primary key and for non-key columns.
15+
>
16+
> However, such columns cannot be [altered](../syntax/alter_table/family#mod-column-groups) or [dropped](../syntax/alter_table/columns.md) from the table —
17+
> attempting to perform these operations will result in an error.
18+
19+
| Type | Maximum Value | YDB Type |
20+
|-------------|----------------------|----------|
21+
| SmallSerial | 2^15–1 | Int16 |
22+
| Serial2 | 2^15–1 | Int16 |
23+
| Serial | 2^31–1 | Int32 |
24+
| Serial4 | 2^31–1 | Int32 |
25+
| Serial8 | 2^63–1 | Int64 |
26+
| BigSerial | 2^63–1 | Int64 |
27+
28+
If the sequence reaches its maximum value, insertion will result in an error:
29+
30+
```text
31+
Error: Failed to get next val for sequence: /dev/test/users/_serial_column_user_id, status: SCHEME_ERROR
32+
<main>: Error: sequence [OwnerId: <some>, LocalPathId: <some>] doesn't have any more values available, code: 200503
33+
```
34+
35+
**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).
36+
As a result, the values in such a column may have gaps and may not form a continuous sequence.
37+
38+
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.
39+
40+
## Usage Example
41+
42+
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.
43+
44+
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.
45+
46+
```yql
47+
CREATE TABLE users (
48+
user_hash Uint64,
49+
user_id Serial,
50+
name Utf8,
51+
email Utf8,
52+
PRIMARY KEY (user_hash, user_id)
53+
);
54+
55+
The `user_hash` field can be calculated on the application side, for example, by applying a hash function to the `email`.
56+
57+
``` yql
58+
UPSERT INTO users (user_hash, name, email) VALUES (123456789, 'Alice', 'alice@example.com');
59+
INSERT INTO users (user_hash, name, email) VALUES (987654321, 'Bob', 'bob@example.com');
60+
REPLACE INTO users (user_hash, name, email) VALUES (111111111, 'John', 'john@example.com');
61+
```
62+
63+
Result (example `user_hash` values are used):
64+
65+
| user_hash | email | name | user_id |
66+
|-------------|---------------------|-------|---------|
67+
| 123456789 | alice@example.com | Alice | 1 |
68+
| 987654321 | bob@example.com | Bob | 2 |
69+
| 111111111 | john@example.com | John | 3 |
70+
71+
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:
72+
73+
``` yql
74+
UPSERT INTO users (user_hash, user_id, name, email) VALUES (222222222, 10, 'Peter', 'peter@example.com');
75+
```
76+
77+
### Suboptimal Schema Example
78+
79+
```yql
80+
CREATE TABLE users_bad (
81+
user_id Serial,
82+
name Utf8,
83+
email Utf8,
84+
PRIMARY KEY (user_id)
85+
);
86+
```
87+
88+
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.

‎ydb/docs/en/core/yql/reference/types/toc_i.yaml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,9 @@ items:
33
href: index.md
44
- name: Simple
55
href: primitive.md
6+
- name: Serial
7+
href: serial.md
8+
when: feature_serial
69
- name: Optional
710
href: optional.md
811
- name: Containers

‎ydb/docs/ru/core/yql/reference/syntax/alter-sequence.md

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# ALTER SEQUENCE
2+
3+
Изменяет параметры уже существующего объекта `Sequence`, привязанного к колонке [Serial](../types/serial.md) типа.
4+
5+
## Синтаксис:
6+
7+
```yql
8+
ALTER SEQUENCE [ IF EXISTS ] path_to_sequence
9+
[ INCREMENT [ BY ] increment ]
10+
[ START [ WITH ] start_value ]
11+
[ RESTART [ [ WITH ] restart_value ]];
12+
```
13+
14+
## Параметры
15+
16+
* `path_to_sequence` - абсолютный путь до объекта `Sequence`.
17+
18+
Путь формируется как `<path_to_table>/_serial_column_{column_name}`,
19+
где `<path_to_table>` — абсолютный путь до таблицы, a `{column_name}` — имя колонки типа `Serial`.
20+
Например, для таблицы с путём `/local/users` и колонки `user_id` путь к соответствующему `Sequence` будет `/local/users/_serial_column_user_id`.
21+
* `IF EXISTS` - при использовании этой конструкции, выражение не возвращает ошибку, если не существует `Sequence` по указаному пути.
22+
* `INCREMENT [ BY ] increment` - задает шаг изменения последовательности. Значение по умолчанию: 1.
23+
* `START [ WITH ] start_value` - устанавливает новое стартовое значение для последовательности. Изменение этого параметра через `ALTER SEQUENCE` не влияет на текущее значение последовательности, но будет использовано, если выполнить `ALTER SEQUENCE RESTART` без указания значения. Значение по умолчанию: 1.
24+
* `RESTART [ [ WITH ] restart_value ]` - изменяет текущее значение последовательности на указанное в `restart_value`. Если значение не указано, текущее значение последовательности будет установлено в текущее стартовое значение.
25+
26+
## Примеры
27+
28+
``` yql
29+
CREATE TABLE users (
30+
user_hash Uint64,
31+
user_id Serial,
32+
name Utf8,
33+
email Utf8,
34+
PRIMARY KEY (user_hash, user_id)
35+
);
36+
```
37+
38+
Изменить шаг последовательности для `user_id` и установить текущее значение равным 1000:
39+
40+
```yql
41+
ALTER SEQUENCE `/Root/users/_serial_column_user_id`
42+
INCREMENT BY 5
43+
RESTART 1000;
44+
```
45+
46+
Альтернативный способ изменить текущее значение — сначала изменить стартовое значение, а затем выполнить `RESTART` (после этого последующие сбросы через `RESTART` без указания `restart_value` будут устанавливать текущее значение в 1000):
47+
48+
```yql
49+
ALTER SEQUENCE `/Root/users/_serial_column_user_id` INCREMENT BY 5 START WITH 1000;
50+
ALTER SEQUENCE `/Root/users/_serial_column_user_id` RESTART;
51+
```

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

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -96,17 +96,11 @@ WITH (
9696
9797
{% if feature_column_container_type == true %}
9898
99-
Для неключевых колонок допускаются любые типы данных{% if feature_serial %} , кроме [серийных](../../types/serial.md) {% endif %}, для ключевых - только [примитивные](../../types/primitive.md){% if feature_serial %} и [серийные](../../types/serial.md){% endif %}. При указании сложных типов (например, `List<String>`) тип заключается в двойные кавычки.
99+
Для неключевых колонок допускаются любые типы данных, для ключевых - только [примитивные](../../types/primitive.md){% if feature_serial %} и [серийные](../../types/serial.md){% endif %}. При указании сложных типов (например, `List<String>`) тип заключается в двойные кавычки.
100100
101101
{% else %}
102102
103-
{% if feature_serial %}
104-
105-
Для ключевых колонок допускаются только [примитивные](../../types/primitive.md) и [серийные](../../types/serial.md) типы данных, для неключевых колонок допускаются только [примитивные](../../types/primitive.md).
106-
107-
{% else %}
108-
109-
Для ключевых и неключевых колонок допускаются только [примитивные](../../types/primitive.md) типы данных.
103+
Для ключевых и неключевых колонок допускаются только [примитивные](../../types/primitive.md){% if feature_serial %}и [серийные](../../types/serial.md){% endif %} типы данных.
110104
111105
{% endif %}
112106

0 commit comments

Comments
 (0)