自動 Time-to-Live による行の自動削除

自動有効期間 (自動 TTL) では、タイムスタンプ列の値に基づいて構成可能な期間が経過すると、Unity カタログのマネージドテーブルから行が自動的に削除されます。有効期限を日数で定義し、比較のためにタイムスタンプ列を指定します。 Databricks は、 DELETE、 PURGE、および VACUUM 操作をバックグラウンドで実行して、期限切れの行を削除し、ストレージからクリアします。

自動有効期間を使用する方法の 2 つの例を次に示します。

ストレージコストを低く抑えるために、1 年以上前のデータを削除できます。 created_atタイムスタンプ列に 365 日の有効期限を指定して、作成から 1 年後に行を期限切れにします。
別のビジネスプロセスによって削除対象としてマークされているデータを削除したい場合があります。カスタム del_request_approved タイムスタンプ列に 20 日間の有効期限を指定して、削除要求が処理されてから 20 日後に行を期限切れにします。

Important

正確な削除のタイミングは保証されず、システムの負荷によって異なる場合があります。削除を確認するには、予測最適化システムテーブルに対してクエリを実行するか、テーブルに対して DESCRIBE HISTORY を実行します。システムテーブルを参照してください。

行の有効期限と完全な削除の間のバッファー時間には、最大 6 日間とデータ保持テーブルプロパティの値を加算できます。既定値は 7 日です。特定の期間内に削除するように自動有効期間を構成する方法については、「ターゲットの有効期限の構成値を計算する」および「タイムトラベルクエリのデータ保有期間を構成する」を参照してください。

自動有効期間は、Unity カタログで管理される Delta Lake テーブル、Apache Iceberg テーブル、および Lakeflow パイプラインを使用したストリーミングテーブルで使用できます。

必要条件

予測最適化を有効にする必要があります。「Unity Catalog 管理テーブルの予測最適化」を参照してください。
- 自動有効期間が有効になっているテーブルで予測最適化をオフにすると、自動有効期間が実行されなくなります。
自動有効期間ポリシーを設定または削除するには、テーブルに対する MODIFY アクセス許可が必要です。「基本的なテーブルのアクセス許可」を参照してください。
Databricks Runtime 17.3 以降。
- Databricks Runtime 17.2 以下では、自動有効期間を使用してテーブルの読み取りと書き込みを行うことができます。

自動 Time-to-Live をオンにする

ソーステーブルに応じて、自動有効期間を異なる方法で有効にします。

Delta Lake と Apache Iceberg マネージドテーブル

新しいテーブルに対して自動有効期間ポリシーを設定するには、<expiration_days>に負以外の整数を指定し、DATEにTIMESTAMP、TIMESTAMP_NTZ、または<time_column_name>の型を持つ列を指定します。

CREATE TABLE table_name DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>;

既存のテーブルに対して自動有効期間ポリシーを設定するには:

ALTER TABLE table_name DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>;

たとえば、 created_at タイムスタンプの 30 日後に行を削除するには、次のようにします。

ALTER TABLE my_catalog.my_schema.my_table DELETE ROWS 30 DAYS AFTER created_at;

Lakeflow パイプラインを使用したストリーミングテーブル

パイプライン内の新しいストリーミングテーブルに対して自動 Time-to-Live ポリシーを設定するには、2 つの値を指定します。 <expiration_days> には 0 以上の整数を、DATE には TIMESTAMP、TIMESTAMP_NTZ、または <time_column_name> 型の列を指定します。

SQL

CREATE STREAMING TABLE table_name
DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>
AS SELECT * FROM STREAM(source);

Python

from pyspark import pipelines as dp

@dp.table(
  auto_ttl={"timestamp_column": <time_column_name>, "expire_in_days": <expiration_days>}
)
def function_name():
  return (query)

SQL を使用して自動 Time-to-Live を使用するようにストリーミングテーブルを変更することはサポートされていません。既存のストリーミングテーブルの自動有効期間を変更するには、パイプラインコードを更新して再発行します。

自動 Time-to-Live を使用したテーブルからの読み取りのストリーミング

構造化ストリーミング、Lakeflow パイプライン、またはストリーミングテーブルを使用して、自動 Time-to-Live が有効になっているテーブルから読み取る場合は、ストリーミング読み取りで skipChangeCommits 設定します。自動 Time-to-Live 削除操作は、データの変更時に表示されます。この設定がないと、自動 Time-to-Live による削除時に、ストリーミング読み取りが失敗します。

次の例を参照してください。

構造化ストリーミング

# Source table with auto time-to-live
spark.sql("ALTER TABLE source_table DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>")

# Structured Streaming read
spark.readStream.format("delta").option("skipChangeCommits", "true").table("source_table")

Lakeflow パイプライン

from pyspark import pipelines as dp

# Source table with auto time-to-live
spark.sql("ALTER TABLE source_table DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>")

