変更履歴の操作
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 の情報の行は引き続き存在します。
制限事項
変更履歴には次の制限事項があります。
- 追加についての情報のみを表示できます。更新や削除については表示できません。
- データはテーブルのタイムトラベル ウィンドウに制限されます。