Änderungsverlauf verwenden

Mit dem BigQuery-Änderungsverlauf können Sie den Änderungsverlauf einer BigQuery-Tabelle verfolgen. Der Änderungsverlauf für eine Tabelle wird als Tabellenwertfunktion (Table-Value-Funktion, TVF) angezeigt, die bestimmte Arten von Änderungen anzeigt, die während eines bestimmten Zeitraums vorgenommen wurden. Mit diesem Feature können Sie inkrementelle Änderungen an einer Tabelle verarbeiten. Wenn Sie wissen, welche Änderungen an einer Tabelle vorgenommen wurden, können Sie beispielsweise ein Tabellenreplikat inkrementell außerhalb von BigQuery pflegen und teure Kopien vermeiden.

Erforderliche Berechtigungen

Zum Aufrufen des Änderungsverlaufs einer Tabelle benötigen Sie die Berechtigung bigquery.tables.getData für diese Tabelle. Die folgenden vordefinierten IAM-Rollen (Identity and Access Management) enthalten diese Berechtigung:

roles/bigquery.dataViewer
roles/bigquery.dataEditor
roles/bigquery.dataOwner
roles/bigquery.admin

Wenn eine Tabelle Zugriffsrichtlinien auf Zeilenebene hat oder hatte, kann nur ein Tabellenadministrator auf Verlaufsdaten für die Tabelle zugreifen. Die Berechtigung bigquery.rowAccessPolicies.overrideTimeTravelRestrictions ist für die Tabelle erforderlich und in der vordefinierten IAM-Rolle roles/bigquery.admin enthalten.

Wenn eine Tabelle die Sicherheit auf Spaltenebene bietet, können Sie den Änderungsverlauf nur für die Spalten aufrufen, auf die Sie Zugriff haben.

TVF `APPENDS`

Die TVF APPENDS gibt eine Tabelle aller Zeilen zurück, die für einen bestimmten Zeitraum an eine Tabelle angehängt sind. Die folgenden Vorgänge fügen dem Änderungsverlauf APPENDS Zeilen hinzu:

DDL-Anweisung CREATE TABLE
DDL-Anweisung INSERT
DDL-Anweisung MERGE
Daten in BigQuery laden
Streamingaufnahme

Syntax

APPENDS(
  TABLE table,
  start_timestamp DEFAULT NULL,
  end_timestamp DEFAULT NULL)

table: Der Name der BigQuery-Tabelle. Es kann keine Ansicht, Unterabfrage, externe Tabelle, materialisierte Ansicht oder Platzhaltertabelle sein. Diesem Argument muss das Wort TABLE vorangestellt werden.
start_timestamp: Ein TIMESTAMP, der den frühesten Zeitpunkt angibt, an dem eine Änderung in der Ausgabe enthalten ist. Wenn der Wert NULL ist, werden alle Änderungen seit der Tabellenerstellung zurückgegeben. Wenn die Tabelle nach start_timestamp erstellt wird, wird stattdessen die tatsächliche Erstellungszeit der Tabelle verwendet. Wenn die Zeit vor der Zeitreisen liegt, wird ein Fehler zurückgegeben. Bei Standardtabellen beträgt dieses Fenster sieben Tage. Sie können jedoch das Zeitfenster für die Zeitfenster kleiner als dieses konfigurieren.
end_timestamp: Ein TIMESTAMP, der die letzte ausschließliche Zeit angibt, zu der eine Änderung in der Ausgabe enthalten ist. Wenn NULL festgelegt ist, werden alle Änderungen einbezogen, die bis zum Beginn der Abfrage vorgenommen wurden.

Rückgabewert

Die TVF APPENDS gibt eine Tabelle mit den folgenden Spalten zurück:

