--- metadata: - name: generator content: Diplodoc Platform v5.50.6 alternate: - https://ydb.tech/docs/en/yql/reference/syntax/alter_table/columns.md?version=main - https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/columns.md?version=main sourcePath: ru/core/yql/reference/syntax/alter_table/columns.md --- > **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt # Изменение колонок YDB поддерживает возможность добавлять колонки в строковые и колоночные таблицы, удалять неключевые колонки из таблиц, а также изменять свойства существующих колонок. ## ADD COLUMN Строит новую колонку с указанными именем, типом и опциями для указанной таблицы. ```yql ALTER TABLE table_name ADD COLUMN column_name column_data_type [FAMILY ] [NULL | NOT NULL] [DEFAULT ] [COMPRESSION([algorithm=[, level=]])] [ENCODING([OFF|DICT])]; ``` ## Параметры запроса ### table_name Путь таблицы, для которой требуется добавить новую колонку. ### column_name Имя колонки, которая будет добавлена в указанную таблицу. При выборе имени для колонки учитывайте общие [правила именования колонок](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#column-naming-rules). ### column_data_type Тип данных колонки. Полный список типов данных, которые поддерживает YDB доступен в разделе [Типы данных YQL](https://ydb.tech/docs/ru/yql/reference/types/index.md?version=main). ### FAMILY (настройка колонки) Указание принадлежности данной колонки к указанной группе колонок. Подробнее в разделе [Группы колонок](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/family.md?version=main). ### DEFAULT {% note warning %} Опция `DEFAULT` поддерживается: * Только для [строковых](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#row-oriented-tables) таблиц. * Только с литеральными значениями. {% endnote %} Позволяет задать значение по умолчанию для колонки. Если при вставке строки значение для данной колонки не указано, будет использовано указанное значение по умолчанию. Значение по умолчанию должно соответствовать типу данных колонки. Конструкция `DEFAULT false NOT NULL` недопустима по причине неоднозначности интерпретации. В таком случае следует использовать перечисление через запятые или изменить порядок опций. ### NULL Опция колонки, которое разрешает запись `NULL` в качестве значений колонки. Это является поведением по умолчанию. ### NOT NULL Ограничение колонки, которое запрещает запись `NULL` в качестве значений колонки. По умолчанию это ограничение отсутствует. ### COMPRESSION([algorithm=[, level=]]) {% note warning %} Поддерживается только для [колоночных](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#column-oriented-tables) таблиц. {% endnote %} Для колонок можно задать следующие параметры сжатия: * `algorithm` — алгоритм сжатия данных. Допустимые значения: `off` (отключение сжатия), `lz4`, `zstd`. * `level` — уровень сжатия, поддерживается только для алгоритма `zstd` (допустимы значения от 0 до 22). Если `COMPRESSION()` указан без параметров, для колонки используется сжатие по умолчанию. Сейчас это `lz4`; в будущих версиях появится возможность настраивать сжатие по умолчанию на уровне кластера или таблицы. ### ENCODING([OFF|DICT]) {% note warning %} Поддерживается только для [колоночных](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#column-oriented-tables) таблиц. {% endnote %} Позволяет задать способ кодирования данных колонки. Доступные варианты: * `ENCODING(DICT)` — включает словарное кодирование (dictionary encoding). Повторяющиеся значения заменяются небольшими целочисленными идентификаторами, а сами значения хранятся в словаре. Словарное кодирование эффективно для колонок с низкой кардинальностью (небольшим количеством уникальных значений). Позволяет сократить объем хранимых данных и ускорить выполнение некоторых операций. Поддерживается только для сравнимых типов данных, таких как `String`, `Timestamp`, `UInt64` и других. Для несравнимых типов, таких как `Json`, `JsonDocument` или `Yson`, использование `ENCODING(DICT)` приведет к ошибке. * `ENCODING(OFF)` — отключает специальное кодирование. Данные будут храниться в стандартном формате без дополнительного кодирования. Если `ENCODING()` задается без параметров, то для колонки будет использоваться кодирование по умолчанию. Сейчас это `OFF`; в будущих версиях появится возможность настраивать кодирование по умолчанию на уровне базы или таблицы. ## Пример Приведённый ниже код добавит к таблице `episodes` колонку `views` с типом данных `Uint64`. ```yql ALTER TABLE episodes ADD COLUMN views Uint64; ``` Приведённый ниже код добавит к таблице `episodes` колонку `rate` с типом данных `Double` и значением по умолчанию `5.0`. ```yql ALTER TABLE episodes ADD COLUMN rate Double NOT NULL DEFAULT 5.0; ALTER TABLE episodes ADD COLUMN rate Double (DEFAULT 5.0, NOT NULL); -- альтернативный синтаксис ``` ## ALTER COLUMN Изменяет свойства существующей колонки в указанной таблице. Изменение свойства происходит без пересоздания колонки. Некоторые свойства применяются только к свежим записанным данным или в процессе компакшена (детали можно найти в описании конкретного свойства) ```yql ALTER TABLE table_name ALTER COLUMN column_name SET [FAMILY ] [NOT NULL] [DEFAULT ] [COMPRESSION([algorithm=[, level=]])] [ENCODING([OFF|DICT])]; ALTER TABLE table_name ALTER COLUMN column_name DROP [FAMILY] [NOT NULL] [DEFAULT] [COMPRESSION] [ENCODING]; ``` ### Параметры запроса #### table_name Путь к таблице, в которой требуется изменить колонку. #### column_name Имя колонки, которая будет изменена в указанной таблице. #### SET Установить свойство для указанной колонки. #### DROP Удалить свойство для указанной колонки. ### FAMILY (настройка колонки) Указание принадлежности данной колонки к указанной группе колонок. Подробнее в разделе [Группы колонок](https://ydb.tech/docs/ru/yql/reference/syntax/create_table/family.md?version=main). ### DEFAULT {% note warning %} Опция `DEFAULT` поддерживается: * Только для [строковых](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#row-oriented-tables) таблиц. * Только с литеральными значениями. {% endnote %} Позволяет задать значение по умолчанию для колонки. Если при вставке строки значение для данной колонки не указано, будет использовано указанное значение по умолчанию. Значение по умолчанию должно соответствовать типу данных колонки. ### NOT NULL Существуют две операции: * `SET NOT NULL` — устанавливает ограничение `NOT NULL` для колонки. * `DROP NOT NULL` — снимает ограничение `NOT NULL` с колонки, снова разрешая значения `NULL`. Подробнее о работе этих операций можно прочитать [здесь](https://ydb.tech/docs/ru/yql/reference/syntax/alter_table/not_null.md?version=main). ### COMPRESSION([algorithm=[, level=]]) {% note warning %} Поддерживается только для [колоночных](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#column-oriented-tables) таблиц. {% endnote %} Для колонок можно задать следующие параметры сжатия: * `algorithm` — алгоритм сжатия данных. Допустимые значения: `off` (отключение сжатия), `lz4`, `zstd`. * `level` — уровень сжатия, поддерживается только для алгоритма `zstd` (допустимы значения от 0 до 22). Если `COMPRESSION()` указан без параметров, для колонки используется сжатие по умолчанию. Сейчас это `lz4`; в будущих версиях появится возможность настраивать сжатие по умолчанию на уровне кластера или таблицы. ### ENCODING([OFF|DICT]) {% note warning %} Поддерживается только для [колоночных](https://ydb.tech/docs/ru/concepts/datamodel/table.md?version=main#column-oriented-tables) таблиц. {% endnote %} Позволяет задать способ кодирования данных колонки. Доступные варианты: * `ENCODING(DICT)` — включает словарное кодирование (dictionary encoding). Повторяющиеся значения заменяются небольшими целочисленными идентификаторами, а сами значения хранятся в словаре. Словарное кодирование эффективно для колонок с низкой кардинальностью (небольшим количеством уникальных значений). Позволяет сократить объем хранимых данных и ускорить выполнение некоторых операций. Поддерживается только для сравнимых типов данных, таких как `String`, `Timestamp`, `UInt64` и других. Для несравнимых типов, таких как `Json`, `JsonDocument` или `Yson`, использование `ENCODING(DICT)` приведет к ошибке. * `ENCODING(OFF)` — отключает специальное кодирование. Данные будут храниться в стандартном формате без дополнительного кодирования. Если `ENCODING()` задается без параметров, то для колонки будет использоваться кодирование по умолчанию. Сейчас это `OFF`; в будущих версиях появится возможность настраивать кодирование по умолчанию на уровне базы или таблицы. В одном запросе `ALTER TABLE` можно указать несколько действий `ALTER COLUMN` через запятую. ### Примеры Приведённый ниже код задаёт значение по умолчанию для колонки `rate` в таблице `episodes`. ```yql ALTER TABLE episodes ALTER COLUMN rate SET DEFAULT 5.0; ``` Приведённый ниже код одним запросом изменяет значения по умолчанию для нескольких колонок таблицы — у `col_1` и `col_2` устанавливает новые значения, у `col_3` сбрасывает значение по умолчанию. ```yql ALTER TABLE default_columns ALTER COLUMN col_1 SET DEFAULT "new_a"u, ALTER COLUMN col_2 SET DEFAULT 99, ALTER COLUMN col_3 DROP DEFAULT; ``` Сброс настроек сжатия колонки ```yql ALTER TABLE compressed_table ALTER COLUMN info SET COMPRESSION(); ``` После выполнения запроса для колонки снова действует алгоритм сжатия по умолчанию (см. описание опции `COMPRESSION` выше). Включение словарного кодирования на колонке ```yql ALTER TABLE movies ALTER COLUMN genre SET ENCODING(DICT); ``` ## DROP COLUMN Удаляет колонку из таблицы с указанным именем. ```yql ALTER TABLE table_name DROP COLUMN column_name; ``` ### Параметры запроса #### table_name Путь к таблице, в которой требуется удалить колонку. #### column_name Имя колонки, которая будет удалена из указанной таблицы. ### Пример Приведённый ниже код удалит колонку `views` из таблицы `episodes`. ```yql ALTER TABLE episodes DROP COLUMN views; ```