Skip to content

Repo sync for protected branch #2953

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
learn-build-service-prod merged 3 commits into from
Oct 31, 2026
Merged

Repo sync for protected branch #2953

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
490bf6e
Document smart hot cache for query acceleration (#7608)
shanisolomon Oct 30, 2026
dbbf6cd
Merge pull request #7630 from MicrosoftDocs/main
learn-build-service-prod[bot] Oct 31, 2026
c7f6f5a
Merging changes synced from https://github.com/MicrosoftDocs/dataexpl…
Oct 31, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions data-explorer/kusto-tocs/management/toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -608,6 +608,9 @@ items:
- name: Query acceleration policy
href: /kusto/management/query-acceleration-policy?view=azure-data-explorer&preserve-view=true
displayName: external table, delta table
- name: Smart hot cache
href: /kusto/management/smart-hot-cache?view=azure-data-explorer&preserve-view=true
displayName: smart acceleration, adaptive hot cache, external table, delta table
- name: Update policy over external delta tables
href: /kusto/management/update-policy?view=azure-data-explorer&preserve-view=true#update-policy-over-external-delta-tables-preview
displayName: external table, delta table
Expand Down
13 changes: 11 additions & 2 deletions data-explorer/kusto/management/alter-merge-query-acceleration-policy-command.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: .alter-merge query acceleration policy Command
description: Learn how to use the .alter-merge query acceleration policy command to accelerate queries over external delta tables.
ms.reviewer: sharmaanshul
ms.topic: reference
ms.date: 09/16/2025
ms.date: 09/22/2026
---

# `.alter-merge query acceleration policy` command
Expand Down Expand Up @@ -38,10 +38,13 @@ You must have at least [Database Admin](../access-control/role-based-access-cont
| 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. |
| Hot | `Timespan` | | The rolling hot period for a static policy. Minimum value = 1 day. If no policy exists, specify `Hot` or both `MinHot` and `MaxHot`. Don't specify this property when configuring smart hot cache because the system manages its value. |
| 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. |
| HotDateTimeColumn | `String` | | Name of a datetime column used to determine hot-cache eligibility. A data file will be cached if its min/max stats for this column are within the configured Hot period and/or HotWindows. If not specified, eligibility is determined using the file modificationTime. Eligibility is computed using [delta log](https://github.com/delta-io/delta/blob/master/PROTOCOL.md#add-file-and-remove-file) metadata only - setting this property does not add query-time overhead|
| MinHot | `Timespan` | | The minimum rolling hot period for [smart hot cache](smart-hot-cache.md). Must be specified together with `MaxHot`. Minimum value = 1 day. |
| MaxHot | `Timespan` | | The maximum rolling hot period for [smart hot cache](smart-hot-cache.md). Must be specified together with `MinHot`. |
| Profile | `String` | | The smart hot cache optimization profile. Supported values are `Performance` (default) and `Cost`. |

### Example

Expand All @@ -57,6 +60,12 @@ In case the external table doesn't have query acceleration policy defined:
{ "IsEnabled": true, "Hot": "1.00:00:00" }
```

To enable smart hot cache:

```json
{ "IsEnabled": true, "MinHot": "1.00:00:00", "MaxHot": "30.00:00:00", "Profile": "Performance" }
```


## Returns

Expand Down
18 changes: 15 additions & 3 deletions data-explorer/kusto/management/alter-query-acceleration-policy-command.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: .alter query acceleration policy command
description: Learn how to use the .alter query acceleration policy command to accelerate queries over external delta tables.
ms.reviewer: sharmaanshul
ms.topic: reference
ms.date: 06/29/2026
ms.date: 09/22/2026
---

# `.alter query acceleration policy` command
Expand Down Expand Up @@ -39,10 +39,13 @@ You must have at least [Database Admin](../access-control/role-based-access-cont
| Property | Type | Required | Description |
| ------------------- | ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| IsEnabled | `Boolean` | :heavy_check_mark: | Indicates whether the policy is enabled. |
| Hot | `Timespan` | :heavy_check_mark: | The hot period defined in the query acceleration policy. Minimum value = 1 d. |
| Hot | `Timespan` | | The rolling hot period for a static policy. Minimum value = 1 day. Required unless both `MinHot` and `MaxHot` are specified. Don't specify this property when configuring smart hot cache because the system manages its value. |
| 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, the external table operates in non-accelerated mode. Default is 5 minutes. Minimum is 1 minute. This property can also be overridden at query time by using the [`external_table()` function's](../query/external-table-function.md) `MaxAgeOverride` parameter. |
| HotDateTimeColumn | `String` | | The Name of a datetime column used to determine hot-cache eligibility. A data file will be cached if its min/max stats for this column are within the configured Hot period and/or HotWindows. If not specified, eligibility is determined using the file modificationTime. Eligibility is computed using [delta log](https://github.com/delta-io/delta/blob/master/PROTOCOL.md#add-file-and-remove-file) metadata only - setting this property does not add query-time overhead |
| MinHot | `Timespan` | | The minimum rolling hot period for [smart hot cache](smart-hot-cache.md). Must be specified together with `MaxHot`. Minimum value = 1 day. |
| MaxHot | `Timespan` | | The maximum rolling hot period for [smart hot cache](smart-hot-cache.md). Must be specified together with `MinHot`. |
| Profile | `String` | | The smart hot cache optimization profile. Supported values are `Performance` (default) and `Cost`. |

::: moniker-end

Expand All @@ -51,11 +54,14 @@ You must have at least [Database Admin](../access-control/role-based-access-cont
| Property | Type | Required | Description |
| ------------------- | ---------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| IsEnabled | `Boolean` | :heavy_check_mark: | Indicates whether the policy is enabled. |
| Hot | `Timespan` | :heavy_check_mark: | The hot period defined in the query acceleration policy. Minimum value = 1 d. |
| Hot | `Timespan` | | The rolling hot period for a static policy. Minimum value = 1 day. Required unless both `MinHot` and `MaxHot` are specified. Don't specify this property when configuring smart hot cache because the system manages its value. |
| 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, the external table operates in non-accelerated mode. Default is 5 minutes. Minimum is 1 minute. This property can also be overridden at query time by using the [`external_table()` function's](../query/external-table-function.md) `MaxAgeOverride` parameter. |
| ManagedIdentity | `string` | | Optional managed identity for which the query acceleration background operations are executed. This identity must have relevant delta table permissions and must be enabled for AutomatedFlows in the cluster / database managed identity policy. For more information, see [Managed identities overview](/azure/data-explorer/managed-identities-overview). |
| HotDateTimeColumn | `String` | | Optional. The name of a datetime column in the Delta table whose values will be used to determine hot-cache eligibility. When set, data files whose rows have values within the configured Hot period (and/or HotWindows) are selected for caching. |
| MinHot | `Timespan` | | The minimum rolling hot period for [smart hot cache](smart-hot-cache.md). Must be specified together with `MaxHot`. Minimum value = 1 day. |
| MaxHot | `Timespan` | | The maximum rolling hot period for [smart hot cache](smart-hot-cache.md). Must be specified together with `MinHot`. |
| Profile | `String` | | The smart hot cache optimization profile. Supported values are `Performance` (default) and `Cost`. |

::: moniker-end

Expand All @@ -69,6 +75,12 @@ You must have at least [Database Admin](../access-control/role-based-access-cont
{ "IsEnabled": true, "Hot": "1.00:00:00" }
```

To enable smart hot cache:

```json
{ "IsEnabled": true, "MinHot": "1.00:00:00", "MaxHot": "30.00:00:00", "Profile": "Performance" }
```

## Returns

The command returns a table with one record that includes the modified policy object.
Expand Down
4 changes: 3 additions & 1 deletion data-explorer/kusto/management/query-acceleration-policy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Query acceleration policy
description: Learn how to use the query acceleration policy to accelerate queries over external delta tables.
ms.reviewer: sharmaanshul
ms.topic: reference
ms.date: 06/29/2026
ms.date: 09/22/2026
---
# Query acceleration policy

Expand All @@ -21,6 +21,8 @@ Query acceleration is supported in Eventhouse over OneLake, Azure Data Lake Stor
To enable query acceleration in the Fabric UI, see [Query acceleration over OneLake shortcuts](https://go.microsoft.com/fwlink/?linkid=2296674).
::: moniker-end

To automatically align the accelerated data period with observed query patterns, configure [smart hot cache](smart-hot-cache.md).

> [!IMPORTANT]
> To troubleshoot problems with query acceleration, see [Troubleshoot query acceleration over external delta tables](query-acceleration-troubleshooting-guide.md).

Expand Down
4 changes: 2 additions & 2 deletions data-explorer/kusto/management/show-query-acceleration-policy-command.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: .show query acceleration policy command
description: Learn how to use the .show query acceleration policy command to accelerate queries over external delta tables.
ms.reviewer: sharmaanshul
ms.topic: reference
ms.date: 09/16/2025
ms.date: 09/22/2026
---

# `.show query acceleration policy` command
Expand Down Expand Up @@ -50,7 +50,7 @@ The command returns a table with a record per external table with the following

| PolicyName | EntityName | Policy | ChildEntities | EntityType |
| ----------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------- |
| QueryAccelerationPolicy | [MyDatabase].[MyExternalTable] | `{<br> "IsEnabled": true,<br> "Hot": "1.00:00:00",<br> "HotWindows": [{"MinValue":"2025-07-06 07:53:55","MaxValue":"2025-07-07 07:53:55"}], "MaxAge": "5m", "HotDateTimeColumn":"dt1"}` | | ExternalTable |
| QueryAccelerationPolicy | [MyDatabase].[MyExternalTable] | `{<br> "IsEnabled": true,<br> "Hot": "7.00:00:00",<br> "MinHot": "1.00:00:00",<br> "MaxHot": "30.00:00:00",<br> "Profile": "Performance",<br> "MaxAge": "5m",<br> "HotDateTimeColumn": "dt1"<br>}` | | ExternalTable |

## Related content

Expand Down
71 changes: 71 additions & 0 deletions data-explorer/kusto/management/smart-hot-cache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
---
title: Smart hot cache for query acceleration
description: Learn how smart hot cache automatically adjusts the query acceleration hot period for external delta tables.
ms.reviewer: sharmaanshul
ms.topic: concept-article
ms.date: 09/22/2026
---

# Smart hot cache for query acceleration

> [!INCLUDE [applies](../includes/applies-to-version/applies.md)] [!INCLUDE [fabric](../includes/applies-to-version/fabric.md)] [!INCLUDE [azure-data-explorer](../includes/applies-to-version/azure-data-explorer.md)]

The [query acceleration policy](query-acceleration-policy.md) uses the `Hot` property to determine the rolling period of external delta table data to accelerate. With a static policy, you set `Hot` manually and update it as query patterns change.

Smart hot cache automatically adjusts `Hot` based on observed query patterns. You define the allowed range with `MinHot` and `MaxHot`, and the system periodically selects a value within that range.

> [!NOTE]
> Smart hot cache adjusts only the rolling `Hot` period. It doesn't create or modify `HotWindows`.

## Optimization profiles

Use the `Profile` property to control what happens when no query signal is available.

| Profile | No-signal behavior | Recommended use case |
|---|---|---|
| `Performance` | Keeps the current `Hot` value. This profile is the default. | You want to optimize for query performance. |
| `Cost` | Sets `Hot` to `MinHot`, reducing caching to the configured minimum when there are no queries. | You want to optimize cost by minimizing the hot-cache footprint during periods without query activity. |

When query signal is available, both profiles use the calculated P95 lookback constrained by `MinHot` and `MaxHot`.

## How smart hot cache works

Smart hot cache observes query patterns and adjusts `Hot` once a day based on the 95th percentile (P95) query lookback over the previous seven days. The adjusted value is constrained to the range from `MinHot` through `MaxHot`.

If you configure `HotDateTimeColumn`, smart hot cache uses query patterns for that column. Otherwise, it uses the first datetime column in the external table schema that has observed query activity.

## Configure smart hot cache

Set `MinHot` and `MaxHot` to different values to enable smart hot cache. Both properties are required.

The following example configures a range of one through 30 days and uses the default `Performance` profile:

```kusto
.alter external table MyExternalTable policy query_acceleration '{"IsEnabled": true, "MinHot": "1.00:00:00", "MaxHot": "30.00:00:00", "Profile": "Performance"}'
```

When you configure `MinHot` and `MaxHot`, don't specify `Hot`. The system initializes `Hot` to `MinHot` and then manages its value within the configured range.

## Configuration rules

* Set `MinHot` and `MaxHot` together.
* `MinHot` must be less than or equal to `MaxHot`.
* `MinHot` must be at least one day.
* Don't specify `Hot` when configuring smart hot cache. The system manages this value.
* Enable smart hot cache only when the policy is enabled and `MinHot` and `MaxHot` have different values.
* If `MinHot` and `MaxHot` are equal, the policy uses a static `Hot` period.

## Return to a static hot period

Set `MinHot` and `MaxHot` to the same value to use a static hot period. When both values are equal, smart hot cache doesn't adjust the period.

```kusto
.alter external table MyExternalTable policy query_acceleration '{"IsEnabled": true, "MinHot": "7.00:00:00", "MaxHot": "7.00:00:00"}'
```

## Related content

* [Query acceleration policy](query-acceleration-policy.md)
* [`.alter query acceleration policy` command](alter-query-acceleration-policy-command.md)
* [`.alter-merge query acceleration policy` command](alter-merge-query-acceleration-policy-command.md)
* [`.show query acceleration policy` command](show-query-acceleration-policy-command.md)
3 changes: 3 additions & 0 deletions data-explorer/kusto/management/toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -607,6 +607,9 @@ items:
- name: Query acceleration policy
href: query-acceleration-policy.md
displayName: external table, delta table
- name: Smart hot cache
href: smart-hot-cache.md
displayName: smart acceleration, adaptive hot cache, external table, delta table
- name: Update policy over external delta tables
href: update-policy.md#update-policy-over-external-delta-tables-preview
displayName: external table, delta table
Expand Down
Loading