Lakebase に接続する

Structured Streamingを使ってLakebaseや外部PostgreSQLデータベースに書き込み、組み込みのバッチ処理、自動再試行、ワークスペース管理認証機能を備えています。

Lakebase シンクを使用するタイミング

Lakebaseのシンクは、Lakebaseや外部PostgreSQLデータベースへの低遅延ストリーミング書き込みに使います。 このシンクでは、バッチ処理、接続管理、エラー処理を処理するためにカスタム foreach 関数を実装する必要はありません。

一般的なユース ケースは次のとおりです。

  • 運用ダッシュボードまたは顧客向けの機能のために、アプリケーション データベースをリアルタイムで更新します。
  • 集計されたストリーミング結果やフィルター処理されたストリーミング結果など、絶えず変化するデータをトランザクション データベースに同期します。
  • Structured Streaming クエリの出力を、クラシック コンピュートの リアルタイムモードで 数十ミリ秒単位のレイテンシで Lakebase テーブルに書き込む。

Lakebase から Lakehouse の Delta Lake テーブルにデータを同期するには、逆方向の「 Lakebase Change Data Feed」を参照してください。

要件

  • Databricks Runtime 18 LTS 以上
    • 外部PostgreSQL接続には Databricks Runtime 19 以上を使用し、 UC ComputeのカスタムJDBC プレビューにオプトインする必要があります。
    • インターバルデータ型は Databricks Runtime 19 以上を使う必要があります。
    • アップサートのマージ戦略は Databricks Runtime 19 以上を使う必要があります。
    • mergeSchema を使った加法的スキーマ進化には、Databricks Runtime 19 以降を使用する必要があります。
  • 専用または標準アクセスモードを備えたクラシックコンピュート、またはノートブックやジョブ向けのサーバーレスコンピュートなどがあります。 サーバーレス計算では Trigger.AvailableNow()を使いましょう。 サーバーレス コンピューティングでのストリーミングを参照してください。
  • Lakebase データベース、または外部 PostgreSQL データベースへの Unity Catalog 接続。

識別子の要件

すべてのターゲットに対して、Databricksはスキーマ、テーブル、カラム、プライマリーキーのカラム名(文字またはアンダースコアで始まり、文字、数字、アンダースコアのみを含む)を使用することを推奨しています。 シンクは自動的にLakebaseテーブルを作成することでこれらの要件を強制します。 これらの要件を満たさない識別子を使用するには、クエリを始める前にターゲットテーブルを作成してください。

データベースへの接続

Lakebase シンクでは、次の接続方法がサポートされています。

Unityカタログに登録されたLakebaseテーブル

Unity カタログに登録されている Lakebase テーブルの場合、コネクタは資格情報を自動的に管理し、クエリを実行しているユーザーまたはサービス プリンシパルの ID を使用します。 テーブルが存在しない場合は、コネクタによってテーブルが作成されます。

Lakebase データベースを Unity カタログに登録するには、「 Unity カタログに Lakebase データベースを登録する」を参照してください。

Lakebase テーブルに書き込むには、完全修飾テーブル名 catalog.schema.table を指定して .toTable() メソッドを使用します:

Python

(df.writeStream
  .outputMode("update")
  .option("upsertkey", "<primary-key-columns>")  # Optional
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .toTable("<catalog>.<schema>.<table>")
)

Scala

df.writeStream
  .outputMode("update")
  .option("upsertkey", "<primary-key-columns>")  // Optional
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .toTable("<catalog>.<schema>.<table>")

