Add partitioning examples to YQL CREATE TABLE (#8618)

Co-authored-by: Ivan Blinkov <ivan@ydb.tech>

Author: Pseudolukian

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

@@ -124,20 +124,57 @@ By default, if the `STORE` parameter is not specified, a row-oriented table is c
 
   {% endif %}
 
+  Example of creating a row-oriented table using partitioning options:
+
+  ```yql
+  CREATE TABLE <table_name> (
+    a Uint64,
+    b Uint64,
+    c Float,
+    PRIMARY KEY (a, b)
+  )
+  WITH (
+    AUTO_PARTITIONING_BY_SIZE = ENABLED,
+    AUTO_PARTITIONING_PARTITION_SIZE_MB = 512
+  );
+  ```
+
+  Such code will create a row-oriented table with automatic partitioning by partition size (`AUTO_PARTITIONING_BY_SIZE`) enabled, and with the preferred size of each partition (`AUTO_PARTITIONING_PARTITION_SIZE_MB`) set to 512 megabytes. The full list of row-oriented table partitioning options can be found in the [{#T}](../../../../concepts/datamodel/table.md#partitioning) section.
+
+
 - Creating a column-oriented table
 
   ```yql
   CREATE TABLE table_name (
     a Uint64 NOT NULL,
-    b Uint64 NOT NULL,
+    b Timestamp NOT NULL,
     c Float,
     PRIMARY KEY (a, b)
   )
+  PARTITION BY HASH(b)
   WITH (
     STORE = COLUMN
   );
   ```
 
+  Example of creating a column-oriented table with an option to specify the minimum physical number of partitions for storing data:
+
+  ```yql
+  CREATE TABLE table_name (
+    a Uint64 NOT NULL,
+    b Timestamp NOT NULL,
+    c Float,
+    PRIMARY KEY (a, b)
+  )
+  PARTITION BY HASH(b)
+  WITH (
+    STORE = COLUMN,
+    AUTO_PARTITIONING_MIN_PARTITIONS_COUNT = 10
+  );
+  ```
+
+  This code will create a columnar table with 10 partitions. The full list of column-oriented table partitioning options can be found in the [{#T}](../../../../concepts/datamodel/table.md#olap-tables-partitioning) section.
+
 {% endlist %}
 
 {% else %}
@@ -186,6 +223,7 @@ CREATE TABLE <table_name> (
   PRIMARY KEY (a, b)
 );
 ```
+
 {% endif %}
 
 {% if backend_name == "YDB" %}

ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/with.md

@@ -31,18 +31,58 @@ WITH (
 
 {% if backend_name == "YDB" %}
 
-In the `WITH` clause, you can also specify TTL (Time to Live) — the lifespan of a row. [TTL](../../../../concepts/ttl.md) automatically removes rows from the string table when the specified number of seconds have passed from the time recorded in the TTL column. TTL can be set when the table is created or added later via `ALTER TABLE`. The code below will create a string table with TTL:
 
-```yql
-CREATE TABLE my_table (
-    id Uint64,
-    title Utf8,
-    expire_at Timestamp,
-    PRIMARY KEY (id)
-)
-WITH (
-    TTL = Interval("PT0S") ON expire_at
-);
+A colum-oriented table is created by specifying the parameter `STORE = COLUMN` in the `WITH` clause:
+
+```sql
+ CREATE TABLE table_name (
+    a Uint64 NOT NULL,
+    b Timestamp NOT NULL,
+    c Float,
+    PRIMARY KEY (a, b)
+  )
+  PARTITION BY HASH(b)
+  WITH (
+    STORE = COLUMN
+  );
 ```
 
+The properties and capabilities of columnar tables are described in the article [{#T}](../../../../concepts/datamodel/table.md), and the specifics of their creation through YQL are described on the page [{#T}](./index.md). Also, the TTL (Time to Live) — the lifespan of a row — can be specified in the WITH clause for row-based and columnar tables. [TTL](../../../../concepts/ttl.md) automatically deletes rows when the specified number of seconds has passed since the time recorded in the TTL column. TTL can be specified when creating row-based and columnar tables or added later using the `ALTER TABLE` command only for row-based tables.
+
+Example of creating a row-oriented and column-oriented tables with TTL:
+
+{% list tabs %}
+
+- Creating row-oriented table with TTL
+
+    ```sql
+    CREATE TABLE my_table (
+        id Uint64,
+        title Utf8,
+        expire_at Timestamp,
+        PRIMARY KEY (id)
+    )
+    WITH (
+        TTL = Interval("PT0S") ON expire_at
+    );
+    ```
+
+- Creating column-oriented table with TTL
+
+    ```sql
+    CREATE TABLE table_name (
+        a Uint64 NOT NULL,
+        b Timestamp NOT NULL,
+        c Float,
+        PRIMARY KEY (a, b)
+    )
+    PARTITION BY HASH(b)
+    WITH (
+        STORE = COLUMN,
+        TTL = Interval("PT0S") ON b
+    );
+    ```
+
+{% endlist %}
+
 {% endif %}

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

@@ -126,20 +126,59 @@ WITH (
 
   {% endif %}
 
+  Пример создания строковой таблицы с использованием опций партиционирования:
+
+  ```yql
+  CREATE TABLE <table_name> (
+    a Uint64,
+    b Uint64,
+    c Float,
+    PRIMARY KEY (a, b)
+  )
+  WITH (
+    AUTO_PARTITIONING_BY_SIZE = ENABLED,
+    AUTO_PARTITIONING_PARTITION_SIZE_MB = 512
+  );
+  ```
+
+  Такой код создаст строковую таблицу с включенным автоматическим партиционированием по размеру партиции (`AUTO_PARTITIONING_BY_SIZE`) и предпочитаемым размером каждой партиции (`AUTO_PARTITIONING_PARTITION_SIZE_MB`) в 512 мегабайт. Полный список опций партиционирования строковой таблицы находится в разделе [{#T}](../../../../concepts/datamodel/table.md#partitioning_row_table) статьи [{#T}](../../../../concepts/datamodel/table.md).
+
 - Создание колоночной таблицы
 
   ```yql
   CREATE TABLE table_name (
     a Uint64 NOT NULL,
-    b Uint64 NOT NULL,
+    b Timestamp NOT NULL,
     c Float,
     PRIMARY KEY (a, b)
   )
+  PARTITION BY HASH(b)
   WITH (
     STORE = COLUMN
   );
   ```
 
+  При создании колоночных таблиц обязательно нужно использовать конструкцию `PARTITION BY HASH` с указанием первичных ключей, которые имеют высококардинальный тип данных (например, `Timestamp`), так как колоночные таблицы партиционируют данные не по первичным ключам, а по специально выделенным ключам — ключам партицирования. Подробно про ключи партиционирования колоночных таблиц изложено в статье [{#T}](../../../../dev/primary-key/column-oriented.md).
+
+  В настоящий момент колоночные таблицы не поддерживают автоматического репартицирования, поэтому важно указывать правильное число партиций при создании таблицы с помощью параметра `AUTO_PARTITIONING_MIN_PARTITIONS_COUNT`:
+
+  ```yql
+  CREATE TABLE table_name (
+    a Uint64 NOT NULL,
+    b Timestamp NOT NULL,
+    c Float,
+    PRIMARY KEY (a, b)
+  )
+  PARTITION BY HASH(b)
+  WITH (
+    STORE = COLUMN,
+    AUTO_PARTITIONING_MIN_PARTITIONS_COUNT = 10
+  );
+  ```
+  
+  Такой код создаст колоночную таблицу с 10-ю партициями. С полным списком опций партиционирования колоночных таблиц можно ознакомиться в разделе [{#T}](../../../../concepts/datamodel/table.md#olap-tables-partitioning) статьи [{#T}](../../../../concepts/datamodel/table.md).
+
+
 {% endlist %}
 
 {% else %}

ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/with.md

@@ -31,18 +31,57 @@ WITH (
 
 {% if backend_name == "YDB" and oss == true %}
 
-Также в блоке `WITH` можно задать TTL (Time to Live) — время жизни строки. [TTL](../../../../concepts/ttl.md) автоматически удаляет из строковой таблицы строки, когда проходит указанное количество секунд от времени, записанного в TTL-колонку. TTL можно задать при создании таблицы, а можно добавить позже через `ALTER TABLE`. Код ниже создаст строковую таблицу таблицу с TTL:
+Колоночная таблица создаётся путём указанием параметра `STORE = COLUMN` в блоке `WITH`:
 
 ```yql
-CREATE TABLE my_table (
-    id Uint64,
-    title Utf8,
-    expire_at Timestamp,
-    PRIMARY KEY (id)
-)
-WITH (
-    TTL = Interval("PT0S") ON expire_at
-);
-```
+ CREATE TABLE table_name (
+    a Uint64 NOT NULL,
+    b Timestamp NOT NULL,
+    c Float,
+    PRIMARY KEY (a, b)
+  )
+  PARTITION BY HASH(b)
+  WITH (
+    STORE = COLUMN
+  );
+
+Свойства и возможности колоночных таблиц описаны в статье [{#T}](../../../../concepts/datamodel/table.md), а специфика их создания через YQL описана на странице [{#T}](./index.md). Также в блоке `WITH` можно задать TTL (Time to Live) — время жизни строки для строковых и колоночных таблиц. [TTL](../../../../concepts/ttl.md) автоматически удаляет строки, когда проходит указанное количество секунд от времени, записанного в TTL-колонку. TTL можно задать при создании строковой и колоночной таблицы или добавить позже командой `ALTER TABLE` только в строковую таблицу.
+
+Пример создания строковой и колоночной таблицы с TTL:
+
+{% list tabs %}
+
+- Создание строковой таблицы с TTL
+
+    ```yql
+    CREATE TABLE my_table (
+        id Uint64,
+        title Utf8,
+        expire_at Timestamp,
+        PRIMARY KEY (id)
+    )
+    WITH (
+        TTL = Interval("PT0S") ON expire_at
+    );
+    ```
+
+- Создание колоночной таблицы с TTL
+
+    ```yql
+    CREATE TABLE table_name (
+        a Uint64 NOT NULL,
+        b Timestamp NOT NULL,
+        c Float,
+        PRIMARY KEY (a, b)
+    )
+    PARTITION BY HASH(b)
+    WITH (
+        STORE = COLUMN,
+        TTL = Interval("PT0S") ON b
+    );
+    ```
+
+{% endlist %}
+
 
 {% endif %}