ClickHouseデータソースの設定
ClickHouseデータソースは、オフライン同期でClickHouseとプラットフォームのプリセットデータウェアハウスの間でテーブルデータを転送するために使用します。このドキュメントでは、接続設定、双方向の読み取り元とデータの流向の設定、対応するフィールドタイプ、同期の検証、ワークフロースケジュールについて説明します。
接続前の準備と使用上の制限
対応バージョン
ClickHouse 24.0以降のバージョン。
準備事項
構成を始める前に、以下の事項を確認してください。
- ClickHouse → プリセットデータウェアハウス と プリセットデータウェアハウス → ClickHouse に対応しています。このプランでは、ClickHouseと他の外部データソースの間で直接データを同期することはできません。
- ClickHouseの サーバーアドレス/IP、ポート、データベース名、ユーザー名、パスワード を用意します。プラットフォームの実行環境から対象サービスにアクセスできる必要があります。ネットワークアクセスが制限されている場合は、プラットフォームサーバーの実際の送信元アドレスと許可されているアクセス範囲を確認してください。
- 接続用アカウントには、データベースへのアクセス権限と、選択したテーブルのメタデータを参照する権限が必要です。ソーステーブルを読み取るには読み取り権限、目標テーブルに書き込むには対応する書き込み権限が必要です。分散テーブルを使用する場合は、対応するクラスター情報とシャード情報も取得できる必要があります。
- 目標テーブルを事前に用意し、フィールドタイプ、NULL制約、パーティション定義を確認します。プリセットデータウェアハウスの目標テーブルの作成方法は、スペーステーブルの作成と管理を参照してください。ClickHouseの目標テーブルは、対応するデータベース内に事前に作成する必要があります。
- テーブル選択画面で利用可能なテーブルに従ってください。Aggregating系エンジンのテーブルとマテリアライズドビューは、通常の選択可能なテーブルとしては使用しません。ClickHouseが対応するすべてのエンジンやタイプを、このプランで同期できると判断しないでください。
| 環境の構成方法 | 設定要件 |
|---|---|
| 環境を区別しない | 開発環境と本番環境で、同じ接続情報と認証情報の構成を使用します |
| 独立環境構成 | 開発環境と本番環境をそれぞれ構成します。どちらの構成からも、プランで選択したデータベースとテーブルにアクセスできる必要があります |
データプレビューは開発環境の構成を、手動実行は本番環境の構成を使用します。両方の構成について、サーバーアドレス、データベースとテーブルの権限、ネットワークアクセスをそれぞれ確認してください。パスワードは安全な方法で受け渡し、認証情報をスクリーンショット、ログ、公開ドキュメントに記載しないでください。
ClickHouseデータソースの作成
- データ開発プラットフォーム > 連携 > データソース に移動し、+ データソース をクリックします。
- ClickHouse を選択して 次へ をクリックし、データソース名と備考を入力します。
- 環境を区別しない または 独立環境構成 を選択します。独立環境構成では、開発環境と本番環境の情報をそれぞれ入力する必要があります。
- 以下の接続パラメータを入力します。接続性テスト で テスト をクリックし、テストに成功したことを確認してから 完了 をクリックします。
| 構成項目 | 説明 |
|---|---|
| データソース名 | 現在のスペースで接続を識別するための名前。作成後は変更できません |
| 備考 | 任意入力。接続の用途を記載できます |
| サーバーアドレス/IP | ClickHouseサービスのホストアドレス。複数のアドレスは半角カンマで区切ります。ポートは下の項目に個別に入力し、アドレス内には重複して記載しないでください |
| ポート | ClickHouseへのアクセスに使用するサービスポート。管理者に確認してください |
| データベース名 | ClickHouse内に作成済みで、接続用アカウントがアクセスできるデータベース |
| ユーザー名 | 今回の読み取りまたは書き込みに必要な権限を持つアカウント |
| パスワード | ユーザー名に対応するパスワード |
| 高度な構成 | 必要に応じてJSON形式の拡張構成を入力します。追加の構成要件がなければ空欄にできます |
接続性テスト(画面では 紐付けテスト、実行ボタンは テスト期間)に成功した後も、同期プランでデータベースとテーブルを読み込み、ソースデータをプレビューして実行検証を行い、実際のテーブル権限と読み取り・書き込み結果を確認する必要があります。パスワードを変更した場合やデータベース権限を調整した場合は、接続と関連プランを再検証してください。
読み取り元の構成
ClickHouseからプリセットデータウェアハウスへの読み取り
- データ開発プラットフォーム > 連携 > オフライン同期 に移動し、+ 統合プラン をクリックします。
- データソース で ClickHouse と作成済みのデータソースを選択します。
- データ取得方法 を選択し、テーブル全体の読み取りまたはカスタムクエリで読み取り元を構成します。
- データプレビュー をクリックし、ソースフィールド、実際の値、読み取り範囲を確認します。
- データの流向 でプラットフォームの プリセットデータウェアハウス を選択し、目標スペーステーブルを選択して、目標パーティションと書き込みモードを構成します。
| データ取得方法 | 構成方法 |
|---|---|
| テーブル全体 | データベースとデータテーブルを選択します。一部のデータのみ読み取る場合は、データフィルター を有効にしてフィルター条件を入力します |
| カスタムクエリ | 同期対象フィールドを返す読み取り専用のクエリSQLを入力し、絞り込み条件をクエリ内に記述します。この方法では、テーブル全体の読み取りに使用するデータベース、データテーブルの選択項目やデータフィルターを個別に構成しません |
テーブル全体の読み取りにおけるデータフィルターには、WHERE を含む完全な条件句(例:WHERE status = 'active')を入力し、完全な SELECT クエリは入力しないでください。カスタムクエリでは、アクセス先のデータベースを確認し、必要に応じてSQL内にデータベース名とテーブル名を明示してください。返されるフィールド名が明確で、タイプを認識できることも確認します。
| プリセットデータウェアハウスへの書き込み構成項目 | 説明 |
|---|---|
| 目標テーブル | 今回のデータを受け取るプリセットデータウェアハウス内のスペーステーブル。存在しない場合は、先に ライブラリテーブル で作成してください |
| パーティション情報 | 目標がパーティションテーブルの場合は、そのテーブルの要件に従ってパーティション値を入力します。スペースパラメータを使用して実行時のパーティションを構成することもできます |
| 書き込みモード | 目標データの保持要件に応じて 追加書き込み(画面では 書き込み前に既存のデータを保持)または 上書き書き込み を選択し、実行前に目標テーブル、目標パーティション、データの保持要件を再確認してください |
データソース、データベース、データテーブル、データ取得方法を切り替えた後は、読み取り範囲、プレビュー結果、フィールドマッピングを再確認してください。ソーステーブルの構造やクエリ結果が変わった場合も、再解析してマッピングを確認する必要があります。
データの流向の構成
プリセットデータウェアハウスからClickHouseへの書き込み
データソース でプリセットデータウェアハウスのソーステーブルを構成し、データの流向 で ClickHouse と作成済みのデータソースを選択します。続けてClickHouseの目標データベースとデータテーブルを選択します。
| 構成項目 | 説明 |
|---|---|
| データソース名 | 現在のスペースに作成済みのClickHouseデータソース。未作成の場合は、データソース管理 で構成できます |
| データベース名 | 今回の書き込み先となるClickHouseデータベース |
| データテーブル名 | ClickHouseに用意済みで、接続用アカウントに書き込み権限がある目標テーブル |
| シャードフィールドの使用 | 以下のシャード条件を満たす場合に有効化できます。有効化する前に、フィールドマッピングに対応する目標シャードフィールドを含める必要があります |
| 書き込みモード | 追加書き込み(画面では 書き込み前に既存のデータを保持)のみをサポートし、目標テーブルにデータを追加します。再実行する前に、重複レコードが発生しないか評価してください |
| バッチ件数 | 高度な構成 の バッチサイズ にあり、画面上のデフォルト値は 20000、設定可能な範囲は 10000–100000 です |
ClickHouseへの書き込みでは、上書き書き込みや更新挿入モードは提供していません。同じソース範囲で再試行する場合は、過去の実行結果と目標データを先に確認し、重複した追加を避けてください。
シャードフィールドの使用
シャード機能は、条件を満たす分散テーブルへの書き込みに使用します。以下の条件をすべて満たす必要があります。
- 目標テーブルが Distributed エンジンのテーブルで、対応するクラスターで
internal_replicationが有効になっていること。 - プラットフォームが、目標テーブルで使用するシャードフィールドを認識できること。任意のシャード式を、そのまま選択可能なフィールドとして扱うことはできません。
- フィールドマッピングにその目標シャードフィールド(画面では 分割フィールド)が含まれ、有効なソースの対応関係が設定されていること。
条件を満たしたら、シャードフィールドの使用(画面の 分片フィールドを使用する)を有効にします。スイッチを使用できない場合は、目標テーブル、クラスター構成、フィールドマッピングを確認してください。目標データベースやテーブルを切り替えた場合、またはシャードフィールドのマッピングを削除した場合は、この設定を再確認する必要があります。
フィールドマッピングと対応するフィールドタイプ
読み取り元とデータの流向の構成後、フィールドマッピング でソースフィールドと目標フィールドの対応関係を設定します。個別に選択するか、同名マッピング または 同じ行のマッピング を使用してから各項目を確認できます。1つの目標フィールドに対応付けられるソースフィールドは1つだけです。
図は既存のプランにおけるフィールドの対応関係を示しています。現在の接続、フィールドの解析結果、実際の同期結果の検証に代わるものではありません。
読み取りに対応するフィールドタイプ
ClickHouseをデータの読み取り元として使用する場合、正しく解析できる以下の基本タイプに対応しています。パラメーター付きタイプやラッパータイプは、後述の使用上の制限も満たす必要があります。
| タイプの分類 | 対応するClickHouseのフィールドタイプ |
|---|---|
| ブール値 | Bool、boolean |
| 整数 | Int8、UInt8、Int16、UInt16、Int32、UInt32、Int64、UInt64、Int128、UInt128、Int256、UInt256 |
| 浮動小数点数 | Float32、Float64 |
| 固定小数点数 | Decimal、Decimal32、Decimal64、Decimal128、Decimal256 |
| 文字列と列挙型 | String、FixedString、Enum、Enum8、Enum16 |
| 日付と時刻 | Date、DateTime、DateTime32、DateTime64 |
| 地理タイプ | Point、Ring、Polygon |
| 間隔 | IntervalYear、IntervalQuarter、IntervalMonth、IntervalWeek、IntervalDay、IntervalHour、IntervalMinute、IntervalSecond |
| 複合タイプ | Array、Map。完全な構造を確認する必要があります |
Nested、UUID、IPv4、IPv6、Date32、MultiPolygonなど、記載のないタイプやその他の認識できないタイプには対応していません。Tuple、Nullable(T)、LowCardinality(T)の制限は後述の説明を参照してください。名前だけで対応していると判断しないでください。
書き込みに対応するフィールドタイプ
ClickHouseをデータの流向として使用する場合、対応する基本タイプと非対応のタイプは上表と同じです。目標テーブルは事前に作成し、フィールドのパラメーター、完全な構造、制約が実際の書き込み要件を満たす必要があります。
MATERIALIZED、EPHEMERAL、ALIASなどの読み取り専用の生成フィールドは、通常の書き込みフィールドとして設定できません。これはフィールドの種別に関する制限であり、フィールド自体のデータタイプとは異なります。
フィールドタイプの使用上の制限
| タイプまたはシナリオ | 対応条件と制限 |
|---|---|
| 整数、固定小数点数、固定長文字列、列挙型 | 完全な値の範囲、精度、小数点以下の桁数、長さ、列挙型の許容値を確認してください。基本タイプの対応範囲に含まれていても、すべてのフィールド定義や実際の値に適用できるとは限りません |
| パラメーター付きタイプ | テーブル全体の読み取りとカスタムクエリでは、フィールドの解析結果が異なる場合があります。長さや精度を数値パラメーターで指定するタイプは、完全な定義を確認してください。タイムゾーン文字列を含む時刻タイプや許容値を指定した列挙型は、現在の読み取り方法で正しく解析できることを確認してください |
Nullable(T) | 外側のラッパーのみ、内部タイプとして認識できます。内部タイプ自体も対応範囲内である必要があり、目標フィールドのNULL制約も確認してください。すべての入れ子のラッパー形式に適用できるわけではありません |
LowCardinality(T) | 内部タイプが自動的に認識される保証はありません。現在のフィールドの解析結果と利用可否を確認してください。内部タイプに対応しているという理由だけで、そのラッパータイプも使用できると判断しないでください |
Tuple(...) | パラメーター付きのTupleが正しく認識される保証はありません。現在の完全なフィールド定義と解析結果に従ってください。無条件で対応するタイプには含めません |
Array、Mapおよび入れ子構造 | 完全な要素定義、キーと値の定義、NULL制約を確認してください。最上位のタイプに対応していても、任意の内部構造に対応しているわけではありません |
ClickHouseのタイプ定義については、ClickHouse公式データタイプ説明を参照してください。データベースが対応するタイプすべてに、このプランが対応しているわけではありません。ソーステーブルまたは目標テーブルの構造を変更した後は、フィールドを再解析して対応関係を確認してください。データプレビューに表示されることも、同期の検証に代わるものではありません。
保存、検証、スケジュール
基本情報と同期検証
- ソーステーブルまたはクエリ、フィルター範囲、目標テーブルとパーティション、書き込みモード、フィールドマッピングを確認します。まず読み取り元の データプレビュー でフィールドとサンプル値を確認します。
- プラン名、担当者、同期速度、備考を入力し、保存 をクリックします。保存後はプラン名を変更できません。
- 手動実行 をクリックし、ポップアップに従って実行モードを選択します。今回のパラメータ値を確認してから実行を開始します。手動実行は 本番環境の構成 を使用し、実行モードは開発環境と本番環境の切り替えには使用しません。
- 手動実行記録 でステータスとログを確認します。タスクが正常に完了したら、目標テーブルでデータ量、フィールドの対応関係、および数値、時刻、複合タイプ、NULL値などのサンプルを確認します。
独立環境構成では、開発環境でデータを読み込んだりプレビューしたりできても、本番環境の認証情報や読み取り・書き込み権限が用意されているとは限りません。初回実行前に、両方の構成のデータベース、テーブル、パーティション、パラメータをそれぞれ確認してください。プリセットデータウェアハウスへ上書きする場合は目標範囲を確認し、ClickHouseへ追加書き込みする場合は再試行や繰り返し実行の影響を評価してください。
マウントされたタスクフロー
手動での検証に合格したら、プランをタスクフローにマウントし、スケジュール周期に従って実行できます。
- 保存済みのプランを開き、ジョブフローにマウントする をクリックして、目標タスクフローを選択します。対応するタスクフローがない場合は、選択画面から新規作成するか、タスクフローの作成を参照してください。目標タスクフローが一覧に表示されない場合は、更新してから再度選択できます。
- ノード名、実行モード、担当者などを入力し、ノードを作成してマウント をクリックして、現在のプランに関連付けられた オフライン同期プラン ノードを作成します。
- タスクフローへ移動 をクリックし、ノードと上流・下流の依存関係、およびスケジュール実行で使用するデータベース、テーブル、パーティション、スペースパラメータを確認します。
- ワークフロースケジュールの構成を完了して保存し、ワークフロー公開を行います。マウントに成功しても、ノードが公開されて稼働中になったことにはなりません。
プランをタスクフローにマウントした後は、プランの詳細ページから手動実行できません。タスクフローからそのノードを実行して検証してください。
タスクフローのマウント解除
- タスクフローがまだ公開されていない場合は、タスクフローの 開発モード で対応する オフライン同期プラン ノードを削除します。
- タスクフローが公開済みの場合は、先に 開発モード で対応するノードを削除してから、タスクフローを再公開する必要があります。これにより、本番環境でのそのノードのマウントを解除できます。
よくある質問
| 現象 | 確認事項 |
|---|---|
| 接続性テストに失敗する | サーバーアドレス、個別のポート、データベース、アカウントとパスワード、およびプラットフォームサーバーのネットワークアクセス範囲を確認してください |
| 接続できるが、テーブルが見つからない、またはプレビューできない | データベース名とテーブル名、メタデータ参照権限と読み取り権限、テーブルエンジンを選択できるかを確認してください。カスタムクエリでは、SQLのデータベースとフィールドタイプも確認する必要があります |
| シャードのスイッチを使用できない | Distributedテーブル、クラスターの internal_replication、認識可能なシャードフィールド、およびマッピングにその目標フィールドが含まれているかを確認してください |
| プレビューは正常だが、実行に失敗する | 本番環境の認証情報、目標への書き込み権限、データベースとテーブル、パーティション、パラメータ、および実際の実行ログを確認してください |
| 繰り返し実行した後に重複レコードが発生する | 追加書き込みの範囲と過去の実行結果を確認し、同じデータを繰り返し読み取って書き込んでいないか確認してください |

