Arbeta med tabellhistorik

För Apache Iceberg- och Delta Lake-tabeller skapar varje åtgärd som ändrar en tabell en ny tabellversion. Använd historikinformation för att granska operationer, återställa en tabell eller fråga en tabell vid en viss tidpunkt med tidsresa.

Hämta tabellhistorik

DESCRIBE HISTORY Kör kommandot för att hämta information, inklusive åtgärder, användare och tidsstämpel för varje skrivning till en tabell. Åtgärderna returneras i omvänd kronologisk ordning.

För de kolumner som DESCRIBE HISTORY returneras, värdena i kolumnen operationParameters och per-operation-metrikerna i operationMetrics kolumnen, se tabellhistorikschema och operationsmetrik.

Kvarhållning av tabellhistorik bestäms av tabellinställningen logRetentionDuration, som är 30 dagar som standard.

DESCRIBE HISTORY table_name       -- get the full history of the table

DESCRIBE HISTORY table_name LIMIT 1  -- get the last operation only

Information om Spark SQL-syntax finns i DESCRIBE HISTORY.

Information om Scala, Java och Python syntax finns i Delta Lake API-dokumentationen.

Katalogutforskaren visar tabellhistorik visuellt på fliken Historik .

Identifiera typen av OPTIMIZE åtgärd

Automatisk komprimering, flytande klustring och Z-ordning visas i tabellhistoriken som OPTIMIZE-operationer. Du kan avgöra vilken som kördes genom att granska kolumnen operationParameters.

Om du vill klassificera varje OPTIMIZE åtgärd i en tabells historik kör du följande:

SELECT
  version,
  timestamp,
  CASE
    WHEN operationParameters.clusterBy IS NOT NULL AND operationParameters.clusterBy <> '[]' THEN 'Liquid clustering'
    WHEN operationParameters.zOrderBy IS NOT NULL AND operationParameters.zOrderBy <> '[]' THEN 'Z-ordering'
    WHEN operationParameters.auto = 'true' THEN 'Auto compaction'
    ELSE 'Manual OPTIMIZE'
  END AS optimize_type,
  operationParameters.auto AS is_auto_compaction,
  operationParameters.clusterBy AS cluster_by,
  operationParameters.zOrderBy AS z_order_by,
  operationMetrics.numRemovedFiles AS files_compacted,
  operationMetrics.numAddedFiles AS files_added,
  operationMetrics.numRemovedBytes AS bytes_removed,
  operationMetrics.numAddedBytes AS bytes_added
FROM (DESCRIBE HISTORY table_name)
WHERE operation = 'OPTIMIZE'
ORDER BY version DESC;

I följande avsnitt beskrivs varje operationParameters värde i detalj. För definitioner av de operationMetrics nycklar som föregående fråga väljer, se Operationsmått.

Automatisk komprimering

Automatisk komprimering anger parametern auto till true. Azure Databricks utlöser automatisk komprimering automatiskt efter en skrivning. När auto är false har en användare eller ett schemalagt jobb kört kommandot OPTIMIZE.

En automatisk komprimeringsåtgärd visar till exempel följande:

operationParameters: {
  "auto": "true"
}

Mer information om automatisk komprimering finns i Automatisk komprimering.

Klustring av vätska

Flytande klustring fyller parametern clusterBy med kolumnnamnen för klustring. En tom clusterBy matris ([]) anger endast filkomprimering.

En åtgärd som grupperade data efter kolumnerna date och region visar till exempel följande:

operationParameters: {
  "clusterBy": "[\"date\",\"region\"]"
}

Mer information om flytande klustring finns i Använda flytande klustring för tabeller.

Z-ordning

Z-ordering fyller parametern zOrderBy med kolumnnamnen Z-order. En tom zOrderBy matris ([]) anger att åtgärden inte tillämpade Z-ordning.

En åtgärd som till exempel tillämpade Z-ordning date i kolumnen visar följande:

operationParameters: {
  "zOrderBy": "[\"date\"]"
}

Åtgärdsomfång

Parametern predicate anger om åtgärden kördes i den fullständiga tabellen eller bara en del av den:

• En tom predicate matris ([]) innebär att åtgärden kördes på hela tabellen.
• En ifylld predicate matris innebär att ett målkommando OPTIMIZE table_name WHERE <partition_predicate> endast körs på de partitioner som matchar predikatet.