次のプレースホルダーを置き換えてください。

  • <catalog>.<schema>.<table>: ターゲットテーブルの完全修飾名。 catalogは、Lakebase データベースの登録時に作成した Unity カタログです。「Unity カタログに Lakebase データベースを登録する」を参照してください。 テーブルが存在しない場合は、コネクタによって作成されます。
  • <primary-key-columns>: オプション。 ターゲットテーブルの主キーのすべての列をカンマ区切られたリスト(例えば id や user_id,event_type)。 Upsertの行動を参照してください。
  • /Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>: クエリがチェックポイントを格納する Unity Catalog のボリュームパス。 クラウド オブジェクト ストレージ URI を使用することもできます。 場所は、ローカル ディスクではなく書き込み可能なストレージであり、各ストリーミング クエリに固有である必要があります。 これはターゲット テーブルに依存しません。 「構造化ストリーミング チェックポイント」を参照してください。

batchsizeやbatchintervalなどのオプション構成については、PostgreSQLのシンクオプションを参照してください。

Unityカタログに登録されていないLakebaseテーブル

Unity カタログに登録されていない Lakebase テーブルの場合、コネクタは資格情報を自動的に管理し、クエリを実行しているユーザーまたはサービス プリンシパルの ID を使用します。 テーブルが存在しない場合は、コネクタによってテーブルが作成されます。

Lakebaseテーブルに書き込みを行うには、 endpoint と dbtable オプションを使用します:

Python

(df.writeStream
  .format("postgresql")
  .outputMode("update")
  .option("endpoint", "<project-id>.<branch-id>.<endpoint-id>")
  .option("database", "<database>")  # Optional. Defaults to databricks_postgres.
  .option("dbtable", "<schema>.<table>")
  .option("upsertkey", "<primary-key-columns>")  # Optional
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .start()
)

Scala

df.writeStream
  .format("postgresql")
  .outputMode("update")
  .option("endpoint", "<project-id>.<branch-id>.<endpoint-id>")
  .option("database", "<database>")  // Optional. Defaults to databricks_postgres.
  .option("dbtable", "<schema>.<table>")
  .option("upsertkey", "<primary-key-columns>")  // Optional
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .start()

次のプレースホルダーを置き換えてください。

  • <project-id>.<branch-id>.<endpoint-id>:あなたのレイクベースのエンドポイント。 [コンピューティング] タブの [ID の取得] メニューの [リソース名] で 3 つの値をすべて検索します。このメニューの形式はprojects/<project-id>/branches/<branch-id>/endpoints/<endpoint-id>。 「 コンピューティング識別子」を参照してください。
  • <database>: オプション。 ターゲットとなるPostgreSQLデータベースの名前。 既定値は databricks_postgres です。 データベース の管理を参照してください。
  • <schema>.<table>: schema.table 形式のターゲットテーブル。 スキーマを省略すると、シンクは public スキーマを使用します。 自動テーブル作成には、文字または下線で始まり、文字、数字、アンダースコアのみを含む識別子を使用してください。
  • <primary-key-columns>: オプション。 ターゲットテーブルの主キーのすべての列をカンマ区切られたリスト(例えば id や user_id,event_type)。 Upsertの行動を参照してください。
  • /Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>: クエリがチェックポイントを格納する Unity Catalog のボリュームパス。 クラウド オブジェクト ストレージ URI を使用することもできます。 場所は、ローカル ディスクではなく書き込み可能なストレージであり、各ストリーミング クエリに固有である必要があります。 これはターゲット テーブルに依存しません。 「構造化ストリーミング チェックポイント」を参照してください。

batchsizeやbatchintervalなどのオプション構成については、PostgreSQLのシンクオプションを参照してください。

Unity Catalog認証情報を用いた外部PostgreSQL

Important

この機能は パブリック プレビュー段階です。 ワークスペース管理者は、PreviewsページからUC ComputeのカスタムJDBCへのアクセスを制御できます。 Manage Azure Databricks プレビューを参照してください。

コードに認証情報を保存せずに、Unity Catalog接続を使って外部PostgreSQLデータベースに認証してください。 ターゲットテーブルはすでに存在している必要があります。

タイプ POSTGRESQLの接続を作りましょう。 接続を作成 を参照してください。 クエリを実行するユーザーまたはサービスプリンシパルは接続に USE CONNECTION を持っている必要があります。

