Usa el cliente de Spark Connect sin servidores

El cliente de Managed Service para Apache Spark Connect (google-cloud-spark-connect) es una biblioteca cliente de Python compilada sobre el cliente de código abierto Apache Spark Connect. Permite que tus aplicaciones, secuencias de comandos y notebooks locales ejecuten cargas de trabajo de PySpark en una sesión remota de Managed Service para Apache Spark a través del protocolo Spark Connect.

En comparación con el uso directo del cliente estándar de Apache Spark Connect, google-cloud-spark-connect proporciona los siguientes beneficios:

  • Autenticación y ciclo de vida de la sesión automatizados: ManagedSparkSession.builder.getOrCreate() aprovisiona, configura o reutiliza automáticamente una sesión interactiva remota de Managed Service para Apache Spark y adjunta credenciales de Google Cloud actualización. El código escrito con ManagedSparkSession también se ejecuta sin cambios cuando se envía como una carga de trabajo por lotes de Managed Service para Apache Spark, siempre que el paquete google-cloud-spark-connect esté instalado en el entorno de Python de la carga de trabajo por lotes.
  • Barras de progreso en vivo y vínculos de supervisión: Muestra barras de progreso en tiempo real en notebooks y terminales interactivas durante la creación de sesiones y la ejecución de trabajos de Spark (seguimiento de la finalización de tareas en las etapas), junto con vínculos directos a la página de detalles de la sesión en la consola de Google Cloud , la IU de Spark y las páginas de ejecución de consultas de Spark individuales.
  • Extras de notebooks interactivos: Cuando se instala con el extra interactive, la importación de google.cloud.managed_spark_connect en un notebook de IPython o Jupyter carga automáticamente lo siguiente:
    • explore_dataframe() (con la tecnología de google-colabsqlviz) para explorar, filtrar, ordenar, agregar y trazar gráficos de DataFrames de PySpark de forma interactiva sin escribir código de trazado.
    • Comandos mágicos %%sparksql y %sparksql para ejecutar consultas en SQL de Spark en celdas de notebook con visualización interactiva de resultados y vinculación de variables o DataFrames de Python.
    • Comando mágico %dpip para instalar paquetes de PyPI directamente en el controlador y los ejecutores de la sesión remota sin compilar una imagen de contenedor personalizada.

Al igual que el cliente de Spark Connect de código abierto, google-cloud-spark-connect no requiere una instalación local de Spark. Con el extra [client], solo se instala el paquete ligero pyspark-client en lugar de la distribución completa de pyspark, por lo que no necesitas descargar Spark ni instalar Java en tu máquina para ejecutar PySpark en Managed Service para Apache Spark.

En este documento, se muestra cómo instalar, configurar y usar el cliente.

Antes de comenzar

  1. Asegúrate de tener los roles de Identity and Access Management que contienen los permisos necesarios para administrar las sesiones interactivas y los perfiles de entorno de ejecución (plantillas de sesión).

  2. Si ejecutas el cliente fuera de Google Cloud, proporciona credenciales de autenticación. Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS en la ruta de acceso del archivo de claves de tu cuenta de servicio.

Instala o desinstala el cliente

Puedes instalar o desinstalar el paquete google-cloud-spark-connect con pip.

Instalar

Para notebooks locales y entornos de desarrollo (como VS Code con Google Cloud Data Agent Kit o JupyterLab), instala el cliente desde la línea de comandos en un entorno virtual:

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

Esto instala google-cloud-spark-connect, con dos extras opcionales:

  • interactive: Instala extensiones de notebooks interactivas (explore_dataframe(), %%sparksql y %dpip). Se puede omitir para las secuencias de comandos de Python independientes fuera de un notebook.
  • client: Instala el paquete ligero pyspark-client, que no requiere una JVM local.

En entornos de notebooks administrados, como Colab Enterprise (en los que se preinstala pyspark completo), ejecuta %pip install con el extra spark en lugar de client en una celda de configuración dedicada en la parte superior de tu notebook:

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

Desinstalar

