Манипуляции со Столбцами

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

Синтаксис:

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

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

• 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 для таблиц на всех удаленных серверах.