.drop extents command

Applies to: ✅ Azure Data Explorer

Drops extents from a specified database or table.

This command has several variants: In one, the extents to be dropped are specified by a Kusto query. In the other variants, extents are specified using a mini-language described below.

Note

Data shards are called extents, and all commands use "extent" or "extents" as a synonym. For more information on extents, see Extents (Data Shards) Overview.

Caution

If you drop an extent, all the rows in that extent will be deleted. To delete individual records, use Soft delete.

Permissions

If the TableName is specified, you must have at least Table Admin permissions to run the command.

If the TableName isn't specified, you must have at least Database Admin permissions to run the command.

Syntax

Drop extents with a query

.drop extents [whatif] <| Query

Learn more about syntax conventions.

Parameters

Name Type Required Description
whatif string If specified, the extents will be reported instead of being dropped.
Query string ✔️ The results of this Kusto Query Language (KQL) query specify the source tables and the extent IDs to be dropped. Should return a recordset with columns called "ExtentId" and "TableName".

Drop a specific or multiple extents

.drop extents (ExtentIds) from TableName

Parameters

Name Type Required Description
ExtentIds guid ✔️ One or more comma-separated unique identifiers of the extents to be dropped.
TableName string The name of the table where the extent to be dropped is located.

Drop extents by specified properties

.drop extents [older N (days | hours)] from (TableName | all tables) [trim by (extentsize | datasize) Size (MB | GB | bytes)] [limit LimitCount]

Parameters

Name Type Required Description
N int ✔️ Drop extents older than N days/hours.
TableName string The name of the table where the extent to be dropped is located
Size int ✔️ Trim the data in the database until the sum of extents matches the required size (MaxSize).
LimitCount int ✔️ Applied to first LimitCount extents.

The command supports emulation mode that produces an output as if the command would have run, but without actually executing it. Use .drop-pretend instead of .drop.

Returns

The command returns a table with the following information.

Output parameter Type Description
ExtentId string ExtentId that was dropped because of the command
TableName string Table name, where extent belonged
CreatedOn dateTime Timestamp that holds information about when the extent was initially created

For example, the return value of a command might look like the following table.

Extent ID Table Name Created On
43c6e03f-1713-4ca7-a52a-5db8a4e8b87d TestTable 2015-01-12 12:48:49.4298178

Examples

Drop a specific extent

Use an Extent ID to drop a specific extent.

.drop extent 609ad1e2-5b1c-4b79-90c0-1dec262e9f46 from Table1

Drop multiple extents

Use a list of Extent IDs to drop multiple extents.

.drop extents (609ad1e2-5b1c-4b79-90c0-1dec262e9f46, 310a60c6-8529-4cdf-a309-fe6aa7857e1d) from Table1

Remove all extents by time created

Remove all extents created more than 10 days ago, from all tables in database MyDatabase

.drop extents <| .show database MyDatabase extents | where CreatedOn < now() - time(10d)

Remove some extents by time created

Remove all extents in tables Table1 and Table2 whose creation time was over 10 days ago

.drop extents older 10 days from tables (Table1, Table2)

Remove an extent using extent_id()

Remove an extent from a table using the built-in extent_id() function.

.drop extents  <|
    StormEvents
    | where EventId == '66144'
    | summarize by ExtentId = extent_id(), TableName = "StormEvents"

Emulation mode: Show which extents would be removed by the command

Note

Extent ID parameter isn't applicable for this command.

.drop-pretend extents older 10 days from all tables

Remove all extents from 'TestTable'

.drop extents from TestTable

Note

Removing all extents does not necessarily delete all the data in the table, if streaming ingestion is enabled. To clear all the data of a table, use .clear table data TestTable.