queryinsights.external_api_call_stats（Transact-SQL）

适用于：Microsoft Fabric 中的 SQL 分析终结点和 Microsoft Fabric 中的仓库

queryinsights.external_api_call_stats Microsoft Fabric Data Warehouse 中的视图为通过 AI 函数调用外部 API 的查询提供了功能级诊断。 使用此视图调查外部服务延迟、重试、限速、有效载荷大小、执行模式和失败行。

视图中每个查询使用的不同外部函数各有一行。 通过使用distributed_statement_id功能级统计数据、查询文本、状态和经过时间来连接queryinsights.exec_requests_history。

列名称 数据类型 Description
distributed_statement_id uniqueidentifier 识别调用该函数的查询。 加入本栏至 queryinsights.exec_requests_history.distributed_statement_id。 与 function_name一起，它识别查询中的一个函数。
database_name varchar（200） 查询所在数据库的名称。
function_name 瓦尔查尔（256） 外部函数的名称，如 ai_analyze_sentiment 或 MyFunctionSet.ScoreModel。
function_type varchar(32) 外部功能类型。 该值为 AI_FUNCTION。
execution_mode varchar（16） 函数使用的调用模式。 其值为 batch、 row或 mixed。 批处理模式每个请求最多可处理60行。 行模式每个请求处理一行。
call_count int 发送到外部端点的HTTP调用总数，包括HTTP层重试。
batch_call_count int 批处理模式下的HTTP调用次数。 当 是 时row，其值为 。0execution_mode
row_call_count int 行模式下的HTTP调用次数。 当 是 时batch，其值为 。0execution_mode
call_retry_count int 初始调用后的完整调用次数或批量重试次数。 该值不包括HTTP层的重试，这些重试包含在 call_count。
external_service_wait_time_ms bigint 等待外部端点的总时间（以毫秒计）。
data_sent_bytes bigint 发送给外部端点的总请求有效载荷大小（字节单位）。
data_received_bytes bigint 从外部端点接收的总响应有效载荷大小（字节单位）。
rows_total int 函数处理的行总数。
rows_succeeded int 返回有效结果的行数。
rows_failed int 因处理错误返回 NULL 的行数。 该值等于 rows_total - rows_succeeded。
rows_throttled int 重试次数耗尽后，HTTP 状态代码为 429 的行数。
rows_content_filtered int 内容安全过滤器阻挡的行数。
rows_text_too_long int 由于输入超过最大文本长度，拒绝了行数。
rows_service_error int HTTP 500、502、503或504响应和重试后失败的行数，以及因非用户输入导致的不可重考服务错误影响的行。

注解

  • 不使用外部函数的查询不会产生行。queryinsights.external_api_call_stats
  • 调用多个不同外部函数的查询会为每个函数生成一行。
  • 使用 is_using_external_api 该 queryinsights.exec_requests_history 列来识别在视图中可能有对应行的查询。
  • call_count 包含HTTP层重试。 call_retry_count 跟踪完整调用或批次的重试，不包括HTTP层的重试。
  • 比较 batch_call_count 和 row_call_count 判断该函数是批量处理行、单独处理，还是两种模式。
  • 有效载荷计数器仅包含尺寸。 Query Insights 不存储外部请求或响应内容。
  • 故障计数器有助于分类常见原因，但它们不会自动修复限速、内容过滤、输入长度无效或服务失败。
  • queryinsights.external_api_call_stats queryinsights所有视图仅在Fabric Data Warehouse和SQL分析端点中提供。

Permissions

你应该能访问 Fabric Capacity 工作区内的 SQL 分析端点或仓库，权限为贡献者或更高权限，或者访问 Monitor 权限的查看者权限。

示例

使用此视图识别调用外部函数的查询，并调查功能级性能和故障。 下面是一些示例。

A. 查找最近调用外部 API 的查询

返回最近100个调用AI功能的查询：

SELECT TOP 100
       distributed_statement_id,
       submit_time,
       status,
       total_elapsed_time_ms,
       command
FROM queryinsights.exec_requests_history
WHERE is_using_external_api = 1
ORDER BY submit_time DESC;

