Almacena en caché los DataFrames en computación serverless

Importante

Esta característica está en versión preliminar pública. Los administradores de espacios de trabajo pueden controlar el acceso a la caché de DataFrame en computación serverless desde la página de Previsualizaciones . Consulte Administrar versiones preliminares de Azure Databricks.

En computación sin servidor, puedes almacenar en caché un DataFrame con df.cache() o df.persist() para reutilizar un resultado caro en tu sesión. Azure Databricks calcula el DataFrame cuando llamas a cache() y materializa el resultado como una instantánea. DataFrame y DataFrames que construyes a partir de él leen la instantánea durante el resto de la sesión en lugar de recalcularla.

Requirements

  • La vista previa del almacenamiento en caché de DataFrame en la computación sin servidor está habilitada para tu espacio de trabajo (activada por defecto). Los administradores del espacio de trabajo pueden deshabilitarlo desde la página de Previsualizaciones . La vista previa no está disponible en los espacios de trabajo con el perfil de seguridad de cumplimiento activado. Consulte Gestionar vistas previas a nivel de espacio de trabajo.
  • Los cuadernos y trabajos en computación serverless deben usar la versión 5 o superior del entorno.
  • Databricks Connect para Python debe ser 18.1.8 o superior, y Databricks Connect para Scala debe ser 18.1.5 o superior.

Las versiones anteriores del cliente reciben el error CACHE_REQUIRES_NEWER_CLIENT_ON_SERVERLESS_GC.

Cuándo usar caché de DataFrame en computación serverless

Almacena en caché un DataFrame en computación serverless cuando necesites:

  • Reutiliza el resultado de una unión costosa, agregación o filtro varias veces en la misma sesión.
  • Calcula un microlote en streaming una vez en una función foreachBatch y luego escríbelo en varios destinos.
  • Entrenar o ajustar varios modelos de aprendizaje automático con los mismos datos de características preparados.
  • Mantén una instantánea estable mientras ejecutas varios pasos de un análisis, incluso si cambian las tablas de origen.

Consulte los procedimientos recomendados.

Almacene en caché las API de DataFrame en computación serverless

El siguiente ejemplo almacena en caché un día de pedidos unidos a datos de clientes, calcula los ingresos totales del día, añade los ingresos por región a una tabla de informes y luego libera la caché. Ambos resultados leen la instantánea en caché en lugar de ejecutar el join de nuevo.

Python

from pyspark.sql import functions as F

# The DataFrame to cache: one day of orders joined with customer data.
oct_15_orders = (
    spark.table("main.sales.orders")
    .filter(F.col("order_date") == "2026-10-15")
    .join(spark.table("main.sales.customers"), "customer_id")
)
oct_15_orders.cache()

# Both results are built from oct_15_orders, so they read the cached snapshot.
total_revenue = oct_15_orders.agg(F.sum("amount")).first()[0]
print(f"Total revenue on 2026-10-15: {total_revenue}")

revenue_by_region = oct_15_orders.groupBy("order_date", "region").agg(F.sum("amount").alias("revenue"))
revenue_by_region.write.mode("append").saveAsTable("main.reports.revenue_by_region")

# Release the cache and the DataFrame when you no longer need it.
# oct_15_orders and DataFrames built from it can no longer be used.
oct_15_orders.unpersist()

Scala

import org.apache.spark.sql.functions._

// The DataFrame to cache: one day of orders joined with customer data.
val oct15Orders = spark.table("main.sales.orders")
  .filter(col("order_date") === "2026-10-15")
  .join(spark.table("main.sales.customers"), "customer_id")
oct15Orders.cache()

// Both results are built from oct15Orders, so they read the cached snapshot.
val totalRevenue = oct15Orders.agg(sum("amount")).first().get(0)
println(s"Total revenue on 2026-10-15: $totalRevenue")

val revenueByRegion = oct15Orders.groupBy("order_date", "region").agg(sum("amount").alias("revenue"))
revenueByRegion.write.mode("append").saveAsTable("main.reports.revenue_by_region")

// Release the cache and the DataFrame when you no longer need it.
// oct15Orders and DataFrames built from it can no longer be used.
oct15Orders.unpersist()

En las siguientes descripciones de la API, df representa cualquier DataFrame en tu sesión, como oct_15_orders en el ejemplo anterior.

df.cache()

