Armazene DataFrames em cache na computação serverless

Importante

Esse recurso está em Visualização Pública. Administradores de workspace podem controlar o acesso ao cache de DataFrame em computação serverless a partir da página Versões preliminares. Consulte Gerenciar visualizações do Azure Databricks.

Na computação sem servidor, você pode armazenar em cache um DataFrame com df.cache() ou df.persist() para reutilizar um resultado caro na sua sessão. O Azure Databricks calcula o DataFrame quando você chama cache() e materializa o resultado como um snapshot. O DataFrame e os DataFrames que você constrói a partir dele então leem o snapshot pelo resto da sua sessão em vez de recalculá-lo.

Requirements

  • A prévia de cache de DataFrame na computação serverless está ativada para seu workspace (ativada por padrão). Administradores do espaço de trabalho podem desativá-lo na página Previews. A prévia não está disponível em espaços de trabalho com o perfil de segurança de conformidade ativado. Consulte Gerenciar visualizações no nível do espaço de trabalho.
  • Notebooks e jobs em computação serverless devem usar a versão do ambiente 5 ou superior.
  • O Databricks Connect para Python deve ser 18.1.8 ou superior, e o Databricks Connect para Scala deve ser 18.1.5 ou superior.

Clientes desatualizados apresentam o erro CACHE_REQUIRES_NEWER_CLIENT_ON_SERVERLESS_GC.

Quando usar cache de DataFrame em computação serverless

Armazene em cache um DataFrame em computação serverless quando você precisar:

  • Reutilize o resultado de uma junção, agregação ou filtro caro várias vezes na mesma sessão.
  • Calcule um micro-lote em streaming uma vez em uma função foreachBatch, depois escreva em vários destinos.
  • Treine ou ajuste vários modelos de aprendizado de máquina com os mesmos dados de características preparados.
  • Mantenha um snapshot estável enquanto executa várias etapas de uma análise, mesmo que as tabelas de origem mudem.

Consulte as práticas recomendadas.

Armazenar em cache APIs de DataFrame em computação serverless

O exemplo a seguir armazena em cache um dia de pedidos junto com dados do cliente, calcula a receita total do dia, adiciona a receita por região a uma tabela de relatórios e então libera o cache. Ambos os resultados leram o snapshot em cache em vez de rodar a junção novamente.

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

Nas descrições da API a seguir, df significa qualquer DataFrame em sua sessão, como oct_15_orders no exemplo anterior.

df.cache()

Calcula df imediatamente e armazena o resultado em cache como um snapshot para o resto da sua sessão.

  • Retornos: O mesmo DataFrame cacheado, df, agora baseado no snapshot em vez do cálculo em suas tabelas de origem. Veja o seguinte comportamento.
  • Comportamento:
    • Executa a consulta do DataFrame imediatamente e materializa o resultado como um snapshot antes que a chamada retorne.
    • Após a chamada, df e o DataFrame retornado (df em si) são baseados no snapshot. Eles não estão mais conectados ao cálculo nas tabelas de origem, então leem o snapshot em vez de recalcular a consulta.
    • DataFrames derivados de df, diretamente ou através de outros DataFrames derivados, leem o snapshot automaticamente em vez de executar a consulta original novamente. Consulte Leia o instantâneo.
    • O snapshot é local para sua sessão. Apenas a sessão que armazenou em cache df pode lê-lo. Veja Isolamento e privilégios.
    • O snapshot dura até o fim da sessão, no máximo sete dias. O Azure Databricks então libera automaticamente seu espaço de armazenamento em segundo plano. Chamar df.unpersist() permite que ele libere espaço de armazenamento mais cedo. Veja Ciclo de Vida e limites de tempo e Armazenamento e limpeza.
    • Se o cálculo de df falhar, df.cache() gera o erro e df não é armazenado em cache.
    • Chamar df.cache() em um DataFrame que já está em cache não faz nada. df não é calculado novamente.

