Databricks Connect for Python をインストールする

[アーティクル]
11/05/2024

Note

この記事では、Databricks Runtime 13.3 LTS 以降用の Databricks Connect について説明します。

この記事では、Databricks Connect for Python をインストールする方法について説明します。「Databricks Connect とは」を参照してください。この記事の Scala バージョンについては、「Databricks Connect for Scala をインストールする」を参照してください。

要件

Databricks Connect for Python をインストールするには、次の要件を満たす必要があります。

サーバーレスコンピューティングに接続する場合は、ワークスペースがサーバーレスコンピューティングの要件を満たしている必要があります。

Note

サーバーレスコンピューティングは、Databricks Connect バージョン 15.1 以降でサポートされています。さらに、サーバーレス上の Databricks Runtime リリース以下の Databricks Connect バージョンは完全に互換性があります。「リリースノート」を参照してください。 Databricks Connect バージョンがサーバーレスコンピューティングと互換性があるかどうかを確認するには、「Databricks への接続を検証する」を参照してください。
クラスターに接続する場合は、ターゲットクラスターが、Databricks Runtime のバージョン要件を含むクラスター構成要件を満たしている必要があります。

開発用コンピューターに Python 3 がインストールされていて、開発用コンピューターにインストールされている Python のマイナーバージョンが、次の表のバージョン要件を満たしている必要があります。

コンピューティングの種類	Databricks Connect バージョン	互換性のある Python バージョン
サーバーレス	15.1 以降	3.11
クラスター	15.1 以降	3.11
クラスター	13.3 LTS から 14.3 LTS	3.10

PySpark UDF を使用する場合は、開発用コンピューターにインストールされている Python のマイナーバージョンが、クラスターまたはサーバーレスコンピューティングにインストールされている Databricks Runtime に含まれる Python のマイナーバージョンと一致している必要があります。お使いのクラスターのマイナー Python バージョンを確認するには、クラスターまたはサーバーレスコンピューティングの Databricks Runtime リリースノートの「システム環境」セクションを参照してください。「Databricks Runtime リリースノートのバージョンと互換性」と「サーバーレスコンピューティングのリリースノート」を参照してください。

Python 仮想環境をアクティブ化する

Databricks では、Databricks Connect で使用する Python バージョンごとに Python "仮想環境" をアクティブにすることを強く推奨しています。 Python 仮想環境は、正しいバージョンの Python と Databricks Connect を一緒に使用していることを確認するのに役立ちます。これらのツールとそのアクティブ化方法の詳細については、venv または Poetry に関するページを参照してください。

Databricks Connect クライアントをインストールする

このセクションでは、venv または Poetry を使って Databricks Connect クライアントをインストールする方法について説明します。

Note

Visual Studio Code 用の Databricks 拡張機能が既にインストールされている場合は、これらのセットアップ手順に従う必要はありません。Visual Studio Code 用の Databricks 拡張機能には、Databricks Runtime 13.3 LTS 以降用の Databricks Connect のサポートが既に組み込まれているためです。「Visual Studio Code の Databricks 拡張機能に Databricks Connect を使用したデバッグコード」へスキップしてください。

venv を使って Databricks Connect クライアントをインストールする

仮想環境がアクティブな状態で、uninstall コマンドを実行して PySpark をアンインストールします (既にインストールされている場合)。これは、databricks-connect パッケージが PySpark と競合するために必要です。詳細については、「PySpark インストールの競合」を参照してください。 PySpark が既にインストールされているかどうかを調べるには、show コマンドを実行します。
```
# Is PySpark already installed?
pip3 show pyspark

# Uninstall PySpark
pip3 uninstall pyspark
```
仮想環境がアクティブな状態のままで、install コマンドを実行して Databricks Connect クライアントをインストールします。 --upgrade オプションを使用して、既存のクライアントインストールを指定したバージョンにアップグレードします。
```
pip3 install --upgrade "databricks-connect==15.4.*"  # Or X.Y.* to match your cluster version.
```
注意

Databricks では、最新のパッケージがインストールされるように、databricks-connect=X.Y ではなく databricks-connect==X.Y.* を指定する "ドットとアスタリスク" の表記を追加することをお勧めします。これは要件ではありませんが、そのクラスターでサポートされている最新の機能を使用できるようにするのに役立ちます。

スキップして「接続プロパティを構成する」に進んでください。

Poetry を使って Databricks Connect クライアントをインストールする