Para desinstalar el cliente, ejecuta el siguiente comando:

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

Configura el cliente

Especifica el proyecto y la región de tu sesión. Puedes establecer estos valores con variables de entorno o con la API de Builder en tu código.

Variables de entorno

Configura las variables de entorno GOOGLE_CLOUD_PROJECT y 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")
# Only available for Managed Spark runtime version 2.3
# 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"


API de Builder

Usa los métodos .projectId(), .location() y .sessionId().

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

Inicia una sesión de Spark

Para iniciar una sesión de Spark, importa ManagedSparkSession en tu aplicación o notebook de PySpark y, luego, llama a la API de ManagedSparkSession.builder.getOrCreate(). Te recomendamos que configures un ID de sesión personalizado con .sessionId() para que, cuando vuelvas a ejecutar tu notebook o ejecutes varios notebooks dentro del tiempo de actividad (TTL) de la sesión, se reutilice la sesión activa y se elimine el tiempo de inicio de la sesión.

  1. Importa la clase ManagedSparkSession. En un notebook de IPython o Jupyter, importar google.cloud.managed_spark_connect también carga automáticamente los extras interactivos del notebook (explore_dataframe(), %%sparksql y %dpip) si el extra interactive está instalado.

  2. Llama a .sessionId() y .getOrCreate() para iniciar o reutilizar la sesión.

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

Mientras se inicia una sesión nueva, el cliente muestra una barra de progreso en vivo y un vínculo a la página de detalles de la sesión en la consola de Google Cloud (en VS Code, el vínculo abre la sesión en Data Agent Kit). Si ya existe una sesión activa con el ID especificado, el cliente se conecta a ella en lugar de crear una nueva. En ese caso, el cliente ignora la configuración de la sesión en tu código. Para aplicar los cambios de configuración, finaliza la sesión existente (spark.stop(terminate=True)) o usa un ID de sesión diferente. Si ya finalizó una sesión con el ID especificado, el cliente borra automáticamente la sesión anterior y crea una nueva con el mismo ID. Una vez que la sesión esté activa, haz lo siguiente:

  • Cuando se evalúa spark en una celda de notebook, se muestran vínculos directos a la página de detalles de la sesión y a la IU de Spark.
  • Cuando se ejecutan acciones de Spark (como df.show(), df.collect() o df.toPandas()), se muestra una barra de progreso de la tarea en tiempo real y un vínculo de consulta de Spark a la página de ejecución de la operación en la IU de Spark.

Configura las propiedades de Spark

Para configurar las propiedades de Spark, encadena uno o más métodos .config() al compilador.

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

Usa la configuración avanzada

Puedes configurar los parámetros de sesión comunes, como el ID de sesión, la versión del entorno de ejecución, la subred, la cuenta de servicio, la plantilla de sesión, el TTL (.ttl()/ .ttlSeconds() y .idleTtl()/.idleTtlSeconds()) o las etiquetas, directamente con los métodos de compilación:

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

Para personalizar por completo el recurso de sesión subyacente, pasa un objeto google.cloud.dataproc_v1.Session a .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()
)

Reutiliza una sesión con nombre

Establecer un ID de sesión personalizado con .sessionId() te permite reutilizar una sola sesión de Spark en varios notebooks o en reinicios del kernel dentro del TTL de la sesión, lo que elimina la latencia de inicio de la sesión y reduce los costos.

  1. En tu primer cuaderno, crea una sesión con un ID personalizado.

    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. En otro notebook (o después de reiniciar el kernel), vuelve a usar la sesión especificando el mismo ID de sesión.

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

Los IDs de sesión deben tener entre 4 y 63 caracteres, comenzar con una letra minúscula y contener solo letras minúsculas, números y guiones. El ID no puede terminar con un guion. Las sesiones con nombre persisten hasta que se finalizan de forma explícita o alcanzan su TTL configurado. Si una sesión con el ID especificado ya se encuentra en un estado TERMINATED, TERMINATING o FAILED, el cliente emite una advertencia, borra la sesión anterior y crea una nueva con el mismo ID (borrar la sesión anterior quita sus metadatos anteriores y el historial de la IU de Spark de Managed Service para Apache Spark, aunque los registros siguen disponibles en Cloud Logging).

