ALTER SETTINGS PROFILE

Изменяет профили настроек. Синтаксис:

ALTER SETTINGS PROFILE [IF EXISTS] name1 [RENAME TO new_name |, name2 [,...]]
    [ON CLUSTER cluster_name]
    [SETTINGS variable [= value] [MIN [=] min_value] [MAX [=] max_value] [CONST|READONLY|WRITABLE|CHANGEABLE_IN_READONLY] | INHERIT 'profile_name'] [,...]
    [ADD|MODIFY SETTINGS variable [= value] [MIN [=] min_value] [MAX [=] max_value] [CONST|READONLY|WRITABLE|CHANGEABLE_IN_READONLY] [,...]
    [SET variable [= value] [MIN [=] min_value] [MAX [=] max_value] [CONST|READONLY|WRITABLE|CHANGEABLE_IN_READONLY] [,...] ]
    [DROP SETTINGS variable [,...] ]
    [ADD PROFILES 'profile_name' [,...] ]
    [DROP PROFILES 'profile_name' [,...] ]
    [DROP ALL SETTINGS]
    [DROP ALL PROFILES]
    [TO {{role1 | user1 [, role2 | user2 ...]} | NONE | ALL | ALL EXCEPT {role1 | user1 [, role2 | user2 ...]}}]

Предложение ON CLUSTER позволяет изменять профили настроек в кластере, см. Distributed DDL.

Замена и изменение настроек

ALTER SETTINGS PROFILE поддерживает два разных способа изменения настроек и родительских (наследуемых) профилей. Они работают совершенно по-разному, поэтому важно выбрать подходящий вариант.

Форма замены: просто `SETTINGS` / `INHERIT`

Предложение SETTINGS без дополнительных ключевых слов (то есть без ADD, MODIFY или DROP) полностью заменяет список настроек и все родительские профили профиля на ровно то, что вы перечислите. Всё, что было задано ранее, но не указано в списке, будет молча удалено — без каких-либо предупреждений.

CREATE SETTINGS PROFILE OR REPLACE p
    SETTINGS max_execution_time = 10, enable_lazy_columns_replication = 1;

ALTER SETTINGS PROFILE p SETTINGS max_memory_usage = 16106127360;

SHOW CREATE SETTINGS PROFILE p;
-- → CREATE SETTINGS PROFILE p SETTINGS max_memory_usage = 16106127360
-- max_execution_time and enable_lazy_columns_replication are gone.

Поскольку форма SETTINGS без дополнительных указаний полностью заменяет содержимое, её использование для того, чтобы “переопределить один параметр” поверх заполненного базового профиля, приведёт к удалению всех остальных параметров (и всех родительских профилей) этого профиля. Если вам нужно изменить только один параметр, сохранив остальные, используйте инкрементальную форму MODIFY/ADD/DROP, описанную ниже.

Это то же поведение, что и у SETTINGS в CREATE SETTINGS PROFILE: это предложение SETTINGS задаёт полный список параметров.

Инкрементальная форма: `ADD` / `MODIFY` / `DROP`

Ключевые слова ADD, MODIFY и DROP изменяют отдельные записи, не затрагивая всё остальное в профиле:

ADD SETTINGS variable = value [constraints] — добавляет настройку, которой ещё нет.
MODIFY SETTINGS variable = value [constraints] — заменяет запись одной настройки. Перезаписывается вся запись целиком (значение и ограничения), поэтому, если вы хотите их сохранить, заново укажите MIN/MAX/READONLY/и т. д.
DROP SETTINGS variable [,...] — удаляет перечисленные настройки.
ADD PROFILES 'profile_name' [,...] / DROP PROFILES 'profile_name' [,...] — добавляет или удаляет родительские (наследуемые) профили.
DROP ALL SETTINGS / DROP ALL PROFILES — удаляет все настройки или все родительские профили.

Несколько таких секций можно объединить в одном операторе, например DROP SETTINGS a ADD SETTINGS b = 1. SET variable = value — это псевдоним для MODIFY SETTINGS variable = value. Он предусмотрен, потому что SET звучит естественно, а ввод заменяющего предложения SETTINGS, когда предполагалось инкрементальное изменение, — распространённая ошибка.

Примеры

Переопределите один параметр, сохранив остальные параметры в уже заполненном профиле:

ALTER SETTINGS PROFILE p MODIFY SETTINGS max_memory_usage = 16106127360;

Добавьте новую настройку с ограничениями и удалите другую:

ALTER SETTINGS PROFILE my_profile
    DROP SETTINGS readonly
    ADD SETTINGS max_threads = 8 MIN 4 MAX 16 WRITABLE;

Управляйте родительскими профилями в инкрементальном режиме:

ALTER SETTINGS PROFILE my_profile ADD PROFILES p1;
ALTER SETTINGS PROFILE my_profile DROP PROFILES p1;

Всегда проверяйте результат командой SHOW CREATE SETTINGS PROFILE:

SHOW CREATE SETTINGS PROFILE my_profile;

Инкрементальные изменения vs полная замена

Предложение SETTINGS само по себе удаляет из профиля все существующие настройки и все наследуемые (родительские) профили перед применением новых.

Чтобы изменить одну настройку, сохранив остальные, используйте ADD SETTINGS или MODIFY SETTINGS (см. примеры ниже).

ADD и MODIFY

И ADD SETTINGS, и MODIFY SETTINGS сохраняют остальные настройки в профиле, но по-разному обрабатывают существующую запись для той же настройки:

ADD SETTINGS variable = value ... сначала удаляет любую существующую запись для variable, а затем добавляет новую. Поэтому эта команда заменяет значение вместе со всеми ограничениями этой настройки. Любые ранее заданные MIN, MAX или режим записи (READONLY/WRITABLE/CONST/CHANGEABLE_IN_READONLY) для variable, которые вы не повторите, будут отброшены.
MODIFY SETTINGS variable = value ... объединяет изменения по полям: команда переопределяет только те поля, которые вы действительно укажете (значение, MIN, MAX или режим записи), а остальные поля этой настройки оставляет без изменений.

Кратко: используйте MODIFY SETTINGS, если хотите изменить только один аспект настройки (например, только значение, сохранив существующий MAX); используйте ADD SETTINGS, если хотите заново определить настройку с нуля.

Примеры

Создайте профиль для использования в примерах ниже:

CREATE SETTINGS PROFILE OR REPLACE p SETTINGS max_execution_time = 60;

ИЗМЕНИТЬ НАСТРОЙКИ

Добавьте или измените один параметр, оставив остальные без изменений:

ALTER SETTINGS PROFILE p MODIFY SETTINGS max_memory_usage = 20000000000;
SHOW CREATE SETTINGS PROFILE p;
-- CREATE SETTINGS PROFILE p SETTINGS
--     max_execution_time = 60,
--     max_memory_usage = 20000000000

Поскольку MODIFY выполняет слияние по полям, изменение только значения настройки сохраняет её существующие ограничения:

ALTER SETTINGS PROFILE p MODIFY SETTINGS max_memory_usage = 20000000000 MAX 30000000000;
ALTER SETTINGS PROFILE p MODIFY SETTINGS max_memory_usage = 25000000000;
SHOW CREATE SETTINGS PROFILE p;
-- ... max_memory_usage = 25000000000 MAX 30000000000  -- the MAX constraint is preserved

ADD SETTINGS

Добавить настройку (при этом сохранив остальные), полностью переопределив её, если она уже существует:

ALTER SETTINGS PROFILE p ADD SETTINGS max_threads = 8 MAX 16 READONLY;

В отличие от MODIFY, при повторном выполнении ADD только со значением ранее заданные ограничения для этого параметра удаляются:

ALTER SETTINGS PROFILE p ADD SETTINGS max_threads = 4;
SHOW CREATE SETTINGS PROFILE p;
-- ... max_threads = 4   -- the MAX and READONLY constraints are gone

DROP SETTINGS

Удаляет одну или несколько настроек по имени:

ALTER SETTINGS PROFILE p DROP SETTINGS max_threads;

Удалите все настройки сразу:

ALTER SETTINGS PROFILE p DROP ALL SETTINGS;

Работа с наследуемыми профилями

Добавляйте и удаляйте родительские (наследуемые) профили, не изменяя собственные настройки профиля:

ALTER SETTINGS PROFILE p ADD PROFILES base_profile;
ALTER SETTINGS PROFILE p DROP PROFILES base_profile;
ALTER SETTINGS PROFILE p DROP ALL PROFILES;

Справочник по SQL

Типы данных

Движки

Функции

Форматы

Настройки

Системные таблицы

Озёра данных

Замена и изменение настроек

Форма замены: просто `SETTINGS` / `INHERIT`

Инкрементальная форма: `ADD` / `MODIFY` / `DROP`

Примеры

Инкрементальные изменения vs полная замена

ADD и MODIFY

Примеры

ИЗМЕНИТЬ НАСТРОЙКИ

ADD SETTINGS

DROP SETTINGS

Работа с наследуемыми профилями

​Замена и изменение настроек

​Форма замены: просто SETTINGS / INHERIT

​Инкрементальная форма: ADD / MODIFY / DROP

​Примеры

​Инкрементальные изменения vs полная замена

​ADD и MODIFY

​Примеры

​ИЗМЕНИТЬ НАСТРОЙКИ

​ADD SETTINGS

​DROP SETTINGS

​Работа с наследуемыми профилями

Замена и изменение настроек

Форма замены: просто `SETTINGS` / `INHERIT`

Инкрементальная форма: `ADD` / `MODIFY` / `DROP`

Примеры

Инкрементальные изменения vs полная замена

ADD и MODIFY

Примеры

ИЗМЕНИТЬ НАСТРОЙКИ

ADD SETTINGS

DROP SETTINGS

Работа с наследуемыми профилями