Table retention policy

Control whole-file expiry for a table in the current account. Updates require account administrator permission and a query scope allowing account management and control commands.

Spec

.alter table <name> policy retention <timespan>
.alter table <name> policy retention '<JSON policy>'
.show table <name> policy retention
.delete table <name> policy retention

The timespan form updates only duration; zero disables time expiry while preserving the size limit. The JSON form replaces both limits. Omitted or null properties disable a limit. Delete disables both limits without deleting the table.

Parameters

Return Value

Show returns TableName, DurationSeconds, and MaxSizeBytes. Disabled limits are null. Updates return no records.

Example

.alter table 'logs' policy retention '{"durationSeconds":604800,"maxSizeBytes":10737418240}'
.show table 'logs' policy retention

Enforcement

The background sweep runs approximately every ten seconds. Either limit can retire files. Time expiry uses the latest record timestamp, inclusive of the cutoff; mixed-age files remain until wholly expired. Newly ingested historical records can expire immediately after publication.

Size counts committed logical table files once, excluding replicas, uncommitted files and attached blobs. After time expiry, oldest files are removed until the remaining size fits. Files with unknown record timestamps use creation time for ordering and do not expire by time. A file larger than the budget can be removed even when it is the last file.

Limits are eventual targets. Ingestion can temporarily exceed them; physical reclamation is asynchronous. Blob references retire transactionally with table files, and shared references continue protecting content.

HTTP and schema browser

Administrators can use the schema browser's Retention action to load, edit or disable limits. Enabling or tightening limits requires confirmation.

For administration without dialogs, open Account Management → Tables and select a table. The page shows schema and retention settings and previews the Kusto command before applying a change. It also supports adding columns, dropping columns, truncating data, and deleting tables. Existing column types remain unchanged. Destructive changes require inline confirmation.

Authenticated GET, PUT and DELETE use /accounts/{accountId}/tables/{tableName}/retention and require account/global administrator permission with account-management capability. PUT accepts the same JSON policy object and replaces both limits. GET and successful mutations return the normalized object. DELETE is idempotent for an existing table. Invalid policies return 400, unauthorized access 403, and missing tables 404. Unknown properties, zero, fractional and negative values are rejected; use null to disable a limit.