変更履歴の操作

BigQuery の変更履歴を使用すると、BigQuery テーブルに対する変更の履歴を追跡できます。テーブルの変更履歴は SQL のテーブル値関数（TVF）として公開され、指定した期間内に行われた特定の種類の変更が表示されます。この機能を使用すると、テーブルに加えられた増分変更を処理できます。テーブルに加えられた変更を把握することで、コストのかかるコピーを回避しながら、BigQuery の外部でテーブルレプリカを段階的に維持できます。

必要な権限

テーブルの変更履歴を表示するには、そのテーブルに対する bigquery.tables.getData 権限が必要です。この権限は、次の Identity and Access Management（IAM）事前定義ロールに含まれています。

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

テーブルに行レベルのアクセスポリシーがあるか、すでに設定されている場合は、テーブル管理者のみがテーブルの過去のデータにアクセスできます。bigquery.rowAccessPolicies.overrideTimeTravelRestrictions 権限は、テーブルに必要であり、roles/bigquery.admin IAM 事前定義ロールに含まれています。

テーブルに列レベルのセキュリティがある場合、アクセスできる列の変更履歴のみを表示できます。

`APPENDS` TVF

APPENDS TVF は、特定の期間にテーブルに追加されたすべての行のテーブルを返します。次のオペレーションでは、APPENDS の変更履歴に行が追加されます。

CREATE TABLE DDL ステートメント
INSERT DML ステートメント
MERGE DML ステートメント
BigQuery へのデータの読み込み
ストリーミング取り込み

構文

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

table: BigQuery テーブル名。ビュー、サブクエリ、外部テーブル、マテリアライズドビュー、ワイルドカードテーブルであることはできません。この引数の前には TABLE という単語が付く必要があります。
start_timestamp: 出力に変更が含まれる最も早い時刻を示す TIMESTAMP。NULL の場合は、テーブル作成以降のすべての変更が返されます。テーブルが start_timestamp の後に作成された場合は、実際のテーブル作成時間が使用されます。時間がタイムトラベルで許可されている時間より前である場合は、エラーが返されます。標準テーブルの場合、このウィンドウは 7 日間ですが、それより短くなるようにタイムトラベル期間を構成できます。
end_timestamp: 変更が出力に含まれる、最新の時刻を示す TIMESTAMP。それが NULL の場合、クエリの開始前に行われたすべての変更が含まれます。

戻り値

APPENDS TVF は、次の列を含むテーブルを返します。

クエリ実行時の入力テーブルのすべての列。列が end_timestamp の後に追加された場合、列の追加前に挿入されたすべての行に NULL 値が入力された状態で表示されます。
_CHANGE_TYPE: 行を生成した変更のタイプを示す STRING。APPENDS の場合、サポートされる値は INSERT のみです。
_CHANGE_TIMESTAMP: 変更したトランザクションの commit 時刻を示す TIMESTAMP。

詳細

挿入された行のレコードは、そのデータが後で削除されても保持されます。削除は APPENDS TVF には反映されません。テーブルがコピーされる場合、コピーしたテーブルで APPENDS TVF を呼び出すと、テーブル作成時に挿入されたすべての行が返されます。UPDATE オペレーションが原因で行が変更されても、効果はありません。

例

この例では、Produce というテーブルにさまざまな変更が行われると APPENDS から返される変更履歴を示しています。タイムトラベル期間よりも長い時間にわたって完了した場合、この例は機能しない可能性があります。まず、テーブルを作成します。

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

次に、このテーブルに 2 つの行を挿入します。

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

追加の完全な変更履歴を表示します。タイムトラベルウィンドウ内のすべての履歴を取得するには、NULL 値を使用します。

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

出力は次のようになります。

+---------+-----------+-------------+--------------------------------+
| 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 |
+---------+-----------+-------------+--------------------------------+

次に、列を追加して値の新しい行を挿入し、インベントリを更新して、「bananas」の行を削除します。

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

新しいテーブルを表示します。

SELECT * FROM mydataset.Produce;

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

追加の完全な変更履歴を表示します。

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

出力は次のようになります。

+---------+-----------+--------+-------------+--------------------------------+
| product | inventory | color  | change_type | change_time                    |
+---------+-----------+--------+-------------+--------------------------------+
| apples  | 10        | NULL   | INSERT      | 2022-04-15 20:06:00.488000 UTC |
| bananas | 20        | NULL   | INSERT      | 2022-04-15 20:06:08.490000 UTC |
| carrots | 30        | NULL   | INSERT      | 2022-04-15 20:06:08.490000 UTC |
| grapes  | 40        | purple | INSERT      | 2022-04-15 20:07:45.751000 UTC |
+---------+-----------+--------+-------------+--------------------------------+

inventory 列には、行がテーブルに最初に挿入されたときに設定された値が表示されます。UPDATE ステートメントによる変更は表示されません。APPENDS TVF はテーブルへの追加のみをキャプチャし、削除はキャプチャしないため、bananas の情報の行は引き続き存在します。

制限事項

変更履歴には次の制限事項があります。

追加についての情報のみを表示できます。更新や削除については表示できません。
データはテーブルのタイムトラベルウィンドウに制限されます。