HDFS テーブルエンジン

このエンジンは、ClickHouse 経由で HDFS 上のデータを管理できるようにすることで、Apache Hadoop エコシステムとの連携を提供します。このエンジンは File および URL エンジンに似ていますが、Hadoop 固有の機能を備えています。

この機能は ClickHouse のエンジニアによるサポート対象ではなく、品質にも難があることが知られています。問題が発生した場合は、自分で修正してプルリクエストを送ってください。

ENGINE = HDFS(URI, format)

エンジンパラメータ

• URI - HDFS 内のファイルの完全な URI。URI のパス部分にはグロブを含めることができます。この場合、テーブルは読み取り専用になります。
• format - 使用可能なファイルフォーマットのいずれか 1 つを指定します。 SELECT クエリを実行するには、そのフォーマットが入力に対応している必要があり、INSERT クエリを実行するには 出力に対応している必要があります。使用可能なフォーマットは フォーマット セクションに一覧があります。
• [PARTITION BY expr]

PARTITION BY — 任意です。ほとんどの場合、パーティションキーは不要です。必要な場合でも、通常は月単位より細かいパーティションキーは必要ありません。パーティション化してもクエリは高速化されません (ORDER BY 式とは異なります) 。細かすぎるパーティション化は絶対に避けてください。クライアント識別子や名前でデータをパーティション化しないでください (代わりに、クライアント識別子または名前を ORDER BY 式の最初のカラムにしてください) 。

月単位でパーティション化するには、toYYYYMM(date_column) 式を使用します。ここで、date_column は Date 型の日付カラムです。この場合のパーティション名は "YYYYMM" フォーマットになります。

例:

1. hdfs_engine_table テーブルを設定します。

CREATE TABLE hdfs_engine_table (name String, value UInt32) ENGINE=HDFS('hdfs://hdfs1:9000/other_storage', 'TSV')

2. ファイルに内容を記述します:

INSERT INTO hdfs_engine_table VALUES ('one', 1), ('two', 2), ('three', 3)

3. データにクエリを実行します:

SELECT * FROM hdfs_engine_table LIMIT 2

┌─name─┬─value─┐
│ one  │     1 │
│ two  │     2 │
└──────┴───────┘

• 読み取りと書き込みは並列で実行できます。
• 次はサポートされていません。
  • ALTER および SELECT...SAMPLE 操作。
  • 索引。
  • ゼロコピー レプリケーションは利用できますが、推奨されません。

パス内の グロブ

複数のパス部分に グロブ を含めることができます。処理対象のファイルは存在しており、かつパスパターン全体に一致している必要があります。ファイル一覧は SELECT 実行時に決定されます (CREATE 時ではありません) 。

• * — 空文字列を含む、/ を除く任意の文字列に置き換えます。
• ? — 任意の 1 文字に置き換えます。
• {some_string,another_string,yet_another_one} — 文字列 'some_string'、'another_string'、'yet_another_one' のいずれかに置き換えます。
• {N..M} — N から M までの範囲内の任意の数値 (両端を含む) に置き換えます。

{} を使った構文は、remote table function に似ています。

例

1. HDFS 上に、次の URI を持つ TSV フォーマットのファイルがいくつかあるとします。

   • 'hdfs://hdfs1:9000/some_dir/some_file_1'
   • 'hdfs://hdfs1:9000/some_dir/some_file_2'
   • 'hdfs://hdfs1:9000/some_dir/some_file_3'
   • 'hdfs://hdfs1:9000/another_dir/some_file_1'
   • 'hdfs://hdfs1:9000/another_dir/some_file_2'
   • 'hdfs://hdfs1:9000/another_dir/some_file_3'

2. これら 6 つのファイルすべてからなるテーブルを作成する方法はいくつかあります。

