从存储引入

.ingest into 命令通过从一个或多个云存储文件“拉取”数据,将数据引入表中。 例如,此命令可以从 Azure Blob 存储中检索 1000 个 CSV 格式的 blob,对其进行分析,然后将它们一起引入到单个目标表中。 数据将追加到表,不会影响现有记录,也不会修改表的架构。 所需的最小权限级别是必需的,因此你可以将数据引入到某个数据库的所有现有表中,或者引入到特定的现有表中。 有关详细信息,请参阅引擎服务上的权限

语法

.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]

参数

  • async:如果指定了此项,命令会立即返回,并继续在后台执行引入操作。 命令的结果将包含一个 OperationId 值,该值随后可以与 .show operation 命令一起使用,以检索引入的完成状态和结果。

  • TableName:要引入数据的表的名称。 表名在上下文中始终相对于数据库,如果未提供架构映射对象,则其架构是将为数据采用的架构。

  • SourceDataLocator:string 类型的文本,或由 () 字符括起来的以逗号分隔的此类文本列表,表示存储连接字符串。 Kusto 使用 URI 格式来描述那些包含要拉取的数据的存储文件。

    • 单个连接字符串必须引用由存储帐户托管的单个文件。
    • 可以通过指定以逗号分隔的多个连接字符串来引入多个文件,也可以通过从外部表的查询进行引入来这样做。

注意

对于包含实际凭据的 SourceDataPointer,强烈建议为其使用经过模糊处理的字符串文本。 该服务将确保清除其内部跟踪、错误消息和其他位置中的凭据。

引入属性

下表列出了 Azure 数据资源管理器支持的属性,对其进行了说明,并提供了示例:

属性 说明 示例
ingestionMapping 一个字符串值,表示如何将数据从源文件映射到表中的实际列。 使用相关的映射类型定义 format 值。 请参阅数据映射 with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")
(已弃用:avroMappingcsvMappingjsonMapping
ingestionMappingReference 一个字符串值,表示如何使用命名的映射策略对象将数据从源文件映射到表中的实际列。 使用相关的映射类型定义 format 值。 请参阅数据映射 with (format="csv", ingestionMappingReference = "Mapping1")
(已弃用:avroMappingReferencecsvMappingReferencejsonMappingReference
creationTime 日期/时间值(格式化为 ISO8601 字符串),在创建引入的数据盘区时使用。 在未指定的情况下会使用当前值 (now())。 在引入的数据较旧时可以重写默认值,以便正确应用保留策略。 指定时,请确保目标表的有效区合并策略中的 Lookback 属性与指定的值一致。 with (creationTime="2017-02-13")
extend_schema 一个布尔值,在指定的情况下会指示命令扩展表的架构(默认为 false)。 此选项仅适用于 .append.set-or-append 命令。 进行架构扩展时,只能在表的末尾添加其他列。 如果原始表架构为 (a:string, b:int),则 (a:string, b:int, c:datetime, d:string) 是有效的架构扩展,而 (a:string, c:datetime) 则不是。
folder 使用 ingest-from-query 命令时分配给表的文件夹。 如果表已存在,则此属性会重写表的文件夹 with (folder="Tables/Temporary")
format 数据格式(请参阅支持的数据格式)。 with (format="csv")
ingestIfNotExists 一个字符串值,如果已指定,则在表的数据已通过一个具有相同值的 ingest-by: 标记进行了标记时,引入操作会失败。 这确保了幂等数据引入。 有关详细信息,请参阅 ingest-by: tags 属性 with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') 表示,如果已存在带 ingest-by:Part0001 标记的数据,请勿完成当前的引入操作。 如果该数据不存在,则在执行这个新的引入操作时,应该设置此标记(防止将来有人尝试再次引入相同的数据)。
ignoreFirstRecord 一个布尔值,在设置为 true 的情况下表示引入操作应该忽略每个文件的第一条记录。 如果文件中的第一条记录是列名称,则此属性适用于 CSV 和类似格式的文件。 默认为 false with (ignoreFirstRecord=false)
persistDetails 一个布尔值,在指定的情况下表示命令应该保留详细的结果(即使命令已成功执行),这样 .show operation details 命令就能够检索它们。 默认为 false with (persistDetails=true)
policy_ingestiontime 一个布尔值,在指定的情况下,说明是否在通过此命令创建的表上启用引入时间策略。 默认值为 true with (policy_ingestiontime=false)
recreate_schema 一个布尔值,在指定的情况下,说明此命令是否会重新创建表的架构。 此属性只适用于 .set-or-replace 命令。 在同时设置的情况下,此属性优先于 extend_schema 属性。 with (recreate_schema=true)
tags 与引入的数据(格式化为 JSON 字符串)相关联的标记的列表 with (tags="['Tag1', 'Tag2']")
validationPolicy 一个 JSON 字符串,表示在引入期间要运行哪些验证。 请参阅数据引入,了解不同选项的说明。 with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}')(实际上,这是默认策略)。
zipPattern 从包含 ZIP 存档的存储中引入数据时,请使用此属性。 这是一个字符串值,表示在要引入的 ZIP 存档中选择具体文件时需使用的正则表达式。 存档中的所有其他文件会被忽略。 with (zipPattern="*.csv")

结果

命令的结果是一个表,其中包含的记录与命令生成的数据分片(“盘区”)的数量一样多。 如果未生成任何数据分片,则返回一条带有空(零值)盘区 ID 的记录。

名称 类型 说明
ExtentId guid 该命令生成的数据分片的唯一标识符。
ItemLoaded string 与此记录相关的一个或多个存储文件。
持续时间 timespan 执行引入所花费的时间。
HasErrors bool 此记录是否表示引入失败。
OperationId guid 表示操作的唯一 ID。 可以与 .show operation 命令一起使用。

注意

此命令不会修改要引入到其中的表的架构。 必要时,数据在引入期间会被“强制纳入”到此架构中,而不采用其他方法(忽略多余的列,将缺少的列视为 null 值)。

示例

下一个示例指示引擎将 Azure Blob 存储中的两个 blob 读取为 CSV 文件,并将其内容引入到表 T 中。 ... 表示 Azure 存储共享访问签名 (SAS),该签名提供对每个 blob 的读取访问权限。 另请注意,使用了经过模糊处理的字符串(字符串值前面的 h),以确保从不记录 SAS。

.ingest into table T (
    h'https://contoso.blob.core.chinacloudapi.cn/container/file1.csv?...',
    h'https://contoso.blob.core.chinacloudapi.cn/container/file2.csv?...'
)

下一个示例用于从 Azure Data Lake Storage Gen 2 (ADLSv2) 引入数据。 此处使用的凭据 (...) 是存储帐户凭据(共享密钥),我们只对连接字符串的机密部分使用字符串模糊处理。

.ingest into table T (
  'abfss://myfilesystem@contoso.dfs.core.chinacloudapi.cn/path/to/file1.csv;...'
)

下一个示例从 Azure Data Lake Storage (ADLS) 引入单个文件。 它使用用户的凭据来访问 ADLS(因此,无需将存储 URI 视为包含机密)。 它还展示了如何指定引入属性。

.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
  with (format='csv')