仮想環境がアクティブな状態で、remove コマンドを実行して PySpark をアンインストールします (既にインストールされている場合)。これは、databricks-connect パッケージが PySpark と競合するために必要です。詳細については、「PySpark インストールの競合」を参照してください。 PySpark が既にインストールされているかどうかを調べるには、show コマンドを実行します。
```
# Is PySpark already installed?
poetry show pyspark

# Uninstall PySpark
poetry remove pyspark
```
仮想環境がアクティブな状態のままで、add コマンドを実行して Databricks Connect クライアントをインストールします。
```
poetry add databricks-connect@~15.4  # Or X.Y to match your cluster version.
```
Note

Databricks では、最新のパッケージがインストールされるように、databricks-connect==15.4 ではなく databricks-connect@~15.4 を指定する "アットとチルダ" の表記を使うことをお勧めします。これは要件ではありませんが、そのクラスターでサポートされている最新の機能を使用できるようにするのに役立ちます。

接続プロパティを構成する

このセクションでは、Databricks Connect と Azure Databricks クラスターまたはサーバーレスコンピューティング間の接続を確立するようにプロパティを構成します。これには、次のものが含まれます。

Azure Databricks ワークスペースのインスタンス名。これは、お使いのコンピューティングの [サーバーホスト名] の値です。「Azure Databricks コンピューティングリソースの接続の詳細を取得する」を参照してください。
使用する Databricks 認証の種類に必要なその他のプロパティ。

Note

OAuth ユーザー対マシン (U2M) 認証は、Databricks SDK for Python 0.19.0 以降でサポートされています。 OAuth U2M 認証を使用するには、コードプロジェクトのインストールされているバージョンの Databricks SDK for Python を 0.19.0 以上に更新する必要がある場合があります。「Databricks SDK for Python を使ってみる」を参照してください。

OAuth U2M 認証の場合は、Python コードを実行する前に Databricks CLI を使用して認証する必要があります。「チュートリアル」を参照してください。
OAuth マシン間 (M2M) 認証 OAuth マシン間 (M2M) 認証は、Databricks SDK for Python 0.18.0 以降でサポートされています。 OAuth M2M 認証を使用するには、コードプロジェクトのインストールされている Databricks SDK for Python のバージョンを 0.18.0 以上に更新する必要がある場合があります。「Databricks SDK for Python を使ってみる」を参照してください。
Databricks SDK for Python では、まだ Azure マネージド ID 認証が実装されていません。

クラスターへの接続を構成する

クラスターへの接続を構成するには、クラスターの ID が必要です。クラスター ID は URL から取得できます。「クラスター URL と ID」を参照してください。

クラスターへの接続は、次のいずれかの方法で構成できます。 Databricks Connect では、次の順序で構成プロパティが検索され、最初に見つかった構成が使用されます。詳細な構成については、「Databricks Connect for Python の高度な使用方法」を参照してください。

DatabricksSession クラスの remote() メソッド。
Databricks の構成プロファイル
DATABRICKS_CONFIG_PROFILE 環境変数
各構成プロパティの環境変数
DEFAULT という名前の Databricks 構成プロファイル

`DatabricksSession` クラスの `remote()` メソッド

Azure Databricks 個人用アクセストークン認証にのみ適用されるこのオプション用に、ワークスペースインスタンス名、Azure Databricks 個人用アクセストークン、およびクラスターの ID を指定します。

次のように、いくつかの方法で DatabricksSession クラスを初期化できます。

DatabricksSession.builder.remote() で、host、token、cluster_id フィールドを設定します。
Databricks SDK の Config クラスを使用します。
cluster_id フィールドと共に Databricks 構成プロファイルを指定します。
DatabricksSession.builder.remote() で Spark Connect 接続文字列を設定します。

Databricks では、コードでこれらの接続プロパティを指定する代わりに、このセクション全体で説明されているように、環境変数または構成ファイルを使用してプロパティを構成することをお勧めします。以下のコード例では、ユーザーまたはその他の構成ストア (Azure KeyVault など) から必要なプロパティを取得するために、提案された retrieve_* 関数の実装を提供することが想定されています。

これらの各方法のコードは次のとおりです。

# Set the host, token, and cluster_id fields in DatabricksSession.builder.remote.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.remote(
   host       = f"https://{retrieve_workspace_instance_name()}",
   token      = retrieve_token(),
   cluster_id = retrieve_cluster_id()
).getOrCreate()

# Use the Databricks SDK's Config class.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   host       = f"https://{retrieve_workspace_instance_name()}",
   token      = retrieve_token(),
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

# Specify a Databricks configuration profile along with the `cluster_id` field.
# If you have already set the DATABRICKS_CLUSTER_ID environment variable with the
# cluster's ID, you do not also need to set the cluster_id field here.
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   profile    = "<profile-name>",
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

Azure Databricks の構成プロファイル

このオプションでは、cluster_id フィールドおよび、使用する Databricks 認証の種類に必要なその他のフィールドが含まれた Azure Databricks 構成プロファイルを作成または指定します。

