排查针对外部增量表的查询加速问题

适用于：✅Azure 数据资源管理器

查询加速策略通过缓存增量表元数据和数据文件来加速对外部增量表的查询。该策略定义哪些日期范围（返回天数和热窗口）加速，以便对这些范围的查询可以更快地运行。

查询加速功能由以下组件组成：

一个后台作业，用于维护增量表元数据的本地快照（目录）。
用于缓存增量表数据文件的后台作业。
利用目录和缓存数据的查询时增强功能。

若要了解为什么事情未按预期工作，请务必确定哪些组件无法正常工作。

本文可帮助你排查以下情况：

对加速的外部增量表的查询将返回 过时的数据，或
对加速的外部增量表的查询 速度低于预期

先决条件

运行以下命令，确保对外部表启用查询加速：
```
.show external table <ETName> policy query_acceleration
| project isnotnull(Policy) and todynamic(Policy).IsEnabled
```
如果此命令返回 false，请使用 .alter query acceleration policy 该命令启用查询加速策略。
确保增量表符合 Delta 协议。

查询加速功能假定增量表符合 Delta 协议。不支持直接在增量表（例如编辑事务日志或 parquet 文件）上执行的手动作，并可能导致意外行为。

如果在增量表上执行了此类作，请重新创建外部表并重新启用查询加速策略。

查询返回过时数据

这是数据新鲜度问题：查询结果不会反映基础增量表中的最新数据。

查询加速会定期刷新加速数据，以便结果不低于策略中配置的 MaxAge 值。根据设计，对加速外部表的查询可能会返回滞后于最新增量表版本的数据。MaxAge 设置为 MaxAge 查询时可接受的最大数据过期时间。

可以通过两种方式控制有效 MaxAge ：

MaxAge使用.alter query acceleration policy命令在查询加速策略中配置属性。
使用external_table()的参数替代MaxAgeOverride每个查询。

查询运行速度不够快

这是性能问题：查询速度低于预期，加速似乎不会提高性能。

出现这种情况的原因有以下几个：

查询加速目录不可用（过期或从未生成） - 请参阅“检查目录是否不可用”部分
查询扫描非访问数据 - 请参阅“检查查询是否超过非访问数据”部分
查询不符合 KQL 最佳做法 - 请参阅 KQL 最佳做法

检查目录是否不可用

查询加速对包含增量表元数据快照的外部表使用本地目录。如果此目录尚未在配置 MaxAge 中更新（请参阅查询加速策略 MaxAge 的属性），则被视为 不可用 ，并且不会在查询时使用。在这种情况下，查询会回退到直接读取远程增量表，这可能会明显降低。

使用以下命令提取目录的当前状态：

.show external table [ETName] details
| extend MinimumUpdateTime = now() - totimespan(todynamic(QueryAccelerationPolicy).MaxAge)
| project IsCatalogUnusable = MinimumUpdateTime > todatetime(todynamic(QueryAccelerationState).LastUpdatedDateTime)

IsCatalogUnusable == true 指示目录已过时，不会使用查询加速。

排查不可用的目录问题

若要了解目录为何不可用，请先检查查询加速状态是否正常，并根据需要解决不正常的原因。

运行：

.show external table [ETName] details
| project state = todynamic(QueryAccelerationState)
| project IsHealthy = state.IsHealthy, UnhealthyReason = state.NotHealthyReason

如果状态正常，但目录仍然过时，可能是最近启用了查询加速策略。请参阅最近已启用查询加速策略
如果状态 不正常，请参阅查询加速运行不正常状态 - 了解和缓解。

最近启用了查询加速策略

首次启用查询加速策略时，生成初始目录需要完成才能在查询中使用。在此时间段内 LastUpdatedDateTime ，该值为空：

.show external table [ETName] details
| project todynamic(QueryAccelerationState).LastUpdatedDateTime

如果 LastUpdatedDateTime 为空，请让第一次更新完成一段时间。这通常需要几分钟时间。后续更新预计要快得多。

查询加速运行不正常状态 - 了解和缓解

当外部表的查询加速不正常时，可以使用以下命令检索不正常的原因：

.show external table [ETName] details
| project todynamic(QueryAccelerationState).NotHealthyReason

使用下表来了解和缓解常见的不正常状态。

注释

若要重新启用外部表的查询加速策略，请运行以下命令：

.execute database script <|
.alter-merge external table [ETName] policy query_acceleration @'{"IsEnabled":false}'
.alter-merge external table [ETName] policy query_acceleration @'{"IsEnabled":true}'

