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 记录跨越多行。

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