# Lakeflow pipelines streaming read
@dp.table
def my_table():
  return spark.readStream.format("delta").option("skipChangeCommits", "true").table("source_table")

ストリーミングテーブル

-- Source table with auto time-to-live
ALTER TABLE source_table DELETE ROWS <expiration_days> DAYS AFTER <time_column_name>;

-- Lakeflow pipelines streaming read
CREATE OR REFRESH STREAMING TABLE my_table AS
SELECT * FROM STREAM(source_table) OPTIONS (skipChangeCommits);

自動 Time-to-Live が有効になっていることを確認する

DESCRIBE TABLE EXTENDEDを使用して、自動有効期間が構成されていることを確認します。 autottl.expireInDaysプロパティとautottl.timestampColumnプロパティが設定されている場合、自動有効期間が有効になります。

[ テーブルのプロパティ] 行に、自動有効期間の設定が表示されます。

DESCRIBE TABLE EXTENDED table_name;

または、SHOW TBLPROPERTIES を使用して、自動 Time-to-Live プロパティを表示します。

SHOW TBLPROPERTIES table_name;

自動 Time-to-Live をオフにする

マネージド Delta Lake または Apache Iceberg テーブルから自動有効期間ポリシーを削除するには:

ALTER TABLE table_name DROP ROW DELETION;

ストリーミングテーブルの自動 Time-to-Live ポリシーを削除するには、パイプラインコードでauto_ttlにNoneを設定し、再発行します。

from pyspark import pipelines as dp

@dp.table(
  auto_ttl=None
)
def function_name():
  return (query)

データのライフサイクル

自動有効期間は、時間ベースの保持要件を持つテーブルのデータライフサイクル管理を自動化するのに役立ちます。

自動有効期間には、複数ステージのデータライフサイクルがあります。行の有効期限が切れた後、予測最適化は DELETE コマンドと VACUUM コマンドを非同期的に実行します。テーブルで削除ベクトルが有効になっている場合、データファイルの書き換えと削除された行の削除をPURGEする前に、予測最適化もVACUUM実行されます。「メタデータのみの削除プロセスを消去してデータの再書き込みを強制する」を参照してください。

正確な削除のタイミングは保証されず、システムの負荷によって異なる場合があります。データが削除されたことを確認する方法については、「システムテーブル」を参照してください。

データ保持要件に合わせて自動有効期間を正しく構成するには、次のステージを確認します。

段階	期間	Description
有効期限	ユーザーは、自動 Time-to-Live がオンの場合に定義します。	行が削除の対象となる時刻列の値から経過した日数。この設定は、自動有効期間を有効にした場合に設定します。
バッファー時間	コマンドあたり最大 3 日間 (`DELETE`、 `VACUUM`)	行が削除対象になるまでと、予測最適化によって削除されるまでの遅延。行の有効期限が切れ、各非同期コマンド ( `DELETE` と `VACUUM`) の間に遅延が発生する可能性があります。通常、各遅延は 3 日未満で、合計で 6 日になります。
データ保持期間	ユーザーはテーブルプロパティを使用して定義します。	削除された行がストレージに保持され、タイムトラベルでアクセス可能な状態で残る期間。 Delta Lake テーブルの場合は、 `delta.deletedFileRetentionDuration`を使用して構成します。 Apache Iceberg テーブルの場合は、 `iceberg.deletedFileRetentionDuration`を使用して構成します。プロパティが設定されていない場合、既定値は 7 日間です。「タイムトラベルクエリのデータ保持を構成する」を参照してください。

VACUUMを使用して完全に削除した後、削除された行は、タイムトラベルを通じてアクセスできなくなります。「VACUUM を使用して未使用のデータファイルを削除する」を参照してください。

データライフサイクルの視覚的なタイムラインを次に示します。時間列の値が t の行は、 VACUUMによってファイルが物理的に削除される前に 4 つのフェーズを経て移動します。

有効期限、バッファー時間、データ保持期間、完全削除フェーズを 1 日のタイムラインに沿って示す、自動有効期間データライフサイクルの図。

ターゲットの有効期限の構成値を計算する

Important

自動 Time-to-Live は、非同期的にデータを削除します。データのライフサイクルを参照してください。

ターゲット日数内にストレージから行を削除するように予測最適化を設定するには、バッファーの最大時間 (6 日) と削除されたファイル保持期間をターゲットから減算します。

target_expiration_days = target_days - 6 - deletedFileRetentionDuration

たとえば、既定の 7 日間の保持期間で 30 日以内に行を削除するには、 expiration_days を 17 DAYS に設定します。

target_expiration_days = 30 - 6 - 7 = 17 days

保持期間が 30 日間の行を 90 日以内に削除するには、 expiration_days を 54 DAYS に設定します。

target_expiration_days = 90 - 6 - 30 = 54 days

自動 Time-to-Live を監視する

