Манипуляции с колонками

Набор запросов, позволяющий изменять структуру таблицы.

Синтаксис:

В запросе укажите список из одного или нескольких действий, разделённых запятыми. Каждое действие является операцией над колонкой.

Поддерживаются следующие действия:

• ADD COLUMN — Добавляет новую колонку в таблицу.
• DROP COLUMN — Удаляет колонку.
• RENAME COLUMN — Переименовывает существующую колонку.
• CLEAR COLUMN — Сбрасывает значения колонки.
• COMMENT COLUMN — Добавляет текстовый комментарий к колонке.
• MODIFY COLUMN — Изменяет тип колонки, выражение по умолчанию, TTL и настройки колонки.
• MODIFY COLUMN REMOVE — Удаляет одно из свойств колонки.
• MODIFY COLUMN MODIFY SETTING - Изменяет настройки колонки.
• MODIFY COLUMN RESET SETTING - Сбрасывает настройки колонки.
• MATERIALIZE COLUMN — Отображает колонку в частях, где колонка отсутствует. Эти действия описаны подробно ниже.

ADD COLUMN

Добавляет новую колонку в таблицу с указанным name, type, codec и default_expr (см. раздел Выражения по умолчанию).

Если включен клаусула IF NOT EXISTS, запрос не вернет ошибку, если колонка уже существует. Если вы укажете AFTER name_after (имя другой колонки), колонка добавляется после указанной в списке колонок таблицы. Если вы хотите добавить колонку в начало таблицы, используйте клаусулу FIRST. В противном случае колонка добавляется в конец таблицы. Для цепочки действий name_after может быть именем колонки, добавленной в одном из предыдущих действий.

Добавление колонки просто изменяет структуру таблицы, не выполняя никаких действий с данными. Данные не появляются на диске после ALTER. Если данные отсутствуют для колонки при чтении из таблицы, они заполняются значениями по умолчанию (путем выполнения выражения по умолчанию, если оно есть, или с использованием нулей или пустых строк). Колонка появится на диске после слияния частей данных (см. MergeTree).

Этот подход позволяет заверить запрос ALTER мгновенно, не увеличивая объем старых данных.

Пример:

DROP COLUMN

Удаляет колонку с именем name. Если указана клаусула IF EXISTS, запрос не вернет ошибку, если колонка не существует.

Удаляет данные из файловой системы. Поскольку это удаляет целые файлы, запрос выполняется практически мгновенно.

подсказка

Вы не можете удалить колонку, если на нее ссылается материализованное представление. В противном случае будет возвращена ошибка.

Пример:

RENAME COLUMN

Переименовывает колонку name в new_name. Если указана клаусула IF EXISTS, запрос не вернет ошибку, если колонка не существует. Поскольку переименование не затрагивает подлежащие данные, запрос выполняется почти мгновенно.

ПРИМЕЧАНИЕ: Колонки, указанные в выражении ключа таблицы (либо с ORDER BY, либо с PRIMARY KEY), не могут быть переименованы. Попытка изменить эти колонки приведет к SQL Error [524].

Пример:

CLEAR COLUMN

Сбрасывает все данные в колонке для заданной партиции. Узнайте больше о настройке имени партиции в разделе Как задать выражение партиции.

Если указана клаусула IF EXISTS, запрос не вернет ошибку, если колонка не существует.

Пример:

COMMENT COLUMN

Добавляет комментарий к колонке. Если указана клаусула IF EXISTS, запрос не вернет ошибку, если колонка не существует.

Каждая колонка может иметь один комментарий. Если комментарий уже существует для колонки, новый комментарий заменяет предыдущий.

Комментарии хранятся в колонке comment_expression, возвращаемой запросом DESCRIBE TABLE.

Пример:

MODIFY COLUMN

Этот запрос изменяет свойства колонки name:

• Тип

• Выражение по умолчанию

• Кодек сжатия

• TTL

• Настройки на уровне колонки

Для примеров изменения кодеков сжатия колонок смотрите Кодеки сжатия колонок.

Для примеров изменения TTL колонок смотрите TTL колонок.

Для примеров изменения настроек на уровне колонок смотрите Настройки на уровне колонки.

Если указана клаусула IF EXISTS, запрос не вернет ошибку, если колонка не существует.

При изменении типа значения конвертируются так, как если бы функции toType были применены к ним. Если изменяется только выражение по умолчанию, запрос не выполняет ничего сложного и завершается практически мгновенно.

Пример:

