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

Dataflow BigQuery to ClickHouse テンプレート

BigQueryからClickHouseへのテンプレートは、BigQueryテーブルからClickHouseテーブルにデータを取り込むためのバッチパイプラインです。このテンプレートは、テーブル全体を読み取ることも、提供されたクエリを使用して特定のレコードを読み取ることもできます。

パイプライン要件​

  • ソースのBigQueryテーブルが存在する必要があります。
  • ターゲットのClickHouseテーブルが存在する必要があります。
  • ClickHouseホストは、Dataflowワーカーのマシンからアクセス可能でなければなりません。

テンプレートパラメータ​



パラメータ名パラメータの説明必須ノート
jdbcUrljdbc:clickhouse://<host>:<port>/<schema> 形式のClickHouse JDBC URLです。✅ユーザー名とパスワードをJDBCオプションとして追加しないでください。その他のJDBCオプションは、JDBC URLの末尾に追加できます。ClickHouse Cloudユーザーの場合は、jdbcUrlにssl=true&sslmode=NONEを追加してください。
clickHouseUsername認証に使用するClickHouseのユーザー名です。✅
clickHousePassword認証に使用するClickHouseのパスワードです。✅
clickHouseTableデータを挿入するターゲットのClickHouseテーブル名です。✅
maxInsertBlockSize挿入の最大ブロックサイズ（ClickHouseIOオプション）。ClickHouseIOオプションです。
insertDistributedSync設定が有効な場合、分散挿入クエリはクラスタ内のすべてのノードにデータが送信されるまで待機します（ClickHouseIOオプション）。ClickHouseIOオプションです。
insertQuorum複製されたテーブルへのINSERTクエリのために、指定された数のレプリカへの書き込みを待機し、データの追加を線形化します。0 - 無効。ClickHouseIOオプションです。この設定はデフォルトのサーバー設定では無効です。
insertDeduplicate複製されたテーブルへのINSERTクエリのために、挿入ブロックの重複除去を行うべきかを指定します。ClickHouseIOオプションです。
maxRetries挿入あたりの最大再試行回数です。ClickHouseIOオプションです。
InputTableSpec読み取るBigQueryテーブルです。inputTableSpecまたはqueryのいずれかを指定します。両方が設定されている場合、queryパラメータが優先されます。例：<BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>。BigQuery Storage Read APIを使用して、BigQueryストレージからデータを直接読み取ります。Storage Read APIの制限に注意してください。
outputDeadletterTable出力テーブルに到達できなかったメッセージのためのBigQueryテーブルです。テーブルが存在しない場合、パイプライン実行中に作成されます。指定しない場合、<outputTableSpec>_error_recordsが使用されます。例：<PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>。
queryBigQueryからデータを読み取るために使用するSQLクエリです。BigQueryデータセットがDataflowジョブとは異なるプロジェクトにある場合、SQLクエリに完全なデータセット名を指定してください。例：<PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>。デフォルトではGoogleSQLが使用され、useLegacySqlがtrueの場合を除きます。inputTableSpecまたはqueryのいずれかを指定する必要があります。両方のパラメータを設定した場合、テンプレートはqueryパラメータを使用します。例：SELECT * FROM sampledb.sample_table。
useLegacySqlレガシーSQLを使用するにはtrueに設定します。このパラメータはqueryパラメータを使用している場合のみ適用されます。デフォルトはfalseです。
queryLocation基となるテーブルの権限なしで認可されたビューから読み取る際に必要です。例：US。
queryTempDatasetクエリの結果を格納するために一時テーブルを作成する既存のデータセットを設定します。例：temp_dataset。
KMSEncryptionKeyクエリソースを使用してBigQueryから読み取る場合、このCloud KMSキーを使用して作成された一時テーブルを暗号化します。例：projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key。
注記

すべてのClickHouseIOパラメータのデフォルト値は、ClickHouseIO Apache Beam Connectorで見つけることができます。

ソースおよびターゲットテーブルのスキーマ​

BigQueryデータセットをClickHouseに効果的にロードするために、カラムの浸透プロセスが次のフェーズで実施されます。

  1. テンプレートはターゲットClickHouseテーブルに基づいてスキーマオブジェクトを構築します。
  2. テンプレートはBigQueryデータセットを反復処理し、カラム名に基づいてマッチングを試みます。

参考

言うまでもなく、あなたのBigQueryデータセット（テーブルまたはクエリのいずれか）は、ClickHouseのターゲットテーブルと全く同じカラム名を持っている必要があります。

データ型マッピング​

BigQueryの型は、ClickHouseテーブルの定義に基づいて変換されます。したがって、上記の表は、指定されたBigQueryテーブル/クエリのターゲットClickHouseテーブルに持っているべき推奨マッピングを示しています。

BigQueryタイプClickHouseタイプノート
配列型配列型内部型は、この表にリストされているサポートされている基本データ型のいずれかでなければなりません。
ブーリアン型ブール型
日付型日付型
日時型日時型Enum8、Enum16、FixedStringでも動作します。
文字列型文字列型BigQueryのすべてのIntタイプ（INT、SMALLINT、INTEGER、BIGINT、TINYINT、BYTEINT）はINT64のエイリアスです。ClickHouseにおいて適切な整数サイズを設定することをお勧めします。テンプレートは定義されたカラムタイプ（Int8、Int16、Int32、Int64）に基づいてカラムを変換します。
数値 - 整数型整数型BigQueryのすべてのIntタイプ（INT、SMALLINT、INTEGER、BIGINT、TINYINT、BYTEINT）はINT64のエイリアスです。ClickHouseにおいて適切な整数サイズを設定することをお勧めします。テンプレートは定義されたカラムタイプに基づいてカラムを変換します。未割り当てのIntタイプがClickHouseテーブルで使用されている場合（UInt8、UInt16、UInt32、UInt64）。
数値 - 浮動小数点型浮動小数点型サポートされているClickHouseタイプ：Float32とFloat64

テンプレートの実行​

BigQueryからClickHouseへのテンプレートは、Google Cloud CLIを介して実行できます。

注記

この文書を確認し、特に上記のセクションをレビューして、テンプレートの設定要件と前提条件を完全に理解してください。

gcloud CLIのインストールと設定​

  • まだインストールされていない場合は、gcloud CLIをインストールします。
  • このガイドの「始める前に」セクションに従って、DataFlowテンプレートを実行するために必要な設定、設定、権限をセットアップします。

実行コマンド​

gcloud dataflow flex-template runコマンドを使用して、Flexテンプレートを使用したDataflowジョブを実行します。

以下はコマンドの例です：

gcloud dataflow flex-template run "bigquery-clickhouse-dataflow-$(date +%Y%m%d-%H%M%S)" \
 --template-file-gcs-location "gs://clickhouse-dataflow-templates/bigquery-clickhouse-metadata.json" \
 --parameters inputTableSpec="<bigquery table id>",jdbcUrl="jdbc:clickhouse://<clickhouse host>:<clickhouse port>/<schema>?ssl=true&sslmode=NONE",clickHouseUsername="<username>",clickHousePassword="<password>",clickHouseTable="<clickhouse target table>"

コマンドの分解​

  • ジョブ名：runキーワードに続くテキストが一意のジョブ名です。
  • テンプレートファイル：--template-file-gcs-locationで指定されたJSONファイルがテンプレートの構造と受け入れられるパラメータに関する詳細を定義しています。指定されたファイルパスは公開されており、使用する準備が整っています。
  • パラメータ：パラメータはカンマで区切ります。文字列ベースのパラメータの値はダブルクオーテーションで囲みます。

予想される応答​

コマンドを実行した後、以下のような応答が表示されるはずです。

job:
  createTime: '2025-01-26T14:34:04.608442Z'
  currentStateTime: '1970-01-01T00:00:00Z'
  id: 2025-01-26_06_34_03-13881126003586053150
  location: us-central1
  name: bigquery-clickhouse-dataflow-20250126-153400
  projectId: ch-integrations
  startTime: '2025-01-26T14:34:04.608442Z'

ジョブの監視​

Google Cloud ConsoleのDataflowジョブタブに移動して、ジョブのステータスを監視します。進捗やエラーを含むジョブの詳細が表示されます：

DataFlow コンソールが実行中の BigQuery から ClickHouse へのジョブを示しています

トラブルシューティング​

コード: 241. DB::Exception: メモリ制限（合計）が超過しました​

このエラーは、ClickHouseが大規模なデータバッチを処理中にメモリが不足すると発生します。この問題を解決するには：

  • インスタンスリソースを増やす：データ処理負荷を処理するために、より大きなインスタンスにClickHouseサーバーをアップグレードします。
  • バッチサイズを減らす：Dataflowジョブ設定でバッチサイズを調整し、ClickHouseに送信するデータのチャンクを小さくして、バッチごとのメモリ消費を減らします。 これらの変更により、データ取り込み中のリソース使用量のバランスを取るのに役立つかもしれません。

テンプレートソースコード​

テンプレートのソースコードは、ClickHouseのDataflowTemplatesフォークで利用可能です。