B. 计算每次通话的外部等待时间

将视图合并，并根据每个HTTP调用的平均外部服务等待时间对外部函数进行排名：

SELECT TOP 100
       h.distributed_statement_id,
       h.submit_time,
       f.function_name,
       f.function_type,
       f.call_count,
       f.external_service_wait_time_ms,
       f.external_service_wait_time_ms
           / NULLIF(f.call_count, 0) AS wait_time_ms_per_call
FROM queryinsights.exec_requests_history AS h
INNER JOIN queryinsights.external_api_call_stats AS f
    ON h.distributed_statement_id = f.distributed_statement_id
WHERE h.is_using_external_api = 1
ORDER BY wait_time_ms_per_call DESC;

C. 查找重试和失败热点

返回至少三次完整调用重试或失败行超过5%的查询：

SELECT h.distributed_statement_id,
       h.submit_time,
       h.status,
       SUM(f.call_retry_count) AS retry_count,
       SUM(f.rows_total) AS rows_total,
       SUM(f.rows_failed) AS rows_failed,
       SUM(f.rows_throttled) AS rows_throttled,
       SUM(f.rows_service_error) AS rows_service_error
FROM queryinsights.exec_requests_history AS h
INNER JOIN queryinsights.external_api_call_stats AS f
    ON h.distributed_statement_id = f.distributed_statement_id
WHERE h.is_using_external_api = 1
GROUP BY h.distributed_statement_id,
         h.submit_time,
         h.status
HAVING SUM(f.call_retry_count) >= 3
    OR SUM(f.rows_failed) > SUM(f.rows_total) * 0.05
ORDER BY retry_count DESC, rows_failed DESC;

D. 查找以外部等待为主导的查询

返回查询时外部服务等待时间超过总查询时间一半：

SELECT h.distributed_statement_id,
       h.submit_time,
       h.total_elapsed_time_ms,
       SUM(f.external_service_wait_time_ms) AS external_wait_time_ms,
       100.0 * SUM(f.external_service_wait_time_ms)
           / NULLIF(h.total_elapsed_time_ms, 0) AS external_wait_pct
FROM queryinsights.exec_requests_history AS h
INNER JOIN queryinsights.external_api_call_stats AS f
    ON h.distributed_statement_id = f.distributed_statement_id
WHERE h.is_using_external_api = 1
GROUP BY h.distributed_statement_id,
         h.submit_time,
         h.total_elapsed_time_ms
HAVING SUM(f.external_service_wait_time_ms)
       > h.total_elapsed_time_ms * 0.50
ORDER BY external_wait_pct DESC;

E. 查找仅行模式查询

返回那些外部函数使用行模式且未进行任何批处理调用的查询：

SELECT h.distributed_statement_id,
       h.submit_time,
       SUM(f.row_call_count) AS row_call_count,
       SUM(f.call_count) AS total_call_count,
       SUM(f.rows_total) AS rows_total
FROM queryinsights.exec_requests_history AS h
INNER JOIN queryinsights.external_api_call_stats AS f
    ON h.distributed_statement_id = f.distributed_statement_id
WHERE h.is_using_external_api = 1
GROUP BY h.distributed_statement_id,
         h.submit_time
HAVING SUM(f.row_call_count) > 0
   AND SUM(f.batch_call_count) = 0
ORDER BY row_call_count DESC;

F. 每行查找大有效载荷

返回平均请求有效载荷超过每处理行32 KB的外部函数调用：

SELECT h.distributed_statement_id,
       h.submit_time,
       f.function_name,
       f.rows_total,
       f.data_sent_bytes,
       f.data_sent_bytes
           / NULLIF(f.rows_total, 0) AS bytes_sent_per_row
FROM queryinsights.exec_requests_history AS h
INNER JOIN queryinsights.external_api_call_stats AS f
    ON h.distributed_statement_id = f.distributed_statement_id
WHERE h.is_using_external_api = 1
  AND f.data_sent_bytes / NULLIF(f.rows_total, 0) > 32768
ORDER BY bytes_sent_per_row DESC;

后续步骤

Microsoft Fabric 中的查询见解

相关内容

  • 上次更新时间为