Перейти к основному содержимому
Перейти к основному содержимому

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

Обзор​

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

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

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

  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'
-- highlight-next-line
SETTINGS async_insert = 1

Просмотрите профиль настроек и его назначение​

SHOW ACCESS

┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ ...                                                                                │
# highlight-next-line
│ 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'
-- highlight-next-line
SETTINGS PROFILE log_ingest

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

<clickhouse>
# highlight-start \{#highlight-start}
    <profiles>
        <log_ingest>
            <async_insert>1</async_insert>
        </log_ingest>
    </profiles>
# highlight-end \{#highlight-end}

    <users>
        <ingester>
            <password_sha256_hex>7e099f39b84ea79559b3e85ea046804e63725fd1f46b37f281276aae20f86dc3</password_sha256_hex>
# highlight-start \{#highlight-start}
            <profile>log_ingest</profile>
# highlight-end \{#highlight-end}
        </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>

Examine the settings profile and assignment​

ПОКАЗАТЬ ДОСТУП

┌─ACCESS─────────────────────────────────────────────────────────────────────────────┐
│ CREATE USER default IDENTIFIED WITH sha256_password                                │
# highlight-next-line \{#highlight-next-line}
│ CREATE USER ingester IDENTIFIED WITH sha256_password SETTINGS PROFILE log_ingest   │
│ CREATE SETTINGS PROFILE default                                                    │
# highlight-next-line \{#highlight-next-line}
│ CREATE SETTINGS PROFILE log_ingest SETTINGS async_insert = true                    │
│ CREATE SETTINGS PROFILE readonly SETTINGS readonly = 1                             │
│ ...                                                                                │
└────────────────────────────────────────────────────────────────────────────────────┘

Assign a setting to a session​

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

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

Assign a setting during a query​

INSERT INTO YourTable
-- highlight-next-line
SETTINGS async_insert=1
VALUES (...)

См. также​