.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