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

Dataflow BigQuery to ClickHouse テンプレート

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

パイプライン要件

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

テンプレートパラメータ



パラメータ名パラメータの説明必須注記
jdbcUrljdbc:clickhouse://<host>:<port>/<schema> 形式の ClickHouse JDBC URL。JDBC オプションとしてユーザー名とパスワードは追加しないでください。他の JDBC オプションは JDBC URL の末尾に追加できます。ClickHouse Cloud ユーザーの場合は、jdbcUrlssl=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 テーブル定義に基づいて変換されます。したがって、上記の表は、あなたのターゲット ClickHouse テーブルで持つべき推奨マッピングを示します(指定された BigQuery テーブル/クエリ用):

BigQuery タイプClickHouse タイプ注記
Array TypeArray Type内部型は、この表にリストされているサポートされているプリミティブデータ型の1つでなければなりません。
Boolean TypeBool Type
Date TypeDate Type
Datetime TypeDatetime TypeEnum8Enum16FixedString でも動作します。
String TypeString TypeBigQuery では、すべての Int タイプ(INTSMALLINTINTEGERBIGINTTINYINTBYTEINT)は INT64 のエイリアスです。ClickHouse で適切な整数サイズを設定することをお勧めします。テンプレートは定義されたカラム型に基づいてカラムを変換します(Int8Int16Int32Int64)。
Numeric - Integer TypesInteger TypesBigQuery では、すべての Int タイプ(INTSMALLINTINTEGERBIGINTTINYINTBYTEINT)は INT64 のエイリアスです。ClickHouse で適切な整数サイズを設定することをお勧めします。テンプレートは定義されたカラム型(Int8Int16Int32Int64)に基づいてカラムを変換します。ClickHouse テーブルで使用される非指定の Int タイプも変換します(UInt8UInt16UInt32UInt64)。
Numeric - Float TypesFloat Typesサポートされている ClickHouse タイプ: Float32 および Float64

テンプレートの実行

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

注記

このドキュメント、特に上記のセクションをよく確認して、テンプレートの構成要件と前提条件を完全に理解してください。

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

  1. CREATE JOB FROM TEMPLATE ボタンを押します。
    DataFlow console
  2. テンプレートフォームが開いたら、ジョブ名を入力し、希望するリージョンを選択します。
    DataFlow template initial form
  3. DataFlow Template 入力に、ClickHouse または BigQuery と入力し、BigQuery to ClickHouse テンプレートを選択します。
    Select BigQuery to ClickHouse template
  4. 選択すると、フォームが展開されて、追加の詳細を提供できるようになります:
    • ClickHouse サーバーの JDBC URL、形式は jdbc:clickhouse://host:port/schema
    • ClickHouse のユーザー名。
    • ClickHouse のターゲットテーブル名。

注記

ClickHouse パスワードオプションはオプションとしてマークされています。パスワードが設定されていないユースケースで使用します。追加するには、Password for ClickHouse Endpoint オプションまでスクロールしてください。

BigQuery to ClickHouse extended template form
  1. テンプレートパラメータ セクションに詳述されている BigQuery / ClickHouseIO 関連の設定をカスタマイズおよび追加します。

ジョブのモニタリング

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

DataFlow console showing a running BigQuery to ClickHouse job

トラブルシューティング

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

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

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

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

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