.drop extents command

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.