En åtgärd som är riktad mot partitionsmatchningen year = 2024 visar till exempel följande:

operationParameters: {
  "predicate": "[\"'year = 2024\"]"
}

Tidsresa

Tidsresor stöder förfrågningar mot tidigare versioner av tabellen baserat på tidsstämpel eller version av tabell (registrerad i transaktionsloggen). Du kan använda tidsresor för program, till exempel följande:

• Återskapa analyser, rapporter eller utdata, till exempel utdata från en maskininlärningsmodell. Detta kan vara användbart för felsökning eller granskning, särskilt i reglerade branscher.
• Skriva komplexa temporala frågor.
• Åtgärda misstag i dina data.
• Att tillhandahålla ögonblicksbildisolering för en uppsättning sökfrågor för snabbt föränderliga tabeller.

Tidsresesyntax

Du kör frågor mot en tabell med tidsresa genom att lägga till ett villkor efter tabellnamnspecifikationen.

• timestamp_expression kan vara något av följande:
  • '2018-10-18T22:15:12.013Z', det vill säga: en sträng som kan konverteras till en tidsstämpel
  • cast('2018-10-18 13:36:32 CEST' as timestamp)
  • '2018-10-18', det vill: en datumsträng
  • current_timestamp() - interval 12 hours
  • date_sub(current_date(), 1)
  • Alla andra uttryck som är eller kan omvandlas till en tidsstämpel
• version är ett långt värde som kan erhållas från utdata från DESCRIBE HISTORY table_spec.

Varken timestamp_expression eller version kan vara underfrågor.

Endast datum- eller tidsstämpelsträngar accepteras. Till exempel "2019-01-01" och "2019-01-01T00:00:00.000Z". Se följande kod för exempelsyntax:

SQL

SELECT * FROM people10m TIMESTAMP AS OF '2018-10-18T22:15:12.013Z';
SELECT * FROM people10m VERSION AS OF 123;

Python

df1 = spark.read.option("timestampAsOf", "2019-01-01").table("people10m")
df2 = spark.read.option("versionAsOf", 123).table("people10m")

Du kan också använda syntaxen @ för att ange tidsstämpeln eller versionen som en del av tabellnamnet. Tidsstämpeln måste vara i yyyyMMddHHmmssSSS format. Du kan ange en version med @v. Se följande kod för exempelsyntax:

SQL

-- Timestamp version
SELECT * FROM people10m@20190101000000000
-- Version number
SELECT * FROM people10m@v123

Python

# Timestamp version
spark.read.table("people10m@20190101000000000")
# Version number
spark.read.table("people10m@v123")

Konfigurera datakvarhållning för frågor om tidsresor

Om du vill köra frågor mot en tidigare tabellversion måste du behålla både loggen och datafilerna för den versionen:

• Datafiler tas bort när VACUUM körs mot en tabell.
• Loggfiler tas bort automatiskt efter att tabellversioner har kontrollpunktats.

Om du vill öka tröskelvärdet för datakvarhållning för tabeller måste du konfigurera följande tabellegenskaper och ersätta <format> med antingen delta eller iceberg:

• <format>.logRetentionDuration = "interval <interval>": styr hur länge historiken för en tabell sparas. Standardvärdet är interval 30 days.
  • I Databricks Runtime 18.0 och senare logRetentionDuration måste vara större än eller lika med deletedFileRetentionDuration. För hanterade Unity Catalog-tabeller gäller detta för Databricks Runtime 12.2 och senare.
• <format>.deletedFileRetentionDuration = "interval <interval>": anger tröskelvärdet VACUUM som används för att ta bort datafiler som inte längre refereras till i den aktuella tabellversionen. Standardvärdet är interval 7 days.

Om du till exempel vill få åtkomst till 30 dagars historiska data anger du delta.deletedFileRetentionDuration = "interval 30 days", vilket matchar standardinställningen för delta.logRetentionDuration.

Du kan ange tabellegenskaper när tabellen skapas eller ange dem med en ALTER TABLE -instruktion. Se Referens för tabellegenskaper.

Exempel på tidsresor

Så här åtgärdar du oavsiktliga borttagningar till en tabell för användaren 111:

INSERT INTO my_table
  SELECT * FROM my_table TIMESTAMP AS OF date_sub(current_date(), 1)
  WHERE userId = 111

