.alter-merge query acceleration policy command

Applies to: ✅ Azure Data Explorer

Alters the query acceleration policy properties of a specific external delta table.

Tip

Use .alter-merge to add or update properties without replacing the whole policy. Array properties are merged (new elements are added, existing values preserved). Use .alter to fully replace the policy, including overwriting arrays.

For limitations, see Limitations.

Permissions

You must have at least Database Admin permissions to run this command.

Syntax

.alter-merge external table ExternalTableName policy query_acceleration 'JSON-serialized policy'

Parameters

Name Type Required Description
ExternalTableName string ✔️ The name of the external delta table.
JSON-serialized policy string ✔️ String literal holding a JSON property bag.

JSON property bag

Property Type Required Description
IsEnabled Boolean Indicates whether the policy is enabled. This property is required if no query acceleration policy is defined on the external table.
Hot Timespan The hot period defined in the query acceleration policy. Minimum value = 1 d. This property is required if no query acceleration policy is defined on the external table.
HotWindows DateTime One or more optional time windows. Delta data files created within these time windows are accelerated.
MaxAge Timespan The external table returns accelerated data if the last index refresh time is greater than @now - MaxAge. Otherwise, external table operates in nonaccelerated mode. Default is 5 minutes. Minimum is 1 minute.

Note

Query acceleration is applied to data within a specific time period, defined as timespan, starting from the modificationTime as stated for each file in the delta log.

Example

In case the external table has query acceleration policy defined:

{ "Hot": "1.00:00:00" }

In case the external table doesn't have query acceleration policy defined:

{ "IsEnabled": true, "Hot": "1.00:00:00" }

Returns

The command returns a table with one record that includes the modified policy object.

Column Type Description
PolicyName string The name of the policy - QueryAcceleration
EntityName string The fully qualified name of the entity: [DatabaseName].[ExternalTableName]
Policy string A JSON-serialization of the query acceleration policy that is set on the external delta table
ChildEntities string The child entities this policy affects - null
EntityType string The type of the entity the policy applies to - ExternalTable

Example

In case the external table has query acceleration policy defined:

.alter-merge external table MyExternalTable policy query_acceleration '{"Hot": "1.00:00:00", "MaxAge" : "00:05:00"}'

In case the external table doesn't have query acceleration policy defined:

.alter-merge external table MyExternalTable policy query_acceleration '{"IsEnabled": true, "Hot": "1.00:00:00", "MaxAge" : "00:05:00"}'

Related content