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バージョン
クラスター
13.3 LTS から 14.3 LTS
3.10
クラスター
15.1 以上
3.11
サーバーレス
15.1 以上
3.10
PySparkUDF を使用する場合は、開発マシンにインストールされている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 クライアントをインストールする
仮想環境をアクティブ化した状態で、
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==14.3.*" # Or X.Y.* to match your cluster version.
注
Databricks では、最新のパッケージがインストールされていることを確認するために、
databricks-connect=X.Y
ではなく "ドット アスタリスク" 表記を追加してdatabricks-connect==X.Y.*
を指定することをお勧めします。これは必須ではありませんが、そのクラスターでサポートされている最新の機能を確実に使用できるようにするのに役立ちます。
「接続プロパティの構成」に進んでください。
Databricks Connect クライアントを Poetryと共にインストールする
仮想環境をアクティブ化した状態で、
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@~14.3 # Or X.Y to match your cluster version.
注
Databricks では、最新のパッケージがインストールされていることを確認するために、
databricks-connect==14.3
ではなくdatabricks-connect@~14.3
を指定する "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 の高度な使用方法」を参照してください。
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サーバーレス コンピュートへの接続をサポートしています。 この機能を使用するには、サーバーレスへの接続要件を満たす必要があります。 「要件」を参照してください。
重要
この機能には、次の制限があります。
サーバレスコンピュートの制限のすべて
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 分間操作がないとタイムアウトします。 PythonSparkこの後、サーバーレス コンピュートに接続するための新しい セッションを作成するために、クライアント側で プロセスを再起動しなければなりません。
Databricksへの接続を検証する
環境、 デフォルト 資格情報、および コンピュート への接続がDatabricks Connectに対して正しく設定されていることを確認するには、databricks-connect test
コマンドを実行します。このコマンドは、セットアップで非互換性が検出されると、ゼロ以外の終了コードと対応するエラー メッセージで失敗します。
databricks-connect test
また、Pythonコードで環境を検証することもできますvalidateSession()
DatabricksSession.builder.validateSession(True).getOrCreate()