メインコンテンツへスキップ
メインコンテンツへスキップ

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

概要​

特定の設定を指定してステートメントを実行する方法はいくつかあります。 設定は階層的に構成されており、後のレイヤーほど前のレイヤーで指定された設定値を再定義します。

優先順位​

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

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

    • SQL（推奨）
    • 1 つ以上の 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       │
└─────────┘

カスタム設定​

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

  • ユーザー ID や組織に基づいてデータをフィルタリングする
  • Context に応じて異なるビジネスロジックを適用する
  • セッション内で複数のクエリにまたがって状態を持つ情報を維持する

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

以下の SQL は、設定 async_inset = 1 を持つユーザー ingester を作成します。

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

次の 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'
-- 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 (...)

関連項目​