PostgreSQLテーブルに書き込みを行うには、 databricks.connection、 database、 dbtable のオプションをご利用ください:

Python

(df.writeStream
  .format("postgresql")
  .outputMode("update")
  .option("databricks.connection", "<connection-name>")
  .option("database", "<database>")
  .option("dbtable", "<schema>.<table>")
  .option("upsertkey", "<primary-key-columns>")  # Optional
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .start()
)

Scala

df.writeStream
  .format("postgresql")
  .outputMode("update")
  .option("databricks.connection", "<connection-name>")
  .option("database", "<database>")
  .option("dbtable", "<schema>.<table>")
  .option("upsertkey", "<primary-key-columns>")  // Optional
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .start()

次のプレースホルダーを置き換えてください。

  • <connection-name>Unity カタログ接続の名前です。
  • <database>: ターゲットとなるPostgreSQLデータベースの名前。
  • <schema>.<table>: schema.table形式の既存のターゲットテーブル。 スキーマを省略すると、シンクは public スキーマを使用します。
  • <primary-key-columns>: オプション。 ターゲットテーブルの主キーのすべての列をカンマ区切られたリスト(例えば id や user_id,event_type)。 Upsertの行動を参照してください。
  • /Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>: クエリがチェックポイントを格納する Unity Catalog のボリュームパス。 クラウド オブジェクト ストレージ URI を使用することもできます。 場所は、ローカル ディスクではなく書き込み可能なストレージであり、各ストリーミング クエリに固有である必要があります。 これはターゲット テーブルに依存しません。 「構造化ストリーミング チェックポイント」を参照してください。

PostgreSQLの接続はTLSを使用しています。 証明書の検証は、 接続を作成する際に選択するUnity Catalog接続の設定に従って行われます:

  • 信頼サーバー証明書:選択すると接続は sslmode=requireを使用し、サーバー証明書の検証なしに接続を暗号化します。
  • ユーザーが指定したサーバー証明書: sslmode=verify-full が選択されていない場合に を使用するため、PEM エンコードされたサーバー証明書を指定します。 証明書を提供しなければ、接続はJVMのデフォルトトラストストアで sslmode=verify-full を使用します。

設定オプション

シンクでは、認識できないオプション ( JDBC_STREAMING_SINK_INVALID_OPTIONS) のエラーが発生します。

シンクの設定オプション、共通オプションおよび各接続方法のオプションについては、 PostgreSQLのシンクオプションをご覧ください。

加法スキーマの進化

Databricks Runtime 19 以降では、既存の Lakebase テーブルまたは外部 PostgreSQL テーブルにない DataFrame 列を追加するには、ストリーミングライターで .toTable() または .option("mergeSchema", "true") の前に .start() を設定してください。 このオプションの既定値は false です。 これがない場合、新しい列を持つDataFrameが原因でクエリが失敗します。

シンクは、クエリの初期化時に新しい列がないか、データを書き込む前にチェックします。 更新されたDataFrameスキーマで、mergeSchema を有効にしてクエリを再開し、新しい列を追加します。 シンクは各バッチ境界でスキーマの変更をチェックしません。

新しい列は NULL 値を許容し、自動的に作成される Lakebase テーブルでは data type mappings が使用されます。 既存の行には追加された列に null 値が含まれています。 シンクが使用するデータベースIDには、ターゲットテーブルを変更する権限が必要です。 外部 PostgreSQL の場合、ターゲットテーブルはすでに存在している必要があります。

スキーマエボリューションはトップレベルの列のみを追加します。 列名を変更したり削除したり、既存の列タイプを変更したり、タイプを広げたりすることはありません。 これらの変更を行うには、クエリを停止し、自分でターゲットテーブルを変更し、互換性のある DataFrame スキーマでクエリを再開してください。

データ型マッピング

