Cache DataFrames på serverless compute

Important

Den här funktionen finns som allmänt tillgänglig förhandsversion. Workspace-administratörer kan kontrollera åtkomsten till DataFrame-cachning på serverless compute från sidan Förhandsgranskning. Se Hantera förhandsversioner av Azure Databricks.

På serverless compute kan du cacha en DataFrame med df.cache() eller df.persist() för att återanvända ett dyrt resultat i din session. Azure Databricks beräknar DataFrame när du anropar cache() och materialiserar resultatet som en ögonblicksbild. DataFrame och de DataFrames du bygger från den läser sedan snapshoten under resten av sessionen i stället för att beräkna om den.

Kravspecifikation

  • Förhandsversionen av DataFrame-cachelagring i serverlös beräkning är aktiverad för din arbetsyta (aktiverad som standard). Workspace-administratörer kan inaktivera det från Förhandsgranskningssidan . Förhandsvisningen finns inte tillgänglig i arbetsytor med compliance-säkerhetsprofilen aktiverad. Se Hantera förhandsversioner på arbetsytenivå.
  • Anteckningsböcker och jobb på serverless compute måste använda miljöversion 5 eller högre.
  • Databricks Connect för Python måste vara 18.1.8 eller högre, och Databricks Connect för Scala måste vara 18.1.5 eller högre.

Äldre klientversioner får CACHE_REQUIRES_NEWER_CLIENT_ON_SERVERLESS_GC-felet.

När ska man använda DataFrame-cache på serverless compute

Cache en DataFrame på serverless compute när du behöver:

  • Återanvänd resultatet av en dyr join, aggregering eller filter flera gånger under samma session.
  • Beräkna en strömmande mikrobatch en gång i en foreachBatch funktion, och skriv den sedan till flera sinkar.
  • Träna eller finjustera flera maskininlärningsmodeller på samma förberedda funktionsdata.
  • Behåll en stabil snapshot medan du kör flera steg i en analys, även om källtabellerna ändras.

Se Metodtips.

Cache DataFrame-API:er på serverlös beräkning

Följande exempel cachar ordrar för en dag kopplade till kunddata, beräknar dagens totala intäkter, lägger till intäkterna per region i en rapporttabell och släpper sedan cachen. Båda resultaten läser den cachade snapshoten istället för att köra joinen igen.

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

I följande API-beskrivningar står df för vilken DataFrame som helst i din session, som oct_15_orders i föregående exempel.

df.cache()

Beräknar df direkt och cachar resultatet som en snapshot för resten av din session.

  • Returvärde: Samma cachade DataFrame, df, nu baserad på snapshoten istället för beräkningen utifrån källtabellerna. Se följande beteende.
  • Beteende:
    • Kör DataFrames fråga direkt och materialiserar resultatet som en ögonblicksbild innan anropet returnerar.
    • Efter anropet är df och den returnerade DataFramen (df självt) baserade på snapshoten. De är inte längre kopplade till beräkningen på källtabellerna, så de läser snapshoten istället för att beräkna om queryn.
    • DataFrames härledda från df, direkt eller via andra härledda DataFrames, läser snapshoten automatiskt istället för att köra den ursprungliga frågan igen. Se Läs ögonblicksbilden.
    • Snapshoten gäller bara för din session. Endast sessionen som cachade df kan läsa den. Se Isolering och privilegier.
    • Ögonblicksbilden varar tills sessionen är slut, i högst sju dagar. Azure Databricks frigör då automatiskt sitt lagringsutrymme i bakgrunden. Att anropa df.unpersist() gör att den kan återta lagringen tidigare. Se Livscykel och tidsgränser samt Lagring och rensning.
    • Om beräkningen df misslyckas, utlöses felet av df.cache() och df cachelagras inte.
    • Att anropa df.cache() på en DataFrame som redan är cachad gör ingenting. df beräknas inte igen.

Snapshoten åtgärdas efter att du har kallat df.cache(). Data som skrivs efteråt till tabellerna som df läser från, och schemaändringar i dessa tabeller såsom tillagda eller omdöpta kolumner, påverkar den inte. För att beräkna om från den senaste datan, bygg DataFrame igen från källtabellerna och cacha den nya DataFrame om du behöver.

Läs snapshoten

I serverlösa beräkningar baseras cache-matchning på DataFrame-härledning. Efter df.cache(), läser endast följande DataFrames snapshoten automatiskt istället för att beräkna om frågan i källtabellerna:

  • DataFrame som du cachelagrade, df.
  • DataFrames härledda från df, till exempel med select(), filter(), , groupBy(), eller join().
  • DataFrames som kedjats vidare från dessa härledda DataFrames.

En ny DataFrame som upprepar samma frågekörning läser källtabellerna, även om dess logik är identisk, eftersom den inte härstammar från df.

Detta gör cache-matchning explicit och under din kontroll: en DataFrame läser cachad data endast när du härleder den från en cachad DataFrame. Varje annan DataFrame läser källtabellerna.

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

