Memorizzare nella cache i DataFrame nel calcolo serverless

Importante

Questa funzionalità è in Anteprima Pubblica. Gli amministratori dello spazio di lavoro possono controllare l'accesso alla cache DataFrame sul compute serverless dalla pagina Anteprime. Vedere Gestire le anteprime di Azure Databricks.

Nel calcolo serverless, puoi memorizzare in cache un DataFrame con df.cache() o df.persist() per riutilizzare un risultato costoso nella tua sessione. Azure Databricks calcola il DataFrame quando chiami cache() e materializza il risultato come snapshot. Il DataFrame e i DataFrame che costruisci da esso leggono poi lo snapshot per il resto della sessione invece di ricalcolarlo.

Requirements

  • L'anteprima della memorizzazione nella cache dei DataFrame nel calcolo serverless è abilitata per il tuo workspace (abilitata per impostazione predefinita). Gli amministratori dello spazio di lavoro possono disabilitarlo dalla pagina delle anteprime . L'anteprima non è disponibile negli spazi di lavoro con il profilo di sicurezza di conformità abilitato. Vedere Gestire le anteprime a livello di area di lavoro.
  • I notebook e i lavori sul calcolo serverless devono utilizzare la versione 5 o superiore dell'ambiente .
  • Databricks Connect per Python deve essere 18.1.8 o superiore, e Databricks Connect per Scala deve essere 18.1.5 o superiore.

I client meno recenti ricevono l'errore CACHE_REQUIRES_NEWER_CLIENT_ON_SERVERLESS_GC.

Quando utilizzare la cache DataFrame nel calcolo serverless

Memorizza in cache un DataFrame su computazione serverless quando hai bisogno di:

  • Riutilizza il risultato di una costosa unione, aggregazione o filtro più volte nella stessa sessione.
  • Calcola un micro-batch in streaming una volta in una foreachBatch funzione, poi scrivilo in diversi sink.
  • Addestra o ottimizza diversi modelli di machine learning sugli stessi dati delle caratteristiche preparati.
  • Mantieni un'istantanea stabile mentre esegui diversi passaggi di un'analisi, anche se le tabelle sorgente cambiano.

Vedere Procedure consigliate.

Memorizzare nella cache le API DataFrame nel calcolo serverless

Il seguente esempio memorizza nella cache un giorno di ordini uniti ai dati dei clienti, calcola il fatturato totale del giorno, aggiunge i ricavi per regione a una tabella report e poi rilascia la cache. Entrambi i risultati leggono lo snapshot memorizzato nella cache invece di eseguire nuovamente la join.

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

Nelle seguenti descrizioni API, df rappresenta qualsiasi DataFrame nella tua sessione, come oct_15_orders nell'esempio precedente.

df.cache()

Calcola df subito e memorizza il risultato come snapshot per il resto della sessione.

  • Restituisce: Lo stesso DataFrame cacheato, df, ora basato sull'istantanea invece che sul calcolo sulle sue tabelle sorgente. Vedi il seguente comportamento.
  • Comportamento:
    • Esegue immediatamente la query del DataFrame e materializza il risultato come istantanea prima che la chiamata ritorni.
    • Dopo la chiamata, df e il DataFrame restituito (df stesso) si basano sullo snapshot. Non sono più collegati al calcolo nelle tabelle sorgente, quindi leggono lo snapshot invece di ricalcolare la query.
    • I DataFrame derivati da df, direttamente o tramite altri DataFrame derivati, leggono automaticamente lo snapshot invece di eseguire nuovamente la query originale. Vedi Leggi lo snapshot.
    • L'istantanea è locale per la tua sessione. Solo la sessione che ha memorizzato df nella cache può leggerlo. Vedi Isolamento e privilegi.
    • L'istantanea dura fino alla fine della sessione, per un massimo di sette giorni. Azure Databricks quindi recupera automaticamente l'archiviazione in background. Chiamare df.unpersist() permette di liberare spazio di archiviazione prima. Vedi ciclo di vita e limiti di tempo e Archiviazione e pulizia.
    • Se il calcolo df fallisce, df.cache() genera l'errore e df non viene memorizzato in cache.
    • Chiamare df.cache() su un DataFrame già nella cache non fa nulla. df non viene calcolato di nuovo.

