适用于：✅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命令在查询加速策略中配置属性。 - 使用
MaxAgeexternal_table()的参数替代每个查询。
对加速的外部增量表的 查询速度低于 预期
如果查询的执行速度低于预期，并且查询加速似乎没有提高性能，请考虑以下潜在原因：
- 不可用的查询加速目录：目录可能已过时或尚未生成。 请参阅“ 排查不可用的目录问题 ”部分，检查情况是否如此。
- 查询访问非加速数据：查询可能正在扫描尚未缓存的数据。 请参阅“ 对非访问数据”部分的查询进行故障排除 ，以检查情况是否如此。
- 不符合 KQL 最佳做法：确保查询遵循 KQL 最佳做法。 请参阅有关优化技术的 KQL 最佳做法 指南。
故障排除步骤
排查不可用的目录问题
步骤 1：检查不可用的目录
查询加速对包含增量表元数据快照的外部表使用本地目录。 如果未在配置 MaxAge 中更新此目录（请参阅查询加速策略 MaxAge 的属性），则被视为 不可用 ，并且不会在查询时使用。 在这种情况下，查询会回退到直接读取远程增量表，这可能会明显降低。
使用以下命令检索目录的当前状态：
.show external table [ETName] details
| extend MinimumUpdateTime = now() - totimespan(todynamic(QueryAccelerationPolicy).MaxAge)
| project IsCatalogUnusable = MinimumUpdateTime > todatetime(todynamic(QueryAccelerationState).LastUpdatedDateTime)
IsCatalogUnusable == true 指示目录已过时，并且不使用查询加速。
步骤 2：检查查询加速状态运行状况
若要了解目录为何不可用，请检查查询加速状态是否正常，并根据需要解决不正常的原因。
运行：
.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• 群集或数据库托管标识策略中的使用类型。 |
对非访问数据进行查询故障排除
步骤 3：检查查询是否超过未访问的数据
若要完全受益于查询加速，必须通过加速数据执行查询。 非加速数据直接从远程增量表读取，这可能会导致严重的延迟。 使用以下命令并筛选包含相关查询的时间范围：
.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随时间推移而增加，请按照 了解和缓解数据加速问题的指南进行作。
- 如果
步骤 4：了解和缓解数据加速问题
未获取的数据（CompletionPercentage < 100）可能源于多个问题。
数据当前正在加速
数据加速可能需要一些时间，尤其是在以下情况下：
- 最近启用了查询加速策略。
- 最近向增量表添加了大量数据。
- 你对增量表运行
OPTIMIZE了优化作，该作导致许多已删除和重新创建的文件。
源增量表上频繁运行 OPTIMIZE 或 MERGE 作，导致对数据文件进行大规模重写可能会对加速性能产生负面影响，因为数据文件会反复重写，需要加速。
数据文件不符合加速条件
不会缓存大于 1 GB 的 Parquet 数据文件。
如果增量表包含许多大型文件，请考虑调整数据生成或优化策略以生成较小的 parquet 文件。 如果此调整需要重新创建 Delta 表，请确保重新创建外部表并重新启用查询加速策略。
群集容量或资源不足
查询加速作受群集的可用查询加速容量的限制。
运行以下命令以查看剩余容量：
.show capacity
| where Resource == 'QueryAcceleration'
| project Remaining
如果
Remaining == 0一致且CompletionPercentage未增加，请考虑：- 横向扩展或纵向扩展群集以提供更多资源。
-
QueryAcceleration通过更改容量策略来增加容量。
注释
更改容量策略可能会对其他作产生不利影响。 根据自己的自由裁量权更改策略。