Alle Spalten der Eingabetabelle zum Zeitpunkt der Ausführung der Abfrage. Wenn eine Spalte nach end_timestamp hinzugefügt wird, wird sie mit den NULL-Werten angezeigt, die in allen Zeilen ausgefüllt sind, die vor dem Hinzufügen der Spalte eingefügt wurden.
_CHANGE_TYPE: ein STRING, der die Art der Änderung angibt, die die Zeile erzeugt hat. Bei APPENDS wird nur der Wert INSERT unterstützt.
_CHANGE_TIMESTAMP: Ein TIMESTAMP, der die Commit-Zeit der Transaktion angibt, die die Änderung vorgenommen hat.

Details

Einträge über eingefügte Zeilen bleiben auch dann erhalten, wenn diese Daten später gelöscht werden. Löschungen werden nicht in der TVF APPENDS berücksichtigt. Wenn eine Tabelle kopiert wird, wird beim Aufrufen der TVF APPENDS für die kopierte Tabelle jede Zeile so zurückgegeben, wie sie zum Zeitpunkt der Tabellenerstellung eingefügt wurde. Wenn eine Zeile aufgrund eines UPDATE-Vorgangs geändert wird, hat dies keine Auswirkungen.

Beispiele

Dieses Beispiel zeigt den von APPENDS zurückgegebenen Änderungsverlauf, da verschiedene Änderungen an einer Tabelle namens Produce vorgenommen werden. Dieses Beispiel funktioniert möglicherweise nicht, wenn die Dauer länger ist als Ihr Zeitfenster. Erstellen Sie zuerst die Tabelle.

CREATE TABLE mydataset.Produce (product STRING, inventory INT64) AS (
  SELECT "apples" AS product, 10 AS inventory);

Fügen Sie dann zwei Zeilen in die Tabelle ein.

INSERT INTO mydataset.Produce
VALUES
  ("bananas", 20),
  ("carrots", 30);

Rufen Sie den vollständigen Änderungsverlauf der Hinzufügungen auf. Verwenden Sie NULL-Werte, um den vollständigen Verlauf innerhalb des Zeitreisefensters abzurufen.

SELECT
  product,
  inventory,
  _CHANGE_TYPE AS change_type,
  _CHANGE_TIMESTAMP AS change_time
FROM
  APPENDS(TABLE mydataset.Produce, NULL, NULL);

Die Ausgabe sieht etwa so aus:

+---------+-----------+-------------+--------------------------------+
| product | inventory | change_type | change_time                    |
+---------+-----------+-------------+--------------------------------+
| apples  | 10        | INSERT      | 2022-04-15 20:06:00.488000 UTC |
| bananas | 20        | INSERT      | 2022-04-15 20:06:08.490000 UTC |
| carrots | 30        | INSERT      | 2022-04-15 20:06:08.490000 UTC |
+---------+-----------+-------------+--------------------------------+

Fügen Sie dann eine Spalte hinzu, fügen Sie eine neue Zeile mit Werten ein, aktualisieren Sie das Inventar und löschen Sie die Zeile "Bananen".

ALTER TABLE mydataset.Produce ADD COLUMN color STRING;
INSERT INTO mydataset.Produce VALUES ("grapes", 40, "purple");
UPDATE mydataset.Produce SET inventory = inventory + 5 WHERE TRUE;
DELETE mydataset.Produce WHERE product = "bananas";

Sehen Sie sich die neue Tabelle an.

SELECT * FROM mydataset.Produce;

+---------+-----------+--------+
| product | inventory | color  |
+---------+-----------+--------+
| apples  | 15        | NULL   |
| carrots | 35        | NULL   |
| grapes  | 45        | purple |
+---------+-----------+--------+

Rufen Sie den vollständigen Änderungsverlauf der Hinzufügungen auf.

SELECT
  product,
  inventory,
  color,
  _CHANGE_TYPE AS change_type,
  _CHANGE_TIMESTAMP AS change_time
FROM
  APPENDS(TABLE mydataset.Produce, NULL, NULL);