シンクは、各DataFrame列が対応するターゲット列と互換性があるかを確認し、既存のLakebaseや外部PostgreSQLテーブルに書き込みます。

以下の表は、Databricks Runtime 18 LTS以上でサポートされている型を示しています:

Spark の種類 自動生成のLakebaseテーブルタイプ 既存のPostgreSQLテーブルにおける互換性型
ByteType、ShortType smallint smallint
IntegerType integer integer
LongType bigint bigint
FloatType real real
DoubleType double precision double precision
DecimalType numeric numeric
StringType text varchar、text
VarcharType(n) varchar(n) varchar、text
CharType(n) char(n) char
BinaryType bytea bytea
BooleanType boolean boolean
TimestampType timestamptz timestamptz
TimestampNTZType timestamp timestamp
DateType date date
ArrayType、MapType、StructType、VariantType、NullType jsonb json、jsonb

以下の表は、Databricks Runtime 19以上でサポートされている型を示しています:

Spark の種類 自動生成のLakebaseテーブルタイプ 既存のPostgreSQLテーブルにおける互換性型
DayTimeIntervalType、YearMonthIntervalType interval interval

アップサートの挙動

upsertkeyオプションはターゲットテーブルの主キー列を識別します。 既存のテーブルの場合、 upsertkey の列はテーブルの主キーと正確に一致しなければなりません。 オプションを省略すると、シンクはテーブルから主キーを読み取ります。 シンクが作成するLakebaseテーブルの場合、 upsertkey がプライマリキーを定義します。 オプションを省略すると、シンクは主キーのないテーブルを作成します。

ターゲットテーブルに主キーがある場合、シンクはPostgreSQLの文法でアップサート INSERT INTO ... ON CONFLICT (<primary_key_columns>) DO UPDATE SET ... します。 ターゲットテーブルにプライマリキーがない場合、シンクはインサートを実行します。 クエリの出力モードはこの挙動に影響を与えません。

すべての主キー列はDataFrameに存在し、数値型や文字列型などの比較可能な型を使用する必要があります。

アップサートが非プライマリーキー列を更新する方法を制御するには、「 アップサートのマージ戦略」を参照してください。

アップサートのマージ戦略

Databricks Runtime 19以降では、行同士が同じプライマリキーを持つ場合、シンクが非プライマリーキーの列をどのように更新するかをマージ戦略で制御できます。 例えば、最も大きなタイムスタンプを保持したり、受信イベントの順序値がより新しい場合にのみ列を更新したりできます。

マージ戦略はアップサートにのみ適用されます。 ターゲットテーブルにプライマリキーがない場合は、 upsert.mergeStrategies や upsert.defaultMergeStrategy を設定するとエラーが発生します。 戦略は主キーでない列にのみ割り当てることができます。 upsert.mergeStrategiesをcolumn:strategy形式のカンマ区切りリストに設定してください。 明示的な戦略がない列に対するデフォルトを設定するには、upsert.defaultMergeStrategyを設定してください。 デフォルトでは、シンクは latest 戦略を使います。

サポートされているマージ戦略

Strategy Behavior
latest 到着順で最新の値を使いましょう。 これが既定値です。
earliest 到着順で最も早い値を使用します。
latestNonNull 到着順に最新のnullでない値を使用してください。
earliestNonNull 到着順序による最も早い非null値を使用します。
greatest 既存の値と入力値のうち、大きい方を採用します。 nullの値は無視されるため、nullの入ってきた値は既存の値を置き換えません。
least 既存の値と入力値の中から小さい方を使いましょう。 nullの値は無視されるため、nullの入ってきた値は既存の値を置き換えません。
latestBy(column) 指定された並び替え列で最大値を持つ行の値を使用します。 latestByとearliestByが同点やヌルをどう扱っているかをご覧ください。
earliestBy(column) 指定された順序列の値が最も小さい行の値を使用します。 latestByとearliestByが同点やヌルをどう扱っているかをご覧ください。

