メインコンテンツまでスキップ
メインコンテンツまでスキップ

Connect dlt to ClickHouse

Community Maintained

dlt はオープンソースのライブラリで、Python スクリプトに追加して、さまざまな場合に乱雑なデータソースからデータを、構造化されたライブデータセットにロードすることができます。

Install dlt with ClickHouse​

To Install the dlt library with ClickHouse dependencies:​

Setup Guide​

1. Initialize the dlt Project​

新しい dlt プロジェクトを初期化するには、以下のようにします：

注記

このコマンドは、チェスをソースとして、ClickHouseを宛先としてパイプラインを初期化します。

上記のコマンドは、.dlt/secrets.toml や ClickHouse のための要件ファイルを含むいくつかのファイルとディレクトリを生成します。以下のように要件ファイルで指定されている必要な依存関係をインストールできます：

または pip install dlt[clickhouse] を使うことで、dlt ライブラリと ClickHouse を宛先として使用するために必要な依存関係をインストールできます。

2. Setup ClickHouse Database​

ClickHouse にデータをロードするには、ClickHouse データベースを作成する必要があります。以下に、実施すべき大まかな手順を示します：

  1. 既存の ClickHouse データベースを使用するか、新しいものを作成します。

  2. 新しいデータベースを作成するには、clickhouse-client コマンドラインツールまたはお好みの SQL クライアントを使用して ClickHouse サーバーに接続します。

  3. 新しいデータベース、ユーザーを作成し、必要な権限を付与するために、以下の SQL コマンドを実行します：

3. Add Credentials​

次に、.dlt/secrets.toml ファイルに ClickHouse の資格情報を設定します：

注記

HTTP_PORT http_port パラメータは、ClickHouse サーバーの HTTP インターフェースに接続する際に使用するポート番号を指定します。これは、ネイティブ TCP プロトコルに使用されるデフォルトポート 9000 とは異なります。

外部ステージングを使用しない場合（つまり、パイプラインでステージングパラメータを設定しない場合）、http_port を設定する必要があります。これは、組み込みの ClickHouse ローカルストレージステージングが clickhouse content ライブラリを使用し、ClickHouse と HTTP 経由で通信するためです。

ClickHouse サーバーが、http_port で指定したポートで HTTP 接続を受け入れるように構成されていることを確認してください。たとえば、http_port = 8443 を設定した場合、ClickHouse はポート 8443 で HTTP リクエストを待機している必要があります。外部ステージングを使用している場合は、clickhouse-connect が使用されないため、http_port パラメータを省略できます。

clickhouse-driver ライブラリで使用するのと同様のデータベース接続文字列を渡すことができます。上記の資格情報は次のように見えます：

Write Disposition​

すべての write dispositions がサポートされています。

dlt ライブラリの書き込みディスポジションは、データを宛先にどのように書き込むかを定義します。書き込みディスポジションには、3 つのタイプがあります：

Replace: このディスポジションは、リソースのデータで宛先のデータを置き換えます。すべてのクラスとオブジェクトを削除し、データをロードする前にスキーマを再作成します。詳細については こちらで学ぶことができます。

Merge: この書き込みディスポジションは、リソースのデータと宛先のデータをマージします。merge ディスポジションでは、リソースに対して primary_key を指定する必要があります。詳細については こちらをご覧ください。

Append: これはデフォルトのディスポジションです。既存のデータにデータを追加し、primary_key フィールドを無視します。

Data Loading​

データは、データソースに応じて最も効率的な方法で ClickHouse にロードされます：

  • ローカルファイルの場合、clickhouse-connect ライブラリを使用して、INSERT コマンドを使用してファイルを ClickHouse テーブルに直接ロードします。
  • S3、Google Cloud Storage、または Azure Blob Storage のようなリモートストレージのファイルに対しては、ClickHouse テーブル関数（s3、gcs、azureBlobStorage）を使用してファイルを読み取り、データをテーブルに挿入します。

Datasets​

Clickhouse は 1 つのデータベース内に複数のデータセットをサポートしていませんが、dlt はさまざまな理由からデータセットに依存しています。Clickhouse と dlt を連携させるために、dlt が Clickhouse データベースに生成するテーブルの名前にはデータセット名がプレフィックスとして付加され、設定可能な dataset_table_separator で区切られます。さらに、データを含まない特別なセンチネルテーブルが作成され、dlt が Clickhouse 宛先に既に存在する仮想データセットを認識できるようになります。

