Skip to main content

ClickHouseとGoogle Cloud Storageの統合

Note

ClickHouse CloudをGoogle Cloudで使用している場合、このページは適用されません。サービスはすでにGoogle Cloud Storageを使用しています。GCSからデータをSELECTまたはINSERTする方法をお探しの場合は、gcsテーブル関数をご参照ください。

ClickHouseは、ストレージと計算を分離することを求めるユーザーにとって、GCSが魅力的なストレージソリューションであることを認識しています。これを達成するために、MergeTreeエンジンのストレージとしてGCSを使用するサポートが提供されています。これにより、ユーザーはGCSのスケーラビリティとコストメリット、およびMergeTreeエンジンの挿入とクエリのパフォーマンスを活用することができます。

GCSバックのMergeTree

ディスクの作成

GCSバケットをディスクとして利用するためには、まずClickHouseの設定ファイル内でconf.dに宣言する必要があります。以下にGCSディスクの宣言例を示します。この設定には、GCS "ディスク"、キャッシュ、およびDDLクエリでテーブルをGCSディスク上に作成する際に指定されるポリシーを設定するための複数のセクションが含まれています。それぞれの説明を以下に示します。

storage_configuration > disks > gcs

この設定の該当部分は、以下のように示されています。

  • バッチ削除は行われません。GCSは現在バッチ削除をサポートしていないため、エラーメッセージを抑制するために自動検出が無効となっています。
  • ディスクのタイプはtypes3であり、S3 APIが使用されています。
  • GCSによって提供されるエンドポイント
  • サービスアカウントのHMACキーおよびシークレット
  • ローカルディスク上のメタデータパス
<clickhouse>
<storage_configuration>
<disks>
<gcs>
<support_batch_delete>false</support_batch_delete>
<type>s3</type>
<endpoint>https://storage.googleapis.com/BUCKET NAME/FOLDER NAME/</endpoint>
<access_key_id>SERVICE ACCOUNT HMAC KEY</access_key_id>
<secret_access_key>SERVICE ACCOUNT HMAC SECRET</secret_access_key>
<metadata_path>/var/lib/clickhouse/disks/gcs/</metadata_path>
</gcs>
</disks>
<policies>
<gcs_main>
<volumes>
<main>
<disk>gcs</disk>
</main>
</volumes>
</gcs_main>
</policies>
</storage_configuration>
</clickhouse>

storage_configuration > disks > cache

次に示す設定例では、ディスクgcsに対して10Giのメモリキャッシュを有効にしています。

<clickhouse>
<storage_configuration>
<disks>
<gcs>
<support_batch_delete>false</support_batch_delete>
<type>s3</type>
<endpoint>https://storage.googleapis.com/BUCKET NAME/FOLDER NAME/</endpoint>
<access_key_id>SERVICE ACCOUNT HMAC KEY</access_key_id>
<secret_access_key>SERVICE ACCOUNT HMAC SECRET</secret_access_key>
<metadata_path>/var/lib/clickhouse/disks/gcs/</metadata_path>
</gcs>
<gcs_cache>
<type>cache</type>
<disk>gcs</disk>
<path>/var/lib/clickhouse/disks/gcs_cache/</path>
<max_size>10Gi</max_size>
</gcs_cache>
</disks>
<policies>
<gcs_main>
<volumes>
<main>
<disk>gcs_cache</disk>
</main>
</volumes>
</gcs_main>
</policies>
</storage_configuration>
</clickhouse>

storage_configuration > policies > gcs_main

ストレージ構成ポリシーは、データがどこに保存されるかを選択できるようにします。以下に示すポリシーは、gcs_mainというポリシーを指定することで、データをディスクgcsに保存できるようにしています。たとえば、CREATE TABLE ... SETTINGS storage_policy='gcs_main'のように。

<clickhouse>
<storage_configuration>
<disks>
<gcs>
<support_batch_delete>false</support_batch_delete>
<type>s3</type>
<endpoint>https://storage.googleapis.com/BUCKET NAME/FOLDER NAME/</endpoint>
<access_key_id>SERVICE ACCOUNT HMAC KEY</access_key_id>
<secret_access_key>SERVICE ACCOUNT HMAC SECRET</secret_access_key>
<metadata_path>/var/lib/clickhouse/disks/gcs/</metadata_path>
</gcs>
</disks>
<policies>
<gcs_main>
<volumes>
<main>
<disk>gcs</disk>
</main>
</volumes>
</gcs_main>
</policies>
</storage_configuration>
</clickhouse>