latestByとearliestByは同点やヌルをどう扱うか

latestBy(column) earliestBy(column)、入力される順序値とテーブルに既に保存されている値を比較して値を選びます。 その保存値を正確に保つためには、ソートに使用する列で、upsert.mergeStrategies または upsert.defaultMergeStrategy を通じて、一致する戦略を使用する必要があります:

  • latestBy(column)の場合、順序列はgreatestを使わなければなりません。
  • earliestBy(column)の場合、順序列はleastを使わなければなりません。

たとえば、is_success:latestBy(last_updated_at) には last_updated_at:greatest が必要です。

両方の順序値がnullでない場合、 latestBy(column) は入力順序値が既存の順序値より厳密に大きい(>)場合のみ列を更新します。 earliestBy(column)の場合、それは厳密に小さい(<)でなければなりません。 両方の戦略において、順序値が等しい場合、シンクは列の既存の値を保持します。 1つのバッチ内で、複数の行が同じプライマリキーと順序値を持つ場合、シンクは最初に受け取った行を保持します。

例えば、 is_success が latestBy(last_updated_at) を使い、入ってくる行が既存の行と同じ last_updated_at を持つ場合、入ってくる値が異なってもシンクは既存の is_successを保持します。

どちらの戦略でも、NULL ではない順序付け値がNULL 値より優先されます。 nullでない順序値を持つ入力行は、順序値がnullである既存の値を置き換えます。 nullの順序値を持つ受信行は、既存の値を置き換えません。既存の順序値もnullの場合を含めてです。

例: カスタム アップサート ロジックをモデル化する

列 id、 last_updated_at、 creation_date、 is_successの列を持つ表を考えます。 次のような論理を表現したいかもしれません:

INSERT INTO events ...
ON CONFLICT (id) DO UPDATE
SET
  -- Keep the most recent timestamp.
  last_updated_at = GREATEST(events.last_updated_at, EXCLUDED.last_updated_at),

  -- Keep the earliest non-null creation date.
  creation_date = COALESCE(events.creation_date, EXCLUDED.creation_date),

  -- Keep the value of is_success from the event with the most recent last_updated_at.
  is_success = CASE
    WHEN EXCLUDED.last_updated_at IS NOT NULL
      AND (events.last_updated_at IS NULL
        OR EXCLUDED.last_updated_at > events.last_updated_at)
    THEN EXCLUDED.is_success
    ELSE events.is_success
  END;

この論理をモデル化するために、以下のマージ戦略を用いてください。

Python

(df.writeStream
  .format("postgresql")
  .outputMode("update")
  .option("databricks.connection", "<connection-name>")
  .option("database", "<database>")
  .option("dbtable", "<schema>.<table>")
  .option("upsertkey", "id")
  .option("upsert.mergeStrategies", "last_updated_at:greatest,creation_date:earliestNonNull,is_success:latestBy(last_updated_at)")
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .start()
)

Scala

df.writeStream
  .format("postgresql")
  .outputMode("update")
  .option("databricks.connection", "<connection-name>")
  .option("database", "<database>")
  .option("dbtable", "<schema>.<table>")
  .option("upsertkey", "id")
  .option("upsert.mergeStrategies", "last_updated_at:greatest,creation_date:earliestNonNull,is_success:latestBy(last_updated_at)")
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .start()

パラメータ化されたデフォルトのマージ戦略

Databricks Runtime 19 以降では、upsert.defaultMergeStrategy も latestBy(column) と earliestBy(column) を受け付けます。 これらのデフォルトを使用して、主キー以外の列にも同じ順序ルールを適用し、各列を upsert.mergeStrategiesに表示しません。 明示的な列ごとの戦略はデフォルトを上書きしますが、以下に説明する順序列は例外です。

