保留策略Retention policy

保留策略控制自动从表或具体化视图中删除数据的机制。The retention policy controls the mechanism that automatically removes data from tables or materialized views. 删除持续传递到表中且相关性基于期限的数据是非常有用的。It's useful to remove data that continuously flows into a table, and whose relevance is age-based. 例如，该策略可用于保存诊断事件的表，这些事件在两周后可能变得无意义。For example, the policy can be used for a table that holds diagnostics events that may become uninteresting after two weeks.

可以为特定的表或具体化视图，或整个数据库配置保留策略。The retention policy can be configured for a specific table or materialized view, or for an entire database. 然后，该策略将应用于数据库中所有不会替代它的表。The policy then applies to all tables in the database that don't override it.

设置保留策略对于不断引入数据的群集很重要，因为这会限制成本。Setting up a retention policy is important for clusters that are continuously ingesting data, which will limit costs.

保留策略“外部”的数据可以删除。Data that is "outside" the retention policy is eligible for removal. 不保证删除操作发生的具体时间。There is no specific guarantee when removal occurs. 即使触发了保留策略，数据也可能暂时保留。Data may "linger" even if the retention policy is triggered.

保留策略经常设置为引入后限制数据的使用期限。The retention policy is most commonly set to limit the age of the data since ingestion. 有关详细信息，请参阅 SoftDeletePeriod。For more information, see SoftDeletePeriod.

备注

  • 删除时间不确切。The deletion time is imprecise. 系统保证在超过限制之前不会删除数据，但超过限制后不会立即删除数据。The system guarantees that data won't be deleted before the limit is exceeded, but deletion isn't immediate following that point.
  • 可以在表级保留策略中设置软删除周期 0，但不能在数据库级保留策略中进行此设置。A soft-delete period of 0 can be set as part of a table-level retention policy, but not as part of a database-level retention policy.
    • 完成此操作后，引入的数据将不会提交到源表，从而无需长期保存数据。When this is done, the ingested data won't be committed to the source table, avoiding the need to persist the data. 因此，只能将 Recoverability 设置为 Disabled。As a result, Recoverability can only be set to Disabled.
    • 将数据引入到表中时，此类配置非常有用。Such a configuration is useful mainly when the data gets ingested into a table. 事务性更新策略用于转换它，并将输出重定向到另一个表。A transactional update policy is used to transform it and redirect the output into another table.

策略对象The policy object

保留策略包括以下属性：A retention policy includes the following properties:

  • SoftDeletePeriod ：SoftDeletePeriod :
    • 保证数据可查询的时间跨度。Time span for which it's guaranteed that the data is kept available to query. 时间段从引入数据的时间开始度量。The period is measured starting from the time the data was ingested.
    • 默认为 100 years。Defaults to 100 years.
    • 更改表或数据库的软删除时段时，新值将同时应用于现有数据和新数据。When altering the soft-delete period of a table or database, the new value applies to both existing and new data.
  • 可恢复性 ：Recoverability :
    • 删除数据后的数据可恢复性（启用/禁用）。Data recoverability (Enabled/Disabled) after the data was deleted.
    • 默认为 Enabled。Defaults to Enabled.
    • 如果设置为 Enabled，则数据可以在软删除后的 14 天内被恢复。If set to Enabled, the data will be recoverable for 14 days after it's been soft-deleted.

控制命令Control commands

默认值Defaults

默认情况下，在创建数据库或表时，不定义保留策略。By default, when a database or a table is created, it doesn't have a retention policy defined. 通常，将创建数据库，然后立即由其创建者根据已知要求设置其保留策略。Normally, the database is created and then immediately has its retention policy set by its creator according to known requirements. 对尚未设置策略的数据库或表的保留策略运行 show 命令时，Policy 显示为 null。When you run a show command for the retention policy of a database or table that hasn't had its policy set, Policy appears as null.

可以使用以下命令应用默认的保留策略（具有上述默认值）。The default retention policy, with the default values mentioned above, can be applied using the following command.

.alter database DatabaseName policy retention "{}"
.alter table TableName policy retention "{}"
.alter materialized-view ViewName policy retention "{}"

该命令会将以下策略对象应用于数据库或表。The command results in the following policy object applied to the database or table.

{
  "SoftDeletePeriod": "36500.00:00:00", "Recoverability":"Enabled"
}

可以使用以下命令来清除数据库或表的保留策略。Clearing the retention policy of a database or table can be done using the following command.

.delete database DatabaseName policy retention
.delete table TableName policy retention

示例Examples

适用于有名为 MyDatabase 的数据库和有表 MyTable1、MyTable2 和 MySpecialTable 的群集。For a cluster that has a database named MyDatabase, with tables MyTable1, MyTable2, and MySpecialTable.

软删除期为七天，禁用可恢复性Soft-delete period of seven days and recoverability disabled