Изменение типа колонки является единственным сложным действием — оно изменяет содержимое файлов с данными. Для больших таблиц это может занять много времени.

Запрос также может изменить порядок колонок с использованием клаусул FIRST | AFTER, смотрите описание ADD COLUMN, но тип колонки является обязательным в этом случае.

Пример:

Запрос ALTER является атомарным. Для таблиц MergeTree он также осуществляется без блокировок.

Запрос ALTER для изменения колонок реплицируется. Инструкции сохраняются в ZooKeeper, а затем каждая реплика применяет их. Все запросы ALTER выполняются в одном и том же порядке. Запрос ожидает завершения соответствующих действий на других репликах. Однако запрос на изменение колонок в реплицированной таблице может быть прерван, и все действия будут выполнены асинхронно.

MODIFY COLUMN REMOVE

Удаляет одно из свойств колонки: DEFAULT, ALIAS, MATERIALIZED, CODEC, COMMENT, TTL, SETTINGS.

Синтаксис:

Пример

Удалить TTL:

См. также

• REMOVE TTL.

MODIFY COLUMN MODIFY SETTING

Изменяет настройку колонки.

Синтаксис:

Пример

Изменить max_compress_block_size колонки на 1MB:

MODIFY COLUMN RESET SETTING

Сбрасывает настройку колонки, также удаляет декларацию настройки в выражении колонки запроса CREATE таблицы.

Синтаксис:

Пример

Сбросить настройку колонки max_compress_block_size на значение по умолчанию:

MATERIALIZE COLUMN

Материализует колонку с выражением значения DEFAULT или MATERIALIZED. При добавлении материализованной колонки с помощью ALTER TABLE table_name ADD COLUMN column_name MATERIALIZED существующие строки без материализованных значений не заполняются автоматически. Команда MATERIALIZE COLUMN может быть использована для переписывания существующих данных колонок после того, как выражение DEFAULT или MATERIALIZED было добавлено или обновлено (что обновляет только метаданные, но не изменяет существующие данные). Учтите, что материализация колонки в ключе сортировки является недопустимой операцией, поскольку это может нарушить порядок сортировки. Реализовано как мутация.

Для колонок с новым или обновленным выражением значения MATERIALIZED все существующие строки переписываются.

Для колонок с новым или обновленным выражением значения DEFAULT поведение зависит от версии ClickHouse:

• В ClickHouse < v24.2 все существующие строки переписываются.
• В ClickHouse >= v24.2 различает, если значение строки в колонке с выражением значения DEFAULT было явно указано при вставке или нет, т.е. вычислено из выражения значения DEFAULT. Если значение было явно указано, ClickHouse сохраняет его как есть. Если значение было вычислено, ClickHouse изменяет его на новое или обновленное выражение значения MATERIALIZED.

Синтаксис:

• Если вы укажете PARTITION, колонка будет материализована только с указанной партицией.

Пример

См. также

• MATERIALIZED.

Ограничения

Запрос ALTER позволяет создавать и удалять отдельные элементы (колонки) в вложенных структурах данных, но не целые вложенные структуры данных. Чтобы добавить вложенную структуру данных, вы можете добавлять колонки с именем, например name.nested_name и типом Array(T). Вложенная структура данных эквивалентна нескольким колонкам массива с именем, имеющим один и тот же префикс перед точкой.

Нет поддержки для удаления колонок в первичном ключе или ключе выборки (колонки, используемые в выражении ENGINE). Изменение типа для колонок, входящих в первичный ключ, возможно только в том случае, если это изменение не приведет к модификации данных (например, вам разрешается добавлять значения в Enum или изменять тип с DateTime на UInt32).

Если запрос ALTER недостаточен для внесения необходимых изменений в таблицу, вы можете создать новую таблицу, скопировать в нее данные с помощью запроса INSERT SELECT, затем переключить таблицы с помощью запроса RENAME и удалить старую таблицу.

Запрос ALTER блокирует все чтения и записи для таблицы. Другими словами, если в это время выполняется длинный SELECT, запрос ALTER будет ожидать его завершения. В то же время все новые запросы к той же таблице будут ожидать, пока выполняется этот ALTER.

Для таблиц, которые не хранят данные сами по себе (например, Merge и Distributed), ALTER просто изменяет структуру таблицы и не меняет структуру подчиненных таблиц. Например, при выполнении ALTER для Distributed таблицы вам также придется выполнить ALTER для таблиц на всех удаленных серверах.