提交Kusto查询至集群前预校验KQL语法的实现方案咨询

完全可以在不提交KQL到集群的前提下完成语法合法性校验，以下优先提供PowerShell实现方案，同时附其他可选实现方式，均适配CI流水线集成场景。

PowerShell实现方案 #

核心依赖微软官方提供的Microsoft.Azure.Kusto.LibraryNuGet包，该包内置独立的KQL语法解析器，不需要连接Kusto集群即可完成纯语法校验，仅会检查语句的语法规范，不会校验表、列等元数据是否存在。

实现步骤 #

1. 首次运行前安装依赖包并加载程序集

# 安装Kusto语法库到本地目录（仅首次执行）
Install-Package Microsoft.Azure.Kusto.Library -Source nuget.org -OutputDirectory ./kusto-lib -Force
# 加载语法解析程序集
Add-Type -Path (Resolve-Path "./kusto-lib/Microsoft.Azure.Kusto.Library.*/lib/netstandard2.0/Microsoft.Azure.Kusto.Library.dll").Path

2. 定义KQL语法校验函数

function Test-KqlSyntax {
    param(
        [Parameter(Mandatory=$true)]
        [string]$KqlQuery
    )
    # 调用官方解析器执行语法校验
    $parseResult = [Microsoft.Azure.Kusto.Language.KustoCode]::Parse($KqlQuery)
    # 筛选语法错误
    $errors = $parseResult.Diagnostics | Where-Object { 
        $_.Severity -eq [Microsoft.Azure.Kusto.Language.DiagnosticSeverity]::Error 
    } | ForEach-Object { $_.Message }
    
    return [PSCustomObject]@{
        IsValid = $errors.Count -eq 0
        Errors  = $errors
    }
}

3. CI场景批量校验脚本示例

$hasInvalid = $false
# 遍历仓库下所有.kql后缀的文件执行校验
Get-ChildItem -Path ./kusto-scripts -Recurse -Filter *.kql | ForEach-Object {
    $kqlContent = Get-Content $_.FullName -Raw
    $checkRes = Test-KqlSyntax -KqlQuery $kqlContent
    if (-not $checkRes.IsValid) {
        Write-Host "文件$($_.FullName)语法错误：$($checkRes.Errors -join "；")"
        $hasInvalid = $true
    }
}

# 校验不通过时返回非零退出码，阻断CI流程
if ($hasInvalid) {
    exit 1
}
Write-Host "所有KQL文件语法校验通过"

其他可选实现方案 #

• Kusto CLI工具：官方提供的命令行工具内置语法校验能力，无需自行编码，直接执行kusto-cli --parse-only --query "待校验KQL语句"即可返回校验结果，适配各类流水线环境。
• Node.js/TypeScript实现：使用官方azure-kusto-data包内置的KustoParser模块，可实现同PowerShell版本一致的语法校验逻辑。

进阶说明 #

如果需要同时校验KQL中引用的表名、字段名是否和目标集群一致，可以额外配置集群只读权限，提前拉取集群元数据Schema，结合语法解析结果做二次校验，该场景需要连通集群网络。

内容的提问来源于stack exchange，提问作者moutonjr