O snapshot é fixado depois que você chama df.cache(). Os dados escritos depois nas tabelas das quais o df lê, e as alterações de esquema nessas tabelas, como colunas adicionadas ou renomeadas, não afetam isso. Para recalcular a partir dos dados mais recentes, construa o DataFrame novamente a partir das tabelas de origem e armazene em cache o novo DataFrame se precisar.

Leia o instantâneo

Na computação serverless, a correspondência de cache é baseada na derivação de DataFrame. Após df.cache(), apenas os seguintes DataFrames leem o snapshot automaticamente, em vez de recalcular a consulta nas tabelas fonte:

  • O DataFrame que você armazenou no cache, df.
  • DataFrames derivados de df, por exemplo, com select(), filter(), groupBy(), ou join().
  • DataFrames ainda mais encadeados a partir desses DataFrames derivados.

Um novo DataFrame que repete a mesma consulta lê as tabelas fonte, mesmo que sua lógica seja idêntica, porque não é derivado de df.

Isso torna a correspondência de cache explícita e sob seu controle: um DataFrame lê dados em cache apenas quando você os deriva de um DataFrame em cache. Todo outro DataFrame lê as tabelas de origem.

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 lê o snapshot em vez dos DataFrames dos quais foi construído, você não pode referenciar as colunas de df por meio desses DataFrames. Confira Limitações.

df.persist(storageLevel)

Um alias de df.cache() que aceita um nível de armazenamento.

  • Parâmetros:
    • storageLevel (opcional): Um StorageLevel, como StorageLevel.DISK_ONLY. Computação serverless aceita qualquer nível de armazenamento e o ignora. O snapshot é armazenado da mesma forma para todos os níveis de armazenamento e df.storageLevel retorna StorageLevel.DISK_ONLY.

O valor de retorno e o comportamento são os mesmos que df.cache().

df.unpersist(blocking)

Libera o snapshot em cache de df e destrói o DataFrame.

  • Parâmetros:
    • blocking (opcional): Ignorado. df.unpersist() retorna imediatamente para qualquer um dos valores.
  • Retorna: O mesmo DataFrame, df, agora destruído.
  • Comportamento:
    • Marca o instantâneo como pronto para ser reivindicado. O Azure Databricks então apaga os dados em cache e libera o espaço de armazenamento em segundo plano.
    • Destrói df: df e quaisquer DataFrames previamente derivados dele não são mais utilizáveis, e qualquer consulta subsequente sobre eles gera CACHE_DATAFRAME_ACCESS_AFTER_UNCACHE. Se você armazenar em cache um DataFrame derivado de df antes de você chamar df.unpersist(), esse DataFrame permanece utilizável, porque ele tem seu próprio snapshot.
    • Para continuar trabalhando com a mesma fonte de dados, construa um novo DataFrame a partir da fonte de dados original, em vez de reutilizar o DataFrame não armazenado em cache.
    • Chamar df.unpersist() em um DataFrame que nunca foi cacheado, ou que já foi removido do cache, é um no-op.

Use df.unpersist() quando não precisar mais dos dados em cache, por exemplo, quando nenhuma etapa posterior do seu notebook ou job os ler. Isso permite que o Azure Databricks recupere o espaço de armazenamento para reutilização mais cedo. Não use df.unpersist() para atualizar dados. Para trabalhar com os dados mais recentes, construa um novo DataFrame a partir das tabelas de origem.

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

Obtém o nível de armazenamento de df.

  • Retornos: StorageLevel.DISK_ONLY enquanto df está armazenado em cache. StorageLevel.NONE antes de você armazenar em cache e depois de chamar 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 as assinaturas de métodos, veja a referência PySpark para cache, persist, unpersist e storageLevel.

Ciclo de vida e limites de tempo