Så här åtgärdar du oavsiktliga felaktiga uppdateringar av en tabell:

MERGE INTO my_table target
  USING my_table TIMESTAMP AS OF date_sub(current_date(), 1) source
  ON source.userId = target.userId
  WHEN MATCHED THEN UPDATE SET *

Så här frågar du efter antalet nya kunder som lagts till under den senaste veckan:

SELECT
(
  SELECT count(distinct userId)
  FROM my_table
)
-
(
  SELECT count(distinct userId)
  FROM my_table TIMESTAMP AS OF date_sub(current_date(), 7)
) AS new_customers

Kontrollpunkter för transaktionsloggar

Transaktionsloggen registrerar tabellversioner som JSON-filer i transaktionsloggkatalogen tillsammans med tabelldata.

För att optimera kontrollpunktsfrågor aggregeras tabellversioner till Parquet-kontrollpunktsfiler, vilket förbättrar prestandan genom att förhindra behovet av att läsa alla JSON-versioner av tabellhistoriken. Användarna behöver inte interagera direkt med kontrollpunkter.

Azure Databricks optimerar kontrollpunktsfrekvensen för datastorlek och arbetsbelastning. Kontrollpunktsfrekvensen kan komma att ändras utan föregående meddelande.

Återställa en tabell till ett tidigare tillstånd

RESTORE Använd kommandot för att återställa en tabell till en tidigare version eller tidsstämpel, inklusive för följande scenarier:

• Du kan återställa en redan återställd tabell.
• Du kan återställa en klonad tabell.

Tänk på följande krav:

• Om du vill återställa en tabell måste du ha MODIFY behörighet för tabellen.
• När datafilerna har tagits bort manuellt eller av VACUUMkan du inte återställa en tabell till en äldre version som refererar till dessa filer. Det går fortfarande att delvis återställa till den här versionen om spark.sql.files.ignoreMissingFiles är inställd på true.
• Om du vill återställa med tidsstämpeln använder du formaten yyyy-MM-dd HH:mm:ss eller yyyy-MM-dd.

RESTORE TABLE target_table TO VERSION AS OF <version>;
RESTORE TABLE target_table TO TIMESTAMP AS OF <timestamp>;

Syntaxinformation finns i RESTORE.

Beteende för direktuppspelning

Återställning är en dataförändrande åtgärd och kan resultera i duplicerade data för underordnade arbetsbelastningar. Loggposter som lagts till av RESTORE kommandot innehåller dataChange inställt på true.

För underordnade arbetsbelastningar, till exempel ett strukturerat direktuppspelningsjobb som bearbetar uppdateringarna till en tabell, betraktas posterna i dataändringsloggen som lagts till av återställningsåtgärden som nya datauppdateringar och bearbetning av dem kan resultera i dubbletter av data.

Ett exempel:

I föregående exempel RESTORE resulterar kommandot i uppdateringar som tidigare visades vid läsning av tabellversion 0 och 1. Om en strömmande fråga läser den här tabellen igen betraktas dessa filer som nyligen tillagda data och bearbetas igen.

Återställa mått

När detta är klart rapporterar RESTORE följande mätvärden som en DataFrame med en enda rad:

• table_size_after_restore: Tabellens storlek efter återställningen.

• num_of_files_after_restore: Antalet filer i tabellen efter återställningen.

• num_removed_files: Antal filer som tagits bort (logiskt borttagna) från tabellen.

• num_restored_files: Antal filer som återställts på grund av återgång.

• removed_files_size: Total storlek i byte för de filer som tas bort från tabellen.

• restored_files_size: Total storlek i byte för de filer som återställs.

  

Hitta den senaste incheckningsversionen

Om du vill hämta versionsnumret för den senaste incheckningen som skrivits av den aktuella SparkSession i alla trådar och alla tabeller gör du en förfrågan till SQL-konfigurationen spark.databricks.<format>.lastCommitVersionInSession. Ersätt <format> med antingen delta eller iceberg, beroende på tabellens format.

Ett exempel:

SQL

SET spark.databricks.delta.lastCommitVersionInSession

Python

spark.conf.get("spark.databricks.delta.lastCommitVersionInSession")

Scala

spark.conf.get("spark.databricks.delta.lastCommitVersionInSession")

Om inga incheckningar har gjorts av SparkSession kommer en fråga mot nyckeln att returnera ett tomt värde.