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

注

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

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

要件

ターゲットの Databricks ワークスペースとクラスターは、 Databricks Connect のクラスター構成の要件を満たしている必要があります。
開発マシンに Python 3 をインストールする必要があり、クライアント Python インストールのマイナーバージョンは、Databricks クラスターのマイナー Python バージョンと同じである必要があります。クラスターのマイナー Python バージョンを見つけるには、クラスターの Databricks Runtime リリースノートの「システム環境」セクションを参照してください。リリースノートDatabricks Runtimeバージョンと互換性を参照してください。

注

PySpark UDF を使用する場合は、開発用コンピューターにインストールされているマイナーバージョンの Python が、クラスターにインストールされている Databricks Runtime に含まれているマイナーバージョンの Python と一致することが重要です。
Databricks Connect のメジャーパッケージとマイナーパッケージのバージョンは、Databricks Runtime のバージョンと一致する必要があります。 Databricks では、Databricks Runtime のバージョンと一致する Databricks Connect の最新のパッケージを常に使用することをお勧めします。たとえば、Databricks Runtime 14.0 クラスターを使用する場合は、databricks-connect パッケージの14.0バージョンも使用する必要があります。

注

利用可能な Databricks Connect リリースとメンテナンス更新プログラムの一覧については、 Databricks Connect リリースノートを参照してください。

Databricks Runtime バージョンと一致する Databricks Connect の最新パッケージを使用する必要はありません。 Databricks Runtime 13.3 LTS 以降では、Databricks Connect パッケージのバージョン以上のすべてのバージョンの Databricks Runtime に対して Databricks Connect パッケージを使用できます。ただし、Databricks Runtime の新しいバージョンで利用可能な機能を使用する場合は、それに応じて Databricks Connect パッケージをアップグレードする必要があります。
Databricks では、Databricks Connect で使用する Python バージョンごとに Python 仮想環境 をアクティブ化することを強くお勧めします。 Python 仮想環境は、正しいバージョンの Python と Databricks Connect を一緒に使用していることを確認するのに役立ちます。これは、関連する技術的な問題の解決を削減または短縮するのに役立ちます。次のセクションでは、venvまたは Poetry のために Python 仮想環境をアクティブ化する方法を参照してください。これらのツールの詳細については、「 venv 」または「Poetry」を参照してください。

venv を使用して Python 仮想環境をアクティブ化する

開発用マシンで venv を使用していて、クラスターで Python 3.10 を実行している場合は、そのバージョンで venv 環境を作成する必要があります。次のコマンド例では、Python 3.10 で venv 環境をアクティブ化するためのスクリプトを生成し、それらのスクリプトを現在の作業ディレクトリ内の .venv という名前の隠しフォルダーに配置します。

# Linux and macOS
python3.10 -m venv ./.venv

# Windows
python3.10 -m venv .\.venv

これらのスクリプトを使用してこの venv 環境をアクティブ化するには、「 venvs の仕組み」を参照してください。

「クライアントの設定」に進んでください。

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

Poetry をまだインストールしていない場合は、インストールします。
開発用マシンで Poetry を使用していて、クラスターで Python 3.10 を実行している場合は、そのバージョンで Poetry 仮想環境を作成する必要があります。既存の Python コードプロジェクトのルートディレクトリから、次のコマンドを実行して、Python コードプロジェクトを Poetry 用に初期化するように poetry に指示します。
```
poetry init
```
「Poetry」には、入力を求めるプロンプトがいくつか表示されます。これらのプロンプトはいずれも Databricks Connect に固有のものではありません。これらのプロンプトの詳細については、「 init」を参照してください。
プロンプトを完了すると、Poetry によって Python プロジェクトに pyproject.toml ファイルが追加されます。 pyproject.toml ファイルの詳細については、「pyproject.toml ファイル」を参照してください。
Python コードプロジェクトのルートディレクトリから、pyproject.toml ファイルを読み取り、依存関係を解決してインストールし、依存関係をロックする poetry.lock ファイルを作成し、最後に仮想環境を作成するように poetry に指示します。これを行うには、次のコマンドを実行します。
```
poetry install
```
Python コードプロジェクトのルートディレクトリから、仮想環境をアクティブ化してシェルに入るように poetry に指示します。これを行うには、次のコマンドを実行します。
```
poetry shell
```

仮想環境がアクティブ化され、シェルに入ると、仮想環境の名前がターミナルプロンプトの直前に括弧内に表示されます(例: (my-project-py3.10))。

仮想環境を非アクティブ化してシェルを終了するには、コマンド exitを実行します。