Eftersom df läser snapshoten i stället för de DataFrames som den byggdes från kan du inte referera till kolumnerna i df via dessa DataFrames. Se Begränsningar.

df.persist(storageLevel)

Ett alias för df.cache() som accepterar en lagringsnivå.

  • Parametrar:
    • storageLevel (valfritt): En StorageLevel, såsom StorageLevel.DISK_ONLY. Serverless Compute accepterar alla lagringsnivåer och ignorerar den. Snapshoten lagras på samma sätt för varje lagringsnivå och df.storageLevel returnerar StorageLevel.DISK_ONLY.

Returvärdet och beteendet är desamma som df.cache().

df.unpersist(blocking)

Släpper den cachade snapshoten av df och förstör DataFrame.

  • Parametrar:
    • blocking (valfritt): Ignorerad. df.unpersist() returnerar omedelbart för båda värdena.
  • Returvärde: Samma DataFrame, df, nu förstörd.
  • Beteende:
    • Markerar ögonblicksbilden som redo att återvinnas. Azure Databricks raderar sedan den cachade datan och frigör lagringsutrymmet igen i bakgrunden.
    • Förstör df: df och alla DataFrames som tidigare härletts från den är inte längre användbara, och varje efterföljande förfrågan på dem väcker CACHE_DATAFRAME_ACCESS_AFTER_UNCACHE. Om du cacher en DataFrame som härstammar från df innan du kallar df.unpersist(), förblir den DataFrame användbar eftersom den har sin egen snapshot.
    • För att fortsätta arbeta med samma datakälla, bygg en ny DataFrame från den ursprungliga datakällan istället för att återanvända den ocachade DataFrame.
    • Att anropa df.unpersist() på en DataFrame som aldrig har cachats, eller som redan har avcachats, är en no-op.

Anropa df.unpersist() när du inte längre behöver de cachelagrade data, till exempel när inget senare steg i din notebook eller ditt jobb läser dem. Detta gör att Azure Databricks kan frigöra lagringsutrymmet tidigare. Använd inte df.unpersist() för att uppdatera data. För att arbeta med den senaste datan, bygg en ny DataFrame från källtabellerna.

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

Hämtar lagringsnivån för df.

  • Returvärde: StorageLevel.DISK_ONLY medan df är cachad. StorageLevel.NONE innan du cachar den och efter att du anropar 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

För metodsignaturerna, se PySpark-referensen för cache, persist, unpersist och storageLevel.

Livscykel och tidsgränser

Cachad data finns endast inom Azure Databricks-sessionen där du cachar den. Den blir otillgänglig när sessionen är slut och varar högst sju dagar. Efter sjudagarsgränsen genererar användning av en cachad DataFrame ett fel i stället för att läsa källtabellerna igen. För att cacha igen, starta en ny session.

Lagring och rensning

Azure Databricks hanterar automatiskt lagringen för cachad data. Cachade data lagras i molnlagring, där den specifika lagringsplatsen beror på din typ av arbetsyta:

När cachad data blir otillgänglig frigör Azure Databricks automatiskt lagringsutrymmet i bakgrunden. Detta inkluderar fall där sessionen avslutas på grund av en frånkoppling eller en krasch. Att anropa df.unpersist() gör det möjligt för Azure Databricks att återta lagringen tidigare.

Isolering och behörigheter

Alla användare som kan köra kod på serverless compute kan cacha en DataFrame. Du behöver inga extra privilegier.

Cachelagrade data ger sessionsnivåisolering. Endast sessionen som cachade en DataFrame kan läsa dess cachade data. Andra användare kan inte komma åt det, inklusive andra användare av samma anteckningsblock.

Den cachade datan innehåller det du fick läsa när du cachade den. Behörighetsändringar, radfilter och kolumnmasker som appliceras på källtabellerna i efterhand gäller inte för den cachade datan.

Regelverk

  • Cache när du behöver en stabil snapshot: Om du kör flera transformationer, aggregeringar eller drilldowns på samma beräknade data ger snapshoten dem en konsekvent baslinje som inte ändras när källtabellerna ändras.
  • Cacha dyra beräkningar, inte vanliga tabellläsningar: df.cache() materialiserar frågeresultatet och senare läsningar skannar den ögonblicksbilden. Om du cachelagrar en vanlig tabellläsning, såsom spark.table("main.sales.orders").cache(), skannar senare läsningar fortfarande en fullständig kopia av tabellen, så cachelagring ger liten nytta. Caching lönar sig efter dyrt arbete som joiner, aggregeringar och komplexa filter.
  • Cacha inte data som du bara läser en gång: df.cache() beräknar och lagrar resultatet direkt, vilket tar tid och lagringsutrymme. Om du bara läser resultatet en gång är den initiala kostnaden inte värd det.
  • Använd cachen genom att härleda från den cachade DataFrame: För att läsa snapshoten, bygg senare operationer från den cachade DataFrame-variabeln, till exempel df.select(...) eller df.filter(...). En oberoende DataFrame byggd från samma beräkning på källtabellerna använder inte cachen.
  • Använd inte cache för delning av data mellan sessioner eller användare: Cachad data är privat för din session. Andra sessioner, anteckningsböcker, jobbkörningar och användare kan inte läsa det. För att dela beräknade resultat mellan sessioner eller med andra användare, skriv dem till en permanent tabell.
  • Håll sessioner med cachad data under sju dagar: Se livscykel och tidsgränser. Om ditt arbetsflöde behöver data under en längre tid, skriv den till en tabell.
  • Anropa df.unpersist() när du inte längre behöver den cachade datan: Detta gör att Azure Databricks kan återta lagringen tidigare. Efter anropet kan DataFrame och de DataFrames som härstammar från det inte användas.
  • Använd inte df.unpersist() för att uppdatera data: df.unpersist() avslutar ögonblicksbildens livslängd. För att fånga upp ändringar i källtabellerna, bygg en ny DataFrame från källtabellerna.

