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

dltをClickHouseに接続する

dltは、さまざまなデータソースからデータを整然としたライブデータセットにロードするためにPythonスクリプトに追加できるオープンソースライブラリです。

ClickHouseと共にdltをインストールする​

ClickHouseの依存関係を持つdltライブラリをインストールするには:​

セットアップガイド​

1. dltプロジェクトを初期化する​

新しいdltプロジェクトを初期化するには、以下のコマンドを使用します:

注記

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

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

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

2. ClickHouseデータベースのセットアップ​

ClickHouseにデータをロードするには、ClickHouseデータベースを作成する必要があります。以下は、行うべきおおまかな手順です:

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

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

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

3. 認証情報を追加する​

次に、.dlt/secrets.tomlファイルにClickHouseの認証情報を設定します。以下のように設定してください:

注記

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

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

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

データベース接続文字列は、clickhouse-driverライブラリで使用されるものに似た形式で渡すことができます。上記の認証情報は次のようになります:

書き込みディスポジション​

すべての書き込みディスポジションがサポートされています。

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

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

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

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

データのロード​

データは、データソースに応じた最も効率的な方法を使用してClickHouseにロードされます:

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

データセット​

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

サポートされているファイル形式​

  • 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をロードすると、予測可能に丸め誤差が発生します。

サポートされているカラムヒント​

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

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

テーブルエンジン​

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

サポートされている値は次のとおりです:

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

ステージングサポート​

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

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

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

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

Google Cloud Storageをステージングエリアとして使用​

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

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キー（gcp_access_key_idおよびgcp_secret_access_key）に加えて、client_email、project_id、private_keyをサービスアカウント用に[destination.filesystem.credentials]の下で提供する必要があります。これは、GCSステージングサポートが一時的な回避策として実装されており、まだ最適化されていないためです。

dltはこれらの認証情報をClickHouseに渡し、ClickHouseが認証およびGCSアクセスを処理します。

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

dbtサポート​

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

dltの状態の同期​

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