查询级别会话设置

概述

有多种方式可以在运行语句时指定特定的设置。 设置是分层配置的，每一后续层都会覆盖该设置在前一层中的值。

优先级顺序

定义设置时的优先级顺序为：

1. 直接将设置应用于某个用户，或在某个设置配置文件中为用户应用设置

   • 使用 SQL（推荐）
   • 将一个或多个 XML 或 YAML 文件添加到 /etc/clickhouse-server/users.d 目录

2. 会话级设置

   • 从 ClickHouse Cloud SQL 控制台或 clickhouse client 的交互模式发送 SET setting=value。类似地，也可以在 HTTP 协议中使用 ClickHouse 会话。 为此，需要指定 session_id HTTP 参数。

3. 查询级设置

   • 在非交互模式启动 clickhouse client 时，通过启动参数 --setting=value 设置。
   • 使用 HTTP API 时，以 CGI 参数形式传递（URL?setting_1=value&setting_2=value...）。
   • 在 SELECT 查询的 SETTINGS 子句中定义设置。该设置值仅应用于该次查询，在查询执行完成后将被重置为默认值或先前的值。

将设置恢复为默认值

如果您修改了某个设置并希望将其恢复为默认值，请将该值设为 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       │
└─────────┘

自定义设置

除了常见的settings之外，用户还可以定义自定义设置。 自定义设置允许您传递会话特定参数，并可在查询、策略或函数中引用这些参数。这在您需要执行以下操作时非常有用：

• 根据用户身份或所属组织筛选数据
• 根据上下文应用不同的业务逻辑
• 在同一会话的多次查询之间保留有状态信息

自定义设置名称必须以某个前缀开头，而此前缀必须来自您定义的预定义前缀列表。 前缀列表可通过 custom_settings_prefixes 服务器 settings 指定，并在服务器配置文件中定义。

在下面的示例中，SQL_ 被选为自定义前缀：

<custom_settings_prefixes>SQL_</custom_settings_prefixes>

注意

在 ClickHouse Cloud 中，无法指定自定义前缀。 所有自定义用户设置都以 SQL_ 为前缀。

要定义自定义设置，请使用 SET 命令：

SET SQL_a = 123;

要获取自定义设置的当前值，请使用 getSetting() function：

SELECT getSetting('SQL_a');

示例

这些示例都将 async_insert 设置为 1，并展示如何在正在运行的系统中查看这些设置。

使用 SQL 将设置直接应用到用户

以下示例创建用户 ingester，并为其设置 async_insert = 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 (...)

另请参阅

• 查看 Settings 页面，了解 ClickHouse 各项设置的说明。
• 全局服务器设置