CREATE TABLE table_with_range (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/some_file_{1..3}', 'TSV')

別の方法：

CREATE TABLE table_with_question_mark (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/some_file_?', 'TSV')

テーブルは、両方のディレクトリ内にあるすべてのファイルで構成されます (すべてのファイルは、クエリで指定されたフォーマットとスキーマに適合している必要があります) :

CREATE TABLE table_with_asterisk (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/{some,another}_dir/*', 'TSV')

例

file000、file001、…、file999 という名前のファイルを持つテーブルを作成します。

CREATE TABLE big_table (name String, value UInt32) ENGINE = HDFS('hdfs://hdfs1:9000/big_dir/file{0..9}{0..9}{0..9}', 'CSV')

GraphiteMergeTree と同様に、HDFS engine は ClickHouse の設定ファイルを使った拡張設定に対応しています。使用できる設定キーは 2 種類あり、グローバル (hdfs) とユーザーレベル (hdfs_*) です。まずグローバル設定が適用され、次にユーザーレベル設定が適用されます (存在する場合) 。

<!-- Global configuration options for HDFS engine type -->
<hdfs>
<hadoop_kerberos_keytab>/tmp/keytab/clickhouse.keytab</hadoop_kerberos_keytab>
<hadoop_kerberos_principal>clickuser@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
<hadoop_security_authentication>kerberos</hadoop_security_authentication>
</hdfs>

<!-- Configuration specific for user "root" -->
<hdfs_root>
<hadoop_kerberos_principal>root@TEST.CLICKHOUSE.TECH</hadoop_kerberos_principal>
</hdfs_root>

HDFS Configuration Reference を参照すると、一部のパラメーターについて理解しやすくなる場合があります。

• hadoop_security_kerberos_ticket_cache_path と libhdfs3_conf はグローバル設定のみ可能で、ユーザーごとの設定には対応していません

hadoop_security_authentication パラメータの値が kerberos の場合、ClickHouse は Kerberos による認証を使用します。 パラメータは こちら にあり、hadoop_security_kerberos_ticket_cache_path が役立つ場合があります。 libhdfs3 の制限により、サポートされるのは従来方式のみであることに注意してください。 datanode との通信は SASL では保護されません (HADOOP_SECURE_DN_USER は、このような セキュリティ方式であることを示す信頼できる指標です) 。参考として tests/integration/test_storage_kerberized_hdfs/hdfs_configs/bootstrap.sh を使用してください。

hadoop_kerberos_keytab、hadoop_kerberos_principal、または hadoop_security_kerberos_ticket_cache_path のいずれかを指定すると、Kerberos 認証が使用されます。この場合、hadoop_kerberos_keytab と hadoop_kerberos_principal は必須です。

libhdfs3 は HDFS NameNode HA をサポートしています。

• HDFS ノードから hdfs-site.xml を /etc/clickhouse-server/ にコピーします。
• ClickHouse の設定ファイルに次の設定を追加します。

<hdfs>
    <libhdfs3_conf>/etc/clickhouse-server/hdfs-site.xml</libhdfs3_conf>
</hdfs>

• 次に、HDFS URI の NameNode アドレスには、hdfs-site.xml の dfs.nameservices のタグ値を使用します。たとえば、hdfs://appadmin@192.168.101.11:8020/abc/ を hdfs://appadmin@my_nameservice/abc/ に置き換えます。

• _path — ファイルのパス。型: LowCardinality(String).
• _file — ファイル名。型: LowCardinality(String).
• _size — ファイルサイズ (バイト単位) 。型: Nullable(UInt64)。サイズが不明な場合、値は NULL です。
• _time — ファイルの最終更新時刻。型: Nullable(DateTime)。時刻が不明な場合、値は NULL です。
• _etag — ファイルの ETag。型: LowCardinality(String)。HDFS にはネイティブの ETag がないため、値はファイルの最終更新時刻とサイズから <mtime_seconds>_<size> の形式で生成されます。libhdfs3 は最終更新時刻を秒単位の精度でしか公開しないため、同じ秒内に同じサイズのまま書き換えると同じ値になります。そのため、この生成された ETag はコンテンツキャッシュのキーとして使用されません。

• hdfs_truncate_on_insert - insert 前にファイルを切り詰められるようにします。デフォルトでは無効です。
• hdfs_create_new_file_on_insert - フォーマットに接尾辞がある場合、insert のたびに新しいファイルを作成できるようにします。デフォルトでは無効です。
• hdfs_skip_empty_files - 読み取り時に空のファイルをスキップできるようにします。デフォルトでは無効です。

関連項目

• 仮想カラム