自動 TTL による行の自動削除

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

自動 Time-to-Live の2つの使用例を次に示します。

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

重要

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

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

Auto time-to-live は、Unity Catalog マネージド Delta Lake テーブル、Apache Iceberg テーブル、および LakeFlow Spark宣言型パイプラインを使用するストリーミングテーブルで利用可能です。

要件

予測的最適化を有効にする必要があります。Unity Catalog マネージドテーブルの予測的最適化を参照してください。
- 自動TTLが有効なテーブルで予測的最適化をオフにすると、自動TTLの実行が防止されます。
自動 TTL ポリシーを設定または削除するには、テーブルに対してMODIFY権限が必要です。基本テーブルのアクセス許可を参照してください。
Databricks Runtime 17.3以降。
- Databricks Runtime 17.2 以下では、自動有効期間機能を持つテーブルの読み取りおよび書き込みが可能です。

自動存続期間をオンにします

ソーステーブルによって、Auto Time-to-Live の有効化方法が異なります：

Delta LakeおよびApache Icebergのマネージドテーブル

新しいテーブルに自動Time-to-Live ポリシーを設定するには、<expiration_days> には0以上の整数を、<time_column_name> にはDATE、TIMESTAMP、またはTIMESTAMP_NTZの型の列を指定します。

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

既存のテーブルに自動Time-to-Liveポリシーを設定するには：

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

たとえば、created_atのタイムスタンプから30日後に行を削除するには、

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

ストリーミングテーブル (Lakeflow Spark宣言型パイプライン)

Lakeflow Spark宣言型パイプラインの新しいストリーミングテーブルに自動有効期間ポリシーを設定するには、<expiration_days>に非負の整数を、<time_column_name>にDATE、TIMESTAMP、またはTIMESTAMP_NTZ型の列を指定してください:

SQL
Python

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={&quot;timestamp_column&quot;: &lt;time_column_name&gt;, &quot;expire_in_days&quot;: &lt;expiration_days&gt;}
)
def function_name():
  return (query)

SQL を使用して自動Time-to-Liveを使用するようにストリーミングテーブルを変更することはサポートされていません。既存のストリーミングテーブルのオートタイムトゥライブを変更するには、パイプラインコードを更新し、再パブリッシュしてください。

自動存続期間を持つテーブルからのストリーミング読み込み

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

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

Structured Streaming
Lakeflow Spark Declarative Pipelines
Streaming tables

Python
# 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")

Python
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>")

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

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

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

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

DESCRIBE TABLE EXTENDED を使用して、自動 TTL が構成されていることを確認してください。autottl.expireInDays および autottl.timestampColumn プロパティが設定されている場合、自動 Time-to-Live が有効になります。

自動Time-to-Live設定は、「**テーブルプロパティ**」行に表示されます。

SQL
DESCRIBE TABLE EXTENDED table_name;

または、SHOW TBLPROPERTIES を使用して自動タイム・ツー・リブプロパティを参照するには：

SQL
SHOW TBLPROPERTIES table_name;

自動有効期間をオフにします。

マネージド Delta Lake または Apache Iceberg テーブルから自動 Time-to-Live ポリシーを削除するには：

SQL
ALTER TABLE table_name DROP ROW DELETION;

ストリーミングテーブルの自動有効期間ポリシーを削除するには、パイプラインコードでauto_ttlをNoneに設定して再公開します。

Python
from pyspark import pipelines as dp

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

データのライフサイクル

自動Time-to-Liveは、時間ベースの保持要件を持つテーブルにおいて、データライフサイクル管理の自動化を支援します。

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

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

データ保持要件に合わせて自動TTLを正しく構成するには、以下の手順を確認してください。

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

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

データのライフサイクルのビジュアルタイムラインを以下に示します。t に書き込まれた行が、VACUUM によってファイルが物理的に削除されるまでに 4 つのフェーズを経る様子です：

1日のタイムラインに沿って、有効期限、バッファ時間、データ保持期間、および永続削除フェーズを示す自動Time-to-Liveデータライフサイクルの図

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

重要

自動TTLによってデータは非同期的に削除されます。データのライフサイクルをご覧ください。

指定した日数内にストレージから行を削除するよう予測的最適化を設定するには、目標から最大バッファ時間（6日間）と削除済みファイルの保持期間を差し引きます：

Text
target_expiration_days = target_days - 6 - deletedFileRetentionDuration

例えば、デフォルトの7日間の保持期間で30日以内の行を削除するには、expiration_daysを17 DAYSに設定します。

Text
target_expiration_days = 30 - 6 - 7 = 17 days

保持期間を30日として90日以内に行を削除するには、expiration_daysを54 DAYSに設定してください：

Text
target_expiration_days = 90 - 6 - 30 = 54 days

自動有効期限のモニタリング

システムテーブルを使用すると、自動Time-to-Liveイベントを検証し、コストを監視し、障害に対するアラートを設定できます。

システムテーブル

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

過去7日間におけるすべてのテーブルの自動TTLオペレーションを確認するには、以下のクエリを実行してください：

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

自動 TTL の失敗に対するアラートを設定します

自動TTL操作が失敗した場合に通知を受け取るには、予測的最適化システムテーブルで失敗した操作を確認するクエリを使用して、Databricks SQLアラートを作成します。アラートの作成方法については「Databricks SQLアラート」を、クエリ例については「システムテーブルのドキュメント」を参照してください。

オートタイムツーライブコストの試算

次のクエリを使用して、過去 30 日間に自動 Time-to-Live オペレーションが消費した DBU の数を確認してください。

SQL
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 を使用して、特定のテーブルで実行された最近の操作を表示します。

SQL
DESCRIBE HISTORY table_name;

制限事項：

自動 Time-to-Live には次の制限が適用されます：

重要

自動有効期間はマテリアライズドビューではサポートされていません。
ALTER TABLE ストリーミングテーブルでの自動 Time-to-Live の変更には、ALTER STREAMING TABLE 構文はサポートされていません。既存のストリーミングテーブルに自動 Time-To-Live ポリシーを追加または変更するには、パイプラインコードで auto_ttl パラメーターを更新し、パイプラインを再公開します。
自動Time-to-Liveポリシーで定義されている時間列に対しては、列の名前変更はサポートされていません。列マッピングをオンにすると、この制限は引き続き適用されます。Delta Lake 列マッピングを使用した列の名前変更と削除を参照してください。
まれに、自動TTL操作によりトランザクション競合が発生する可能性があります。トランザクションの競合のリスクを減らすには、リキッドクラスタリングを使用してください。これにより、行レベルの同時実行との競合が減少します。「テーブルにリキッドクラスタリングを使用する」を参照してください。
プライベートサービス接続が原因でサーバレスコンピュートがGCSにアクセスできない場合、自動のTime-to-Liveオペレーションは失敗する可能性があります。ワークスペースの Private Service Connect を有効にするを参照してください。

要件​

自動存続期間をオンにします​

Delta LakeおよびApache Icebergのマネージドテーブル​

ストリーミングテーブル (Lakeflow Spark宣言型パイプライン)​

自動存続期間を持つテーブルからのストリーミング読み込み​

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

自動有効期間をオフにします。​

データのライフサイクル​

ターゲット有効期限の構成値を計算します。​

自動有効期限のモニタリング​

システムテーブル​

自動 TTL の失敗に対するアラートを設定します​

オートタイムツーライブコストの試算​

特定のテーブルでのオペレーションを確認します​

制限事項：​

要件