サーバーレス Spark Connect クライアントを使用する

Managed Service for Apache Spark Connect クライアント(google-cloud-spark-connect)は、オープンソースの Apache Spark Connect クライアントをベースに構築された Python クライアント ライブラリです。これにより、ローカル アプリケーション、スクリプト、ノートブックは、Spark Connect プロトコルを介してリモートの Managed Service for Apache Spark セッションで PySpark ワークロードを実行できます。

標準の Apache Spark Connect クライアントを直接使用する場合と比較して、google-cloud-spark-connect には次のメリットがあります。

  • セッションのライフサイクルと認証の自動化: ManagedSparkSession.builder.getOrCreate() は、リモートの Managed Service for Apache Spark インタラクティブ セッションを自動的にプロビジョニング、構成、または再利用し、更新用の Google Cloud 認証情報をアタッチします。ManagedSparkSession で記述されたコードは、google-cloud-spark-connect パッケージがバッチ ワークロードの Python 環境にインストールされている場合、Managed Service for Apache Spark バッチ ワークロードとして送信されたときにも変更なしで実行されます。
  • ライブ進行状況バーとモニタリング リンク: セッションの作成中と Spark ジョブの実行中に、ノートブックとインタラクティブ ターミナルにリアルタイムの進行状況バーを表示します(ステージ間のタスク完了を追跡)。また、 Google Cloud コンソールのセッションの詳細ページ、Spark UI、個々の Spark Query 実行ページへの直接リンクも表示されます。
  • インタラクティブ ノートブックのエクストラ: interactive エクストラとともにインストールすると、IPython または Jupyter ノートブックに google.cloud.managed_spark_connect をインポートすると、次のものが自動的に読み込まれます。
    • explore_dataframe()(google-colabsqlviz を利用)を使用すると、プロットコードを記述せずに、PySpark DataFrame をインタラクティブに探索、フィルタ、並べ替え、集計、グラフ化できます。
    • %%sparksql マジック コマンドと %sparksql マジック コマンド。ノートブック セルで Spark SQL クエリを実行し、インタラクティブな結果の可視化と Python 変数または DataFrame のバインディングを行います。
    • %dpip マジック コマンド。カスタム コンテナ イメージをビルドせずに、PyPI パッケージをリモート セッションのドライバとエグゼキュータに直接インストールします。

オープンソースの Spark Connect クライアントと同様に、google-cloud-spark-connect ではローカルに Spark をインストールする必要はありません。[client] エクストラを使用すると、完全な pyspark ディストリビューションではなく、軽量の pyspark-client パッケージのみがインストールされます。そのため、Managed Service for Apache Spark で PySpark を実行するために、Spark をダウンロードしたり、マシンに Java をインストールしたりする必要はありません。

このドキュメントでは、クライアントをインストール、構成、使用する方法について説明します。

始める前に

  1. インタラクティブ セッションとランタイム プロファイル(セッション テンプレート)の管理に必要な権限を含む Identity and Access Management ロールがあることを確認します。

  2. Google Cloudの外部でクライアントを実行する場合は、認証情報を指定します。GOOGLE_APPLICATION_CREDENTIALS 環境変数をサービス アカウント キーファイルのパスに設定します。

クライアントをインストールまたはアンインストールする

google-cloud-spark-connect パッケージのインストールまたはアンインストールには、pip を使用します。

インストール

ローカル ノートブックと開発環境(Google Cloud Data Agent Kit を使用する VS Code や JupyterLab など)の場合は、仮想環境のコマンドラインからクライアントをインストールします。

pip install 'google-cloud-spark-connect[interactive,client]'

これにより、google-cloud-spark-connect がインストールされます。次の 2 つのオプションを追加できます。

  • interactive: インタラクティブなノートブック拡張機能(explore_dataframe()、%%sparksql、%dpip)をインストールします。ノートブック外のスタンドアロン Python スクリプトの場合は省略できます。
  • client: 軽量の pyspark-client パッケージをインストールします。このパッケージにはローカル JVM は必要ありません。

Colab Enterprise などのマネージド ノートブック環境(完全な pyspark がプリインストールされている)では、ノートブックの上部にある専用のセットアップ セルで client ではなく spark エクストラを指定して %pip install を実行します。

%pip install 'google-cloud-spark-connect[interactive,spark]'

アンインストール

クライアントをアンインストールするには、次のコマンドを実行します。

