構成ファイル

注記

XMLベースの設定プロファイルと構成ファイルは、現在ClickHouse Cloudではサポートされていません。そのため、ClickHouse Cloudではconfig.xmlファイルは見つかりません。代わりに、SQLコマンドを使用して設定をSettings Profilesを通じて管理する必要があります。

詳細については、"設定の構成"を参照してください。

ClickHouseサーバーは、XMLまたはYAML構文の構成ファイルで設定できます。ほとんどのインストールタイプでは、ClickHouseサーバーはデフォルトの構成ファイルとして/etc/clickhouse-server/config.xmlで実行されますが、コマンドラインオプション--config-fileまたは-Cを使用して、サーバーの起動時に手動で構成ファイルの場所を指定することも可能です。追加の構成ファイルは、メイン構成ファイルに対して相対的なディレクトリconfig.d/に配置できます。たとえば、/etc/clickhouse-server/config.d/ディレクトリに配置します。このディレクトリのファイルとメイン構成は、ClickHouseサーバーで構成が適用される前の前処理ステップでマージされます。構成ファイルはアルファベット順にマージされます。更新を簡素化し、モジュール化を改善するために、デフォルトのconfig.xmlファイルを変更せずに保ち、追加のカスタマイズをconfig.d/に配置することが最良の方法です。ClickHouse keeperの構成は、/etc/clickhouse-keeper/keeper_config.xmlにあります。したがって、追加のファイルは/etc/clickhouse-keeper/keeper_config.d/に配置する必要があります。

XMLとYAMLの構成ファイルを混在させることが可能で、たとえばメイン構成ファイルconfig.xmlと、追加の構成ファイルconfig.d/network.xml、config.d/timezone.yaml、およびconfig.d/keeper.yamlを持つことができます。ただし、1つの構成ファイル内でXMLとYAMLを混在させることはサポートされていません。XML構成ファイルは<clickhouse>...</clickhouse>を最上位タグとして使用する必要があります。YAML構成ファイルでは、clickhouse:はオプションであり、欠落している場合はパーサーが自動的に挿入します。

構成のマージ

2つの構成ファイル（通常はメイン構成ファイルとconfig.d/からの別の構成ファイル）は、次のようにマージされます。

• ノード（つまり、要素へのパス）が両方のファイルに現れ、属性replaceまたはremoveを持たない場合、それはマージされた構成ファイルに含まれ、両方のノードからの子が再帰的に含まれ、マージされます。
• 両方のノードの1つが属性replaceを含む場合、マージされた構成ファイルに含まれますが、属性replaceを持つノードからの子のみが含まれます。
• 両方のノードの1つが属性removeを含む場合、そのノードはマージされた構成ファイルに含まれません（既に存在する場合は削除されます）。

例:

と

が生成するマージされた構成ファイル:

環境変数とZooKeeperノードによる置換

要素の値を環境変数の値で置き換える必要がある場合は、属性from_envを使用できます。

例: $MAX_QUERY_SIZE = 150000 の場合:

これは次と等しいです:

ZooKeeperノードを使用しても同様です:

これは次と等しいです:

デフォルト値

from_envまたはfrom_zk属性を持つ要素は、追加で属性replace="1"を持つ場合があります（後者はfrom_env/from_zkの前に現れる必要があります）。この場合、要素はデフォルト値を定義できます。要素は、設定されている場合は環境変数またはZooKeeperノードの値を取り、そうでない場合はデフォルト値を使用します。

前述の例ですが、MAX_QUERY_SIZEが設定されていない場合:

結果:

ファイル内容による置換

構成の一部をファイルの内容で置き換えることも可能です。これには2つの方法があります。

• 値の置換: 要素が属性inclを持つ場合、その値は参照されたファイルの内容に置き換えられます。置換用のファイルへのパスはデフォルトで/etc/metrika.xmlです。これは、サーバー構成のinclude_from要素で変更できます。置換値は、このファイルの/clickhouse/substitution_name要素で指定されています。inclで指定された置換が存在しない場合、それはログに記録されます。ClickHouseが欠落した置換をログに記録しないようにするには、属性optional="true"を指定します（たとえば、マクロ用設定など）。