Si ya existe una sesión activa con el ID especificado, el cliente se conecta a ella y omite la configuración de la sesión en tu código. Para aplicar los cambios de configuración, finaliza la sesión existente o usa un ID de sesión diferente.

Para finalizar una sesión con nombre, llama a spark.stop(terminate=True). Si llamas a spark.stop() sin argumentos, se desconecta el cliente, pero se deja una sesión con nombre en ejecución. spark.stop() finaliza las sesiones creadas sin .sessionId().

Usa comandos mágicos de Spark SQL

El extra interactive incluye el comando mágico de celda %%sparksql y el comando mágico de línea %sparksql para ejecutar consultas en SQL de Spark en notebooks de Jupyter y renderizar tablas y gráficos interactivos con google-colabsqlviz (el mismo widget de visualización que usa explore_dataframe()).

Cuando instalas google-cloud-spark-connect con el extra interactive y, luego, importas google.cloud.managed_spark_connect en un notebook, la extensión mágica se carga automáticamente.

  1. Opcional: Carga la extensión mágica de forma explícita si no importaste google.cloud.managed_spark_connect.

    %load_ext google.cloud.managed_spark_magics
    
  2. Opcional: Establece la configuración predeterminada.

    %config SparkSql.limit=20
    
  3. Ejecuta consultas en SQL con la magia de celda %%sparksql (que renderiza una tabla interactiva y almacena el DataFrame completo en _df de forma predeterminada) o la magia de línea %sparksql (que suprime la visualización de la tabla y devuelve el DataFrame directamente):

    %%sparksql
    SELECT * FROM your_table
    
    df = %sparksql SELECT * FROM your_table
    
  4. Opcional: Pasa variables y DataFrames de Python a una consulta. Los valores literales de SQL con tipo se pueden vincular con :name, los identificadores de tabla o columna con IDENTIFIER(:name) y los DataFrames en el espacio de nombres del notebook con {df}:

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

Para usar las opciones avanzadas, agrega marcas al comando %%sparksql. Por ejemplo, para almacenar en caché los resultados y crear una vista, ejecuta el siguiente comando:

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

Las siguientes opciones están disponibles:

  • --cache o -c: Almacena en caché el DataFrame.
  • --eager o -e: Calcula el resultado de inmediato con localCheckpoint(eager=True).
  • --view VIEW o -v VIEW: Crea una vista temporal.
  • --limit N o -l N: Anula el límite predeterminado de visualización de filas (solo magia de celda).
  • --display MODE o -d MODE: Establece el modo de visualización (colabsqlviz o html; solo para la magia de celda).
  • --quiet o -q: Suprime la visualización de la tabla.
  • --explain [MODE]: Imprime el plan de consulta en lugar de mostrar los resultados.
  • --session NAME o -s NAME: Se ejecuta en el SparkSession de la variable NAME.
  • variable_name: Almacena el resultado en una variable (solo magia de celda; el valor predeterminado es _df).

Instala paquetes de PyPI en la sesión remota

Para usar paquetes de Python de terceros dentro de las funciones definidas por el usuario (UDF) de PySpark sin compilar una imagen de contenedor personalizada ni reiniciar la sesión, puedes instalar paquetes de PyPI directamente en el controlador y los ejecutores de la sesión remota:

Magia con cuadernos

En un notebook interactivo con un ManagedSparkSession activo, usa el comando mágico %dpip (se carga automáticamente con google.cloud.managed_spark_connect cuando se instala el extra interactive):

%dpip install scipy

%dpip solo instala paquetes en la sesión remota. Para importar un paquete en el código local fuera de Spark, instálalo también en tu entorno de Python local.

API de Python

En las secuencias de comandos o los notebooks, pasa pypi=True a spark.addArtifacts():

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

¿Qué sigue?