Calcula df de inmediato y almacena en caché el resultado como una instantánea para el resto de la sesión.

  • Devuelve: El mismo DataFrame en caché, df, ahora basado en la instantánea en lugar del cálculo realizado sobre sus tablas de origen. Consulta lo siguiente.
  • Comportamiento:
    • Ejecuta la consulta del DataFrame inmediatamente y materializa el resultado como una instantánea antes de que la llamada regrese.
    • Después de la llamada, df y el DataFrame devuelto (df en sí mismo) se basan en la instantánea. Ya no están conectados al cálculo en las tablas fuente, por lo que leen la instantánea en lugar de recalcular la consulta.
    • Los DataFrames derivados de df, directamente o a través de otros DataFrames derivados, leen la instantánea automáticamente en lugar de ejecutar la consulta original de nuevo. Ver Lee la instantánea.
    • La instantánea es local de tu sesión. Solo la sesión que almacenó df en caché puede leerlo. Consulta Aislamiento y privilegios.
    • La instantánea dura hasta que termina la sesión, como máximo siete días. Azure Databricks recupera automáticamente espacio de almacenamiento en segundo plano. Llamar df.unpersist() le permite liberar el almacenamiento antes. Consulta Ciclo de vida y límites de tiempo y Almacenamiento y limpieza.
    • Si el cómputo df falla, df.cache() genera el error y df no se almacena en caché.
    • Llamar a df.cache() en un DataFrame que ya está en caché no sirve de nada. df no se vuelve a calcular.

La instantánea se fija después de llamar a df.cache(). Los datos escritos después en las tablas de las que df lee, y los cambios en el esquema de esas tablas, como columnas añadidas o renombradas, no lo afectan. Para recalcular a partir de los datos más recientes, construye el DataFrame de nuevo desde las tablas de origen y almacena en caché el nuevo DataFrame si lo necesitas.

Lee la instantánea

En computación sin servidor, la coincidencia de caché se basa en la derivación de DataFrame. Después de df.cache(), solo los siguientes DataFrames leen automáticamente la instantánea en lugar de recalcular la consulta en las tablas fuente:

  • El DataFrame que guardaste en caché, df.
  • DataFrames derivados de df, por ejemplo con select(), filter(), groupBy(), o join().
  • DataFrames encadenados adicionalmente a partir de esos DataFrames derivados.

Un nuevo DataFrame que repite la misma consulta lee las tablas fuente, aunque su lógica sea idéntica, porque no se deriva de df.

Esto hace que la coincidencia de caché sea explícita y esté bajo tu control: un DataFrame lee los datos almacenados en caché solo cuando los obtienes de un DataFrame almacenado en caché. Uno de cada dos DataFrame lee las tablas de origen.

Python

oct_15_orders = (
    spark.table("main.sales.orders")
    .filter(F.col("order_date") == "2026-10-15")
    .join(spark.table("main.sales.customers"), "customer_id")
)
# The join runs one time, when you call cache().
oct_15_orders.cache()

# Derived from oct_15_orders: read the snapshot, so the join doesn't run again.
large_orders = oct_15_orders.filter(F.col("amount") > 1000)
revenue_by_region = oct_15_orders.groupBy("order_date", "region").agg(F.sum("amount").alias("revenue"))

# Derived from large_orders, which is derived from oct_15_orders: also reads the snapshot.
large_orders_by_region = large_orders.groupBy("region").count()

# Not derived from oct_15_orders: reads the source tables and runs the join again.
same_query = (
    spark.table("main.sales.orders")
    .filter(F.col("order_date") == "2026-10-15")
    .join(spark.table("main.sales.customers"), "customer_id")
)

Scala

val oct15Orders = spark.table("main.sales.orders")
  .filter(col("order_date") === "2026-10-15")
  .join(spark.table("main.sales.customers"), "customer_id")
// The join runs one time, when you call cache().
oct15Orders.cache()

// Derived from oct15Orders: read the snapshot, so the join doesn't run again.
val largeOrders = oct15Orders.filter(col("amount") > 1000)
val revenueByRegion = oct15Orders.groupBy("order_date", "region").agg(sum("amount").alias("revenue"))

// Derived from largeOrders, which is derived from oct15Orders: also reads the snapshot.
val largeOrdersByRegion = largeOrders.groupBy("region").count()

