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

設定上の制約事項

概要​

ClickHouse における設定に対する「制約」とは、その設定に付与できる制限やルールを指します。これらの制約を適用することで、データベースの安定性、セキュリティ、および予測可能な動作を維持できます。

制約の定義​

設定に対する制約は、user.xml 設定ファイルの profiles セクションで定義できます。これにより、ユーザーが SET ステートメントを使用して一部の設定を変更できないようにします。

制約は次のように定義します。

<profiles>
  <user_name>
    <constraints>
      <設定名_1>
        <min>lower_boundary</min>
      </設定名_1>
      <設定名_2>
        <max>upper_boundary</max>
      </設定名_2>
      <設定名_3>
        <min>lower_boundary</min>
        <max>upper_boundary</max>
      </設定名_3>
      <設定名_4>
        <readonly/>
      </設定名_4>
      <設定名_5>
        <min>lower_boundary</min>
        <max>upper_boundary</max>
        <changeable_in_readonly/>
      </設定名_5>
      <設定名_6>
        <min>lower_boundary</min>
        <max>upper_boundary</max>
        <disallowed>value1</disallowed>
        <disallowed>value2</disallowed>
        <disallowed>value3</disallowed>
        <changeable_in_readonly/>
      </設定名_6>
    </constraints>
  </user_name>
</profiles>

ユーザーが制約に違反しようとすると例外がスローされ、設定は変更されずにそのまま維持されます。

制約の種類​

ClickHouse でサポートされている制約には、いくつかの種類があります。

  • min
  • max
  • disallowed
  • readonly（エイリアス const）
  • changeable_in_readonly

min と max 制約は、数値設定に対する下限および上限を指定し、互いに組み合わせて使用できます。

disallowed 制約は、特定の設定に対して許可してはならない値を指定するために使用できます。

readonly または const 制約は、ユーザーが対応する設定を一切変更できないことを示します。

changeable_in_readonly 制約タイプを使用すると、readonly 設定が 1 に設定されている場合でも、min/max の範囲内であればその設定を変更できます。それ以外の設定は、readonly=1 モードでは変更できません。

注記

changeable_in_readonly は、settings_constraints_replace_previous が有効化されている場合にのみサポートされます。

<access_control_improvements>
  <settings_constraints_replace_previous>true</settings_constraints_replace_previous>
</access_control_improvements>

複数の制約プロファイル​

ユーザーに対して複数のプロファイルがアクティブな場合、それらの制約はマージされます。 マージ方法は settings_constraints_replace_previous によって決まります:

  • true (推奨): 同じ設定に対する制約はマージ時に置き換えられ、最後に適用される制約のみが使用され、それ以前のものはすべて無視されます。 これには、新しい制約で設定されていないフィールドも含まれます。
  • false (デフォルト): 同じ設定に対する制約は、未設定の種類の制約は前のプロファイルから引き継ぎ、設定されている種類の制約は新しいプロファイルの値で置き換える形でマージされます。

読み取り専用モード​

読み取り専用モードは readonly 設定によって有効になります。これは readonly 制約タイプと混同しないでください。

  • readonly=0: 読み取り専用に関する制限はありません。
  • readonly=1: 読み取りクエリのみ許可され、changeable_in_readonly が設定されていない限り、設定を変更できません。
  • readonly=2: 読み取りクエリのみ許可されますが、readonly 設定自体を除き、その他の設定を変更できます。

例​

users.xml に次の行が含まれているとします。

<profiles>
  <default>
    <max_memory_usage>10000000000</max_memory_usage>
    <force_index_by_date>0</force_index_by_date>
    ...
    <constraints>
      <max_memory_usage>
        <min>5000000000</min>
        <max>20000000000</max>
      </max_memory_usage>
      <force_index_by_date>
        <readonly/>
      </force_index_by_date>
    </constraints>
  </default>
</profiles>

以下のクエリはすべて例外をスローします。

SET max_memory_usage=20000000001;
SET max_memory_usage=4999999999;
SET force_index_by_date=1;

Code: 452, e.displayText() = DB::Exception: max_memory_usage は 20000000000 を超える値に設定してはいけません。
Code: 452, e.displayText() = DB::Exception: max_memory_usage は 5000000000 未満の値に設定してはいけません。
Code: 452, e.displayText() = DB::Exception: force_index_by_date は変更してはいけません。
注記

default プロファイルは特別に扱われます。default プロファイルに定義されたすべての制約はデフォルトの制約となり、各ユーザーに対して明示的に上書きされるまで、すべてのユーザーに対して制約として適用されます。

MergeTree 設定に対する制約​

MergeTree 設定 に対して制約を設定できます。 これらの制約は、MergeTree エンジンを使用するテーブルを作成するとき、 またはそのストレージ設定を変更するときに適用されます。

<constraints> セクション内で参照する場合は、 MergeTree 設定名の前に merge_tree_ プレフィックスを付ける必要があります。

例​

明示的に storage_policy を指定して新しいテーブルを作成できないようにすることができます。

<profiles>
  <default>
    <constraints>
      <merge_tree_storage_policy>
        <const/>
      </merge_tree_storage_policy>
    </constraints>
  </default>
</profiles>