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

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

Синтаксис:

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

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

• 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 блокирует все операции чтения и записи для таблицы. Другими словами, если в момент выполнения запроса ALTER выполняется длительный SELECT, запрос ALTER будет ждать его завершения. В то же время все новые запросы к той же таблице будут ждать, пока выполняется этот ALTER.

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