.move extents command

Applies to: ✅ Azure Data Explorer

This command runs in the context of a specific database. It moves the specified extents from the source table to the destination table.

Note

• For more information on extents, see Extents (data shards) overview.
• A .move command either completes or fails for all source extents. There are no partial outcomes.

Permissions

You must have at least Table Admin permissions for the source and destination tables.

Restrictions

• Both source and destination tables must be in the context database.
• All columns in the source table are expected to exist in the destination table with the same name and data type.
• If the destination table is a source table of a materialized view, the command might fail since the materialized view won't process the records in the moved extents. See more details in the materialized views limitations page. You can workaround this error by setting a new ingestion time during the move command. See setNewIngestionTime in supported properties.

Syntax

Move all extents:

.move [async] extents all from table sourceTableName to table DestinationTableName [ with (PropertyName = PropertyValue [, ...])]

Move extents specified by ID:

.move [async] extents from table SourceTableName to table DestinationTableName [ with (PropertyName = PropertyValue [, ...])] ( GUID [, ...] )

Move extents specified by query results:

.move [async] extents to table DestinationTableName [ with (PropertyName = PropertyValue [,...])] <| Query

Learn more about syntax conventions.

Parameters

Name	Type	Required	Description
async	string		If specified, the command runs asynchronously.
SourceTableName	string	✔️	The name of the table containing the extents to move.
DestinationTableName	string	✔️	The name of the table to which to move the extents.
PropertyName, PropertyValue	string		One or more Supported properties.
Query	string	✔️	The results of this Kusto Query Language (KQL) query specify the source table and the extent IDs to be moved from it. Should return a recordset with columns called "ExtentId" and "TableName".

Supported properties

Property name	Type	Required	Description
setNewIngestionTime	bool		If set to true, a new ingestion time is assigned to all records in extents being moved. This is useful when records should be processed by workloads that depend on database cursors, such as materialized views and continuous data export.
extentCreatedOnFrom	datetime	✔️	Apply on extents created after this point in time.
extentCreatedOnTo	datetime	✔️	Apply on extents created before this point in time.

Note

For better performance, set extentCreatedOnFrom and extentCreatedOnTo parameters to the smallest possible range.

Returns

When the command is run synchronously, a table with the following schema is returned.

Output parameter	Type	Description
OriginalExtentId	string	A unique identifier (GUID) for the original extent in the source table, which has been moved to the destination table.
ResultExtentId	string	A unique identifier (GUID) for the result extent that has been moved from the source table to the destination table. Upon failure - "Failed".
Details	string	Includes the failure details, in case the operation fails.

When the command is run asynchronously, an operation ID (GUID) is returned. Monitor the operation's status with the .show operations command, and retrieve the results of a successful execution with the .show operation details command.

Examples

Move all extents

Move all extents in table MyTable to table MyOtherTable:

.move extents all from table MyTable to table MyOtherTable

Move two specific extents in a specified creation time range

Move two specific extents (by their extent IDs) in a specified creation time range from table MyTable to table MyOtherTable:

.move extents from table MyTable to table MyOtherTable with (extentCreatedOnFrom=datetime(2023-03-10), extentCreatedOnTo=datetime(2023-03-12)) (AE6CD250-BE62-4978-90F2-5CB7A10D16D7,399F9254-4751-49E3-8192-C1CA78020706)

Move all extents in a specified creation time range from specific tables

Move all extents in a specified creation time range from specific tables (MyTable1, MyTable2) to table MyOtherTable:

.move extents to table MyOtherTable with (extentCreatedOnFrom=datetime(2023-03-10), extentCreatedOnTo=datetime(2023-03-12)) <| .show tables (MyTable1,MyTable2) extents

Move all extents with set new ingestion time

.move extents all from table MyTable to table MyOtherTable with (setNewIngestionTime=true)

Sample output

OriginalExtentId	ResultExtentId	Details
e133f050-a1e2-4dad-8552-1f5cf47cab69	0d96ab2d-9dd2-4d2c-a45e-b24c65aa6687
cdbeb35b-87ea-499f-b545-defbae091b57	a90a303c-8a14-4207-8f35-d8ea94ca45be
4fcb4598-9a31-4614-903c-0c67c286da8c	97aafea1-59ff-4312-b06b-08f42187872f
2dfdef64-62a3-4950-a130-96b5b1083b5a	0fb7f3da-5e28-4f09-a000-e62eb41592df