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 记录跨越多行。
有关映射语法的详细信息,请参阅数据映射。