HDFS テーブルエンジン

このエンジンでは、ClickHouse 経由で HDFS 上のデータを管理でき、Apache Hadoop エコシステムとのインテグレーションを実現します。File エンジンや URL エンジンと似ていますが、Hadoop 固有の機能を備えています。

このエンジンは、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

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 操作。
  • 索引。
  • ゼロコピー レプリケーションは利用できますが、推奨されません。

ゼロコピー レプリケーションは本番環境向けではありません

ClickHouse バージョン 22.8 以降では、ゼロコピー レプリケーションはデフォルトで無効になっています。この機能を本番環境で使用することは推奨されません。

パス内の グロブ

複数のパス部分に グロブ を含めることができます。処理対象のファイルは存在しており、かつパスパターン全体に一致している必要があります。ファイル一覧は 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_*) です。まずグローバル設定が適用され、次にユーザーレベル設定が適用されます (存在する場合) 。

<!-- HDFSエンジンタイプのグローバル設定オプション -->
<hdfs>
  <hadoop_kerberos_keytab>/tmp/keytab/clickhouse.keytab</hadoop_kerberos_keytab>
  <hadoop_kerberos_principal>[e-mail]</hadoop_kerberos_principal>
  <hadoop_security_authentication>kerberos</hadoop_security_authentication>
</hdfs>

<!-- ユーザー "root" 固有の設定 -->
<hdfs_root>
  <hadoop_kerberos_principal>[e-mail]</hadoop_kerberos_principal>
</hdfs_root>

​

設定オプション

​

libhdfs3 でサポートされる設定

パラメーター	デフォルト値
rpc_client_connect_tcpnodelay	true
dfs_client_read_shortcircuit	true
output_replace-datanode-on-failure	true
input_notretry-another-node	false
input_localread_mappedfile	true
dfs_client_use_legacy_blockreader_local	false
rpc_client_ping_interval	10 * 1000
rpc_client_connect_timeout	600 * 1000
rpc_client_read_timeout	3600 * 1000
rpc_client_write_timeout	3600 * 1000
rpc_client_socket_linger_timeout	-1
rpc_client_connect_retry	10
rpc_client_timeout	3600 * 1000
dfs_default_replica	3
input_connect_timeout	600 * 1000
input_read_timeout	3600 * 1000
input_write_timeout	3600 * 1000
input_localread_default_buffersize	1 * 1024 * 1024
dfs_prefetchsize	10
input_read_getblockinfo_retry	3
input_localread_blockinfo_cachesize	1000
input_read_max_retry	60
output_default_chunksize	512
output_default_packetsize	64 * 1024
output_default_write_retry	10
output_connect_timeout	600 * 1000
output_read_timeout	3600 * 1000
output_write_timeout	3600 * 1000
output_close_timeout	3600 * 1000
output_packetpool_size	1024
output_heartbeat_interval	10 * 1000
dfs_client_failover_max_attempts	15
dfs_client_read_shortcircuit_streams_cache_size	256
dfs_client_socketcache_expiryMsec	3000
dfs_client_socketcache_capacity	16
dfs_default_blocksize	64 * 1024 * 1024
dfs_default_uri	”hdfs://localhost:9000”
hadoop_security_authentication	”simple”
hadoop_security_kerberos_ticket_cache_path	""
dfs_client_log_severity	”INFO”
dfs_domain_socket_path	""

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

​

ClickHouse の追加設定

パラメータ	デフォルト値
hadoop_kerberos_keytab	""
hadoop_kerberos_principal	""
libhdfs3_conf	""

​

制限事項

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

​

Kerberos サポート

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 は必須です。

​

HDFS NameNode HA のサポート

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 です。

​

ストレージ設定

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

関連項目

• 仮想カラム