Настройки сеанса на уровне запроса

Настройки на уровне запроса

​

Обзор

Существует несколько способов выполнять команды с определёнными настройками. Настройки задаются на нескольких уровнях, и каждый следующий уровень переопределяет предыдущие значения настройки.

​

Порядок приоритета

Порядок приоритета при определении настройки следующий:

1. Применение настройки непосредственно к пользователю или в профиле настроек

   • SQL (рекомендуется)
   • добавление одного или нескольких XML- или YAML-файлов в /etc/clickhouse-server/users.d

2. Настройки сеанса

   • Отправьте SET setting=value из SQL-консоли ClickHouse Cloud или через clickhouse client в интерактивном режиме. Аналогичным образом можно использовать сеансы ClickHouse в HTTP-протоколе. Для этого необходимо указать HTTP-параметр session_id.

3. Настройки запроса

   • При запуске clickhouse client в неинтерактивном режиме задайте параметр запуска --setting=value.
   • При использовании HTTP API передавайте CGI-параметры (URL?setting_1=value&setting_2=value...).
   • Задайте настройки в секции SETTINGS запроса SELECT. Значение настройки применяется только к этому запросу и после его выполнения сбрасывается до значения по умолчанию или предыдущего значения.

​

Возврат настройки к значению по умолчанию

Если вы изменили настройку и хотите вернуть ей значение по умолчанию, установите DEFAULT. Синтаксис выглядит так:

SET setting_name = DEFAULT

Например, значение async_insert по умолчанию — 0. Предположим, вы изменили его на 1:

SET async_insert = 1;

SELECT value FROM system.settings where name='async_insert';

Ответ:

┌─value──┐
│ 1      │
└────────┘

Следующая команда возвращает его значение к 0:

SET async_insert = DEFAULT;

SELECT value FROM system.settings where name='async_insert';

Теперь параметр снова имеет значение по умолчанию:

┌─value───┐
│ 0       │
└─────────┘

​

Пользовательские настройки

Помимо общих настроек, пользователи могут определять пользовательские настройки. Пользовательские настройки позволяют передавать параметры, специфичные для сеанса, на которые можно ссылаться в запросах, политиках или функциях. Это полезно, когда вам нужно:

• Фильтровать данные по идентификатору пользователя или организации
• Применять различную бизнес-логику в зависимости от контекста
• Сохранять информацию о состоянии между запросами в рамках сеанса

Имя пользовательской настройки должно начинаться с одного из нескольких предопределённых префиксов из заданного вами списка. Список префиксов можно указать с помощью настройки сервера custom_settings_prefixes, заданной в файле конфигурации сервера.

В примере ниже в качестве пользовательского префикса выбран SQL_:

<custom_settings_prefixes>SQL_</custom_settings_prefixes>

В ClickHouse Cloud невозможно указать собственный префикс. Все пользовательские настройки начинаются с префикса SQL_.

Чтобы задать пользовательскую настройку, используйте команду SET:

SET SQL_a = 123;

Чтобы получить текущее значение пользовательской настройки, используйте функцию getSetting():

SELECT getSetting('SQL_a');

​

Примеры

Во всех этих примерах значение настройки async_insert установлено в 1, а также показано, как просматривать настройки в работающей системе.

​

Применение настройки к пользователю напрямую с помощью SQL

Это создаст пользователя ingester с настройкой async_inset = 1:

CREATE USER ingester
IDENTIFIED WITH sha256_hash BY '7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3'
SETTINGS async_insert = 1

​

Изучите профиль настроек и его назначение пользователю

SHOW ACCESS

┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ ...                                                                                │
│ CREATE USER ingester IDENTIFIED WITH sha256_password SETTINGS async_insert = true  │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘

​

Использование SQL для создания профиля настроек и назначения его пользователю

Ниже создаётся профиль log_ingest с настройкой async_inset = 1:

CREATE
SETTINGS PROFILE log_ingest SETTINGS async_insert = 1

Эта команда создаёт пользователя ingester и назначает ему профиль настроек log_ingest:

CREATE USER ingester
IDENTIFIED WITH sha256_hash BY '7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3'
SETTINGS PROFILE log_ingest

​

Создание профиля настроек и пользователя с помощью XML

/etc/clickhouse-server/users.d/users.xml

<clickhouse>
    <profiles>
        <log_ingest>
            <async_insert>1</async_insert>
        </log_ingest>
    </profiles>

    <users>
        <ingester>
            <password_sha256_hex>7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3</password_sha256_hex>
            <profile>log_ingest</profile>
        </ingester>
        <default replace="true">
            <password_sha256_hex>7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3</password_sha256_hex>
            <access_management>1</access_management>
            <named_collection_control>1</named_collection_control>
        </default>
    </users>
</clickhouse>

​

Изучите профиль настроек и его назначение

SHOW ACCESS

┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ CREATE USER default IDENTIFIED WITH sha256_password                                │
│ CREATE USER ingester IDENTIFIED WITH sha256_password SETTINGS PROFILE log_ingest   │
│ CREATE SETTINGS PROFILE default                                                    │
│ CREATE SETTINGS PROFILE log_ingest SETTINGS async_insert = true                    │
│ CREATE SETTINGS PROFILE readonly SETTINGS readonly = 1                             │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘

​

Назначить настройку для сеанса

SET async_insert =1;
SELECT value FROM system.settings where name='async_insert';

┌─value──┐
│ 1      │
└────────┘

​

Задать настройку при выполнении запроса

INSERT INTO YourTable
SETTINGS async_insert=1
VALUES (...)

​

См. также

• Описание настроек ClickHouse приведено на странице Настройки.
• Глобальные настройки сервера