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

注

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

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

要件

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

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

  注

  サーバレス コンピュートは、 Databricks Connect バージョン 15.1 以降でサポートされています。 Databricks ConnectDatabricks Runtimeまた、サーバレスの リリース以前の バージョンも完全に互換性があります。リリースノートを参照してください。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

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

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

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

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

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

注

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

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

1. 仮想環境をアクティブ化した状態で、 uninstall コマンドを実行して、PySpark が既にインストールされている場合はアンインストールします。 これは、 databricks-connect パッケージが PySpark と競合するためです。 詳細については、「 PySpark インストールの競合」を参照してください。 PySpark が既にインストールされているかどうかを確認するには、 show コマンドを実行します。

   # Is PySpark already installed?
   pip3 show pyspark
   
   # Uninstall PySpark
   pip3 uninstall pyspark
   

2. 仮想環境がまだアクティブ化されている状態で、 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.*を指定することをお勧めします。これは必須ではありませんが、そのクラスターでサポートされている最新の機能を確実に使用できるようにするのに役立ちます。

「接続プロパティの構成」に進んでください。

Databricks Connect クライアントを Poetryと共にインストールする

1. 仮想環境をアクティブ化した状態で、 remove コマンドを実行して、PySpark が既にインストールされている場合はアンインストールします。 これは、 databricks-connect パッケージが PySpark と競合するためです。 詳細については、「 PySpark インストールの競合」を参照してください。 PySpark が既にインストールされているかどうかを確認するには、 show コマンドを実行します。

   # Is PySpark already installed?
   poetry show pyspark
   
   # Uninstall PySpark
   poetry remove pyspark
   

2. 仮想環境をアクティブ化した状態で、 add コマンドを実行して Databricks Connect クライアントをインストールします。

   poetry add databricks-connect@~15.4  # Or X.Y to match your cluster version.
   

   注

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

接続プロパティの構成

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

• Databricks ワークスペース インスタンス名。 これは、コンピュートの Server ホスト名 の値です。 「Databricks コンピュート リソースの接続の詳細を取得する」を参照してください。

• 使用するDatabricks 認証タイプに必要なその他のプロパティ。

注

• OAuth ユーザー対マシン (U2M) 認証の場合は、Python コードを実行する前に Databricks CLI を使用して認証する必要があります。 チュートリアルを参照してください。

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

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

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

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

2. Databricks 構成プロファイル

3. DATABRICKS_CONFIG_PROFILE 環境変数

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

5. デフォルトという名前のDatabricks構成プロファイル

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

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

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

• DatabricksSession.builder.remote()の host、 token、 cluster_id フィールドを設定します。

• Databricks SDK の Config クラスを使用します。

• Databricks 構成プロファイルを cluster_id フィールドと共に指定します。

• DatabricksSession.builder.remote()で Spark Connect 接続文字列を設定します。

Databricks では、コード内でこれらの接続プロパティを指定する代わりに、このセクション全体で説明されているように、環境変数または構成ファイルを使用してプロパティを構成することをお勧めします。 次のコード例では、ユーザーまたはAWS Systems Manager メンバ Storeなどの他の設定ストアから必要なプロパティを取得するために、提案された 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()

Databricks 構成プロファイル

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

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

• Databricks 個人用アクセストークン認証の場合: host と token.

• OAuth マシン間 (M2M) 認証 (サポートされている場合): host、 client_id、および client_secret。

• OAuth ユーザー対マシン (U2M) 認証 (サポートされている場合) の場合: host.

注

Databricks のユーザー名とパスワードを使用した基本認証は、2024 年 7 月 10 日にサポートが終了しました。 Databricks 管理パスワードのサポート終了を参照してください。

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

注

auth loginコマンドの--configure-clusterオプションを使用すると、新規または既存の構成プロファイルにcluster_idフィールドを自動的に追加できます。 詳細については、コマンドdatabricks auth login -hを実行してください。

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

• 構成プロファイルに cluster_id フィールドを含め、構成プロファイルの名前だけを指定します。

• 構成プロファイル名と cluster_id フィールドを指定します。

DATABRICKS_CLUSTER_ID 環境変数にクラスターの 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環境変数

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

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

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

• Databricks 個人用アクセストークン認証の場合: host と token.

• OAuth マシン間 (M2M) 認証 (サポートされている場合): host、 client_id、および client_secret。

• OAuth ユーザー対マシン (U2M) 認証 (サポートされている場合) の場合: host.

注

Databricks のユーザー名とパスワードを使用した基本認証は、2024 年 7 月 10 日にサポートが終了しました。 Databricks 管理パスワードのサポート終了を参照してください。

注

auth login コマンドの--configure-clusterを使用して、新規または既存の構成プロファイルに cluster_id フィールドを自動的に追加できます。詳細については、コマンド databricks auth login -hを実行してください。

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

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

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

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

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

• Databricks 個人用アクセストークン認証の場合: DATABRICKS_HOST と DATABRICKS_TOKEN.

• OAuthマシン間(M2M)認証の場合:DATABRICKS_HOST、DATABRICKS_CLIENT_ID、およびDATABRICKS_CLIENT_SECRET。

• OAuth user-to-machine (U2M) 認証の場合: DATABRICKS_HOST.

注

Databricks のユーザー名とパスワードを使用した基本認証は、2024 年 7 月 10 日にサポートが終了しました。 Databricks 管理パスワードのサポート終了を参照してください。

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

from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

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

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

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

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

• Databricks 個人用アクセストークン認証の場合: host と token.

• OAuth マシン間 (M2M) 認証 (サポートされている場合): host、 client_id、および client_secret。

• OAuth ユーザー対マシン (U2M) 認証 (サポートされている場合) の場合: host.

注

Databricks のユーザー名とパスワードを使用した基本認証は、2024 年 7 月 10 日にサポートが終了しました。 Databricks 管理パスワードのサポート終了を参照してください。

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

注

auth loginコマンドの--configure-clusterオプションを使用すると、 cluster_idフィールドをDEFAULT構成プロファイルに自動的に追加できます。 詳細については、コマンドdatabricks auth login -hを実行してください。

次に、 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()
  

注

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

Databricksへの接続を検証する

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

databricks-connect test

また、Pythonコードで環境を検証することもできますvalidateSession()

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