pip uninstall google-cloud-spark-connect pyspark-client

クライアントを構成する

セッションのプロジェクトとリージョンを指定します。これらの値は、環境変数を使用するか、コードでビルダー API を使用して設定できます。

環境変数

GOOGLE_CLOUD_PROJECT および GOOGLE_CLOUD_REGION 環境変数を設定します。

# Google Cloud Configuration for Managed Spark Connect Integration Tests
# Copy this file to .env and fill in your actual values

# ============================================================================
# REQUIRED CONFIGURATION
# ============================================================================

# Your Google Cloud Project ID
GOOGLE_CLOUD_PROJECT="your-project-id"

# Google Cloud Region where Managed Spark sessions will be created
# Integration tests also accept a comma-separated ordered list of fallback regions
# (e.g. "us-east1,us-central1,us-west1") when using a short subnet name.
GOOGLE_CLOUD_REGION="us-central1"

# Path to service account key file (if using SERVICE_ACCOUNT auth)
GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

# ============================================================================
# AUTHENTICATION CONFIGURATION
# ============================================================================

# Authentication type (SERVICE_ACCOUNT or END_USER_CREDENTIALS). If not set, API default is used.
# MANAGED_SPARK_CONNECT_AUTH_TYPE="SERVICE_ACCOUNT"
# MANAGED_SPARK_CONNECT_AUTH_TYPE="END_USER_CREDENTIALS"

# Service account email for workload authentication (optional)
# MANAGED_SPARK_CONNECT_SERVICE_ACCOUNT="your-service-account@your-project.iam.gserviceaccount.com"

# ============================================================================
# SESSION CONFIGURATION
# ============================================================================

# Session timeout in seconds (how long session stays active)
# MANAGED_SPARK_CONNECT_TTL_SECONDS="3600"

# Session idle timeout in seconds (how long session stays active when idle)
# MANAGED_SPARK_CONNECT_IDLE_TTL_SECONDS="900"

# Automatically terminate session when Python process exits (true/false)
# MANAGED_SPARK_CONNECT_SESSION_TERMINATE_AT_EXIT="false"

# Custom file path for storing active session information
# MANAGED_SPARK_CONNECT_ACTIVE_SESSION_FILE_PATH="/tmp/managed_spark_connect_session"

# ============================================================================
# DATA SOURCE CONFIGURATION
# ============================================================================

# Default data source for Spark SQL (currently only supports "bigquery")
# MANAGED_SPARK_CONNECT_DEFAULT_DATASOURCE="bigquery"

# ============================================================================
# ADVANCED CONFIGURATION
# ============================================================================

# Custom Dataproc API endpoint (uncomment if needed)
# GOOGLE_CLOUD_DATAPROC_API_ENDPOINT="your-region-dataproc.googleapis.com"

# Subnet name or URI for Managed Spark Connect (optional; defaults to "default" in tests)
# Accepts a short subnet name (e.g. "default") or full resource URI:
# MANAGED_SPARK_CONNECT_SUBNET="default"
# MANAGED_SPARK_CONNECT_SUBNET="projects/your-project-id/regions/us-central1/subnetworks/your-subnet-name"


Builder API

.projectId()、.location()、.sessionId() メソッドを使用します。

spark = (
    ManagedSparkSession.builder
    .projectId("my-project")
    .location("us-central1")
    .sessionId("my-spark-session")
    .getOrCreate()
)

Spark セッションを開始する

Spark セッションを開始するには、PySpark アプリケーションまたはノートブックに ManagedSparkSession をインポートし、ManagedSparkSession.builder.getOrCreate() API を呼び出します。.sessionId() を使用してカスタム セッション ID を設定することをおすすめします。これにより、ノートブックを再実行するか、セッションの有効期間(TTL)内に複数のノートブックを実行すると、アクティブなセッションが再利用され、セッションの起動時間がなくなります。

  1. ManagedSparkSession クラスをインポートします。IPython または Jupyter ノートブックで google.cloud.managed_spark_connect をインポートすると、interactive エクストラがインストールされている場合は、インタラクティブ ノートブック エクストラ(explore_dataframe()、%%sparksql、%dpip)も自動的に読み込まれます。

  2. .sessionId() と .getOrCreate() を呼び出して、セッションを開始または再利用します。

    from google.cloud.managed_spark_connect import ManagedSparkSession
    spark = ManagedSparkSession.builder.sessionId("my-spark-session").getOrCreate()
    