不健康的原因	示例 `NotHealthyReason`	Action
禁止外部表访问	`InaccessibleDeltaTable: Access to Delta table is forbidden`	验证外部表的连接字符串，包括身份验证方法，以及基础存储的权限是否正确。
外部表连接字符串不指向有效的增量表	`DeltaTableNotFound: Delta table does not exist`	更改外部表的连接字符串，使其面向有效的 Delta 表位置。确保路径指向表的根文件夹，而不是_delta_log目录。
增量表列映射模式已更改	`ColumnMappingModeChange: Column mapping mode has changed. Previous: 'None', New: 'Name'`	重新创建外部表并重新启用查询加速策略。
增量表列映射已更改	`NewColumnMapping: New column mapping was introduced. Column 'Col1' is now mapped to 'Col2'`	重新创建外部表并重新启用查询加速策略，使列映射与增量表保持一致。
增量表列类型已更改	`ColumnTypeMismatch: Column 'Col1' type has changed. Previous delta type: 'long', New type: 'string'. Respective external table type: long`	重新创建（或更改）外部表，使其架构与增量表列类型保持一致，然后重新启用查询加速。
找不到热日期/时间列	`HotDateTimeColumn 'Col1' does not exist as a datetime column in the Delta table schema`	更改查询加速策略以包含有效的 `HotDateTimeColumn` （增量表中的类型 `datetime` 列），或根据需要将属性留空。
Delta 表具有以下不受支持的查询加速功能之一 • 列映射模式“名称” • 使用绝对路径引用文件的 AddFile 事务 • 具有绝对路径的删除向量	`Unsupported feature: Column mapping of type 'Id'`	使用受支持的配置（例如，使用 `Name` 列映射类型）重新创建增量表，然后重新启用查询加速。
托管标识错误	`Managed identity must be specified for external tables with impersonation authentication.`	确保查询加速策略包含具有以下条件的有效托管标识： • 对 Delta 表的相应权限 `AutomatedFlows`• 群集或数据库托管标识策略中的使用类型。

检查查询是否针对未访问的数据

若要完全受益于查询加速，必须通过 加速数据执行查询。非加速数据直接从远程增量表读取，这可能会导致严重的延迟。

使用以下命令并筛选包含相关查询的时间范围：

.show queries
| where StartedOn > ago(1h)
| extend ExternalDataStats = OverallQueryStats.input_dataset_statistics.external_data

如果 ExternalDataStats.iterated_artifacts 或 ExternalDataStats.downloaded_items 大于 0，则表示数据是从远程增量表（非加速路径）读取的。以下部分可帮助你了解原因。

对非访问数据进行查询故障排除

查询可能读取非加速数据的原因有两个主要原因：

查询时间筛选器未完全在查询加速热时段或热时段内。
策略热期中的数据未完全缓存。

查询筛选器未完全在热时段或热时段内

运行以下命令以查看热缓存属性，并确保查询筛选器匹配它们：

.show external table [ETName] policy query_acceleration
| project Policy = todynamic(Policy)
| project Policy.Hot, Policy.HotWindows

确保查询的时间筛选器完全包含在配置的 Hot 时间段内或定义的 HotWindows时间段内。

如果是一次性查询，则不建议更改策略。但是，如果预计在同一时间范围内运行多个查询，该查询位于配置的 Hot 时间段之外或已定义 HotWindows ，并且需要改进性能，请通过以下方式更改策略：

增加热期和/或
添加与查询模式匹配的其他热窗口。

热时段内的数据未完全缓存

使用以下命令检查加速进度：

.show external table [ETName] details
| project state = todynamic(QueryAccelerationState)
| project state.CompletionPercentage, state.PendingDataFilesCount

如果 CompletionPercentage < 100允许更多时间加速数据。
如果不 CompletionPercentage 随时间推移而增加，请按照了解和缓解数据加速问题的指南进行作。

了解和缓解数据加速问题

未获取的数据（CompletionPercentage < 100）可能源于多个问题。

数据当前正在加速

数据加速可能需要一些时间，尤其是在以下情况下：

最近已启用查询加速策略，或
最近向增量表添加了大量数据，或
增量表经历了优化作，例如 OPTIMIZE ，这会导致许多已删除和重新创建的文件。

经常在源增量表上运行 OPTIMIZE 或 MERGE 作，导致对数据文件进行大规模重写可能会对加速性能产生负面影响，因为重复重写数据文件，需要加速。

数据文件不符合加速条件

不会缓存大于 1 GB 的 Parquet 数据文件。

如果增量表包含许多大型文件，请考虑调整数据生成或优化策略以生成较小的 parquet 文件。如果这需要重新创建 Delta 表，请确保重新创建外部表并重新启用查询加速策略。

群集容量或资源不足

查询加速作受群集的可用查询加速容量的限制。

运行以下命令以查看剩余容量：

.show capacity
| where Resource == 'QueryAcceleration'
| project Remaining

如果 Remaining == 0 一致且 CompletionPercentage 未增加，请考虑：
- 横向扩展或纵向扩展群集以提供更多资源。
- QueryAcceleration通过更改容量策略来增加容量。注意：更改容量策略可能对其他作产生不利影响。根据自己的自由裁量权更改策略。

Last updated on 2025-12-12

通过