Lo snapshot viene fissato dopo aver chiamato df.cache(). I dati scritti successivamente nelle tabelle da cui df legge, e i cambiamenti di schema in quelle tabelle, come colonne aggiunte o rinominate, non lo influenzano. Per ricalcolare dai dati più recenti, compila di nuovo il DataFrame dalle tabelle sorgente e memorizza in cache il nuovo DataFrame se necessario.

Leggi l'istantanea

Nell'elaborazione serverless, la corrispondenza della cache si basa sulla derivazione del DataFrame. Dopo df.cache(), solo i seguenti DataFrame leggono automaticamente l'istantanea invece di ricalcolare la query sulle tabelle sorgente:

  • Il DataFrame che hai memorizzato nella cache, df.
  • DataFrame derivati da df, ad esempio con select(), filter(), groupBy(), o join().
  • DataFrame ulteriormente concatenati a partire da quei DataFrame derivati.

Un nuovo DataFrame che ripete la stessa query legge le tabelle sorgente, anche se la sua logica è identica, perché non deriva da df.

Questo rende esplicita e sotto il tuo controllo il matching della cache: un DataFrame legge i dati memorizzati nella cache solo quando li derivi da un DataFrame cacheato. Ogni altro DataFrame legge le tabelle sorgente.

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

Poiché df legge lo snapshot invece dei DataFrame da cui è stato costruito, non puoi fare riferimento alle colonne di df tramite quei DataFrame. Vedere Limitazioni.

df.persist(storageLevel)

Un alias di df.cache() che accetta un livello di archiviazione.

  • Parametri:
    • storageLevel (opzionale): Un StorageLevel, come StorageLevel.DISK_ONLY. Il calcolo serverless accetta qualsiasi livello di storage e lo ignora. L'istantanea viene memorizzata allo stesso modo per ogni livello di archiviazione e df.storageLevel restituisce StorageLevel.DISK_ONLY.

Il valore di ritorno e il comportamento sono gli stessi di df.cache().

df.unpersist(blocking)

Rilascia lo snapshot df memorizzato in cache e distrugge il DataFrame.

  • Parametri:
    • blocking (opzionale): Ignorato. df.unpersist() ritorna subito per entrambi i valori.
  • Restituisce: Lo stesso DataFrame, df, ora distrutto.
  • Comportamento:
    • Segna l'istantanea come pronta per essere reclamata. Azure Databricks poi elimina i dati memorizzati nella cache e recupera lo spazio di archiviazione in background.
    • Distrugge df: df e qualsiasi DataFrame precedentemente derivato da essa non è più utilizzabile, e qualsiasi query successiva su di essi solleva CACHE_DATAFRAME_ACCESS_AFTER_UNCACHE. Se memorizzi in cache un DataFrame derivato da df prima che chiami df.unpersist(), quel DataFrame rimane utilizzabile perché ha un proprio snapshot.
    • Per continuare a lavorare con la stessa fonte dati, costruire un nuovo DataFrame dalla fonte originale, invece di riutilizzare il DataFrame non cacheato.
    • Chiamare df.unpersist() su un DataFrame che non è mai stato memorizzato nella cache, o che è già stato rimosso dalla cache, è un no-op.

Chiama df.unpersist() quando non hai più bisogno dei dati memorizzati nella cache, ad esempio quando nessun passaggio successivo del tuo notebook o del job li legge. Questo permette ad Azure Databricks di recuperare lo storage prima. Non usare df.unpersist() per aggiornare i dati. Per lavorare con i dati più recenti, costruisci un nuovo DataFrame dalle tabelle sorgente.

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

Ottiene il livello di memorizzazione di df.

  • Restituisce: StorageLevel.DISK_ONLY mentre df è archiviato. StorageLevel.NONE prima di memorizzarlo e dopo aver chiamato 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

Per le firme dei metodi, vedi il riferimento PySpark per cache, persist, unpersist e storageLevel.

Limiti relativi al ciclo di vita e al tempo