このディスク宣言に関連する設定の完全なリストはこちらで確認できます。

テーブルの作成

書き込み権限のあるバケットを使用するようにディスクを設定した場合、下記の例のようにテーブルを作成できるはずです。簡潔にするために、NYCタクシーのカラムの一部を使用し、データをGCSバックのテーブルに直接ストリームします:

CREATE TABLE trips_gcs
(
`trip_id` UInt32,
`pickup_date` Date,
`pickup_datetime` DateTime,
`dropoff_datetime` DateTime,
`pickup_longitude` Float64,
`pickup_latitude` Float64,
`dropoff_longitude` Float64,
`dropoff_latitude` Float64,
`passenger_count` UInt8,
`trip_distance` Float64,
`tip_amount` Float32,
`total_amount` Float32,
`payment_type` Enum8('UNK' = 0, 'CSH' = 1, 'CRE' = 2, 'NOC' = 3, 'DIS' = 4)
)
ENGINE = MergeTree
PARTITION BY toYYYYMM(pickup_date)
ORDER BY pickup_datetime
SETTINGS storage_policy='gcs_main'
INSERT INTO trips_gcs SELECT trip_id, pickup_date, pickup_datetime, dropoff_datetime, pickup_longitude, pickup_latitude, dropoff_longitude, dropoff_latitude, passenger_count, trip_distance, tip_amount, total_amount, payment_type FROM s3('https://ch-nyc-taxi.s3.eu-west-3.amazonaws.com/tsv/trips_{0..9}.tsv.gz', 'TabSeparatedWithNames') LIMIT 1000000;

ハードウェアによっては、この後の1m行の挿入に数分かかる場合があります。進行状況はsystem.processesテーブルで確認できます。行数を1000万の制限まで調整して、いくつかのサンプルクエリを試してみてください。

SELECT passenger_count, avg(tip_amount) as avg_tip, avg(total_amount) as avg_amount FROM trips_gcs GROUP BY passenger_count;

レプリケーションの処理

GCSディスクを使用したレプリケーションは、ReplicatedMergeTreeテーブルエンジンを使用することで実現できます。詳しくは、GCSを使用して2つのGCPリージョンにわたって単一シャードをレプリケートするガイドをご覧ください。

詳しく学ぶ

Cloud Storage XML APIは、Amazon Simple Storage Service(Amazon S3)などのサービスで動作するツールやライブラリと相互運用可能です。

スレッド調整に関する詳細情報は、パフォーマンスの最適化をご覧ください。

Google Cloud Storage (GCS) の使用

Tip

オブジェクトストレージは既にClickHouse Cloudでデフォルトで使用されているため、ClickHouse Cloudで実行している場合はこの手順を実行する必要はありません。

デプロイの計画

このチュートリアルは、Google Cloudで動作し、Google Cloud Storage (GCS) をClickHouseストレージディスクの "タイプ"として使用する、レプリケートされたClickHouseのデプロイメントを説明するために書かれています。

このチュートリアルでは、Google Cloud EngineのVMにClickHouseサーバーノードをデプロイし、それぞれに関連するGCSバケットをストレージとして持ちます。レプリケーションは、VMとしてデプロイされた一連のClickHouse Keeperノードによって調整されます。

高可用性のためのサンプル要件:

  • 2つのGCPリージョンに2つのClickHouseサーバーノード
  • 同じリージョンに配置された2つのGCSバケット
  • ClickHouseサーバーノードと同じリージョンに2つを含む3つのClickHouse Keeperノード。三つ目は最初の2つのKeeperノードのうちの1つと同じリージョンにできますが、異なるアベイラビリティゾーンに配置してください。

ClickHouse Keeperは機能するために2つのノードを必要とするため、高可用性のために3つのノードが必要です。

VMの準備

3つのリージョンに5つのVMをデプロイします:

リージョンClickHouseサーバーバケットClickHouse Keeper
1chnode1bucket_regionnamekeepernode1
2chnode2bucket_regionnamekeepernode2
3 *keepernode3