デフォルトが latestBy(column)の場合、シンクは自動的に順序列に greatest を適用します。 デフォルトが earliestBy(column)の場合、自動的に leastが適用されます。 順序列に戦略を明示的に割り当てる場合、それは必要な greatest または least 戦略に一致している必要があります。

次の例では、他のすべての非主キー列の値を選択するために last_updated_at を使用します。

Python

(df.writeStream
  .format("postgresql")
  .outputMode("update")
  .option("databricks.connection", "<connection-name>")
  .option("database", "<database>")
  .option("dbtable", "<schema>.<table>")
  .option("upsertkey", "id")
  .option("upsert.defaultMergeStrategy", "latestBy(last_updated_at)")
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .start()
)

Scala

df.writeStream
  .format("postgresql")
  .outputMode("update")
  .option("databricks.connection", "<connection-name>")
  .option("database", "<database>")
  .option("dbtable", "<schema>.<table>")
  .option("upsertkey", "id")
  .option("upsert.defaultMergeStrategy", "latestBy(last_updated_at)")
  .option("checkpointLocation", "/Volumes/<catalog>/<schema>/<volume>/<checkpoint-name>")
  .start()

パフォーマンスチューニング

バッチ処理とバックプレッシャ

いずれかの条件が満たされると、フラッシュがトリガーされます。

  • バッファーは batchsize 行に達し、既定では 1000 に達します。
  • バッファーの有効期間が batchinterval を超えています。既定では 100 milliseconds。

データベースが受信データ レートに対応できない場合、シンクはバックプレッシャをソースにアップストリームに伝達します。

待機時間とスループットのガイダンス:

  • リアルタイム モードの待機時間が短いワークロードの場合は、フラッシュ前の最大時間を短くするために batchinterval を減らします。 概念についてはリアルタイム モードの概念 、コード例については リアルタイムモードの例 を参照してください。
  • 高スループットのワークロードの場合は、各トランザクションのオーバーヘッドを減らすために batchsize を増やします。

接続の動作

シンクは Executor 上で接続プーリングを使用します。 既定では、各タスクは 1 つのデータベース接続を使用します。

Databricks では、接続ごとに既定値の 1 タスクを使用することをお勧めします。 接続ごとにタスクの数を増やすと、接続の競合が発生し、高スループット接続の待機時間が長くなる可能性があります。

接続に対するタスクの比率を構成するには、 spark.databricks.sql.streaming.jdbc.tasksPerConnection Spark 構成を設定します。 ターゲット データベースの接続制限が低い場合は、シャッフル パーティションの数を減らすか、 spark.databricks.sql.streaming.jdbc.tasksPerConnectionを増やします。

シンクは、接続エラー、デッドロック、レート制限など、一時的な JDBC エラーを自動的に再試行します。 シンクがすべての再試行を使い果たした場合、クエリは失敗します。

サポートされているトリガーと出力モード

Triggers

この表は、クラシックおよびサーバーレスコンピュートにおける構造化ストリーミングトリガータイプのサポートを示しています:

トリガー クラシック コンピューティング サーバーレスコンピュート(ノートブックとジョブ)
RealTime Yes No
ProcessingTime Yes No
AvailableNow Yes Yes
Once Yes. Deprecated. AvailableNow を使用してください。 Yes. Deprecated. AvailableNow を使用してください。

出力モード

次の表は、構造化ストリーミング出力モードのサポートを示しています。

出力モード Supported
update Yes
append Yes. 動作は、 updateと同じです。 ターゲット テーブルに主キーがある場合はクエリがアップサートされ、それ以外の場合はクエリが挿入されます。 Upsertの行動を参照してください。
complete No

制限事項

  • Unityカタログ接続を介して接続された外部PostgreSQLデータベースの場合、ターゲットテーブルはすでに存在している必要があります。 シンクはLakebaseでのみ自動的に欠落テーブルを生成します。
  • レイクフローパイプラインはサポートされていません。