シェルを終了したことは、仮想環境の名前がターミナルプロンプトの直前に括弧内に表示されなくなったときです。

Poetry 仮想環境の作成と管理の詳細については、「環境の管理」を参照してください。

クライアントのセットアップ

ヒント

Visual Studio Code 用の Databricks 拡張機能が既にインストールされている場合は、これらのセットアップ手順に従う必要はありません。

Visual Studio Code の Databricks 拡張機能には、Databricks Connect for Databricks Runtime 13.0 以降が既に組み込まれています。「Visual Studio Code の Databricks 拡張機能に対して Databricks Connect を使用してコードをデバッグする」に進んでください。

Databricks Connect の要件を満たしたら、次の手順を実行して Databricks Connect クライアントを設定します。

ステップ 1: Databricks Connect クライアントをインストールする

このセクションでは、 venv または Poetry を使用して 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.0.*"  # Or X.Y.* to match your cluster version.
```
注

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

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

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.0  # Or X.Y to match your cluster version.
```
注

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

ステップ 2: 接続プロパティを構成する

このセクションでは、Databricks Connect とリモート Databricks クラスター間の接続を確立するためのプロパティを構成します。これらのプロパティには、クラスターで Databricks Connect を認証するための設定が含まれます。

Databricks Connect for Databricks Runtime 13.1 以降の場合、Databricks Connect には Databricks SDK for Python が含まれています。この SDK は、認証に対する統合された一貫性のあるアーキテクチャとプログラムによるアプローチである Databricks クライアント統合認証標準を実装します。このアプローチにより、Databricks を使用した認証の設定と自動化が一元化され、予測可能になります。これにより、Databricks 認証を一度構成すると、認証構成をさらに変更することなく、複数の Databricks ツールと SDK でその構成を使用できます。

注

OAuth ユーザー対マシン (U2M) 認証の場合は、Python コードを実行する前に Databricks CLI を使用して認証する必要があります。チュートリアルを参照してください。
Databricks Connect for Databricks Runtime 13.0 では、認証のために Databricks 個人用アクセストークン認証のみがサポートされています。

次の構成プロパティを収集します。
- Databricks ワークスペースインスタンス名。これは、クラスターの Server ホスト名 の値と同じです。「 Databricks コンピュートリソースの接続の詳細を取得する」を参照してください。
- クラスターの ID。クラスター ID は URL から取得できます。「クラスターの URL と ID」を参照してください。
- 使用するサポートされている Databricks 認証の種類に必要なその他のプロパティ。これらのプロパティについては、このセクションで説明します。

コード内で接続を構成します。 Databricks Connect は、構成プロパティが見つかるまで次の順序で検索します。それらが見つかると、残りのオプションの検索を停止します。各オプションの詳細は、次の表の後に表示されます。

構成プロパティー・オプション	適用対象
`DatabricksSession`クラスの`remote()`メソッド	Databricks personal アクセストークン認証のみ
Databricks 構成プロファイル	すべての Databricks 認証の種類
`SPARK_REMOTE` 環境変数	Databricks personal アクセストークン認証のみ
`DATABRICKS_CONFIG_PROFILE` 環境変数	すべての Databricks 認証の種類
各構成プロパティの環境変数	すべての Databricks 認証の種類
という名前の Databricks 構成プロファイル `DEFAULT`	すべての 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 では、コードでこれらの接続プロパティを直接指定することはお勧めしません。代わりに、Databricks では、このセクション全体で説明されているように、環境変数または構成ファイルを使用してプロパティを構成することをお勧めします。次のコード例では、提案された retrieve_* 関数の実装を自分で提供して、ユーザーまたは AWS Systems Manager パラメーターストアなどの他の設定ストアから必要なプロパティを取得することを前提としています。

これらの各アプローチのコードは次のとおりです。

# 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()

# Set the Spark Connect connection string in DatabricksSession.builder.remote.
from databricks.connect import DatabricksSession

workspace_instance_name = retrieve_workspace_instance_name()
token                   = retrieve_token()
cluster_id              = retrieve_cluster_id()

spark = DatabricksSession.builder.remote(
  f"sc://{workspace_instance_name}:443/;token={token};x-databricks-cluster-id={cluster_id}"
).getOrCreate()

Databricks 構成プロファイル

このオプションでは、フィールドcluster_id と、使用する Databricks 認証の種類に必要なその他のフィールドを含む Databricks 構成プロファイルを作成または識別します。