I dati memorizzati nella cache esistono solo all'interno della sessione Azure Databricks dove li memorizzi. Diventa inaccessibile alla fine della sessione e dura al massimo sette giorni. Dopo il limite di sette giorni, l'uso di un DataFrame con cache genera un errore invece di rileggere le tabelle sorgente. Per memorizzare nuovamente nella cache, avvia una nuova sessione.

Archiviazione e pulizia

Azure Databricks gestisce automaticamente lo storage per i dati memorizzati nella cache. I dati memorizzati in cache sono archiviati nel cloud, con la posizione specifica che dipende dal tipo di spazio di lavoro:

Quando i dati memorizzati nella cache diventano inaccessibili, Azure Databricks libera automaticamente lo spazio di archiviazione in background. Questo include casi in cui la sessione termina a causa di una disconnessione o di un crash. Chiamare df.unpersist() permette ad Azure Databricks di recuperare lo storage prima.

Isolamento e privilegi

Qualsiasi utente che possa eseguire codice su computo serverless può memorizzare in cache un DataFrame. Non hai bisogno di privilegi extra.

I dati memorizzati nella cache forniscono isolamento a livello di sessione. Solo la sessione che ha memorizzato in cache un DataFrame può leggere i suoi dati memorizzati nella cache. Altri utenti non possono accedervi, inclusi altri utenti dello stesso notebook.

I dati memorizzati nella cache contengono ciò che ti era permesso leggere quando li hai memorizzati nella cache. Le modifiche ai permessi, i filtri a riga e le maschere di colonna applicate alle tabelle sorgente successivamente non si applicano ai dati memorizzati nella cache.

Procedure consigliate

  • Cache quando hai bisogno di uno snapshot stabile: se esegui diverse trasformazioni, aggregazioni o approfondimenti sugli stessi dati calcolati, lo snapshot fornisce loro una base coerente che non cambia quando cambiano le tabelle sorgente.
  • Cache calcoli costosi, non semplici letture di tabelle: df.cache() materializza il risultato della query e le letture successive scansionano quella istantanea. Se memorizzi in cache una semplice lettura di tabella, come spark.table("main.sales.orders").cache(), le letture successive scansionano comunque una copia completa della tabella, quindi la cache risparmia poco. Il caching ripaga dopo lavori costosi come join, aggregazioni e filtri complessi.
  • Non memorizzare in cache dati che hai letto solo una volta: df.cache() calcola e memorizza subito il risultato, il che richiede tempo e archiviazione. Se leggi il risultato una sola volta, il costo iniziale non vale la pena.
  • Usa la cache derivando dal DataFrame memorizzato: per leggere lo snapshot, costruisci le operazioni successive dalla variabile DataFrame memorizzata, ad esempio df.select(...) o df.filter(...). Un DataFrame indipendente costruito con lo stesso calcolo sulle tabelle sorgente non utilizza la cache.
  • Non usare la cache per la condivisione di dati tra sessioni o utenti: i dati nella cache sono privati e relativi solo alla tua sessione. Altre sessioni, notebook, run di lavoro e gli utenti non possono leggerlo. Per condividere i risultati calcolati tra sessioni o con altri utenti, scrivili su una tabella permanente.
  • Tieni le sessioni con dati memorizzati sotto i sette giorni: Vedi Ciclo di vita e limiti di tempo. Se il tuo flusso di lavoro ha bisogno dei dati più a lungo, scrivili in una tabella.
  • Richiama df.unpersist() quando non hai più bisogno dei dati memorizzati nella cache: Questo permette ad Azure Databricks di liberare lo spazio di archiviazione prima. Dopo la chiamata, il DataFrame e i DataFrame derivati da esso non possono essere utilizzati.
  • Non usare df.unpersist() per aggiornare i dati: df.unpersist() termina la vita dello snapshot. Per rilevare le modifiche nelle tabelle sorgente, costruisci un nuovo DataFrame dalle tabelle sorgente.

Limitations