Os dados em cache existem apenas dentro da sessão do Azure Databricks, onde você os armazena em cache. Ele se torna inacessível quando a sessão termina, e dura no máximo sete dias. Após o limite de sete dias, usar um DataFrame em cache gera um erro em vez de ler novamente as tabelas de origem. Para fazer cache novamente, comece uma nova sessão.

Armazenamento e limpeza

O Azure Databricks gerencia automaticamente o armazenamento para dados em cache. Os dados em cache são armazenados em armazenamento na nuvem, com a localização específica dependendo do tipo de espaço de trabalho:

Após os dados em cache se tornarem inacessíveis, o Azure Databricks automaticamente libera o armazenamento em segundo plano. Isso inclui casos em que a sessão termina devido a uma desconexão ou travamento. Chamar df.unpersist() permite que o Azure Databricks libere o espaço de armazenamento mais cedo.

Isolamento e privilégios

Qualquer usuário que consiga rodar código em computação serverless pode armazenar em cache um DataFrame. Você não precisa de privilégios extras.

Dados em cache fornecem isolamento em nível de sessão. Somente a sessão que armazenou em cache um DataFrame pode ler seus dados em cache. Outros usuários não conseguem acessá-lo, incluindo outros usuários do mesmo notebook.

Os dados em cache contêm o que você podia ler quando fez o cache deles. Mudanças de permissões, filtros de linha e máscaras de coluna aplicadas às tabelas de origem depois não se aplicam aos dados em cache.

Práticas Recomendadas

  • Cache quando você precisa de um snapshot estável: Se você executa várias transformações, agregações ou drill-downs nos mesmos dados calculados, o snapshot fornece uma linha de base consistente que não muda quando as tabelas de origem mudam.
  • Armazene em cache cálculos caros, não leituras simples de tabelas: df.cache() materializa o resultado da consulta, e leituras posteriores escaneiam esse instantâneo. Se você armazenar em cache uma leitura de tabela simples, como spark.table("main.sales.orders").cache(), leituras posteriores ainda escaneiam uma cópia completa da tabela, então o cache economiza pouco. O cache compensa após trabalhos caros, como joins, agregações e filtros complexos.
  • Não armazene em cache dados que você lê apenas uma vez: df.cache() calcula e armazena o resultado imediatamente, o que leva tempo e armazenamento. Se você ler o resultado apenas uma vez, o custo inicial não vale a pena.
  • Use o cache derivado do DataFrame em cache: Para ler o snapshot, construa operações posteriores a partir da variável DataFrame em cache, por exemplo df.select(...) ou df.filter(...). Um DataFrame independente construído a partir da mesma computação nas tabelas de origem não usa o cache.
  • Não use cache para compartilhamento de dados entre sessões ou usuários: Dados em cache são privados para sua sessão. Outras sessões, notebooks, execuções de trabalho e usuários não conseguem lê-lo. Para compartilhar resultados computados entre sessões ou com outros usuários, escreva-os em uma tabela permanente.
  • Mantenha sessões com dados em cache abaixo de sete dias: veja Ciclo de vida e limites de tempo. Se seu fluxo de trabalho precisar dos dados por mais tempo, grave os dados em uma tabela.
  • Chame df.unpersist() quando não precisar mais dos dados em cache: Isso permite que o Azure Databricks libere o armazenamento mais cedo. Após a chamada, o DataFrame e os DataFrames derivados dele não podem ser usados.
  • Não use df.unpersist() para atualizar dados: df.unpersist() encerra a vida do snapshot. Para captar as mudanças nas tabelas de origem, construa um novo DataFrame a partir das tabelas de origem.

Limitações

