Share via

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

  • [アーティクル]

Note

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

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

必要条件

  • ターゲットの Azure Databricks のワークスペースとクラスターは、Databricks Connect のクラスター構成要件を満たしている必要があります。

  • 開発用コンピューターに Python 3 をインストールする必要があり、クライアントの Python インストールのマイナー バージョンは、Azure Databricks クラスターのマイナー Python バージョンと同じである必要があります。 お使いのクラスターのマイナー Python バージョンを確認するには、クラスターの Databricks Runtime リリース ノートの「システム環境」セクションを参照してください。 「Databricks Runtime リリース ノートのバージョンと互換性」を参照してください。

    Note

    PySpark UDF を使用する場合は、開発用コンピューターにインストールされている Python のマイナー バージョンが、クラスターにインストールされている Databricks Runtime に含まれる Python のマイナー バージョンと一致することが重要です。

  • Databricks Connect のメジャーとマイナーのパッケージ バージョンは、Databricks Runtime のバージョンと一致している必要があります。 Databricks では、常に、Azure Databricks Runtime のバージョンと一致する、最新の Databricks Connect のパッケージを使用することをお勧めします。 たとえば、Databricks Runtime 14.0 クラスターを使うときは、14.0 バージョンの databricks-connect パッケージも使う必要があります。

    Note

    利用可能な 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 仮想環境をアクティブ化する

  1. まだそうしていない場合は、Poetry をインストールします。

  2. 開発マシンで Poetry を使っていて、クラスターが Python 3.10 を実行している場合、そのバージョンの Poetry 仮想環境を作成する必要があります。 既存の Python コード プロジェクトのルート ディレクトリから、次のコマンドを実行して、Poetry 用に Python コード プロジェクトを初期化するように poetry に指示します。

    poetry init

  3. Poetry には、完了するためのいくつかのプロンプトが表示されます。 これらのプロンプトはいずれも Databricks Connect に固有のものではありません。 これらのプロンプトの詳細については、init を参照してください。

  4. プロンプトが完了すると、Poetry で Python プロジェクトに pyproject.toml ファイルが追加されます。 pyproject.toml ファイルの詳細については、pyproject.toml ファイルを参照してください。

  5. Python コード プロジェクトのルート ディレクトリから、pyproject.toml ファイルを読み取り、依存関係を解決してインストールし、依存関係をロックする poetry.lock ファイルを作成して、最後に仮想環境を作成するように poetry に指示します。 そのためには、次のコマンドを実行します。

    poetry install

  6. Python コード プロジェクトのルート ディレクトリから、仮想環境をアクティブ化にしてシェルを開始するように poetry に指示します。 そのためには、次のコマンドを実行します。

    poetry shell

ターミナル プロンプトの直前に仮想環境の名前がかっこで囲まれて表示されると、仮想環境がアクティブ化され、シェルが入力されたことがわかります (例: (my-project-py3.10))。

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

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

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

クライアントの設定

ヒント

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

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

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

手順 1: Databricks Connect クライアントをインストールする

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

    注意

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

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

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

  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@~14.0  # Or X.Y to match your cluster version.

    Note

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

手順 2: 接続プロパティの構成

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

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

Note

  1. 次の構成プロパティを収集します。

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

    構成プロパティ オプション 適用対象
    1.DatabricksSession クラスの remote() メソッド Azure Databricks 個人用アクセス トークン認証のみ
    2.Azure Databricks の構成プロファイル すべての Azure Databricks 認証の種類
    3.SPARK_REMOTE 環境変数 Azure Databricks 個人用アクセス トークン認証のみ
    4.DATABRICKS_CONFIG_PROFILE 環境変数 すべての Azure Databricks 認証の種類
    5.各構成プロパティの環境変数 すべての Azure Databricks 認証の種類
    6.DEFAULT という名前の Azure Databricks の構成プロファイル すべての Azure Databricks 認証の種類

    1. 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 では、これらの接続プロパティをコード内で直接指定することはお勧めしません。 その代わりに、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()

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

    2. Azure Databricks の構成プロファイル

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

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

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

    3. SPARK_REMOTE 環境変数

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

      環境変数を設定するには、オペレーティング システムのドキュメントを参照してください。

    4. DATABRICKS_CONFIG_PROFILE 環境変数

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

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

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

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

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      環境変数を設定するには、オペレーティング システムのドキュメントを参照してください。

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

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

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

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

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

      環境変数を設定するには、オペレーティング システムのドキュメントを参照してください。

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

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

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

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

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

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

      from databricks.connect import DatabricksSession

spark = DatabricksSession.builder.getOrCreate()

  3. 環境と 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 の高度な使用方法」を参照してください