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

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

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

  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: 接続プロパティの構成」に進んでください。

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@~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 でその構成を使用できます。

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

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

    構成プロパティー・オプション

    適用対象

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

    Databricks personal アクセストークン認証のみ

    1. Databricks 構成プロファイル

    すべての Databricks 認証の種類

    1. SPARK_REMOTE 環境変数

    Databricks personal アクセストークン認証のみ

    1. DATABRICKS_CONFIG_PROFILE 環境変数

    すべての Databricks 認証の種類

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

    すべての Databricks 認証の種類

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

    すべての Databricks 認証の種類

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

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

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

      • DatabricksSession.builder.remote()hosttokencluster_id フィールドを設定します。

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

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

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

      Databricks では、これらの接続プロパティをコードで直接指定することはお勧めしません。 代わりに、Databricks では、このセクションで説明するように、環境変数または構成ファイルを使用してプロパティを構成することをお勧めします。 次のコード例では、提案された retrieve_* 関数の実装を自分で提供して、ユーザーまたは他の構成ストア ( Google クラウド Secret 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()
      
    2. Databricks 構成プロファイル

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

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

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

      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()
      
    3. 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()
      

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

    4. DATABRICKS_CONFIG_PROFILE 環境変数

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

      DATABRICKS_CLUSTER_ID 環境変数にクラスターの 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. という名前の Databricks 構成プロファイル DEFAULT

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

      DATABRICKS_CLUSTER_ID 環境変数にクラスターの 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 の高度な使用法」を参照してください。