システムテーブルを使用すると、自動 Time-to-Live イベントの検証、コストの監視、エラーのアラートの設定を行うことができます。

システムテーブル

予測最適化システムテーブルを使用して、自動 Time to Live イベントを確認します。予測最適化では、期限切れの行を削除するために DELETE を実行し、ストレージからそれらを削除するために VACUUM を実行し、必要に応じて、削除ベクターが有効になっているテーブルでは、削除された行を含まない新しいファイルを作成するために PURGE を実行します。

次のクエリを実行して、過去 7 日間のすべてのテーブルの自動 Time to Live 操作を確認します。

WITH tables_with_deletes AS (
  SELECT DISTINCT catalog_name, schema_name, table_name
  FROM system.storage.predictive_optimization_operations_history
  WHERE
    operation_type = 'DELETE'
    AND timestampdiff(day, start_time, now()) < 7
)
SELECT hist.*
FROM system.storage.predictive_optimization_operations_history AS hist
INNER JOIN tables_with_deletes AS t
  ON hist.catalog_name = t.catalog_name
  AND hist.schema_name = t.schema_name
  AND hist.table_name = t.table_name
WHERE
  hist.operation_type IN ('DELETE', 'PURGE', 'VACUUM')
  AND timestampdiff(day, hist.start_time, now()) < 7
ORDER BY hist.start_time DESC;

自動 Time-to-Live エラーのアラートを設定する

自動有効期間の操作が失敗したときに通知を受信するには、予測最適化システムテーブルで失敗した操作をチェックするクエリを含む Databricks SQL アラートを作成します。アラートの作成方法については Databricks SQL アラートを参照し、クエリ例についてはシステムテーブルのドキュメントを参照してください。

自動 Time-to-Live コストを見積る

過去 30 日間に自動 time-to-live 操作で消費された DBU 数を確認するには、次のクエリを使用します。

WITH tables_with_deletes AS (
  SELECT DISTINCT table_name
  FROM system.storage.predictive_optimization_operations_history
  WHERE
    operation_type = 'DELETE'
    AND timestampdiff(day, start_time, now()) < 30
)
SELECT SUM(usage_quantity) AS total_estimated_dbu
FROM system.storage.predictive_optimization_operations_history AS hist
INNER JOIN tables_with_deletes AS t
  ON hist.table_name = t.table_name
WHERE
  hist.operation_type IN ('DELETE', 'PURGE', 'VACUUM')
  AND hist.usage_unit = 'ESTIMATED_DBU'
  AND timestampdiff(day, hist.start_time, now()) < 30;

特定のテーブルに対する操作を確認する

DESCRIBE HISTORYを使用して、特定のテーブルで最近実行された操作を確認します。

DESCRIBE HISTORY table_name;

制限事項

自動有効期間には、次の制限事項が適用されます。

Important

具体化されたビューでは、自動 Time-to-Live はサポートされていません。
ALTER TABLE および ALTER STREAMING TABLE 構文は、ストリーミングテーブルでの自動 time-to-live の変更ではサポートされていません。既存のストリーミングテーブルで自動有効期間ポリシーを追加または変更するには、パイプラインコードで auto_ttl パラメーターを更新し、パイプラインを再発行します。
列の名前変更は、自動有効期間ポリシーで定義されている時間列ではサポートされていません。列マッピングが有効になっている場合、この制限は引き続き適用されます。「Delta Lake 列マッピングを使用して列の名前を変更および削除する」を参照してください。
まれに、自動 Time-to-Live 操作によってトランザクションの競合が発生する可能性があります。トランザクションの競合のリスクを軽減するには、行レベルのコンカレンシーとの競合を軽減する液体クラスタリングを使用します。表に液体クラスタリングを使用するを参照してください。

プライベートリンクのためにサーバーレスコンピューティングが ADLS にアクセスできない場合、自動 Time-to-Live 操作が失敗する可能性があります。プライベートリンクのエラーメッセージを表示する

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-14

自動 Time-to-Live による行の自動削除

必要条件

自動 Time-to-Live をオンにする

Delta Lake と Apache Iceberg マネージド テーブル

Lakeflow パイプラインを使用したストリーミング テーブル

SQL

Python

自動 Time-to-Live を使用したテーブルからの読み取りのストリーミング

構造化ストリーミング

Lakeflow パイプライン

ストリーミング テーブル

自動 Time-to-Live が有効になっていることを確認する

自動 Time-to-Live をオフにする

データのライフサイクル

ターゲットの有効期限の構成値を計算する

自動 Time-to-Live を監視する

システム テーブル

自動 Time-to-Live エラーのアラートを設定する

自動 Time-to-Live コストを見積る

特定のテーブルに対する操作を確認する

制限事項

フィードバック

その他のリソース

Delta Lake と Apache Iceberg マネージドテーブル

Lakeflow パイプラインを使用したストリーミングテーブル

ストリーミングテーブル

システムテーブル