// Not derived from oct15Orders: reads the source tables and runs the join again.
val sameQuery = spark.table("main.sales.orders")
  .filter(col("order_date") === "2026-10-15")
  .join(spark.table("main.sales.customers"), "customer_id")

Como df lee la instantánea en lugar de los DataFrames con los que se construyó, no puedes referenciar las columnas de df a través de esos DataFrames. Consulte Limitaciones.

df.persist(storageLevel)

Un alias de df.cache() que acepta un nivel de almacenamiento.

  • Parámetros:
    • storageLevel (opcional): Un StorageLevel, como StorageLevel.DISK_ONLY. La computación sin servidor acepta cualquier nivel de almacenamiento y lo ignora. La instantánea se almacena de la misma manera para cada nivel de almacenamiento y df.storageLevel devuelve StorageLevel.DISK_ONLY.

El valor de retorno y el comportamiento son los mismos que los de df.cache().

df.unpersist(blocking)

Libera la instantánea en caché de df y destruye el DataFrame.

  • Parámetros:
    • blocking (opcional): Ignorado. df.unpersist() devuelve inmediatamente para cualquiera de los dos valores.
  • Devuelve: El mismo DataFrame, df, ahora está destruido.
  • Comportamiento:
    • Marca la instantánea como lista para ser liberada. Azure Databricks entonces elimina los datos almacenados en caché y libera espacio de almacenamiento en segundo plano.
    • Destruye df: df y cualquier DataFrame derivado previamente de él ya no es utilizable, y cualquier consulta posterior sobre ellos genera CACHE_DATAFRAME_ACCESS_AFTER_UNCACHE. Si almacenas en caché un DataFrame derivado de df antes de llamar df.unpersist(), ese DataFrame sigue siendo utilizable porque tiene su propia instantánea.
    • Para seguir trabajando con la misma fuente de datos, construye un nuevo DataFrame a partir de la fuente original, en lugar de reutilizar el DataFrame sin caché.
    • Llamar df.unpersist() a un DataFrame que nunca fue almacenado en caché, o del que ya se ha eliminado de la caché, es un no-op.

Llame a df.unpersist() cuando ya no necesite los datos en caché, por ejemplo, cuando ningún paso posterior en su cuaderno o tarea los lea. Esto permite que Azure Databricks recupere el almacenamiento antes. No uses df.unpersist() para actualizar datos. Para trabajar con los datos más recientes, construye un nuevo DataFrame a partir de las tablas fuente.

Python

oct_15_orders = spark.table("main.sales.orders").filter(F.col("order_date") == "2026-10-15")
oct_15_orders.cache()
large_orders = oct_15_orders.filter(F.col("amount") > 1000)
orders_per_customer = oct_15_orders.groupBy("customer_id").count()
orders_per_customer.cache()  # Has its own snapshot.

# Acknowledge that the cached data is no longer needed.
# This releases the storage and destroys oct_15_orders.
oct_15_orders.unpersist()

oct_15_orders.count()  # Raises CACHE_DATAFRAME_ACCESS_AFTER_UNCACHE.
large_orders.count()  # Raises CACHE_DATAFRAME_ACCESS_AFTER_UNCACHE.
orders_per_customer.count()  # Reads its own snapshot.

# If you need the data again later, build a new DataFrame from the source tables.
oct_15_orders = spark.table("main.sales.orders").filter(F.col("order_date") == "2026-10-15")

Scala

var oct15Orders = spark.table("main.sales.orders").filter(col("order_date") === "2026-10-15")
oct15Orders.cache()
val largeOrders = oct15Orders.filter(col("amount") > 1000)
val ordersPerCustomer = oct15Orders.groupBy("customer_id").count()
ordersPerCustomer.cache() // Has its own snapshot.

// Acknowledge that the cached data is no longer needed.
// This releases the storage and destroys oct15Orders.
oct15Orders.unpersist()

oct15Orders.count() // Throws CACHE_DATAFRAME_ACCESS_AFTER_UNCACHE.
largeOrders.count() // Throws CACHE_DATAFRAME_ACCESS_AFTER_UNCACHE.
ordersPerCustomer.count() // Reads its own snapshot.

// If you need the data again later, build a new DataFrame from the source tables.
oct15Orders = spark.table("main.sales.orders").filter(col("order_date") === "2026-10-15")

df.storageLevel

Obtiene el nivel de almacenamiento de df.

  • Devuelve: StorageLevel.DISK_ONLY mientras df está almacenado en caché. StorageLevel.NONE antes de almacenarlo en caché y después de llamar a df.unpersist().

Python

from pyspark import StorageLevel

oct_15_orders.cache()
oct_15_orders.storageLevel == StorageLevel.DISK_ONLY  # True

Scala

import org.apache.spark.storage.StorageLevel

oct15Orders.cache()
oct15Orders.storageLevel == StorageLevel.DISK_ONLY // true

Para las firmas de métodos, consulte la referencia de PySpark para cache, persist, unpersist y storageLevel.

Límites de ciclo de vida y tiempo

Los datos en caché solo existen dentro de la sesión de Azure Databricks donde los almacenas en caché. Se vuelve inaccesible cuando termina la sesión, y dura como máximo siete días. Tras el límite de siete días, usar un DataFrame en caché genera un error en lugar de volver a leer las tablas fuente. Para volver a usar la caché, inicia una nueva sesión.

Almacenamiento y limpieza

Azure Databricks gestiona automáticamente el almacenamiento de datos en caché. Los datos almacenados en caché se almacenan en la nube, y la ubicación específica depende del tipo de espacio de trabajo:

Después de que los datos en caché se vuelven inaccesibles, Azure Databricks recupera automáticamente el espacio de almacenamiento en segundo plano. Esto incluye casos en los que la sesión termina por una desconexión o un fallo. Llamar a df.unpersist() permite a Azure Databricks liberar el almacenamiento antes.

Aislamiento y privilegios

Cualquier usuario que pueda ejecutar código en computación serverless puede almacenar en caché un DataFrame. No necesitas privilegios extra.

Los datos en caché proporcionan aislamiento a nivel de sesión. Solo la sesión que almacenó en caché un DataFrame puede leer sus datos almacenados en caché. Otros usuarios no pueden acceder a él, incluidos otros usuarios del mismo cuaderno.

Los datos en caché contienen lo que se te permitía leer cuando los guardabas. Los cambios de permisos, filtros de fila y máscaras de columna aplicados a las tablas de origen después no se aplican a los datos almacenados en caché.

Prácticas recomendadas

  • Almacena en caché cuando necesites una instantánea estable: Si ejecutas varias transformaciones, agregaciones o desgloses sobre los mismos datos calculados, la instantánea les proporciona una línea base consistente que no cambia cuando cambian las tablas fuente.
  • Almacene en caché cálculos costosos, no lecturas de tablas simples: df.cache() materializa el resultado de la consulta y las lecturas posteriores escanean esa instantánea. Si almacenas en caché una lectura de tabla simple, como spark.table("main.sales.orders").cache(), las lecturas posteriores aún escanean una copia completa de la tabla, por lo que la caché ahorra poco. El almacenamiento en caché da sus frutos tras trabajos costosos como uniones, agregaciones y filtros complejos.
  • No almacenes en caché datos que lees solo una vez: df.cache() calcula y almacena el resultado al instante, lo que lleva tiempo y almacenamiento. Si lees el resultado solo una vez, el coste inicial no merece la pena.
  • Utiliza la caché derivando del DataFrame almacenado en caché: Para leer la instantánea, compila operaciones posteriores a partir de la variable DataFrame almacenada en caché, por ejemplo df.select(...) o df.filter(...). Un DataFrame independiente construido a partir del mismo cálculo en las tablas de origen no utiliza la caché.
  • No uses caché para compartir datos entre sesiones o usuarios: Los datos almacenados en caché son privados de tu sesión. Otras sesiones, cuadernos, ejecuciones de trabajos y usuarios no pueden leerlo. Para compartir los resultados calculados entre sesiones o con otros usuarios, escríbelos en una tabla permanente.
  • Mantén las sesiones con datos en caché por debajo de siete días: consulta Ciclo de vida y límites de tiempo. Si tu flujo de trabajo necesita los datos durante más tiempo, escríbelos en una tabla.
  • Llama df.unpersist() cuando ya no necesites los datos en caché: Esto permite que Azure Databricks libere el espacio de almacenamiento antes. Después de la llamada, el DataFrame y los DataFrames derivados de él no pueden usarse.
  • No use df.unpersist() para actualizar datos: df.unpersist() termina la vida de la instantánea. Para captar cambios en las tablas fuente, construye un nuevo DataFrame a partir de las tablas fuente.

Limitations