La cache DataFrame nel calcolo serverless presenta le seguenti limitazioni:

  • Nomi e tipi di colonne: I seguenti DataFrame non possono essere memorizzati nella cache. Rinomina o esegui il cast delle colonne prima di metterle in cache, ad esempio con .alias("total_amount").
    • DataFrame con nomi di colonne duplicati.
    • DataFrame con nomi di colonne che contengono spazi o uno qualsiasi dei caratteri ,;{}()=, come sum(amount), derivanti da un'aggregazione.
    • DataFrame con colonne di intervallo.
    • DataFrame con array, mappe o struct che contengono valori di tipo NULL.
    • DataFrame senza colonne, o con solo colonne di tipo NULL.
  • Riferimenti alle colonne: Dopo aver memorizzato in cache un DataFrame, non puoi più fare riferimento alle sue colonne tramite i DataFrame da cui è stato costruito. Ad esempio, dopo oct_15_orders = orders.join(customers, "customer_id") e oct_15_orders.cache(), oct_15_orders.select(orders.amount) aumenta CANNOT_RESOLVE_DATAFRAME_COLUMN. In sostituzione utilizzare oct_15_orders.amount o "amount".
  • API SQL e cache di catalogo: le istruzioni della cache SQL, come CACHE TABLE, e i metodi della cache delle tabelle di spark.catalog non sono supportati nel compute serverless. Vedi Limitazioni della cache. Per riutilizzare un risultato di query in SQL, si utilizza una tabella temporanea locale di sessione.
  • Query sullo schema informativo: Quando molte sessioni in un metastore memorizzano in cache DataFrame, le query su information_schema.volumes e information_schema.schemata possono essere lente o in timeout. Filtrare volumes per catalogo non rende la query più veloce. Le query su information_schema.tables non subiscono modifiche.
  • regioni Azure per enti pubblici: La cache DataFrame non è supportata nel calcolo serverless nelle regioni Azure per enti pubblici.

Migrazione da Compute classico

Per la maggior parte dei carichi di lavoro, la cache sul calcolo serverless dà gli stessi risultati del calcolo classico, e il codice esistente viene eseguito senza modifiche. Nella tabella seguente sono elencate le differenze.

Behavior Calcolo serverless (senza server) Calcolo classico
Corrispondenza della cache Solo il DataFrame memorizzato nella cache e i DataFrame derivati da esso utilizzano automaticamente la cache. Qualsiasi query con la stessa forma del piano utilizza automaticamente la cache.
Aggiornamento dei dati Uno snapshot coerente scattato al momento in cui chiami df.cache(). Varia: i dati memorizzati nella cache vengono aggiornati in alcuni casi e in altri forniscono un'istantanea.
Ambito di condivisione Privato per questa sessione Condiviso tra le sessioni all'interno del cluster.
Materializzazione Eager: viene calcolato subito quando chiami df.cache(). Valutazione lazy: calcolato alla prima azione sul DataFrame.
df.unpersist() Distrugge il DataFrame e rilascia il suo snapshot in modo deterministico. Rilascia la cache in memoria. L'uso successivo del DataFrame può ottenere i dati più recenti o obsoleti, a seconda del prodotto e della fonte dati.

Di seguito vengono descritte le prime due differenze in modo più dettagliato:

  • Corrispondenza della cache:
    • Carichi di lavoro colpiti dal cambiamento: la maggior parte dei carichi di lavoro non è interessata. Se continui a usare la variabile DataFrame memorizzata nella cache, ad esempio con df.select(...) o df.filter(...), la cache funziona come prima. La modifica riguarda solo i carichi di lavoro in cui un DataFrame creato in modo indipendente o una query SQL riutilizza la cache perché ha la stessa forma del piano. Nel calcolo serverless, queste query leggono le tabelle sorgente.
    • Se il tuo carico di lavoro ne risente: usa la variabile DataFrame in cache ovunque ti serva il risultato memorizzato nella cache, invece di ricostruire la stessa query.
  • Freschezza dei dati:
    • Carichi di lavoro colpiti dal cambiamento: La maggior parte dei carichi di lavoro non è interessata, perché è raro rileggere i dati memorizzati in cache dopo aver scritto nelle tabelle sorgente. La modifica riguarda solo i carichi di lavoro che scrivono nelle tabelle sorgente e poi si aspettano che il DataFrame memorizzato nella cache mostri i nuovi dati.
    • Se il tuo carico di lavoro è influenzato: dopo aver scritto nelle tabelle sorgente, costruisci un nuovo DataFrame da esse invece di riutilizzare quello cacheato.

Risorse aggiuntive

  • Ultimo aggiornamento: