Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

Dataflow BigQuery to ClickHouse テンプレート

View as MarkdownEdit this pageReport an issueSet up docs MCP

BigQuery から ClickHouse へのTemplateは、BigQuery テーブルから ClickHouse テーブルにデータを取り込むバッチパイプラインです。 このTemplateでは、テーブル全体を読み取ることも、指定したSQLクエリを使って特定のレコードをフィルタリングすることもできます。

パイプラインの要件

  • ソースとなる BigQuery テーブルが存在している必要があります。
  • ClickHouse のターゲットテーブルが存在している必要があります。
  • Dataflow のワーカーマシンから ClickHouse ホストにアクセスできる必要があります。

Template パラメータ



Parameter Name Parameter Description Required Notes
jdbcUrl jdbc:clickhouse://<host>:<port>/<schema> 形式の ClickHouse JDBC URL。 ✅ username と password は JDBC オプションとして追加しないでください。その他の JDBC オプションは JDBC URL の末尾に追加できます。ClickHouse Cloud ユーザーは、jdbcUrl に ssl=true&sslmode=NONE を追加してください。
clickHouseUsername 認証に使用する ClickHouse の username。 ✅
clickHousePassword 認証に使用する ClickHouse の password。 ✅
clickHouseTable データの挿入先となる ClickHouse のターゲットテーブル。 ✅
maxInsertBlockSize 挿入用の block の作成を制御する場合の、挿入時の最大 block サイズ (ClickHouseIO オプション) 。 ClickHouseIO オプションです。
insertDistributedSync この設定を有効にすると、distributed への INSERT クエリは、データがクラスター内のすべてのノードに送信されるまで待機します。 (ClickHouseIO オプション) ClickHouseIO オプションです。
insertQuorum レプリケートテーブルへの INSERT クエリで、指定した数のレプリカへの書き込みが完了するまで待機し、データ追加を線形化します。0 は無効です。 ClickHouseIO オプションです。この設定はデフォルトの server settings では無効です。
insertDeduplicate レプリケートテーブルへの INSERT クエリで、挿入する blocks の deduplication を実行するかどうかを指定します。 ClickHouseIO オプションです。
maxRetries 挿入ごとの最大再試行回数。 ClickHouseIO オプションです。
InputTableSpec 読み取り元の BigQuery テーブル。inputTableSpec または query のいずれかを指定してください。両方が設定されている場合は、query パラメータが優先されます。例: <BIGQUERY_PROJECT>:<DATASET_NAME>.<INPUT_TABLE>。 BigQuery Storage Read API を使用して BigQuery Storage から直接データを読み取ります。Storage Read API の制限事項に注意してください。
outputDeadletterTable 出力テーブルへの書き込みに失敗したメッセージを格納する BigQuery テーブル。テーブルが存在しない場合は、pipeline の実行中に作成されます。指定しない場合は、<outputTableSpec>_error_records が使用されます。例: <PROJECT_ID>:<DATASET_NAME>.<DEADLETTER_TABLE>。
query BigQuery からデータを読み取るために使用する SQL クエリ。BigQuery データセット が Dataflow job とは別の project にある場合は、SQL クエリ内で完全修飾の データセット 名を指定してください。例: <PROJECT_ID>.<DATASET_NAME>.<TABLE_NAME>。useLegacySql が true でない限り、デフォルトは GoogleSQL です。 inputTableSpec または query のいずれかを必ず指定する必要があります。両方のパラメータを設定した場合、template は query パラメータを使用します。例: SELECT * FROM sampledb.sample_table。
useLegacySql 従来の SQL を使用するには true に設定します。このパラメータは query パラメータを使用する場合にのみ適用されます。デフォルトは false です。
queryLocation 基になるテーブルへの permission がない状態で認可済み VIEW から読み取る場合に必要です。例: US。
queryTempDataset クエリ結果を保存する一時テーブルの作成先として、既存の データセット を指定します。例: temp_dataset。
KMSEncryptionKey クエリ ソースを使用して BigQuery から読み取る場合は、この Cloud KMS key を使用して作成される一時テーブルを暗号化します。例: projects/your-project/locations/global/keyRings/your-keyring/cryptoKeys/your-key。

