externaldata 运算符

2025-08-20

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

externaldata 运算符返回一个表，该表的架构是在查询自身中定义的，并且该表的数据是从外部存储项目（如 Azure Blob 存储中的 Blob 或 Azure Data Lake Storage 中的文件）中读取的。

注意

externaldata 运算符支持：

一组特定的存储服务，如存储连接字符串下列出。
共享访问签名（SAS）密钥、访问密钥、Microsoft Entra 令牌和托管标识身份验证方法。有关详细信息，请参阅存储身份验证方法。

注意

请使用 externaldata 运算符从外部存储项目检索最多 100 MB 的小型引用表。该运算符并非为大数据量而设计。当存储项目的公共终结点位于防火墙后面时，不支持此运算符。

语法

externaldata ( columnName:columnType [, ...] )[storageConnectionString [, ...] ] [with(propertyName=propertyValue [, ...])]

详细了解语法约定。

参数

客户	类型	必需	说明
columnName、 columnType	`string`	✔️	列名及其类型的列表。此列表定义表的架构。
storageConnectionString	`string`	✔️	要查询的存储项目的存储连接字符串。
propertyName、propertyValue	`string`		可选受支持属性的列表，用于确定如何解释从存储中检索的数据。

[!警告] 出于安全原因，请确保 storageConnectionString 属性未指定任何凭据。如果查询需要指定凭据，请使用查询参数来指定整个连接字符串。

例如，假设查询包含一 URI 个名为其值点在 Blob 存储的查询参数，则查询将如下所示：
declare query_parameters(URI:string);
externaldata(x:string)[URI]
如果这是不可能的（例如，你正在使用不支持设置查询参数的客户端），请确保使用模糊字符串文本。

支持的属性

属性	类型	说明
格式	`string`	数据格式。如果未指定，则会尝试从文件扩展名检测数据格式。默认为 `CSV`。支持所有引入数据格式。
ignoreFirstRecord	`bool`	如果设置为 `true`，则会忽略每个文件中的第一条记录。在查询带有标题的 CSV 文件时，此属性很有用。
ingestionMapping	`string`	指示如何将数据从源文件映射到运算符结果集中的实际列。请参阅数据映射。

注意

此运算符不接受任何管道输入。

标准查询限制还适用于外部数据查询。

externaldata 运算符返回给定架构的数据表，表中的数据是从指定的存储项目中分析的，由存储连接字符串指示。

示例

以下示例演示如何查找其列属于存储在 Azure Blob 存储的外部存储文件中的已知 ID 集（每行一行）的所有记录 UserID 。由于未指定数据格式，因此检测到的数据格式是 TXT。

Users
| where UserID in ((externaldata (UserID:string) [
    @"https://storageaccount.blob.core.chinacloudapi.cn/storagecontainer/users.txt;managed_identity=..."
    ]))
| ...

下面的示例查询外部存储中存储的多个数据文件。

externaldata(Timestamp:datetime, ProductId:string, ProductDescription:string)
[
  h@"https://mycompanystorage.blob.core.chinacloudapi.cn/archivedproducts/2019/01/01/part-00000-7e967c99-cf2b-4dbb-8c53-ce388389470d.csv.gz?...SAS...",
  h@"https://mycompanystorage.blob.core.chinacloudapi.cn/archivedproducts/2019/01/02/part-00000-ba356fa4-f85f-430a-8b5a-afd64f128ca4.csv.gz?...SAS...",
  h@"https://mycompanystorage.blob.core.chinacloudapi.cn/archivedproducts/2019/01/03/part-00000-acb644dc-2fc6-467c-ab80-d1590b23fc31.csv.gz?...SAS..."
]
with(format="csv")
| summarize count() by ProductId

可将上述示例视为快速查询多个数据文件（无需定义外部表）的方法。

注意

externaldata 运算符无法识别数据分区。

若要查询分层数据格式（如 JSON、 Parquet、 Avro或 ORC），必须在运算符属性中指定 ingestionMapping。在此示例中，有一个 JSON 文件存储在 Azure Blob 存储中，该文件包含以下内容：

{
  "timestamp": "2019-01-01 10:00:00.238521",   
  "data": {    
    "tenant": "e1ef54a6-c6f2-4389-836e-d289b37bcfe0",   
    "method": "RefreshTableMetadata"   
  }   
}   
{
  "timestamp": "2019-01-01 10:00:01.845423",   
  "data": {   
    "tenant": "9b49d0d7-b3e6-4467-bb35-fa420a25d324",   
    "method": "GetFileList"   
  }   
}
...

若要使用 externaldata 运算符查询此文件，必须指定数据映射。该映射指示如何将 JSON 字段映射到运算符结果集列：

externaldata(Timestamp: datetime, TenantId: guid, MethodName: string)
[ 
   h@'https://mycompanystorage.blob.core.chinacloudapi.cn/events/2020/09/01/part-0000046c049c1-86e2-4e74-8583-506bda10cca8.json?...SAS...'
]
with(format='multijson', ingestionMapping='[{"Column":"Timestamp","Properties":{"Path":"$.timestamp"}},{"Column":"TenantId","Properties":{"Path":"$.data.tenant"}},{"Column":"MethodName","Properties":{"Path":"$.data.method"}}]')

此处使用 MultiJSON 格式，因为单个 JSON 记录跨越多行。

有关映射语法的详细信息，请参阅数据映射。

通过

externaldata 运算符

语法

参数

支持的属性

返回

示例

相关内容

其他资源