El almacenamiento en caché de DataFrame en computación serverless tiene las siguientes limitaciones:

  • Nombres y tipos de columnas: Los siguientes DataFrames no pueden almacenarse en caché. Renombra o convierte las columnas antes de hacer caché, por ejemplo con .alias("total_amount").
    • DataFrames con nombres de columnas duplicados.
    • DataFrames con nombres de columnas que contienen espacios o cualquiera de los caracteres ,;{}()=, como sum(amount), procedentes de una agregación.
    • DataFrames con columnas de intervalo.
    • DataFrames con arrays, mapas o structs que contienen valores de tipo NULL.
    • DataFrames sin columnas, o con solo columnas de tipo NULL.
  • Referencias de columnas: Después de almacenar en caché un DataFrame, no puedes referenciar sus columnas a través de los DataFrames con los que se construyó. Por ejemplo, después de oct_15_orders = orders.join(customers, "customer_id") y oct_15_orders.cache(), oct_15_orders.select(orders.amount) genera CANNOT_RESOLVE_DATAFRAME_COLUMN. Use oct_15_orders.amount o "amount" en su lugar.
  • API SQL y de caché de catálogo: Las sentencias de caché SQL, como CACHE TABLE, y los métodos de caché de tablas de spark.catalog no son compatibles con cómputo sin servidor. Ver Limitaciones de caché. Para reutilizar un resultado de consulta en SQL, utiliza una tabla temporal local de sesión.
  • Consultas de esquema de información: Cuando muchas sesiones en un metastore almacenan en caché DataFrames, las consultas en information_schema.volumes y information_schema.schemata pueden ser lentas o quedar sin tiempo. Filtrar volumes por catálogo no hace que la consulta sea más rápida. Las consultas en information_schema.tables no se ven afectadas.
  • Regiones de Azure Government: La caché de DataFrame no está soportada en computación serverless en regiones de Azure Government.

Migrar desde Compute clásico

Para la mayoría de las cargas de trabajo, la caché en computación serverless da los mismos resultados que en computación clásica, y el código existente se ejecuta sin cambios. En la tabla siguiente se enumeran las diferencias.

Behavior Proceso sin servidor Computación clásica
Coincidencia en caché Solo el DataFrame almacenado en caché y los DataFrames derivados de él usan automáticamente la caché. Cualquier consulta con la misma forma del plan utiliza automáticamente la caché.
Actualización de datos Una instantánea consistente tomada en el momento en que se llama a df.cache(). Varía: los datos en caché se actualizan en ciertos casos y ofrecen una instantánea en otros.
Ámbito de uso compartido Privado para tu sesión. Compartido entre sesiones dentro del clúster.
Materialización Eager: se calcula enseguida cuando llamas a df.cache(). Evaluación diferida: calculado en la primera acción del DataFrame.
df.unpersist() Destruye el DataFrame y libera su instantánea de forma determinista. Libera la caché en memoria. El DataFrame, cuando se use más tarde, puede contener los datos más recientes o desactualizados, dependiendo del producto y la fuente de datos.

A continuación se describen las dos primeras diferencias con más detalle:

  • Coincidencia de caché:
    • Cargas de trabajo afectadas por el cambio: La mayoría de las cargas de trabajo no se ven afectadas. Si sigues usando la variable DataFrame en caché, por ejemplo con df.select(...) o df.filter(...), la caché funciona como antes. El cambio solo afecta a cargas de trabajo donde una consulta de DataFrame o SQL construida de forma independiente reutiliza la caché porque tiene la misma forma del plan. En computación sin servidor, esas consultas leen las tablas fuente.
    • Si tu carga de trabajo se ve afectada: Usa la variable DataFrame en caché donde necesites el resultado en caché, en lugar de construir la misma consulta de nuevo.
  • Actualización de datos:
    • Cargas de trabajo afectadas por el cambio: La mayoría de las cargas de trabajo no se ven afectadas, porque es poco común leer datos almacenados en caché después de escribir en sus tablas fuente. El cambio afecta solo a las cargas de trabajo que escriben en las tablas fuente y luego esperan que el DataFrame almacenado en caché muestre los nuevos datos.
    • Si tu carga de trabajo se ve afectada: Después de escribir en las tablas de origen, crea un nuevo DataFrame a partir de ellas en lugar de reutilizar el que está en caché.

Recursos adicionales

  • Se actualizó por última vez el