各認証タイプに必要な構成プロファイルフィールドは次のとおりです。

Azure Databricks 個人用アクセストークン認証の場合: host と token。
OAuth マシン間 (M2M) 認証の場合 (サポートされている場合): host、client_id、client_secret。
OAuth ユーザー対マシン (U2M) 認証の場合 (サポートされている場合): host。
Microsoft Entra ID (旧称 Azure Active Directory) サービスプリンシパル認証の場合: host、azure_tenant_id、azure_client_id、azure_client_secret、場合によっては azure_workspace_resource_id。
Azure CLI 認証の場合: host。
Azure マネージド ID 認証の場合 (サポートされている場合): host、azure_use_msi、azure_client_id、場合によっては azure_workspace_resource_id。

次に、Config クラスを使用して、この構成プロファイルの名前を設定します。

次のように、いくつかの方法で cluster_id を指定できます。

構成プロファイルに cluster_id フィールドを含め、その後構成プロファイルの名前のみを指定します。
cluster_id フィールドと共に構成プロファイル名を指定します。

クラスターの ID を使用して DATABRICKS_CLUSTER_ID 環境変数を既に設定している場合は、cluster_id を指定する必要はありません。

これらの各方法のコードは次のとおりです。

# Include the cluster_id field in your configuration profile, and then
# just specify the configuration profile's name:
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.profile("<profile-name>").getOrCreate()

# Specify the configuration profile name along with the cluster_id field.
# In this example, retrieve_cluster_id() assumes some custom implementation that
# you provide to get the cluster ID from the user or from some other
# configuration store:
from databricks.connect import DatabricksSession
from databricks.sdk.core import Config

config = Config(
   profile    = "<profile-name>",
   cluster_id = retrieve_cluster_id()
)

spark = DatabricksSession.builder.sdkConfig(config).getOrCreate()

`DATABRICKS_CONFIG_PROFILE` 環境変数

クラスターの ID を使用して DATABRICKS_CLUSTER_ID 環境変数を既に設定している場合は、cluster_id を指定する必要はありません。

各認証タイプに必要な構成プロファイルフィールドは次のとおりです。

Azure Databricks 個人用アクセストークン認証の場合: host と token。
OAuth マシン間 (M2M) 認証の場合 (サポートされている場合): host、client_id、client_secret。
OAuth ユーザー対マシン (U2M) 認証の場合 (サポートされている場合): host。
Microsoft Entra ID (旧称 Azure Active Directory) サービスプリンシパル認証の場合: host、azure_tenant_id、azure_client_id、azure_client_secret、場合によっては azure_workspace_resource_id。
Azure CLI 認証の場合: host。
Azure マネージド ID 認証の場合 (サポートされている場合): host、azure_use_msi、azure_client_id、場合によっては azure_workspace_resource_id。

次に、DATABRICKS_CONFIG_PROFILE 環境変数をこの構成プロファイルの名前に設定します。次に、DatabricksSession クラスを次のように初期化します。

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

各構成プロパティの環境変数

このオプションでは、DATABRICKS_CLUSTER_ID 環境変数と、使用する Databricks 認証の種類に必要なその他の環境変数を設定します。

各認証タイプに必要な環境変数は次のとおりです。

Azure Databricks 個人用アクセストークン認証の場合: DATABRICKS_HOST と DATABRICKS_TOKEN。
OAuth マシン間 (M2M) 認証の場合 (サポートされている場合): DATABRICKS_HOST、DATABRICKS_CLIENT_ID、DATABRICKS_CLIENT_SECRET。
OAuth ユーザー対マシン (U2M) 認証の場合 (サポートされている場合): DATABRICKS_HOST。
Microsoft Entra ID (旧称 Azure Active Directory) サービスプリンシパル認証の場合: DATABRICKS_HOST、ARM_TENANT_ID、ARM_CLIENT_ID、ARM_CLIENT_SECRET、場合によっては DATABRICKS_AZURE_RESOURCE_ID。
Azure CLI 認証の場合: DATABRICKS_HOST。
Azure マネージド ID 認証の場合 (サポートされている場合): DATABRICKS_HOST、ARM_USE_MSI、ARM_CLIENT_ID、場合によっては DATABRICKS_AZURE_RESOURCE_ID。

次に、DatabricksSession クラスを次のように初期化します。

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

`DEFAULT` という名前の Databricks の構成プロファイル

クラスターの ID を使用して DATABRICKS_CLUSTER_ID 環境変数を既に設定している場合は、cluster_id を指定する必要はありません。

各認証タイプに必要な構成プロファイルフィールドは次のとおりです。

