externaldata 运算符
externaldata 运算符返回一个表，该表的架构是在查询自身中定义的，并且该表的数据是从外部存储项目（如 Azure Blob 存储中的 Blob 或 Azure Data Lake Storage 中的文件）中读取的。
注意
externaldata 运算符支持一组特定的存储服务，如存储连接字符串下所列。
注意
externaldata 运算符支持共享访问签名 (SAS) 密钥、访问密钥和 Microsoft Entra 令牌身份验证方法。 有关详细信息，请参阅存储身份验证方法。
注意
请使用 externaldata 运算符从外部存储项目检索最多 100 MB 的小型引用表。 该运算符并非为大数据量而设计。
当存储项目的公共终结点位于防火墙后面时，不支持此运算符。
语法
externaldata (columnName:columnType [, ...] )[ storageConnectionString [, ...] ] [with ( propertyName = propertyValue [, ...])]
详细了解语法约定。
参数
| 客户 | 类型 | 必需 | 说明 |
|---|---|---|---|
| columnName, columnType | string |
✔️ | 列名及其类型的列表。 此列表定义表的架构。 |
| storageConnectionString | string |
✔️ | 要查询的存储项目的存储连接字符串。 |
| propertyName, propertyValue | string |
可选受支持属性的列表，用于确定如何解释从存储中检索的数据。 |
支持的属性
| 属性 | 类型 | 说明 |
|---|---|---|
| format | string |
数据格式。 如果未指定，则会尝试从文件扩展名检测数据格式。 默认为 CSV。 支持所有引入数据格式。 |
| ignoreFirstRecord | bool |
如果设置为 true，则会忽略每个文件中的第一条记录。 在查询带有标题的 CSV 文件时，此属性很有用。 |
| ingestionMapping | string |
指示如何将数据从源文件映射到运算符结果集中的实际列。 请参阅数据映射。 |
返回
externaldata 运算符返回给定架构的数据表，表中的数据是从指定的存储项目中分析的，由存储连接字符串指示。
示例
提取存储在 Azure Blob 存储中的用户 ID 的列表
下面的示例显示了如何查找表中的所有记录，该表的 UserID 列属于一个已知 ID 集，这些 ID 保存在外部存储文件中（每行一个 ID）。 由于未指定数据格式，因此检测到的数据格式是 TXT。
Users
| where UserID in ((externaldata (UserID:string) [
@"https://storageaccount.blob.core.chinacloudapi.cn/storagecontainer/users.txt"
h@"?...SAS..." // Secret token needed to access the blob
]))
| ...
查询多个数据文件
下面的示例查询外部存储中存储的多个数据文件。
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 记录跨越多行。
有关映射语法的详细信息，请参阅数据映射。