Limitations

DataFrame-cache på serverlös beräkning har följande begränsningar:

  • Kolumnnamn och typer: Följande DataFrames kan inte cachelagras. Byt namn på eller casta kolumnerna innan du cachar, till exempel med .alias("total_amount").
    • DataFrames med dubbla kolumnnamn.
    • DataFrames med kolumnnamn som innehåller mellanslag eller någon av tecknen ,;{}()=, till exempel sum(amount) från en aggregering.
    • DataFrames med intervallkolumner.
    • DataFrames med arrayer, kartor eller structs som innehåller NULL-typade värden.
    • DataFrames utan kolumner, eller med endast NULL-typade kolumner.
  • Kolumnreferenser: Efter att du har cacchat en DataFrame kan du inte referera till dess kolumner via de DataFrames den byggdes av. Till exempel, efter oct_15_orders = orders.join(customers, "customer_id") och oct_15_orders.cache() höjer CANNOT_RESOLVE_DATAFRAME_COLUMNoct_15_orders.select(orders.amount). Använd oct_15_orders.amount eller "amount" i stället.
  • SQL- och katalogcache-API:er: SQL-cachesatser, såsom CACHE TABLE, och tabellcachemetoder för spark.catalog stöds inte på serverless compute. Se begränsningar för cachehantering. För att återanvända ett frågeresultat i SQL, använd en sessionslokal tillfällig tabell.
  • frågor om informationsschemat: När många sessioner i en metastore cachar DataFrames kan frågor på information_schema.volumes och information_schema.schemata vara långsamma eller överskrida tidsgränsen. Att filtrera volumes efter katalog gör inte förfrågan snabbare. Frågor/queries på information_schema.tables påverkas inte.
  • Azure Government-regioner: DataFrame-caching stöds inte på serverless compute i Azure Government-regioner.

Migrera från klassisk Compute

För de flesta arbetsbelastningar ger caching på serverless beräkning samma resultat som på klassisk beräkning, och befintlig kod körs utan ändringar. Följande tabell listar skillnaderna.

Behavior Serverlös beräkning Klassisk beräkning
cachematchning Endast den cachade DataFrame och de DataFrames som härstammar från den använder automatiskt cachen. Alla databasfrågor med samma planstruktur använder automatiskt cachen.
Datas färskhet En konsekvent ögonblicksbild tagen vid tidpunkten när du anropar df.cache(). Varierar: cachelagrad data uppdateras i vissa fall och tillhandahåller en ögonblicksbild i andra.
Delningsomfång Privat för din session. Delad mellan sessioner inom klustret.
Materialisering Ivrig: beräknas direkt när du anropar df.cache(). Lazy: beräknad vid första åtgärden på DataFrame.
df.unpersist() Förstör DataFrame-objektet och frigör dess ögonblicksbild på ett deterministiskt sätt. Frigör minnescachen. Senare användning av DataFrame kan ge den senaste eller föråldrade datan, beroende på produkt och datakälla.

Följande beskriver de två första skillnaderna mer i detalj:

  • Cachematchning:
    • Arbetslaster som påverkas av förändringen: De flesta arbetslaster påverkas inte. Om du fortsätter använda den cachade DataFrame-variabeln, till exempel med df.select(...) eller df.filter(...), fungerar cachen som tidigare. Förändringen påverkar endast arbetsbelastningar där en oberoende byggd DataFrame eller SQL-fråga återanvänder cachen eftersom den har samma planform. På serverless compute läser dessa frågor källtabellerna.
    • Om din arbetslast påverkas: Använd den cachade DataFrame-variabeln där du behöver det cachade resultatet, i stället för att bygga samma fråga igen.
  • Dataaktualitet:
    • Arbetsbelastningar som påverkas av ändringen: De flesta arbetsbelastningar påverkas inte, eftersom det är ovanligt att läsa cachad data igen efter att ha skrivit till källtabellerna. Ändringen påverkar endast arbetsbelastningar som skriver till källtabellerna och sedan förväntar sig att den cachade DataFrame visar den nya datan.
    • Om din arbetsbelastning påverkas: Efter att du skrivit till källtabellerna, bygg en ny DataFrame från dem istället för att återanvända den cachelagrade versionen.

Ytterligare resurser

  • Uppdaterades senast