* これは、上記の1または2のリージョンと同じリージョンの異なるアベイラビリティゾーンにできます。

ClickHouseのデプロイ

2つのホストにClickHouseをデプロイします。このサンプル設定では、これらはchnode1chnode2と名付けられています。

chnode1を1つのGCPリージョンに、chnode2をもう1つのリージョンに置いてください。このガイドでは、us-east1us-east4をコンピュートエンジンVM、GCSバケットのために使用します。

Note

clickhouse serverを設定するまで開始しないでください。インストールするだけにしてください。

ClickHouseサーバーノードのデプロイ手順を実行する際は、インストール手順を参照してください。

ClickHouse Keeperのデプロイ

3つのホストにClickHouse Keeperをデプロイします。このサンプル設定では、これらはkeepernode1keepernode2keepernode3と名付けられています。keepernode1chnode1と同じリージョンに、keepernode2chnode2と同じリージョンに、keepernode3は任意のリージョンに配置できますが、そのリージョンのClickHouseノードとは異なるアベイラビリティゾーンに配置してください。

ClickHouse Keeperノードのデプロイ手順を実行する際は、インストール手順を参照してください。

2つのバケットを作成する

高可用性のために、2つのClickHouseサーバーは異なるリージョンに配置されます。各サーバーは同じリージョンにGCSバケットを持ちます。

Cloud Storage > BucketsCREATE BUCKETを選択します。このチュートリアルでは、us-east1us-east4に1つずつ2つのバケットを作成します。これらのバケットは単一リージョン、スタンダードストレージクラスで、公開されていません。プロンプトが表示されたら、公開アクセスの防止を有効にします。フォルダーは作成しないでください。ClickHouseがストレージに書き込んだときに作成されます。

バケットとHMACキーを作成するためのステップバイステップの手順が必要な場合は、Create GCS buckets and an HMAC keyを展開して、指示に従ってください。

GCS バケットと HMAC キーを作成する

ch_bucket_us_east1

バケットを追加

ch_bucket_us_east4

バケットを追加

アクセスキーを生成する

サービスアカウントの HMAC キーとシークレットを作成する

Cloud Storage > Settings > Interoperability を開き、既存の Access key を選択するか、CREATE A KEY FOR A SERVICE ACCOUNT を選択します。このガイドでは、新しいサービスアカウントの新しいキーを作成する手順を説明します。

バケットを追加

新しいサービスアカウントを追加する

すでにサービスアカウントが存在しないプロジェクトの場合は、CREATE NEW ACCOUNT をクリックします。

バケットを追加

サービスアカウントを作成するには3つのステップがあります。最初のステップでは、アカウントに意味のある名前、ID、説明を付けます。

バケットを追加

Interoperability 設定ダイアログでは、IAM ロールとして Storage Object Admin ロールが推奨されます。ステップ2でそのロールを選択します。

バケットを追加

ステップ3はオプションであり、このガイドでは使用しません。ポリシーに基づいて、ユーザーにこれらの特権を与えることができます。

バケットを追加

サービスアカウントの HMAC キーが表示されます。この情報を保存してください。ClickHouse の設定で使用します。

バケットを追加

ClickHouse Keeperの設定

すべてのClickHouse Keeperノードは、次に示すファイルと同じ設定ファイルを持ちますが、server_id行(最初のハイライト行)だけが異なります。ファイルを開いて、ClickHouse Keeperサーバーのホスト名を編集し、それぞれのサーバーでserver_idを、raft_configurationの適切なserverエントリに合わせて設定します。例ではserver_id3に設定されているため、raft_configurationの一致する行をハイライトしています。

  • ファイルをホスト名で編集し、ClickHouseサーバーノードとKeeperノードから解決できることを確認してください
  • ファイルを所定の場所(各Keeperサーバーの/etc/clickhouse-keeper/keeper_config.xml)にコピー
  • それぞれのマシンで、server_idをエントリ番号に基づいて編集
