Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

Обзор

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

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

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

  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>

Чтобы задать пользовательскую настройку, используйте команду 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

<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 (...)

См. также

Navigation