diff --git a/ydb/docs/en/core/_includes/codec_zstd_allow_for_olap_note.md b/ydb/docs/en/core/_includes/codec_zstd_allow_for_olap_note.md new file mode 100644 index 000000000000..6573a7beb786 --- /dev/null +++ b/ydb/docs/en/core/_includes/codec_zstd_allow_for_olap_note.md @@ -0,0 +1,5 @@ +{% note alert %} + +{% include [codec_zstd_allow_for_olap_text](codec_zstd_allow_for_olap_text.md) %} + +{% endnote %} \ No newline at end of file diff --git a/ydb/docs/en/core/_includes/codec_zstd_allow_for_olap_text.md b/ydb/docs/en/core/_includes/codec_zstd_allow_for_olap_text.md new file mode 100644 index 000000000000..4fc5e9a72571 --- /dev/null +++ b/ydb/docs/en/core/_includes/codec_zstd_allow_for_olap_text.md @@ -0,0 +1 @@ +Codec `"zstd"` is supported only for [column-oriented](../concepts/datamodel/table.md#column-oriented-tables) tables. \ No newline at end of file diff --git a/ydb/docs/en/core/_includes/only_allow_for_olap_note.md b/ydb/docs/en/core/_includes/only_allow_for_olap_note.md new file mode 100644 index 000000000000..58ff44fa21d0 --- /dev/null +++ b/ydb/docs/en/core/_includes/only_allow_for_olap_note.md @@ -0,0 +1,9 @@ +{% if oss == true and backend_name == "YDB" %} + +{% note alert %} + +{% include [only_allow_for_olap_text](only_allow_for_olap_text.md) %} + +{% endnote %} + +{% endif %} \ No newline at end of file diff --git a/ydb/docs/en/core/_includes/only_allow_for_olap_text.md b/ydb/docs/en/core/_includes/only_allow_for_olap_text.md new file mode 100644 index 000000000000..d150971666fb --- /dev/null +++ b/ydb/docs/en/core/_includes/only_allow_for_olap_text.md @@ -0,0 +1 @@ +Supported only for [column-oriented](../concepts/datamodel/table.md#column-oriented-tables) tables. \ No newline at end of file diff --git a/ydb/docs/en/core/_includes/only_allow_for_oltp_note.md b/ydb/docs/en/core/_includes/only_allow_for_oltp_note.md new file mode 100644 index 000000000000..96ab849eac16 --- /dev/null +++ b/ydb/docs/en/core/_includes/only_allow_for_oltp_note.md @@ -0,0 +1,9 @@ +{% if oss == true and backend_name == "YDB" %} + +{% note alert %} + +{% include [only_allow_for_oltp_text](only_allow_for_oltp_text.md) %} + +{% endnote %} + +{% endif %} \ No newline at end of file diff --git a/ydb/docs/en/core/_includes/only_allow_for_oltp_text.md b/ydb/docs/en/core/_includes/only_allow_for_oltp_text.md new file mode 100644 index 000000000000..7e8fd85270f6 --- /dev/null +++ b/ydb/docs/en/core/_includes/only_allow_for_oltp_text.md @@ -0,0 +1 @@ +Supported only for [row-oriented](../concepts/datamodel/table.md#row-oriented-tables) tables. \ No newline at end of file diff --git a/ydb/docs/en/core/concepts/datamodel/_includes/table.md b/ydb/docs/en/core/concepts/datamodel/_includes/table.md index 2c0fb6f79ccf..aafe1645df63 100644 --- a/ydb/docs/en/core/concepts/datamodel/_includes/table.md +++ b/ydb/docs/en/core/concepts/datamodel/_includes/table.md @@ -185,6 +185,8 @@ In most cases, working with {{ ydb-short-name }} column-oriented tables is simil + Available in both the primary key and other columns: `Date`, `Datetime`, `Timestamp`, `Int32`, `Int64`, `Uint8`, `Uint16`, `Uint32`, `Uint64`, `Utf8`, `String`; + Available only in columns not included in the primary key: `Bool`, `Decimal`, `Double`, `Float`, `Int8`, `Int16`, `Interval`, `JsonDocument`, `Json`, `Uuid`, `Yson`. +* Column-oriented tables support column groups, but only for compression settings. + Let's recreate the "article" table, this time in column-oriented format, using the following YQL command: ```yql diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/alter_table/family.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/alter_table/family.md index 4e6fdc36d19e..98eb406db202 100644 --- a/ydb/docs/en/core/yql/reference/yql-core/syntax/alter_table/family.md +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/alter_table/family.md @@ -1,11 +1,5 @@ # Changing column groups -{% if oss == true and backend_name == "YDB" %} - -{% include [OLAP_not_allow_note](../../../../_includes/not_allow_for_olap_note.md) %} - -{% endif %} - The mechanism of [column groups](../../../../concepts/datamodel/table.md#column-groups) allows for improved performance of partial row read operations by dividing the storage of table columns into several groups. The most commonly used scenario is to organize the storage of infrequently used attributes into a separate column group. ## Creating column groups {#creating-column-groups} @@ -38,7 +32,18 @@ ALTER TABLE series_with_families ALTER COLUMN release_date SET FAMILY family_small; ``` -Using the `ALTER FAMILY` command, you can change the parameters of the column group. The code below changes the storage type to `hdd` for the `default` column group in the `series_with_families` table: +Using the `ALTER FAMILY` command, you can change the parameters of the column group. + + +### Changing storage type + +{% if oss == true and backend_name == "YDB" %} + +{% include [OLTP_only_allow_note](../../../../_includes/only_allow_for_oltp_note.md) %} + +{% endif %} + +The code below changes the storage type to `hdd` for the `default` column group in the `series_with_families` table: ```yql ALTER TABLE series_with_families ALTER FAMILY default SET DATA "hdd"; @@ -50,4 +55,26 @@ Available types of storage devices depend on the {{ ydb-short-name }} cluster co {% endnote %} +### Changing compression codec + +The code below changes the compression codec to `lz4` for the `default` column group in the `series_with_families` table: + +```yql +ALTER TABLE series_with_families ALTER FAMILY default SET COMPRESSION "lz4"; +``` + +### Changing compression level of codec + +{% if oss == true and backend_name == "YDB" %} + +{% include [OLAP_only_allow_note](../../../../_includes/only_allow_for_olap_note.md) %} + +{% endif %} + +The code below changes the compression level of codec if it supports different compression levels for the `default` column group in the `series_with_families` table: + +```yql +ALTER TABLE series_with_families ALTER FAMILY default SET COMPRESSION_LEVEL 5; +``` + You can specify any parameters of a group of columns from the [`CREATE TABLE`](../create_table/index.md) command. \ No newline at end of file diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/family.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/family.md index 93b9999a198b..86e3e0439ec8 100644 --- a/ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/family.md +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/family.md @@ -1,39 +1,80 @@ # Column groups +Columns of the same table can be grouped to set the following parameters: + +* `DATA`: A storage device type for the data in this column group. Acceptable values: `ssd`, `rot`. + {% if oss == true and backend_name == "YDB" %} -{% include [not_allow_for_olap](../../../../_includes/not_allow_for_olap_note.md) %} +{% include [OLTP_only_allow_note](../../../../_includes/only_allow_for_oltp_note.md) %} {% endif %} -Columns of the same table can be grouped to set the following parameters: +* `COMPRESSION`: A data compression codec. Acceptable values: `off`, `lz4`, `zstd`. -* `DATA`: A storage device type for the data in this column group. Acceptable values: `ssd`, `rot`. -* `COMPRESSION`: A data compression codec. Acceptable values: `off`, `lz4`. +{% if oss == true and backend_name == "YDB" %} + +{% include [codec_zstd_allow_for_olap_note](../../../../_includes/codec_zstd_allow_for_olap_note.md) %} -By default, all columns are in the same group named `default`. If necessary, the parameters of this group can also be redefined. +{% endif %} + +* `COMPRESSION_LEVEL` — compression level of codec if it supports different compression levels. + +{% if oss == true and backend_name == "YDB" %} + +{% include [OLAP_only_allow_note](../../../../_includes/only_allow_for_olap_note.md) %} + +{% endif %} + +By default, all columns are in the same group named `default`. If necessary, the parameters of this group can also be redefined, if they are not redefined, then predefined values are applied. ## Example In the example below, for the created table, the `family_large` group of columns is added and set for the `series_info` column, and the parameters for the default group, which is set by `default` for all other columns, are also redefined. -```yql -CREATE TABLE series_with_families ( - series_id Uint64, - title Utf8, - series_info Utf8 FAMILY family_large, - release_date Uint64, - PRIMARY KEY (series_id), - FAMILY default ( - DATA = "ssd", - COMPRESSION = "off" - ), - FAMILY family_large ( - DATA = "rot", - COMPRESSION = "lz4" - ) -); -``` +{% list tabs %} + +- Creating a row-oriented table + + ```sql + CREATE TABLE series_with_families ( + series_id Uint64, + title Utf8, + series_info Utf8 FAMILY family_large, + release_date Uint64, + PRIMARY KEY (series_id), + FAMILY default ( + DATA = "ssd", + COMPRESSION = "off" + ), + FAMILY family_large ( + DATA = "rot", + COMPRESSION = "lz4" + ) + ); + ``` + +- Creating a column-oriented table + + ```sql + CREATE TABLE series_with_families ( + series_id Uint64, + title Utf8, + series_info Utf8 FAMILY family_large, + release_date Uint64, + PRIMARY KEY (series_id), + FAMILY default ( + COMPRESSION = "lz4" + ), + FAMILY family_large ( + COMPRESSION = "zstd", + COMPRESSION_LEVEL = 5 + ) + ) + WITH (STORE = COLUMN); + ``` + +{% endlist %} {% note info %} diff --git a/ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/index.md b/ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/index.md index a2c702ba908e..26a53c7b0717 100644 --- a/ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/index.md +++ b/ydb/docs/en/core/yql/reference/yql-core/syntax/create_table/index.md @@ -234,6 +234,9 @@ When creating row-oriented tables, it is possible to specify: * [Column groups](family.md). * [Additional parameters](with.md). -For column-oriented tables, only [additional parameters](with.md) can be specified during creation. +When creating column-oriented tables, it is possible to specify: + +* [Column groups](family.md). +* [Additional parameters](with.md). {% endif %} diff --git a/ydb/docs/ru/core/_includes/codec_zstd_allow_for_olap_note.md b/ydb/docs/ru/core/_includes/codec_zstd_allow_for_olap_note.md new file mode 100644 index 000000000000..6573a7beb786 --- /dev/null +++ b/ydb/docs/ru/core/_includes/codec_zstd_allow_for_olap_note.md @@ -0,0 +1,5 @@ +{% note alert %} + +{% include [codec_zstd_allow_for_olap_text](codec_zstd_allow_for_olap_text.md) %} + +{% endnote %} \ No newline at end of file diff --git a/ydb/docs/ru/core/_includes/codec_zstd_allow_for_olap_text.md b/ydb/docs/ru/core/_includes/codec_zstd_allow_for_olap_text.md new file mode 100644 index 000000000000..e47bd461e8db --- /dev/null +++ b/ydb/docs/ru/core/_includes/codec_zstd_allow_for_olap_text.md @@ -0,0 +1 @@ +Кодек `"zstd"` поддерживается только для [колоночных](../concepts/datamodel/table.md#column-oriented-tables) таблиц. \ No newline at end of file diff --git a/ydb/docs/ru/core/_includes/not_allow_for_olap_text.md b/ydb/docs/ru/core/_includes/not_allow_for_olap_text.md index 2538e79d46a7..3d4737e43a06 100644 --- a/ydb/docs/ru/core/_includes/not_allow_for_olap_text.md +++ b/ydb/docs/ru/core/_includes/not_allow_for_olap_text.md @@ -1 +1 @@ -Поддерживается только для [строковых](../concepts/datamodel/table.md#strokovye-tablicy) таблиц. Поддержка функциональности для [колоночных](../concepts/datamodel/table.md#column-tables) таблиц находится в разработке. \ No newline at end of file +Поддерживается только для [строковых](../concepts/datamodel/table.md#row-oriented-tables) таблиц. Поддержка функциональности для [колоночных](../concepts/datamodel/table.md#column-oriented-tables) таблиц находится в разработке. \ No newline at end of file diff --git a/ydb/docs/ru/core/_includes/only_allow_for_olap_note.md b/ydb/docs/ru/core/_includes/only_allow_for_olap_note.md new file mode 100644 index 000000000000..bf118fc2b7fa --- /dev/null +++ b/ydb/docs/ru/core/_includes/only_allow_for_olap_note.md @@ -0,0 +1,9 @@ +{% if oss == true and backend_name == "YDB" %} + +{% note alert %} + +{% include [only_allow_for_olap_text](only_allow_for_olap_text.md) %} + +{% endnote %} + +{% endif %} diff --git a/ydb/docs/ru/core/_includes/only_allow_for_olap_text.md b/ydb/docs/ru/core/_includes/only_allow_for_olap_text.md new file mode 100644 index 000000000000..850d0d1609aa --- /dev/null +++ b/ydb/docs/ru/core/_includes/only_allow_for_olap_text.md @@ -0,0 +1 @@ +Поддерживается только для [колоночных](../concepts/datamodel/table.md#column-oriented-tables) таблиц. \ No newline at end of file diff --git a/ydb/docs/ru/core/_includes/only_allow_for_oltp_note.md b/ydb/docs/ru/core/_includes/only_allow_for_oltp_note.md new file mode 100644 index 000000000000..c9eae0746375 --- /dev/null +++ b/ydb/docs/ru/core/_includes/only_allow_for_oltp_note.md @@ -0,0 +1,9 @@ +{% if oss == true and backend_name == "YDB" %} + +{% note alert %} + +{% include [only_allow_for_oltp_text](only_allow_for_oltp_text.md) %} + +{% endnote %} + +{% endif %} diff --git a/ydb/docs/ru/core/_includes/only_allow_for_oltp_text.md b/ydb/docs/ru/core/_includes/only_allow_for_oltp_text.md new file mode 100644 index 000000000000..648a5411bebc --- /dev/null +++ b/ydb/docs/ru/core/_includes/only_allow_for_oltp_text.md @@ -0,0 +1 @@ +Поддерживается только для [строковых](../concepts/datamodel/table.md#row-oriented-tables) таблиц. \ No newline at end of file diff --git a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md index def326f6acfa..6a350402ed11 100644 --- a/ydb/docs/ru/core/concepts/datamodel/_includes/table.md +++ b/ydb/docs/ru/core/concepts/datamodel/_includes/table.md @@ -221,6 +221,7 @@ CREATE TABLE article ( + Доступно и в первичном ключе и в остальных колонках: `Date`, `Datetime`, `Timestamp`, `Int32`, `Int64`, `Uint8`, `Uint16`, `Uint32`, `Uint64`, `Utf8`, `String`; + Доступно только в колонках, не входящих в первичный ключ: `Bool`, `Decimal`, `Double`, `Float`, `Int8`, `Int16`, `Interval`, `JsonDocument`, `Json`, `Uuid`, `Yson`. +* В колоночных таблицах поддерживаются группы колонок, но пока это используется только для задания сжатия на колонках. Повторим создание таблицы `article`, на этот раз в колоночной форме, с помощью следующей YQL-команды: diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter_table/family.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter_table/family.md index e5c15c039c6a..1729b8ca3d85 100644 --- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter_table/family.md +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/alter_table/family.md @@ -1,11 +1,5 @@ # Создание и изменение групп колонок -{% if oss == true and backend_name == "YDB" %} - -{% include [OLAP_not_allow_note](../../../../_includes/not_allow_for_olap_note.md) %} - -{% endif %} - Механизм {% if oss == true and backend_name == "YDB" %}[групп](../../../../concepts/datamodel/table.md#column-groups){% else %}групп{% endif %} колонок позволяет увеличить производительность операций неполного чтения строк путем разделения хранения колонок строковой таблицы на несколько групп. Наиболее часто используемый сценарий — организация хранения редко используемых атрибутов в отдельной группе колонок. @@ -22,13 +16,13 @@ ALTER TABLE series_with_families ADD FAMILY family_small ( ## Изменение групп колонок -При помощи команды `ALTER COLUMN` можно изменить группу колонок для указанной колонки. Приведенный ниже код для колонки `release_date` в таблице `series_with_families` сменит группу колонок на `family_small`. +При помощи команды `ALTER COLUMN` можно изменить группу колонок для указанной колонки. Приведённый ниже код для колонки `release_date` в таблице `series_with_families` сменит группу колонок на `family_small`. ```yql ALTER TABLE series_with_families ALTER COLUMN release_date SET FAMILY family_small; ``` -Две предыдущие команды можно объединить в один вызов `ALTER TABLE`. Приведенный ниже код создаст в таблице `series_with_families` группу колонок `family_small` и установит её для колонки `release_date`. +Две предыдущие команды можно объединить в один вызов `ALTER TABLE`. Приведённый ниже код создаст в таблице `series_with_families` группу колонок `family_small` и установит её для колонки `release_date`. ```yql ALTER TABLE series_with_families @@ -39,7 +33,17 @@ ALTER TABLE series_with_families ALTER COLUMN release_date SET FAMILY family_small; ``` -При помощи команды `ALTER FAMILY` можно изменить параметры группы колонок. Приведенный ниже код для группы колонок `default` в таблице `series_with_families` сменит тип хранилища на `hdd`: +При помощи команды `ALTER FAMILY` можно изменить параметры группы колонок. + +### Изменение типа хранилища + +{% if oss == true and backend_name == "YDB" %} + +{% include [OLTP_only_allow_note](../../../../_includes/only_allow_for_oltp_note.md) %} + +{% endif %} + +Приведённый ниже код для группы колонок `default` в таблице `series_with_families` сменит тип хранилища на `hdd`: ```yql ALTER TABLE series_with_families ALTER FAMILY default SET DATA "hdd"; @@ -51,4 +55,32 @@ ALTER TABLE series_with_families ALTER FAMILY default SET DATA "hdd"; {% endnote %} +### Изменение кодека сжатия + +{% if oss == true and backend_name == "YDB" %} + +{% include [codec_zstd_allow_for_olap_note](../../../../_includes/codec_zstd_allow_for_olap_note.md) %} + +{% endif %} + +Приведённый ниже код для группы колонок `default` в таблице `series_with_families` сменит кодек сжатия на `lz4`: + +```yql +ALTER TABLE series_with_families ALTER FAMILY default SET COMPRESSION "lz4"; +``` + +### Изменение уровня кодека сжатия + +{% if oss == true and backend_name == "YDB" %} + +{% include [OLAP_only_allow_note](../../../../_includes/only_allow_for_olap_note.md) %} + +{% endif %} + +Приведённый ниже код для группы колонок `default` в таблице `series_with_families` сменит уровень кодека сжатия, если он поддерживает различные уровни сжатия: + +```yql +ALTER TABLE series_with_families ALTER FAMILY default SET COMPRESSION_LEVEL 5; +``` + Могут быть указаны все параметры группы колонок, описанные в команде [`CREATE TABLE`](../create_table/secondary_index.md) \ No newline at end of file diff --git a/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/family.md b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/family.md index 3c57fbe50c35..0dc5d3c673f9 100644 --- a/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/family.md +++ b/ydb/docs/ru/core/yql/reference/yql-core/syntax/create_table/family.md @@ -1,37 +1,79 @@ # Группы колонок +Колонки одной таблицы можно объединять в группы, чтобы задать следующие параметры: + +* `DATA` — тип устройства хранения для данных колонок этой группы. Допустимые значения: `"ssd"`, `"rot"`. + {% if oss == true and backend_name == "YDB" %} -{% include [not_allow_for_olap](../../../../_includes/not_allow_for_olap_note.md) %} +{% include [OLTP_only_allow_note](../../../../_includes/only_allow_for_oltp_note.md) %} {% endif %} -Колонки одной таблицы можно объединять в группы, для того чтобы задать следующие параметры: +* `COMPRESSION` — кодек сжатия данных. Допустимые значения: `"off"`, `"lz4"`, `"zstd"`. -* `DATA` — тип устройства хранения для данных колонок этой группы. Допустимые значения: `"ssd"`, `"rot"`. -* `COMPRESSION` — кодек сжатия данных. Допустимые значения: `"off"`, `"lz4"`. - -По умолчанию все колонки находятся в одной группе с именем `default`. При желании, параметры этой группы тоже можно переопределить. - -В примере ниже для создаваемой таблицы добавляется группа колонок `family_large` и устанавливается для колонки `series_info`, а также переопределяются параметры для группы `default`, которая по умолчанию установлена для всех остальных колонок. - -```yql -CREATE TABLE series_with_families ( - series_id Uint64, - title Utf8, - series_info Utf8 FAMILY family_large, - release_date Uint64, - PRIMARY KEY (series_id), - FAMILY default ( - DATA = "ssd", - COMPRESSION = "off" - ), - FAMILY family_large ( - DATA = "rot", - COMPRESSION = "lz4" - ) -); -``` +{% if oss == true and backend_name == "YDB" %} + +{% include [codec_zstd_allow_for_olap_note](../../../../_includes/codec_zstd_allow_for_olap_note.md) %} + +{% endif %} + +* `COMPRESSION_LEVEL` — уровень сжатия кодека, если кодек поддерживает уровень сжатия. + +{% if oss == true and backend_name == "YDB" %} + +{% include [OLAP_only_allow_note](../../../../_includes/only_allow_for_olap_note.md) %} + +{% endif %} + +По умолчанию все колонки находятся в одной группе с именем `default`. При необходимости параметры этой группы тоже можно переопределить. В противном случае применяются предопределённые значения. + +В примерах ниже для создаваемых таблиц добавляется группа колонок `family_large`, которая устанавливается для колонки `series_info`, а также переопределяются параметры для группы `default`, которая по умолчанию применяется ко всем остальным колонкам. + + +{% list tabs %} + +- Создание строковой таблицы + + ```sql + CREATE TABLE series_with_families ( + series_id Uint64, + title Utf8, + series_info Utf8 FAMILY family_large, + release_date Uint64, + PRIMARY KEY (series_id), + FAMILY default ( + DATA = "ssd", + COMPRESSION = "off" + ), + FAMILY family_large ( + DATA = "rot", + COMPRESSION = "lz4" + ) + ); + ``` + +- Создание колоночной таблицы + + ```sql + CREATE TABLE series_with_families ( + series_id Uint64, + title Utf8, + series_info Utf8 FAMILY family_large, + release_date Uint64, + PRIMARY KEY (series_id), + FAMILY default ( + COMPRESSION = "lz4" + ), + FAMILY family_large ( + COMPRESSION = "zstd", + COMPRESSION_LEVEL = 5 + ) + ) + WITH (STORE = COLUMN); + ``` + +{% endlist %} {% note info %} 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 7fe200b006d8..44be78b367f0 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 @@ -246,6 +246,9 @@ CREATE TABLE ( * [Группы колонок](family.md). * [Дополнительные параметры](with.md). -Для колоночных таблиц при их создании возможно задать только [дополнительные параметры](with.md). +Для колоночных таблиц при их создании возможно задать: + +* [Группы колонок](family.md). +* [Дополнительные параметры](with.md). {% endif %}