/etc/clickhouse-keeper/keeper_config.xml
<clickhouse>
<logger>
<level>trace</level>
<log>/var/log/clickhouse-keeper/clickhouse-keeper.log</log>
<errorlog>/var/log/clickhouse-keeper/clickhouse-keeper.err.log</errorlog>
<size>1000M</size>
<count>3</count>
</logger>
<listen_host>0.0.0.0</listen_host>
<keeper_server>
<tcp_port>9181</tcp_port>
<server_id>3</server_id>
<log_storage_path>/var/lib/clickhouse/coordination/log</log_storage_path>
<snapshot_storage_path>/var/lib/clickhouse/coordination/snapshots</snapshot_storage_path>

<coordination_settings>
<operation_timeout_ms>10000</operation_timeout_ms>
<session_timeout_ms>30000</session_timeout_ms>
<raft_logs_level>warning</raft_logs_level>
</coordination_settings>

<raft_configuration>
<server>
<id>1</id>
<hostname>keepernode1.us-east1-b.c.clickhousegcs-374921.internal</hostname>
<port>9234</port>
</server>
<server>
<id>2</id>
<hostname>keepernode2.us-east4-c.c.clickhousegcs-374921.internal</hostname>
<port>9234</port>
</server>
<server>
<id>3</id>
<hostname>keepernode3.us-east5-a.c.clickhousegcs-374921.internal</hostname>
<port>9234</port>
</server>
</raft_configuration>
</keeper_server>
</clickhouse>

ClickHouseサーバーの設定

ベストプラクティス

このガイドのいくつかのステップでは、構成ファイルを/etc/clickhouse-server/config.d/に配置するように求めます。これはLinuxシステムのデフォルトの場所で、構成上書きファイルのためのものです。このディレクトリにファイルを置くと、デフォルトの構成とコンテンツがマージされます。これらのファイルをconfig.dディレクトリに配置すると、アップグレード中に構成を失うことを避けることができます。

ネットワーク

デフォルトでは、ClickHouseはループバックインターフェースをリッスンしますが、複製されたセットアップではマシン間のネットワークが必要です。すべてのインターフェースでリッスンします:

/etc/clickhouse-server/config.d/network.xml
<clickhouse>
<listen_host>0.0.0.0</listen_host>
</clickhouse>

リモートClickHouse Keeperサーバー

レプリケーションはClickHouse Keeperによって調整されます。この構成ファイルはClickHouse Keeperノードのホスト名とポート番号を識別します。

  • ホスト名を編集してKeeperホストと一致させます
/etc/clickhouse-server/config.d/use-keeper.xml
<clickhouse>
<zookeeper>
<node index="1">
<host>keepernode1.us-east1-b.c.clickhousegcs-374921.internal</host>
<port>9181</port>
</node>
<node index="2">
<host>keepernode2.us-east4-c.c.clickhousegcs-374921.internal</host>
<port>9181</port>
</node>
<node index="3">
<host>keepernode3.us-east5-a.c.clickhousegcs-374921.internal</host>
<port>9181</port>
</node>
</zookeeper>
</clickhouse>

リモートClickHouseサーバー

このファイルは、クラスター内の各ClickHouseサーバーのホスト名とポートを設定します。 デフォルトの構成ファイルにはサンプルのクラスター定義が含まれているため、完全に設定されたクラスターのみを示すために、タグreplace="true"remote_serversエントリに追加して、クリックしてコンフィグレーションをデフォルトとマージするときにremote_serversセクションを置き換えるようにします。

  • ファイルを編集してホスト名を追加し、ClickHouseサーバーノードから解決できることを確認してください
/etc/clickhouse-server/config.d/remote-servers.xml
<clickhouse>
<remote_servers replace="true">
<cluster_1S_2R>
<shard>
<replica>
<host>chnode1.us-east1-b.c.clickhousegcs-374921.internal</host>
<port>9000</port>
</replica>
<replica>
<host>chnode2.us-east4-c.c.clickhousegcs-374921.internal</host>
<port>9000</port>
</replica>
</shard>
</cluster_1S_2R>
</remote_servers>
</clickhouse>

レプリカの識別

このファイルは、ClickHouse Keeperパスに関連する設定を行います。 特に、データがどのレプリカに属しているかを特定するために使用されるマクロです。 1つのサーバーにはレプリカreplica_1として指定し、もう1つのサーバーにはreplica_2と指定します。 名称は変更できますが、例では、1つのレプリカがサウスカロライナに保存され、もう1つが北バージニアに保存され、carolinavirginiaのように異なる値にしてください。