各認証タイプに必要な構成プロファイル項目は次のとおりです。
- Databricks 個人用アクセストークン認証の場合: host と token.
- 基本認証(レガシー)の場合:host、username、および password。
- OAuth マシン間 (M2M) 認証 (サポートされている場合): host、 client_id、および client_secret。
- OAuth ユーザー対マシン (U2M) 認証 (サポートされている場合) の場合: host.
次に、 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()
```
SPARK_REMOTE 環境変数

このオプション (Databricks 個人用アクセストークン認証にのみ適用される) では、SPARK_REMOTE 環境変数を次の文字列に設定し、プレースホルダーを適切な値に置き換えます。
```
sc://<workspace-instance-name>:443/;token=<access-token-value>;x-databricks-cluster-id=<cluster-id>
```
次に、 DatabricksSession クラスを次のように初期化します。
```
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()
```
環境変数を設定するには、ご利用になっているオペレーティングシステムのドキュメントを参照してください。
DATABRICKS_CONFIG_PROFILE 環境変数

このオプションでは、フィールドcluster_id と、使用する Databricks 認証の種類に必要なその他のフィールドを含む Databricks 構成プロファイルを作成または識別します。

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

各認証タイプに必要な構成プロファイル項目は次のとおりです。
- Databricks 個人用アクセストークン認証の場合: host と token.
- 基本認証(レガシー)の場合:host、username、および password。
- OAuth マシン間 (M2M) 認証 (サポートされている場合): host、 client_id、および client_secret。
- OAuth ユーザー対マシン (U2M) 認証 (サポートされている場合) の場合: host.
注

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.
- 基本認証(レガシー)の場合:DATABRICKS_HOST、DATABRICKS_USERNAME、および DATABRICKS_PASSWORD。
- OAuthマシン間(M2M)認証の場合:DATABRICKS_HOST、DATABRICKS_CLIENT_ID、およびDATABRICKS_CLIENT_SECRET。
- OAuth user-to-machine (U2M) 認証の場合: DATABRICKS_HOST.
次に、 DatabricksSession クラスを次のように初期化します。
```
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()
```
環境変数を設定するには、ご利用になっているオペレーティングシステムのドキュメントを参照してください。
という名前の Databricks 構成プロファイル DEFAULT

このオプションでは、フィールドcluster_id と、使用する Databricks 認証の種類に必要なその他のフィールドを含む Databricks 構成プロファイルを作成または識別します。

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

各認証タイプに必要な構成プロファイル項目は次のとおりです。
- Databricks 個人用アクセストークン認証の場合: host と token.
- 基本認証(レガシー)の場合:host、username、および password。
- OAuth マシン間 (M2M) 認証 (サポートされている場合): host、 client_id、および client_secret。
- OAuth ユーザー対マシン (U2M) 認証 (サポートされている場合) の場合: host.
この構成プロファイルに DEFAULTという名前を付けます。

注

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

次に、 DatabricksSession クラスを次のように初期化します。
```
from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()
```

環境と Databricks クラスターへの接続を検証します。
- 次のコマンドは、環境、デフォルトの資格情報、クラスターへの接続がすべて Databricks Connect に対して正しく設定されていることを確認します。
```
databricks-connect test
```
  このコマンドは、環境上で構成されたデフォルトの認証情報を取得します ( DEFAULT構成プロファイルや環境変数など)。
  
  セットアップで非互換性が検出されると、コマンドは失敗し、ゼロ以外の終了コードと対応するエラーメッセージが表示されます。
- さらに、Databricks Connect for Python の一部として含まれるpysparkシェルを使用することもできます。次のコマンドを実行してシェルを起動します。
```
pyspark
```
  Spark シェルは、次のように表示されます。
```
Python 3.10 ...
[Clang ...] on darwin
Type "help", "copyright", "credits" or "license" for more information.
Welcome to
      ____              __
     / __/__  ___ _____/ /__
    _\ \/ _ \/ _ `/ __/  '_/
   /__ / .__/\_,_/_/ /_/\_\   version 13.0
      /_/

Using Python version 3.10 ...
Client connected to the Spark Connect server at sc://...:.../;token=...;x-databricks-cluster-id=...
SparkSession available as 'spark'.
>>>
```
  >>>プロンプトで、spark.range(1,10).show()などの単純な PySpark コマンドを実行します。エラーがなければ、正常に接続されています。
  
  接続に成功した場合、Spark シェルを停止するには、 Ctrl + d または Ctrl + zを押すか、コマンド quit() または exit()を実行します。
  
  databricks-connectバイナリの詳細については、「Databricks Connect for Python の高度な使用法」を参照してください。