• 要素の置換: 要素全体を置換で置き換えたい場合は、要素名としてincludeを使用します。要素名includeは、属性from_zk = "/path/to/node"と組み合わせて使用することができます。この場合、要素値は/path/to/nodeのZooKeeperノードの内容に置き換えられます。ZooKeeperノードとしてXMLサブツリー全体を格納することも可能で、その場合はソース要素に完全に挿入されます。

例:

置換コンテンツを既存の構成とマージするのではなく追加するなら、属性merge="true"を使用できます。たとえば: <include from_zk="/some_path" merge="true">。この場合、既存の構成が置換からの内容とマージされ、既存の構成設定は置換からの値で置き換えられます。

構成の暗号化および隠蔽

対称暗号を使用して構成要素を暗号化できます。たとえば、平文のパスワードや秘密鍵です。そのためには、最初に暗号化コーデックを構成し、次に暗号化する要素に暗号化コーデックの名前を値としてencrypted_by属性を追加します。

属性from_zk、from_env、incl、または要素includeとは異なり、事前処理ファイル内で置換（暗号化された値の復号）は実行されません。復号はサーバープロセスで実行時にのみ行われます。

例:

属性from_envおよびfrom_zkは、encryption_codecsでも適用できます:

暗号化キーと暗号化された値は、どちらの構成ファイルにも定義できます。

例 config.xml:

例 users.xml:

値を暗号化するには、（例）プログラムencrypt_decryptを使用できます:

例:

暗号化された構成要素があっても、暗号化された要素は事前処理された構成ファイルに依然として表示されます。これがClickHouseのデプロイに問題がある場合は、2つの代替案を提案します。事前処理されたファイルのファイル権限を600に設定するか、属性hide_in_preprocessedを使用してください。

例:

ユーザー設定

config.xmlファイルは、ユーザー設定、プロファイル、およびクオータのための別の構成を指定できます。この構成への相対パスはusers_config要素で設定されます。デフォルトではusers.xmlです。users_configが省略されると、ユーザー設定、プロファイル、およびクオータはconfig.xmlに直接指定されます。

ユーザー構成は、config.xmlおよびconfig.d/と同様に別のファイルに分割できます。ディレクトリ名は、.xmlの接尾辞なしでusers_config設定として定義され、.dと連結されます。デフォルトではディレクトリusers.dが使用され、users_configはusers.xmlにデフォルトします。

設定ファイルはまずマージされて設定を考慮した後、インクルードが処理されることに注意してください。

XMLの例

たとえば、各ユーザーのために別々の構成ファイルを次のように持つことができます:

YAMLの例

ここでは、YAMLで書かれたデフォルトの構成を示します: config.yaml.example。

ClickHouseの構成に関するYAMLとXMLフォーマットの違いがいくつかあります。ここでは、YAML形式で構成を書くためのいくつかのヒントを示します。

テキスト値を持つXMLタグは、YAMLのキー・バリューペアで表されます。

対応するXML:

ネストされたXMLノードは、YAMLマップで表されます。

対応するXML:

同じXMLタグを複数回作成するには、YAMLシーケンスを使用します。

対応するXML:

XML属性を提供するには、@プレフィックスを持つ属性キーを使用できます。なお、@はYAML標準によって予約されているため、ダブルクォートで囲む必要があります。

対応するXML:

YAMLシーケンスでも属性を使用することができます。

対応するXML:

前述の構文では、XML属性を持つXMLテキストノードをYAMLとして表現することはできません。この特別なケースは、#text属性キーを使用することで実現できます。

対応するXML:

実装の詳細

各構成ファイルについて、サーバーは起動時にfile-preprocessed.xmlファイルも生成します。これらのファイルには、すべての完了した置換とオーバーライドが含まれており、情報用に使用されます。構成ファイルでZooKeeperの置換が使用されているが、サーバーが起動時にZooKeeperが使用できない場合、サーバーは事前処理されたファイルから構成をロードします。

サーバーは、置換やオーバーライドの実行時に使用された構成ファイル、ファイル、ZooKeeperノードに対する変更を追跡し、ユーザーやクラスターの設定を動的に再読み込みします。つまり、サーバーを再起動することなく、クラスター、ユーザー、およびその設定を変更することができます。