/etc/clickhouse-server/config.d/macros.xml
<clickhouse>
<distributed_ddl>
<path>/clickhouse/task_queue/ddl</path>
</distributed_ddl>
<macros>
<cluster>cluster_1S_2R</cluster>
<shard>1</shard>
<replica>replica_1</replica>
</macros>
</clickhouse>

GCSでのストレージ

ClickHouseのストレージ構成には、diskspoliciesが含まれます。 下記の設定では、ディスクgcstypes3に指定されています。 タイプがs3というのは、ClickHouseがGCSバケットへAWS S3バケットとしてアクセスしているためです。 この構成の2つのコピーが必要で、それぞれのClickHouseサーバーノード用です。

以下の構成でこれらの置換を行う必要があります。

これらの置換は、2つのClickHouseサーバーノード間で異なります:

  • REPLICA 1 BUCKETは、サーバーと同じリージョンにあるバケットの名前に設定
  • REPLICA 1 FOLDERは、1つのサーバーにreplica_1、もう1つにreplica_2に変更

これらの置換は、2つのノード間で同一:

  • access_key_idは、前に生成されたHMACキーに設定
  • secret_access_keyは、前に生成されたHMAC秘密情報に設定
/etc/clickhouse-server/config.d/storage.xml
<clickhouse>
<storage_configuration>
<disks>
<gcs>
<support_batch_delete>false</support_batch_delete>
<type>s3</type>
<endpoint>https://storage.googleapis.com/REPLICA 1 BUCKET/REPLICA 1 FOLDER/</endpoint>
<access_key_id>SERVICE ACCOUNT HMAC KEY</access_key_id>
<secret_access_key>SERVICE ACCOUNT HMAC SECRET</secret_access_key>
<metadata_path>/var/lib/clickhouse/disks/gcs/</metadata_path>
</gcs>
<cache>
<type>cache</type>
<disk>gcs</disk>
<path>/var/lib/clickhouse/disks/gcs_cache/</path>
<max_size>10Gi</max_size>
</cache>
</disks>
<policies>
<gcs_main>
<volumes>
<main>
<disk>gcs</disk>
</main>
</volumes>
</gcs_main>
</policies>
</storage_configuration>
</clickhouse>

ClickHouse Keeperの開始

お使いのオペレーティングシステムのコマンドを使用します。たとえば:

sudo systemctl enable clickhouse-keeper
sudo systemctl start clickhouse-keeper
sudo systemctl status clickhouse-keeper

ClickHouse Keeperのステータスを確認

netcatを使用してClickHouse Keeperにコマンドを送信します。たとえば、mntrはClickHouse Keeperクラスターの状態を返します。 コマンドを各Keeperノードで実行すると、1つはリーダーで、他の2つはフォロワーであることがわかります。

echo mntr | nc localhost 9181
zk_version  v22.7.2.15-stable-f843089624e8dd3ff7927b8a125cf3a7a769c069
zk_avg_latency 0
zk_max_latency 11
zk_min_latency 0
zk_packets_received 1783
zk_packets_sent 1783
zk_num_alive_connections 2
zk_outstanding_requests 0
zk_server_state leader
zk_znode_count 135
zk_watch_count 8
zk_ephemerals_count 3
zk_approximate_data_size 42533
zk_key_arena_size 28672
zk_latest_snapshot_size 0
zk_open_file_descriptor_count 182
zk_max_file_descriptor_count 18446744073709551615
zk_followers 2
zk_synced_followers 2

ClickHouseサーバーの開始

chnode1chnode2で次のコマンドを実行します:

sudo service clickhouse-server start
sudo service clickhouse-server status

検証

ディスクの構成を確認

system.disksには、それぞれのディスクに対するレコードが含まれている必要があります:

  • デフォルト
  • gcs
  • キャッシュ
SELECT *
FROM system.disks
FORMAT Vertical
Row 1:
──────
name: cache
path: /var/lib/clickhouse/disks/gcs/
free_space: 18446744073709551615
total_space: 18446744073709551615
unreserved_space: 18446744073709551615
keep_free_space: 0
type: s3
is_encrypted: 0
is_read_only: 0
is_write_once: 0
is_remote: 1
is_broken: 0
cache_path: /var/lib/clickhouse/disks/gcs_cache/

