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 без дополнительных ключевых слов (то есть без 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 в CREATE SETTINGS PROFILE: это предложение SETTINGS задаёт полный список параметров.

Ключевые слова 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;

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

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

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

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

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

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

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

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

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;