Supported File Formats​

  • jsonl は、直接ロードおよびステージングの両方で推奨されるフォーマットです。
  • parquet も、直接ロードおよびステージングの両方でサポートされています。

clickhouse 宛先には、デフォルトの SQL 宛先からいくつか特有の逸脱があります：

  1. Clickhouse には実験的な object データ型がありますが、少し予測不可能であることがわかったため、dlt Clickhouse 宛先は複雑なデータ型をテキストカラムにロードします。この機能が必要な場合は、Slack コミュニティに連絡ください。追加を検討します。
  2. Clickhouse は time データ型をサポートしていません。時間は text カラムにロードされます。
  3. Clickhouse は binary データ型をサポートしていません。その代わり、バイナリデータは text カラムにロードされます。jsonl からロードする場合、バイナリデータは base64 文字列になり、parquet からロードする場合、binary オブジェクトは text に変換されます。
  4. Clickhouse は null でない列を既存のテーブルに追加することを受け入れます。
  5. Clickhouse は float または double データ型を使用する際に特定の条件下で丸め誤差が発生する可能性があります。丸め誤差が許容できない場合は、decimal データ型を使用してください。たとえば、jsonl でローダーファイル形式を設定して double カラムに値 12.7001 をロードすると、予測可能な丸め誤差が発生します。

Supported Column Hints​

ClickHouse は以下の カラムヒント をサポートしています：

  • primary_key - カラムを主キーの一部としてマークします。複数のカラムがこのヒントを持つことで複合主キーを作成できます。

Table Engine​

デフォルトでは、ClickHouse でのテーブルは ReplicatedMergeTree テーブルエンジンを使用して作成されます。クリックハウスアダプターを使用して代替のテーブルエンジンを指定できます：

サポートされる値は：

  • merge_tree - MergeTree エンジンを使用してテーブルを作成します
  • replicated_merge_tree (デフォルト) - ReplicatedMergeTree エンジンを使用してテーブルを作成します

Staging Support​

ClickHouse はファイルステージング宛先として Amazon S3、Google Cloud Storage、および Azure Blob Storage をサポートしています。

dlt は Parquet または jsonl ファイルをステージングロケーションにアップロードし、ClickHouse テーブル関数を使用して、ステージされたファイルから直接データをロードします。

ステージング宛先の資格情報を構成する方法については、ファイルシステムのドキュメントを参照してください：

ステージングを有効にしてパイプラインを実行するには：

Using Google Cloud Storage as a Staging Area​

dlt は、ClickHouse にデータをロードする際に Google Cloud Storage (GCS) をステージングエリアとして使用することをサポートしています。これは、ClickHouse の GCS テーブル関数 が裏で dlt によって自動的に処理されます。

clickhouse の GCS テーブル関数は、ハッシュベースメッセージ認証コード (HMAC) キーを使用した認証のみをサポートします。これを有効にするために、GCS は Amazon S3 API をエミュレートする S3 互換モードを提供しています。ClickHouse はこれを活用して、S3 統合を介して GCS バケットにアクセスします。

dlt で HMAC 認証を使用して GCS ステージングをセットアップするには：

  1. GCS サービスアカウントの HMAC キーを作成するには、Google Cloud ガイドに従ってください。

  2. dlt プロジェクトの ClickHouse 宛先設定の config.toml で、HMAC キーと共に client_email、project_id、private_key を設定します：

注意: HMAC キーに加え、bashgcp_access_key_id と gcp_secret_access_key の他に、client_email、project_id、private_key を [destination.filesystem.credentials] に提供する必要があります。これは、GCS ステージングサポートが現在、一時的な作業アラウンドとして実装されており、最適化されていないからです。

dlt はこれらの資格情報を ClickHouse に渡し、認証と GCS アクセスを処理します。

将来的には、ClickHouse dlt 宛先の GCS ステージング設定を簡素化し、改善するための作業が進行中です。正式な GCS ステージングサポートは、これらの GitHub イシューで追跡されています：

dbt Support​

dbt との統合は、一般的に dbt-clickhouse を介してサポートされています。

Syncing of dlt state​

この宛先は、dlt 状態の同期を完全にサポートしています。