新しいセッションが開始されると、クライアントにライブ進行状況バーと、 Google Cloud コンソールのセッションの詳細ページへのリンクが表示されます(VS Code では、リンクをクリックすると Data Agent Kit でセッションが開きます)。指定された ID のアクティビティ セッションがすでに存在する場合、クライアントは新しいセッションを作成するのではなく、そのセッションに接続します。この場合、クライアントはコード内のセッション構成を無視します。構成の変更を適用するには、既存のセッション(spark.stop(terminate=True))を終了するか、別のセッション ID を使用します。指定された ID のセッションがすでに終了している場合、クライアントは古いセッションを自動的に削除し、同じ ID で新しいセッションを作成します。セッションがアクティブになると、次のようになります。

  • ノートブック セルで spark を評価すると、セッションの詳細ページと Spark UI への直接リンクが表示されます。
  • Spark アクション(df.show()、df.collect()、df.toPandas() など)を実行すると、リアルタイムのタスク進行状況バーと、Spark UI のオペレーションの実行ページへの Spark クエリリンクが表示されます。

Spark プロパティを構成する

Spark プロパティを構成するには、1 つ以上の .config() メソッドをビルダーにチェーンします。

from google.cloud.managed_spark_connect import ManagedSparkSession

spark = (
    ManagedSparkSession.builder
    .sessionId('my-spark-session')
    .config('spark.executor.memory', '48g')
    .config('spark.executor.cores', '8')
    .getOrCreate()
)

高度な設定を使用する

セッション ID、ランタイム バージョン、サブネットワーク、サービス アカウント、セッション テンプレート、TTL(.ttl() / .ttlSeconds() と .idleTtl() / .idleTtlSeconds())、ラベルなどの一般的なセッション設定は、ビルダー メソッドを使用して直接構成できます。

import datetime
from google.cloud.managed_spark_connect import ManagedSparkSession

spark = (
    ManagedSparkSession.builder
    .projectId('my-project')
    .location('us-central1')
    .sessionId('my-spark-session')
    .runtimeVersion('3.0')
    .subnetwork('SUBNET')
    .idleTtl(datetime.timedelta(minutes=30))
    .getOrCreate()
)

基盤となるセッション リソースを完全にカスタマイズするには、google.cloud.dataproc_v1.Session オブジェクトを .sessionConfig() に渡します。

from google.cloud.managed_spark_connect import ManagedSparkSession
from google.cloud.dataproc_v1 import Session

session_config = Session()
session_config.environment_config.execution_config.subnetwork_uri = 'SUBNET'
session_config.runtime_config.version = '3.0'

spark = (
    ManagedSparkSession.builder
    .projectId('my-project')
    .location('us-central1')
    .sessionId('my-spark-session')
    .sessionConfig(session_config)
    .getOrCreate()
)

名前付きセッションを再利用する

.sessionId() を使用してカスタム セッション ID を設定すると、複数のノートブックで、またはセッションの TTL 内のカーネル再起動全体で、単一の Spark セッションを再利用できます。これにより、セッション起動のレイテンシが排除され、コストが削減されます。

  1. 最初のノートブックで、カスタム ID を使用してセッションを作成します。

    from google.cloud.managed_spark_connect import ManagedSparkSession
    
    session_id = 'my-ml-pipeline-session'
    spark = ManagedSparkSession.builder.sessionId(session_id).getOrCreate()
    df = spark.createDataFrame([(1, 'data')], ['id', 'value'])
    df.show()
    
  2. 別のノートブックで(またはカーネルを再起動した後)、同じセッション ID を指定してセッションを再利用します。

    from google.cloud.managed_spark_connect import ManagedSparkSession
    
    session_id = 'my-ml-pipeline-session'
    spark = ManagedSparkSession.builder.sessionId(session_id).getOrCreate()
    df = spark.createDataFrame([(2, 'more-data')], ['id', 'value'])
    df.show()
    

セッション ID は 4 ~ 63 文字で指定し、先頭は英小文字にしてください。使用できるのは英小文字、数字、ハイフンのみです。ID の末尾をハイフンにすることはできません。名前付きセッションは、明示的に終了されるか、構成された TTL に達するまで維持されます。指定された ID のセッションがすでに TERMINATED、TERMINATING、FAILED のいずれかの状態にある場合、クライアントは警告を出力し、古いセッションを削除して、同じ ID で新しいセッションを作成します(古いセッションを削除すると、以前のメタデータと Spark UI の履歴が Managed Service for Apache Spark から削除されますが、ログは Cloud Logging で引き続き使用できます)。