将数据库中的所有表的软删除期设置为七天，并禁用可恢复性。Set all tables in the database to have a soft-delete period of seven days and disabled recoverability.

  • 选项 1（建议） ：设置数据库级别的保留策略，并验证是否未设置表级别的策略。Option 1 (Recommended) : Set a database-level retention policy, and verify there are no table-level policies set.
.delete table MyTable1 policy retention        // optional, only if the table previously had its policy set
.delete table MyTable2 policy retention        // optional, only if the table previously had its policy set
.delete table MySpecialTable policy retention  // optional, only if the table previously had its policy set
.alter-merge database MyDatabase policy retention softdelete = 7d recoverability = disabled
.alter-merge materialized-view ViewName policy retention softdelete = 7d
  • 选项 2 ：为每个表设置一个表级别的保留策略，其软删除期为七天，并禁用可恢复性。Option 2 : For each table, set a table-level retention policy, with a soft-delete period of seven days and recoverability disabled.
.alter-merge table MyTable1 policy retention softdelete = 7d recoverability = disabled
.alter-merge table MyTable2 policy retention softdelete = 7d recoverability = disabled
.alter-merge table MySpecialTable policy retention softdelete = 7d recoverability = disabled

软删除期为七天，启用可恢复性Soft-delete period of seven days and recoverability enabled

  • 将表 MyTable1 和 MyTable2 设置为具有七天的软删除期，并启用可恢复性。Set tables MyTable1 and MyTable2 to have a soft-delete period of seven days and recoverability enabled.

  • 将表 MySpecialTable 设置为具有 14 天的软删除期，并禁用可恢复性。Set MySpecialTable to have a soft-delete period of 14 days and recoverability disabled.

  • 选项 1（建议） ：设置数据库级保留策略，并设置表级别的保留策略。Option 1 (Recommended) : Set a database-level retention policy, and set a table-level retention policy.

.delete table MyTable1 policy retention   // optional, only if the table previously had its policy set
.delete table MyTable2 policy retention   // optional, only if the table previously had its policy set
.alter-merge database MyDatabase policy retention softdelete = 7d recoverability = disabled
.alter-merge table MySpecialTable policy retention softdelete = 14d recoverability = enabled
  • 选项 2 ：为每个表设置一个表级别保留策略，并设置相关的软删除期和可恢复性。Option 2 : For each table, set a table-level retention policy, with the relevant soft-delete period and recoverability.
.alter-merge table MyTable1 policy retention softdelete = 7d recoverability = disabled
.alter-merge table MyTable2 policy retention softdelete = 7d recoverability = disabled
.alter-merge table MySpecialTable policy retention softdelete = 14d recoverability = enabled

软删除期为七天，并且 MySpecialTable 无限期保留其数据Soft-delete period of seven days, and MySpecialTable keeps its data indefinitely

将表 MyTable1 和 MyTable2 设置为具有七天的软删除期，并且 MySpecialTable 无限期地保留其数据。Set tables MyTable1 and MyTable2 to have a soft-delete period of seven days, and have MySpecialTable keep its data indefinitely.

  • 选项 1 ：为 MySpecialTable 设置数据库级别的保留策略，并设置一个软删除期为 100 年的表级别保留策略（默认保留策略）。Option 1 : Set a database-level retention policy, and set a table-level retention policy, with a soft-delete period of 100 years, the default retention policy, for MySpecialTable.
.delete table MyTable1 policy retention   // optional, only if the table previously had its policy set
.delete table MyTable2 policy retention   // optional, only if the table previously had its policy set
.alter-merge database MyDatabase policy retention softdelete = 7d
.alter table MySpecialTable policy retention "{}" // this sets the default retention policy
  • 选项 2 ：对于表 MyTable1 和表 MyTable2，设置表级别的保留策略，并验证 MySpecialTable 的数据库级别和表级别策略未设置。Option 2 : For tables MyTable1 and MyTable2, set a table-level retention policy, and verify that the database-level and table-level policy for MySpecialTable aren't set.
.delete database MyDatabase policy retention   // optional, only if the database previously had its policy set
.delete table MySpecialTable policy retention   // optional, only if the table previously had its policy set
.alter-merge table MyTable1 policy retention softdelete = 7d
.alter-merge table MyTable2 policy retention softdelete = 7d
  • 选项 3 ：对于表 MyTable1 和表 MyTable2，设置表级别的保留策略。Option 3 : For tables MyTable1 and MyTable2, set a table-level retention policy. 为表 MySpecialTable 设置一个软删除期为 100 年的表级别保留策略（默认保留策略）。For table MySpecialTable, set a table-level retention policy with a soft-delete period of 100 years, the default retention policy.
.alter-merge table MyTable1 policy retention softdelete = 7d
.alter-merge table MyTable2 policy retention softdelete = 7d
.alter table MySpecialTable policy retention "{}"