Row 2:
──────
name: default
path: /var/lib/clickhouse/
free_space: 6555529216
total_space: 10331889664
unreserved_space: 6555529216
keep_free_space: 0
type: local
is_encrypted: 0
is_read_only: 0
is_write_once: 0
is_remote: 0
is_broken: 0
cache_path:

Row 3:
──────
name: gcs
path: /var/lib/clickhouse/disks/gcs/
free_space: 18446744073709551615
total_space: 18446744073709551615
unreserved_space: 18446744073709551615
keep_free_space: 0
type: s3
is_encrypted: 0
is_read_only: 0
is_write_once: 0
is_remote: 1
is_broken: 0
cache_path:

3 rows in set. Elapsed: 0.002 sec.

クラスタに作成されたテーブルが両方のノードに作成されたことを確認

create table trips on cluster 'cluster_1S_2R' (
`trip_id` UInt32,
`pickup_date` Date,
`pickup_datetime` DateTime,
`dropoff_datetime` DateTime,
`pickup_longitude` Float64,
`pickup_latitude` Float64,
`dropoff_longitude` Float64,
`dropoff_latitude` Float64,
`passenger_count` UInt8,
`trip_distance` Float64,
`tip_amount` Float32,
`total_amount` Float32,
`payment_type` Enum8('UNK' = 0, 'CSH' = 1, 'CRE' = 2, 'NOC' = 3, 'DIS' = 4))
ENGINE = ReplicatedMergeTree
PARTITION BY toYYYYMM(pickup_date)
ORDER BY pickup_datetime
SETTINGS storage_policy='gcs_main'
┌─host───────────────────────────────────────┬─port─┬─status─┬─error─┬─num_hosts_remaining─┬─num_hosts_active─┐
│ chnode2.us-east4-c.c.gcsqa-375100.internal │ 9000 │ 0 │ │ 1 │ 1 │
└────────────────────────────────────────────┴──────┴────────┴───────┴─────────────────────┴──────────────────┘
┌─host───────────────────────────────────────┬─port─┬─status─┬─error─┬─num_hosts_remaining─┬─num_hosts_active─┐
│ chnode1.us-east1-b.c.gcsqa-375100.internal │ 9000 │ 0 │ │ 0 │ 0 │
└────────────────────────────────────────────┴──────┴────────┴───────┴─────────────────────┴──────────────────┘

2 rows in set. Elapsed: 0.641 sec.

データが挿入できることを確認

INSERT INTO trips SELECT
trip_id,
pickup_date,
pickup_datetime,
dropoff_datetime,
pickup_longitude,
pickup_latitude,
dropoff_longitude,
dropoff_latitude,
passenger_count,
trip_distance,
tip_amount,
total_amount,
payment_type
FROM s3('https://ch-nyc-taxi.s3.eu-west-3.amazonaws.com/tsv/trips_{0..9}.tsv.gz', 'TabSeparatedWithNames')
LIMIT 1000000

テーブル用にストレージポリシーgcs_mainが使用されていることを確認

SELECT
engine,
data_paths,
metadata_path,
storage_policy,
formatReadableSize(total_bytes)
FROM system.tables
WHERE name = 'trips'
FORMAT Vertical
Row 1:
──────
engine: ReplicatedMergeTree
data_paths: ['/var/lib/clickhouse/disks/gcs/store/631/6315b109-d639-4214-a1e7-afbd98f39727/']
metadata_path: /var/lib/clickhouse/store/e0f/e0f3e248-7996-44d4-853e-0384e153b740/trips.sql
storage_policy: gcs_main
formatReadableSize(total_bytes): 36.42 MiB

1 row in set. Elapsed: 0.002 sec.

Google Cloud Consoleで確認

バケットに移動すると、設定ファイルのstorage.xmlで使用された名前を持つフォルダーがそれぞれのバケットに作成されていることがわかります。フォルダーを展開すると、多くのファイルが表示され、データのパーティションを表しています。

レプリカ1のバケット

replica one bucket

レプリカ2のバケット

replica two bucket