指定された ID のアクティビティ セッションがすでに存在する場合、クライアントはそれに接続し、コード内のセッション構成を無視します。構成の変更を適用するには、既存のセッションを終了するか、別のセッション ID を使用します。

名前付きセッションを終了するには、spark.stop(terminate=True) を呼び出します。引数なしで spark.stop() を呼び出すと、クライアントは切断されますが、名前付きセッションは実行されたままになります。.sessionId() を指定せずに作成されたセッションは、spark.stop() によって終了されます。

Spark SQL マジック コマンドを使用する

interactive エクストラには、%%sparksql セルマジックと %sparksql ラインマジックが含まれています。これらを使用して、Jupyter ノートブックで Spark SQL クエリを実行し、google-colabsqlviz(explore_dataframe() で使用されるのと同じ可視化ウィジェット)を使用してインタラクティブなテーブルとグラフをレンダリングします。

interactive エクストラを使用して google-cloud-spark-connect をインストールし、ノートブックに google.cloud.managed_spark_connect をインポートすると、マジック拡張機能が自動的に読み込まれます。

  1. 省略可: google.cloud.managed_spark_connect をインポートしていない場合は、マジック拡張機能を明示的に読み込みます。

    %load_ext google.cloud.managed_spark_magics
    
  2. 省略可: デフォルト設定を構成します。

    %config SparkSql.limit=20
    
  3. %%sparksql セルマジック(インタラクティブなテーブルをレンダリングし、デフォルトで完全な DataFrame を _df に保存する)または %sparksql ラインマジック(テーブルの表示を抑制し、DataFrame を直接返す)を使用して SQL クエリを実行します。

    %%sparksql
    SELECT * FROM your_table
    
    df = %sparksql SELECT * FROM your_table
    
  4. 省略可: Python 変数と DataFrame をクエリに渡します。:name を使用して型付き SQL リテラル値をバインドし、IDENTIFIER(:name) を使用してテーブルまたは列の識別子をバインドし、{df} を使用してノートブックの名前空間の DataFrame をバインドできます。

    min_id = 10
    df = spark.createDataFrame([(5, 'a'), (15, 'b')], ['id', 'val'])
    
    %%sparksql
    SELECT * FROM {df} WHERE id >= :min_id
    

詳細オプションを使用するには、%%sparksql コマンドにフラグを追加します。たとえば、結果をキャッシュに保存してビューを作成するには、次のコマンドを実行します。

%%sparksql --cache --view result_view df
SELECT * FROM your_table WHERE condition = true

次のオプションが用意されています。

  • --cache または -c: DataFrame をキャッシュに保存します。
  • --eager または -e: localCheckpoint(eager=True) を使用して結果をすぐに計算します。
  • --view VIEW または -v VIEW: 一時ビューを作成します。
  • --limit N または -l N: デフォルトの行表示上限をオーバーライドします(セルマジックのみ)。
  • --display MODE または -d MODE: 表示モード(colabsqlviz または html、セルマジックのみ)を設定します。
  • --quiet または -q: テーブルの表示を抑制します。
  • --explain [MODE]: 結果を表示する代わりに、クエリプランを出力します。
  • --session NAME または -s NAME: 変数 NAME の SparkSession に対して実行されます。
  • variable_name: 結果を変数に格納します(セルマジックのみ。デフォルトは _df)。

リモート セッションに PyPI パッケージをインストールする

カスタム コンテナ イメージをビルドしたり、セッションを再起動したりせずに、PySpark ユーザー定義関数(UDF)内でサードパーティの Python パッケージを使用するには、リモート セッションのドライバとエグゼキュータに PyPI パッケージを直接インストールします。

ノートブック マジック

ManagedSparkSession がアクティブなインタラクティブ ノートブックで、%dpip マジック コマンドを使用します(interactive エクストラがインストールされている場合、google.cloud.managed_spark_connect とともに自動的に読み込まれます)。

%dpip install scipy

%dpip は、リモート セッションにのみパッケージをインストールします。Spark の外部のローカルコードにパッケージをインポートするには、ローカルの Python 環境にもインストールします。

Python API

スクリプトまたはノートブックで、pypi=True を spark.addArtifacts() に渡します。

spark.addArtifacts("scipy", pypi=True)

次のステップ