クエリレベルのセッション設定

クエリレベルの設定

​

概要

特定の設定を指定してステートメントを実行する方法は複数あります。 設定はレイヤー単位で適用され、後続の各レイヤーが前のレイヤーの設定値を上書きします。

​

優先順位

設定を定義する際の優先順位は、次のとおりです。

1. ユーザーに直接、または設定プロファイル内で設定を適用する

   • SQL (推奨)
   • 1 つ以上の XML または YAML ファイルを /etc/clickhouse-server/users.d に追加する

2. セッション設定

   • ClickHouse Cloud の SQL Console または clickhouse client の対話型モードから SET setting=value を送信します。同様に、HTTP protocol で ClickHouse セッションを使用することもできます。これを行うには、 session_id HTTP parameter を指定する必要があります。

3. クエリ設定

   • 非対話型モードで clickhouse client を起動する際に、起動 parameter --setting=value を指定します。
   • HTTP API を使用する場合は、CGI parameter (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       │
└─────────┘

​

カスタム設定

共通の設定に加えて、ユーザーはカスタム設定を定義できます。 カスタム設定を使うと、クエリ、ポリシー、関数内から参照できるセッション固有のパラメータを渡せます。これは、次のような場合に便利です。

• ユーザーの identity や組織に基づいてデータをフィルタする
• コンテキストに応じて異なるビジネスロジックを適用する
• セッション内でクエリ間にまたがって状態を保持する

カスタム設定名は、定義したリストにある、あらかじめ定義されたプレフィックスのいずれかで始める必要があります。 プレフィックスのリストは、サーバー設定ファイルで定義する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 を使って設定をユーザーに直接適用する

これにより、設定 async_inset = 1 を指定したユーザー ingester が作成されます。

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 を使用して設定プロファイルを作成し、ユーザーに割り当てる

これにより、設定 async_inset = 1 を持つ log_ingest プロファイルが作成されます。

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 の設定については、設定 ページを参照してください。
• サーバーのグローバル設定