Azure Databricks 個人用アクセストークン認証の場合: host と token。
OAuth マシン間 (M2M) 認証の場合 (サポートされている場合): host、client_id、client_secret。
OAuth ユーザー対マシン (U2M) 認証の場合 (サポートされている場合): host。
Microsoft Entra ID (旧称 Azure Active Directory) サービスプリンシパル認証の場合: host、azure_tenant_id、azure_client_id、azure_client_secret、場合によっては azure_workspace_resource_id。
Azure CLI 認証の場合: host。
Azure マネージド ID 認証の場合 (サポートされている場合): host、azure_use_msi、azure_client_id、場合によっては azure_workspace_resource_id。

この構成プロファイルに DEFAULT という名前を付けます。

次に、DatabricksSession クラスを次のように初期化します。

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

サーバーレスコンピューティングへの接続を構成する

重要

この機能はパブリックプレビュー段階にあります。

Databricks Connect では、サーバーレスコンピューティングへの接続がサポートされています。この機能を使用するには、サーバーレスに接続するための要件が満たされている必要があります。「要件」を参照してください。

重要

この機能には次の制限があります。

すべての Databricks Connect for Python の制限事項
すべてのサーバーレスコンピューティングの制限事項
UDF には、サーバーレスコンピューティング環境の一部として含まれる Python 依存関係のみを使用できます。「システム環境」を参照してください。追加の依存関係をインストールすることはできません。
カスタムモジュールを含む UDF はサポートされていません。

サーバーレスコンピューティングへの接続は、次のいずれかの方法で構成できます。

ローカル環境変数 DATABRICKS_SERVERLESS_COMPUTE_ID を auto に設定します。この環境変数が設定されている場合、Databricks Connect では cluster_id が無視されます。
ローカルの Databricks 構成プロファイルで、serverless_compute_id = auto を設定し、Databricks Connect Python コードからそのプロファイルを参照します。
```
[DEFAULT]
host = https://my-workspace.cloud.databricks.com/
serverless_compute_id = auto
token = dapi123...
```

または、次のように単に Databricks Connect Python コードを更新します。

from databricks.connect import DatabricksSession as SparkSession

spark = DatabricksSession.builder.serverless(True).getOrCreate()

from databricks.connect import DatabricksSession as SparkSession

spark DatabricksSession.builder.remote(serverless=True).getOrCreate()

Note

サーバーレスコンピューティングセッションは、非アクティブ状態が 10 分続くとタイムアウトになります。その後、サーバーレスコンピューティングに接続するために新しい Spark セッションを作成する必要があります。これは spark = DatabricksSession.builder.serverless(True).getOrCreate() を使用して行えます。

Databricks への接続の検証

環境、既定の資格情報、コンピューティングへの接続が Databricks Connect 用に正しく設定されていることを検証するには、databricks-connect test コマンドを実行します。セットアップで非互換性が検出されると、このコマンドは失敗し、ゼロ以外の終了コードと対応するエラーメッセージが表示されます。

databricks-connect test

次のように、validateSession() を使用して Python コードで環境を検証することもできます。

DatabricksSession.builder.validateSession(True).getOrCreate()

次の方法で共有

Databricks Connect for Python をインストールする

要件

Python 仮想環境をアクティブ化する

Databricks Connect クライアントをインストールする

venv を使って Databricks Connect クライアントをインストールする

Poetry を使って Databricks Connect クライアントをインストールする

接続プロパティを構成する

クラスターへの接続を構成する

`DatabricksSession` クラスの `remote()` メソッド

Azure Databricks の構成プロファイル

`DATABRICKS_CONFIG_PROFILE` 環境変数

各構成プロパティの環境変数

`DEFAULT` という名前の Databricks の構成プロファイル

サーバーレスコンピューティングへの接続を構成する

Databricks への接続の検証

フィードバック

その他のリソース

次の方法で共有

Databricks Connect for Python をインストールする

要件

Python 仮想環境をアクティブ化する

Databricks Connect クライアントをインストールする

venv を使って Databricks Connect クライアントをインストールする

Poetry を使って Databricks Connect クライアントをインストールする

接続プロパティを構成する

クラスターへの接続を構成する

DatabricksSession クラスの remote() メソッド

Azure Databricks の構成プロファイル

DATABRICKS_CONFIG_PROFILE 環境変数

各構成プロパティの環境変数

DEFAULT という名前の Databricks の構成プロファイル

サーバーレス コンピューティングへの接続を構成する

Databricks への接続の検証

フィードバック

その他のリソース

`DatabricksSession` クラスの `remote()` メソッド

`DATABRICKS_CONFIG_PROFILE` 環境変数

`DEFAULT` という名前の Databricks の構成プロファイル

サーバーレスコンピューティングへの接続を構成する