thevar1able/ClickHouse

Fork 0

mirror of https://github.com/ClickHouse/ClickHouse.git synced 2024-12-15 02:41:59 +00:00

Miki Matsumoto 1e15312729 add translated Japanese docs

2024-11-18 11:58:58 +09:00

15 KiB

Raw Blame History

sidebar_label

keywords

slug

description

dlt

clickhouse

dlt

connect

integrate

etl

data integration

/ja/integrations/dlt

dlt統合を使用してClickHouseにデータをロードする

ClickHouseにdltを接続する

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

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

ClickHouseの依存関係を伴う`dlt`ライブラリをインストールするには:

pip install "dlt[clickhouse]"

セットアップガイド

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

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

dlt init chess clickhouse

:::note このコマンドはsourceとしてchessを、destinationとしてClickHouseを持つパイプラインを初期化します。 :::

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

pip install -r requirements.txt

またはpip install dlt[clickhouse]で、ClickHouseを目的地として動作させるためのdltライブラリと必要な依存関係をインストールします。

2. ClickHouseデータベースをセットアップする

ClickHouseにデータをロードするには、ClickHouseデータベースを作成する必要があります。次のような大まかな手順を行います:

既存のClickHouseデータベースを使用するか、新しいものを作成します。
新しいデータベースを作成するには、clickhouse-clientコマンドラインツールやお好みのSQLクライアントを使用してClickHouseサーバーに接続します。
次のSQLコマンドを実行して、新しいデータベース、ユーザーを作成し、必要な権限を付与します:

CREATE DATABASE IF NOT EXISTS dlt;
CREATE USER dlt IDENTIFIED WITH sha256_password BY 'Dlt*12345789234567';
GRANT CREATE, ALTER, SELECT, DELETE, DROP, TRUNCATE, OPTIMIZE, SHOW, INSERT, dictGet ON dlt.* TO dlt;
GRANT SELECT ON INFORMATION_SCHEMA.COLUMNS TO dlt;
GRANT CREATE TEMPORARY TABLE, S3 ON *.* TO dlt;

3. 認証情報を追加する

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

[destination.clickhouse.credentials]
database = "dlt"                         # 作成したデータベース名
username = "dlt"                         # ClickHouseユーザー名。通常のデフォルトは"default"
password = "Dlt*12345789234567"          # ClickHouseのパスワードがあれば
host = "localhost"                       # ClickHouseサーバーのホスト
port = 9000                              # ClickHouse HTTPポート。デフォルトは9000
http_port = 8443                         # ClickHouseサーバーのHTTPインターフェイスに接続するポート。デフォルトは8443
secure = 1                               # HTTPSを使用している場合は1、それ以外は0
dataset_table_separator = "___"          # データセットテーブル名のセパレータ

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

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

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

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

# tomlファイルのセクションが始まる前に、ファイルの上部に保管してください。
destination.clickhouse.credentials="clickhouse://dlt:Dlt*12345789234567@localhost:9000/dlt?secure=1"

Write Disposition

全てのWrite Dispositionがサポートされています。

dltライブラリにおけるWrite Dispositionは、データがデスティネーションにどのように書き込まれるべきかを定義します。3種類のWrite Dispositionがあります:

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

Merge: このWrite Dispositionは、リソースからのデータをデスティネーション内のデータとマージします。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で動作させるためには、ClickHouseデータベース内でdltによって生成されるテーブル名には、データセット名が接頭辞としてつけられ、設定可能なdataset_table_separatorで区切られます。さらに、データを含まない特別なセンチネルテーブルが作成され、dltがどの仮想データセットがすでにClickHouseのデスティネーションに存在するかを認識できるようにします。

Supported File Formats

jsonlは、直接ロードとステージングの両方で使用するための推奨フォーマットです。
parquetは、直接ロードとステージングの両方でサポートされています。

clickhouseデスティネーションには、デフォルトのsqlデスティネーションからいくつかの特定の逸脱があります:

ClickHouseにはエクスペリメンタルなobjectデータ型がありますが、これが予測不可能なことがあるため、dltのClickHouseデスティネーションは複雑なデータ型をテキストカラムにロードします。この機能が必要な場合は、私たちのSlackコミュニティにご連絡ください。追加検討します。
ClickHouseはtimeデータ型をサポートしていません。時間はtextカラムにロードされます。
ClickHouseはbinaryデータ型をサポートしていません。代わりに、バイナリーデータはtextカラムにロードされます。jsonlからロードする際には、バイナリーデータはbase64文字列になり、parquetからロードする際にはbinaryオブジェクトがtextに変換されます。
ClickHouseでは、データが入っているテーブルに対して非NULLのカラムを追加することを許可しています。
ClickHouseはある条件下でfloatまたはdoubleデータ型を使用する際に丸め誤差を生じる可能性があります。丸め誤差を許容できない場合は、decimalデータ型を使用するようにしてください。例えば、ローダーファイルフォーマットがjsonlに設定されている場合に値12.7001をdoubleカラムにロードすると、予測可能に丸め誤差が生じます。

Supported Column Hints

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

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

テーブルエンジン

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

from dlt.destinations.adapters import clickhouse_adapter


@dlt.resource()
def my_resource():
  ...

clickhouse_adapter(my_resource, table_engine_type="merge_tree")

サポートされている値は以下の通りです:

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

ステージングサポート

ClickHouseはAmazon S3、Google Cloud Storage、Azure Blob Storageをファイルステージングのデスティネーションとしてサポートしています。

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

ステージングデスティネーションの認証情報の設定方法については、ファイルシステムドキュメントを参照してください:

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

pipeline = dlt.pipeline(
  pipeline_name='chess_pipeline',
  destination='clickhouse',
  staging='filesystem',  # ステージングを有効にするために追加
  dataset_name='chess_data'
)

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

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

ClickHouseのGCSテーブル関数は、ハッシュベースのメッセージ認証コード（HMAC）キーを使用した認証のみをサポートしています。これを可能にするため、GCSはAmazon S3 APIをエミュレートするS3互換モードを提供しています。ClickHouseはこれを活用して、S3統合を通じてGCSバケットにアクセスできるようにしています。

dltでのHMAC認証を使用したGCSステージングのセットアップ方法:

Google Cloudのガイドに従って、GCSサービスアカウントのHMACキーを作成します。
dltプロジェクトのClickHouseデスティネーション設定config.tomlに、サービスアカウントのclient_email、 project_id、private_keyと共にHMACキーを設定します:

[destination.filesystem]
bucket_url = "gs://dlt-ci"

[destination.filesystem.credentials]
project_id = "a-cool-project"
client_email = "my-service-account@a-cool-project.iam.gserviceaccount.com"
private_key = "-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkaslkdjflasjnkdcopauihj...wEiEx7y+mx\nNffxQBqVVej2n/D93xY99pM=\n-----END PRIVATE KEY-----\n"

[destination.clickhouse.credentials]
database = "dlt"
username = "dlt"
password = "Dlt*12345789234567"
host = "localhost"
port = 9440
secure = 1
gcp_access_key_id = "JFJ$$*f2058024835jFffsadf"
gcp_secret_access_key = "DFJdwslf2hf57)%$02jaflsedjfasoi"

注: 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の問題として追跡されています:

ファイルシステムデスティネーションをGCSのS3互換モードで動作させる
Google Cloud Storageステージングエリアサポート

dbtサポート

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

`dlt`の状態の同期

このデスティネーションはdltの状態同期を完全にサポートしています。

15 KiB Raw Blame History Unescape Escape