从存储引入
适用于：✅Azure 数据资源管理器
.ingest into 命令通过从一个或多个云存储文件“拉取”数据，将数据引入表中。
例如，此命令可以从 Azure Blob 存储中检索 1000 个 CSV 格式的 blob，对其进行分析，然后将它们一起引入到单个目标表中。
数据将追加到表，不会影响现有记录，也不会修改表的架构。
注意
这种引入方法旨在用于探索和原型制作。 不要在生产或大容量方案中使用它。
权限
你必须至少具有表引入者权限才能运行此命令。
语法
.ingest [async] into table TableName SourceDataLocator [with ( IngestionPropertyName = IngestionPropertyValue [, ...] )]
详细了解语法约定。
参数
| 客户 | 类型 | 必需 | 说明 |
|---|---|---|---|
async |
string |
如果指定了此项，命令会立即返回，并继续在后台执行引入操作。 命令的结果将包含一个 OperationId 值，该值随后可以与 .show operation 命令一起使用，以检索引入的完成状态和结果。 |
|
| TableName | string |
✔️ | 要在其中引入数据的表的名称。 表名称始终与上下文中的数据库相关。 如果未提供架构映射对象，将使用上下文中的数据库架构。 |
| SourceDataLocator | string |
✔️ | 单个存储连接字符串，或存储连接字符串的逗号分隔列表。 单个连接字符串必须引用由存储帐户托管的单个文件。 可以通过指定多个连接字符串或者通过从外部表的查询进行引入来引入多个文件。 |
注意
我们建议对 SourceDataLocators 使用已模糊处理的字符串文本。 服务将清理内部跟踪和错误消息中的凭据。
引入属性
重要
在排队引入中，使用引入属性对数据进行批处理。 使用的不同引入映射属性越多（例如不同的 ConstValue 值），引入就会越分散，这可能会导致性能下降。
下表列出并描述了支持的属性，并提供了示例：
| properties | 说明 | 示例 |
|---|---|---|
ingestionMapping |
一个字符串值，表示如何将数据从源文件映射到表中的实际列。 使用相关的映射类型定义 format 值。 请参阅数据映射。 |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")（已弃用： avroMapping、csvMapping、jsonMapping） |
ingestionMappingReference |
一个字符串值，表示如何使用命名的映射策略对象将数据从源文件映射到表中的实际列。 使用相关的映射类型定义 format 值。 请参阅数据映射。 |
with (format="csv", ingestionMappingReference = "Mapping1")（已弃用： avroMappingReference、csvMappingReference、jsonMappingReference） |
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) |
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 字符串，用于指示在引入使用 CSV 格式表示的数据期间要运行的验证。 请参阅数据引入，了解不同选项的说明。 | with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}')（实际上，这是默认策略）。 |
zipPattern |
从包含 ZIP 存档的存储中引入数据时，请使用此属性。 这是一个字符串值，表示在要引入的 ZIP 存档中选择具体文件时需使用的正则表达式。 存档中的所有其他文件会被忽略。 | with (zipPattern="*.csv") |
身份验证和授权
每个存储连接字符串指示用于访问存储的授权方法。 根据授权方法，可能需要向主体授予对外部存储的权限才能执行引入。
下表列出了支持的身份验证方法，以及从外部存储引入数据所需的权限。
| 身份验证方法 | Azure Blob 存储/Data Lake Storage Gen2 | Data Lake Storage Gen1 |
|---|---|---|
| 模拟 | 存储 Blob 数据读取者 | 读取器 |
| 共享访问 (SAS) 令牌 | 列出 + 读取 | Gen1 不支持此身份验证方法。 |
| Microsoft Entra 访问令牌 | ||
| 存储帐户访问密钥 | Gen1 不支持此身份验证方法。 | |
| 托管的标识 | 存储 Blob 数据读取者 | 读取器 |
返回
命令的结果是一个表，其中包含的记录与命令生成的数据分片（“盘区”）的数量一样多。 如果未生成任何数据分片，则返回一条带有空（零值）盘区 ID 的记录。
| 名称 | Type | 说明 |
|---|---|---|
| ExtentId | guid |
该命令生成的数据分片的唯一标识符。 |
| ItemLoaded | string |
与此记录相关的一个或多个存储文件。 |
| 持续时间 | timespan |
执行引入所花费的时间。 |
| HasErrors | bool |
此记录是否表示引入失败。 |
| OperationId | guid |
表示操作的唯一 ID。 可以与 .show operation 命令一起使用。 |
注意
此命令不会修改要引入到其中的表的架构。 必要时，数据在引入期间会被“强制纳入”到此架构中，而不采用其他方法（忽略多余的列，将缺少的列视为 null 值）。
示例
采用共享访问签名的 Azure Blob 存储
以下示例指示数据库从 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 Blob 存储
以下示例演示了如何使用托管标识身份验证从 Azure Blob 存储读取 CSV 文件并将其内容引入到表 T 中。 有关托管标识身份验证方法的更多信息，请参阅托管标识身份验证概述。
.ingest into table T ('https://StorageAccount.blob.core.chinacloudapi.cn/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen 2
以下示例用于从 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 存储
以下示例从 Azure Data Lake Storage (ADLS) 引入单个文件。 它使用用户的凭据来访问 ADLS（因此，无需将存储 URI 视为包含机密）。 它还展示了如何指定引入属性。
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
采用访问密钥的 Amazon S3
以下示例使用访问密钥 ID 和机密访问密钥从 Amazon S3 引入单个文件。
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=AKIAIOSFODNN7EXAMPLE,wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
with (format='csv')
采用预签名 URL 的 Amazon S3
以下示例使用预签名 URL 从 Amazon S3 引入单个文件。
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')