O cache de DataFrame em computação serverless apresenta as seguintes limitações:

  • Nomes e tipos de colunas: Os seguintes DataFrames não podem ser armazenados em cache. Renomeie ou faça cast nas colunas antes de fazer cache, por exemplo, com .alias("total_amount").
    • DataFrames com nomes de colunas duplicados.
    • DataFrames com nomes de colunas que contêm espaços ou qualquer um dos caracteres ,;{}()=, como sum(amount) resultante de uma agregação.
    • DataFrames com colunas de intervalo.
    • DataFrames com arrays, mapas ou structs que contêm valores do tipo NULL.
    • DataFrames sem colunas ou apenas com colunas do tipo NULL.
  • Referências de colunas: Depois de armazenar em cache um DataFrame, você não pode referenciar suas colunas através dos DataFrames a partir dos quais foi construído. Por exemplo, após oct_15_orders = orders.join(customers, "customer_id") e oct_15_orders.cache(), oct_15_orders.select(orders.amount) aumenta CANNOT_RESOLVE_DATAFRAME_COLUMN. Em vez disso, use oct_15_orders.amount ou "amount".
  • APIs SQL e cache de catálogo: Instruções de cache SQL, como CACHE TABLE, e os métodos de cache de tabela de spark.catalog não são suportadas em computação serverless. Veja Limitações de cache. Para reutilizar um resultado de consulta em SQL, use uma tabela temporária local de sessão.
  • Consultas de schema de informações: Quando muitas sessões em uma metastore armazenam em cache DataFrames, consultas em information_schema.volumes e information_schema.schemata podem ser lentas ou expirar. Filtrar volumes por catálogo não torna a consulta mais rápida. As consultas em information_schema.tables não são afetadas.
  • Regiões do Azure Governamental: O cache de DataFrame não é suportado na computação sem servidor nas regiões do Azure Governamental.

Migrar a partir do ambiente de computação clássico

Para a maioria das cargas de trabalho, o cache em computação serverless traz os mesmos resultados que no computo clássico, e o código existente roda sem alterações. A tabela a seguir lista as diferenças.

Behavior Computação sem servidor Computação clássica
Correspondência do cache Apenas o DataFrame em cache e os DataFrames derivados dele usam automaticamente o cache. Qualquer consulta com a mesma forma do plano usa automaticamente o cache.
Atualização de dados Um snapshot consistente tirado no momento em que você chama df.cache(). Varia: os dados em cache são atualizados em certos casos e servem como snapshot em outros.
Escopo de compartilhamento Privado na sua sessão. Compartilhado entre sessões dentro do cluster.
Materialização Eager: calcula imediatamente quando você chama df.cache(). Avaliação tardia: calculado na primeira ação no DataFrame.
df.unpersist() Destrói o DataFrame e libera seu snapshot deterministicamente. Libera o cache em memória. O uso posterior do DataFrame pode retornar os dados mais recentes ou obsoletos, dependendo do produto e da fonte de dados.

A seguir, são descritas as duas primeiras diferenças com mais detalhes:

  • Correspondência do cache:
    • Cargas de trabalho afetadas pela mudança: A maioria das cargas não é afetada. Se você continuar usando a variável DataFrame em cache, por exemplo com df.select(...) ou df.filter(...), o cache funciona como antes. A mudança afeta apenas cargas de trabalho em que um DataFrame construído de forma independente ou uma consulta SQL reutiliza o cache porque tem a mesma forma do plano. Na computação serverless, essas consultas leem as tabelas de origem.
    • Se sua carga de trabalho for afetada: Use a variável DataFrame em cache onde precisar do resultado em cache, em vez de construir a mesma consulta novamente.
  • Atualização de Dados:
    • Cargas de trabalho afetadas pela mudança: A maioria das cargas de trabalho não é afetada, porque ler dados em cache novamente após gravar em suas tabelas de origem é incomum. A mudança afeta apenas cargas de trabalho que gravam nas tabelas de origem e esperam que o DataFrame em cache mostre os novos dados.
    • Se sua carga de trabalho for afetada: Depois de escrever nas tabelas de origem, construa um novo DataFrame a partir delas em vez de reutilizar o DataFrame em cache.

Recursos adicionais

  • Última atualização em