ソーステーブルとターゲットテーブルのスキーマ

BigQuery のデータセットを ClickHouse に効率よくロードするために、このパイプラインでは次のフェーズでカラム推論を行います。

  1. Templateは、ClickHouse のターゲットテーブルに基づいてスキーマオブジェクトを構築します。
  2. Templateは BigQuery のデータセットを走査し、カラム名に基づいて一致を試みます。

データ型マッピング

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

BigQuery Type ClickHouse Type Notes
Array Type Array Type 内部型は、この表に記載されているサポート対象のプリミティブなデータ型のいずれかである必要があります。
Boolean Type Bool Type
Date Type Date Type
Datetime Type Datetime Type Enum8、Enum16、FixedString に対しても使用できます。
String Type String Type BigQuery では、すべての Int 型 (INT、SMALLINT、INTEGER、BIGINT、TINYINT、BYTEINT) は INT64 の別名です。ClickHouse では、適切な Integer サイズを設定することを推奨します。テンプレートは、定義されたカラム型 (Int8、Int16、Int32、Int64) に基づいてカラムを変換するためです。
Numeric - Integer Types Integer Types BigQuery では、すべての Int 型 (INT、SMALLINT、INTEGER、BIGINT、TINYINT、BYTEINT) は INT64 の別名です。ClickHouse では、適切な Integer サイズを設定することを推奨します。テンプレートは、定義されたカラム型 (Int8、Int16、Int32、Int64) に基づいてカラムを変換するためです。さらに、ClickHouse テーブルで符号なし Int 型 (UInt8、UInt16、UInt32、UInt64) が使われている場合も変換されます。
Numeric - Float Types Float Types サポートされる ClickHouse の型: Float32 および Float64

Templateの実行

BigQuery から ClickHouse へのTemplateは、Google Cloud CLI 経由で実行できます。

Google Cloud Console にサインインし、DataFlow を検索します。

  1. CREATE JOB FROM TEMPLATE ボタンをクリックします
    DataFlow コンソール
  2. Templateフォームが開いたら、ジョブ名を入力し、目的のリージョンを選択します。
    DataFlow Templateの初期フォーム
  3. DataFlow Template の入力欄に ClickHouse または BigQuery と入力し、BigQuery to ClickHouse Templateを選択します
    BigQuery to ClickHouse Templateを選択
  4. 選択するとフォームが展開され、追加情報を入力できるようになります。
    • 次の形式の ClickHouse server JDBC URL: jdbc:clickhouse://host:port/schema
    • ClickHouse のユーザー名。
    • ClickHouse のターゲットテーブル名。

BigQuery to ClickHouse の拡張Templateフォーム
  1. Template パラメータ セクションの説明に従って、 BigQuery/ClickHouseIO 関連の設定を必要に応じてカスタマイズして追加します

ジョブを監視する

Google Cloud Console の Dataflow Jobs タブ に移動し、 ジョブのステータスを確認します。進行状況やエラーを含むジョブの詳細を確認できます。

実行中の BigQuery から ClickHouse へのジョブが表示された Dataflow コンソール

トラブルシューティング

メモリ制限 (合計) 超過エラー (コード 241)

このエラーは、大きなバッチデータの処理中に ClickHouse のメモリが不足すると発生します。この問題を解決するには、次の対応を行ってください。

  • インスタンスのリソースを増やす: より多くのメモリを搭載した大きなインスタンスに ClickHouse server をアップグレードし、データ処理の負荷に対応します。
  • バッチサイズを小さくする: Dataflow ジョブの設定でバッチサイズを調整し、より小さな chunk のデータを ClickHouse に送信することで、バッチごとのメモリ消費を抑えます。これらの変更は、データのインジェスト時にリソース使用量のバランスを取るのに役立ちます。

Template のソースコード

Template のソースコードは以下で公開されています。

Navigation