Databricksデータソースの構成
Databricksデータソースは、オフライン同期でDatabricksとプラットフォームのプリセットデータウェアハウスの間でテーブルデータを転送するために使用します。このドキュメントでは、Databricks-JDBCの接続設定、読み取り元とデータの流向の設定、対応するフィールドタイプ、同期の検証、ワークフロースケジュールについて説明します。
使用制限と事前準備
構成を始める前に、以下の事項を確認してください。
- Databricks → プリセットデータウェアハウス と プリセットデータウェアハウス → Databricks をサポートしています。このプランでは、Databricksと他の外部データソースとの直接同期はサポートしていません。
- DatabricksでJDBC接続に使用できるコンピューティングリソースを用意し、対応する JDBC URL と Personal Access Token を取得してください。接続情報は、実際に使用するコンピューティングリソース、ワークスペース、ドライバー構成と一致している必要があります。DatabricksのJDBC接続に関する説明を参照してください。
- Tokenを所有するアカウントには、対象のコンピューティングリソースを使用し、Catalogとデータベース(Schema)にアクセスしてテーブルのメタデータを参照する権限が必要です。読み取り元テーブルには読み取り権限、目標テーブルへの書き込みには該当する書き込み権限が必要です。Databricks管理者が実際の使用範囲に応じて権限を付与してください。
- プラットフォームの実行環境から、JDBC URLに対応するサービスへアクセスできる必要があります。Databricksにネットワークアクセス制限を設定している場合は、プラットフォームサーバーの実際の送信元アドレスと、アクセスを許可する範囲を確認してください。
- 目標テーブルを事前に用意し、フィールドタイプとパーティション定義を確認してください。プリセットデータウェアハウスの目標テーブルの作成方法は、スペーステーブルの作成と管理を参照してください。Databricksの目標テーブルは、目標Catalogとデータベースに事前に用意する必要があります。
| 環境の構成方法 | 設定要件 |
|---|---|
| 環境を区別しない | 開発環境と本番環境で、同じ接続情報と認証情報の構成を使用します |
| 独立環境構成 | 開発環境と本番環境を個別に構成します。両方の構成で、プランが選択するテーブルにアクセスできる必要があります |
データプレビューは開発環境の構成を使用し、手動実行は本番環境の構成を使用します。それぞれの構成のコンピューティングリソース、テーブル権限、ネットワークアクセスを確認してください。
Databricks接続情報の取得
- Databricksワークスペースにログインし、接続するコンピューティングリソースを開きます。クラスターの場合は Compute > 対象クラスター > Configuration > Advanced options > JDBC/ODBC で、SQLウェアハウスの場合は SQL Warehouses > 対象ウェアハウス > Connection details で接続情報を確認できます。
- JDBC URLを取得し、その中のサーバーホスト、ポート、HTTP Pathを確認して、意図したコンピューティングリソースを指していることを確認します。具体的な操作箇所は、DatabricksのJDBC接続に関する説明を参照してください。
- 対象ワークスペースで使用できるPATを用意します。新規作成する場合は、Settings > Developer > Access tokens > Manage で生成し、適切な有効期間を設定してください。作成または使用できない場合は、ワークスペース管理者に連絡してください。操作方法は、Databricks個人用アクセストークンの作成を参照してください。
Tokenは安全な方法で受け渡し、スクリーンショット、ログ、公開ドキュメントに認証情報を記載しないでください。Tokenを変更した場合や権限を調整した場合は、データソース接続と同期プランを再度検証してください。
Databricksデータソースの作成
- データ開発プラットフォーム > 連携 > データソース に移動し、+ データソース をクリックします。
- Databricks-JDBC を選択して 次へ をクリックし、データソース名と備考を入力します。
- 環境を区別しない または 独立環境構成 を選択します。独立環境構成では、開発環境と本番環境の情報をそれぞれ入力する必要があります。
- 以下の接続パラメータを入力します。接続性テスト で テスト をクリックし、テストに成功したことを確認してから 完了 をクリックします。
| 構成項目 | 説明 |
|---|---|
| JDBC URL | Databricksコンピューティングリソースに対応するJDBC接続先です。サービスアドレスと接続パラメータを管理者に確認してください |
| 認証メカニズム | PAT を選択します |
| Personal Access Token | 接続用アカウントの有効なTokenを入力します。今回の読み取りまたは書き込みに必要な権限が必要です |
| 高度な構成 | 必要に応じてJSON形式の拡張構成を入力します。追加の構成要件がなければ空欄にできます |
接続性テストに成功した後も、同期プランでテーブルを読み込み、ソースデータをプレビューして実行検証を行い、実際のテーブル権限と読み取り・書き込み結果を確認する必要があります。
Databricks読み取り元の構成
- データ開発プラットフォーム > 連携 > オフライン同期 に移動し、+ 統合プラン をクリックします。
- データソース で Databricks-JDBC と作成済みのデータソースを選択します。
- データ取得方法 を選択し、テーブル全体の読み取りまたはカスタムクエリで読み取り元を構成します。
- データプレビュー をクリックし、ソースフィールド、実際の値、読み取り範囲を確認します。
- バッチサイズを調整する場合は、高度な構成 を展開して構成します。
図は既存プランの構成例であり、現在の接続やデータ読み取りの検証に代わるものではありません。構成後は、データプレビューで実際の結果を確認してください。
| データ取得方法 | 構成方法 |
|---|---|
| テーブル全体 | Catalog、データベース(Schema)、データテーブルの順に選択します。一部のデータのみ読み取る場合は、データフィルター を有効にしてフィルター条件を入力します |
| カスタムクエリ | 同期対象フィールドを返す読み取り専用のクエリSQLを入力し、絞り込み条件をクエリ内に記述します。この方法では、テーブル全体の読み取りに使用するCatalog、データベース、データテーブルの選択項目やデータフィルターを個別に構成しません |
テーブル全体の読み取りにおけるデータフィルターは、読み取り範囲を限定します。エディターの WHERE 句に従って、例えば WHERE status = 'active' と入力し、完全な SELECT クエリは入力しないでください。カスタムクエリでは、SQLが正しいCatalogとデータベースにアクセスでき、返されるフィールド名が明確で、タイプを認識できることを確認してください。
バッチサイズ のデフォルト値は 1000、設定可能な範囲は 1000–10000 です。データソース、データ取得方法、Catalog、データベース、データテーブルを切り替えた後は、読み取り範囲、プレビュー結果、フィールドマッピングを再確認してください。ソースの構造やクエリ結果が変わった場合も、再解析してマッピングを確認する必要があります。
データの流向の構成
Databricksからプリセットデータウェアハウスへの読み取り
データの流向 でプラットフォームの プリセットデータウェアハウス を選択し、目標スペーステーブルを選択します。目標テーブルをまだ作成していない場合は、先に ライブラリテーブル に移動し、必要なフィールドとパーティション定義で作成してください。スペーステーブルの作成と管理を参照してください。
| 構成項目 | 説明 |
|---|---|
| 目標テーブル | 今回のデータを受け取るプリセットデータウェアハウス内のスペーステーブル |
| パーティション情報 | 目標がパーティションテーブルの場合は、そのテーブルの要件に従って各パーティション値を入力します。スペースパラメータを使用して実行時のパーティションを構成することもできます |
| 書き込みモード | 目標データの保持要件に応じて 新しいデータを挿入 または 上書き書き込み を選択し、実行前に目標テーブルと目標パーティションを再確認してください |
プリセットデータウェアハウスからDatabricksへの書き込み
データソース でプリセットデータウェアハウスのソーステーブルを構成し、データの流向 で Databricks-JDBC と作成済みのデータソースを選択します。目標Catalog、データベース(Schema)、データテーブルの順に選択します。
| 構成項目 | 説明 |
|---|---|
| テーブル書き込み | Databricksに用意済みで、接続用アカウントに書き込み権限がある目標テーブル |
| パーティション情報 | 目標パーティションフィールドが表示される場合は、すべてのパーティション値を入力し、実行時の実際の値を確認する必要があります |
| 書き込みモード | 新しいデータを挿入 のみをサポートし、目標テーブルにデータを追加します。再実行する前に、重複レコードが発生しないか評価してください |
| 前処理文 | 必要に応じて、同期開始前に目標側で実行するSQLを入力します。必要がなければ空欄にできます |
| バッチサイズ | 高度な構成 にあり、デフォルト値は 5000、設定可能な範囲は 1–10000 です |
前処理文は目標側で実際に実行されます。実行に失敗した場合、今回の同期の送信は続行されません。前処理文とその後のデータ書き込みが同一トランザクション内で実行される保証はなく、その後の同期に失敗しても、実行済みの前処理文が自動的に取り消されるとは限りません。入力または再試行する前に、目標環境、SQLによるデータへの影響、繰り返し実行した場合の結果を確認してください。
Databricksへの書き込みモードは追加であり、標準の上書きや更新挿入モードは提供していません。前処理の削除文と追加書き込みを、全体をロールバックできる上書き操作として扱わないでください。
フィールドマッピングと対応するフィールドタイプ
読み取り元とデータの流向の構成後、フィールドマッピング でソースフィールドと目標フィールドの対応関係を設定します。個別に選択するか、同名マッピング または 同じ行のマッピング を使用してから各項目を確認できます。1つの目標フィールドに対応付けられるソースフィールドは1つだけです。
図は既存のプランにおけるフィールドの対応関係を示しており、現在の接続性や今回の実行が検証済みであることを意味するものではありません。
読み取りに対応するフィールドタイプ
Databricksをデータの読み取り元として使用する場合、以下のフィールドタイプに対応しています。タイプ名では大文字と小文字を区別しません。パラメーター付きのフィールドや入れ子構造を持つフィールドは、完全な定義も確認する必要があります。
| タイプの分類 | 対応するDatabricksのフィールドタイプ |
|---|---|
| ブール値 | boolean |
| 整数 | tinyint、smallint、int、integer、bigint |
| 浮動小数点数と固定小数点数 | float、double、decimal |
| 文字列 | string、varchar、char |
| 日付と時刻 | date、timestamp、timestamp_ntz |
| 複合タイプ | array、map、struct。完全な構造を確認する必要があります |
binary、およびinterval、void、variantなどの記載のないタイプや、その他の認識できないタイプには対応していません。
書き込みに対応するフィールドタイプ
Databricksをデータの流向として使用する場合、対応するDatabricksのフィールドタイプは上表と同じです。binary、記載のないタイプ、その他の認識できないタイプには対応していません。
目標テーブルは事前に作成する必要があります。フィールドタイプに対応していても、任意のデータが目標フィールドの完全な定義やNULL制約を満たすとは限りません。
フィールドタイプの使用上の制限
decimal(p,s)、varchar(n)、char(n)は、完全な精度、小数点以下の桁数、長さの要件を確認してください。timestamp、timestamp_ntzは、実際の時刻の意味、タイムゾーン、精度の要件を確認してください。タイプ名だけで結果が要件を満たすと判断しないでください。array<T>、map<K,V>、struct<...>は、要素、キーと値、フィールドの定義を確認してください。フィールド名と順序、NULL制約、入れ子の深さも確認が必要です。最上位のタイプに対応していても、任意の内部構造に対応しているわけではありません。たとえば、arrayに対応しているという理由だけで、array<binary>にも対応していると判断しないでください。- ソーステーブルまたは目標テーブルの構造を変更した後は、フィールドを再解析して対応関係を確認してください。データプレビューにフィールドが表示されても、そのフィールドタイプで同期できるとは限りません。
保存、検証、ワークフロースケジュール
同期結果の保存と検証
- ソーステーブルまたはクエリ、フィルター範囲、目標テーブルとパーティション、書き込みモード、前処理文、フィールドマッピングを確認します。まず読み取り元の データプレビュー でフィールドとサンプル値を確認します。
- プラン名、担当者、備考を入力し、保存 をクリックします。
- 手動実行 をクリックし、ポップアップに従って実行モードを選択します。今回のパラメータ値を確認してから実行を開始します。手動実行は 本番環境の構成 を使用し、実行モードは開発環境と本番環境の切り替えには使用しません。
- 手動実行記録 でステータスとログを確認します。タスクが正常に完了したら、目標テーブルでデータ量、フィールドの対応関係、および数値、時刻、複合タイプ、NULL値などのサンプルを確認します。
独立環境構成では、開発環境でデータを読み込んだりプレビューしたりできても、本番環境の認証情報や読み取り・書き込み権限が用意されているとは限りません。初回実行前に、両方の構成と、目標環境内のテーブル、パーティション、パラメータをそれぞれ確認してください。Databricksへの追加書き込みや前処理文を構成する場合は、再試行が既存データに与える影響も評価する必要があります。
タスクフローへのマウント
手動での検証に合格したら、プランをタスクフローにマウントし、スケジュール周期に従って実行できます。
- 保存済みのプランを開き、ジョブフローにマウントする をクリックして、目標タスクフローを選択します。まだ作成していない場合は、タスクフローの作成を参照してください。
- ノード名、実行モード、担当者などを入力し、ノードを作成してマウント をクリックします。
- タスクフローへ移動 をクリックし、ノードと上流・下流の依存関係、およびスケジュール実行で使用するテーブル、パーティション、スペースパラメータを確認します。
- ワークフロースケジュールの構成を完了して保存し、ワークフロー公開を行います。マウントに成功しても、ノードが公開されて稼働中になったことにはなりません。
プランをタスクフローにマウントした後は、プランの詳細ページから手動実行できません。タスクフローからそのノードを実行して検証してください。
よくある質問
| 現象 | 確認事項 |
|---|---|
| 接続性テストに失敗する | JDBC URL、PATの有効性、コンピューティングリソースへのアクセス権限、プラットフォームサーバーのネットワークアクセス範囲を確認してください |
| 接続できるが、テーブルが見つからない、またはプレビューできない | Catalog、データベース、テーブル名、メタデータ参照権限と読み取り権限を確認してください。カスタムクエリでは、SQLとその参照範囲も確認する必要があります |
| プレビューは正常だが、実行に失敗する | 本番環境の認証情報、目標への書き込み権限、テーブルとパーティション、パラメータ、前処理文を確認し、実行ログを参照してください |
| 再実行後に重複データが発生する | 追加書き込みの範囲と過去の実行結果を確認し、同じデータを繰り返し読み取って書き込んでいないか確認してください |

