.ingest into

2025-05-23

适用于：✅Azure 数据资源管理器

.ingest into 命令通过从一个或多个云存储文件“拉取”数据，将数据引入表中。例如，此命令可以从 Azure Blob 存储中检索 1000 个 CSV 格式的 blob，对其进行分析，然后将它们一起引入到单个目标表中。数据将追加到表，不会影响现有记录，也不会修改表的架构。

注释

此引入方法适用于探索和原型制作。请勿在生产或大容量方案中使用它。有关引入选项的详细信息，请参阅数据引入概述。

权限

必须至少具有表引入器权限才能运行此命令。

语法

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

详细了解语法约定。

参数

名称	类型	必选	DESCRIPTION
`async`	`string`		如果指定了此项，命令会立即返回，并继续在后台执行引入操作。命令的结果将包含一个 `OperationId` 值，该值随后可以与 `.show operation` 命令一起使用，以检索引入的完成状态和结果。
TableName	`string`	✔️	要将数据引入到其中的表的名称。表名称始终与上下文中的数据库相关。如果未提供架构映射对象，将使用上下文中的数据库架构。
SourceDataLocator	`string`	✔️	单个存储连接字符串，或存储连接字符串的逗号分隔列表。单个连接字符串必须引用由存储帐户托管的单个文件。可以通过指定多个连接字符串或者通过从外部表的查询进行引入来引入多个文件。

注释

我们建议对 SourceDataLocators 使用已模糊处理的字符串文本。服务将清理内部跟踪和错误消息中的凭据。

摄入属性

重要

在排队引入数据是使用引入属性批处理的。使用的不同引入映射属性（如不同的 ConstValue 值）越分散，引入就越分散，这可能会导致性能下降。

下表列出了和支持的属性，并提供示例：

资产	DESCRIPTION	示例：
`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']")`
`TreatGzAsUncompressed`	一个布尔值，如果设置为 `true`，则表示扩展名为 `.gz` 的文件不会被压缩。从 Amazon AWS S3 引入时，有时需要此标志。	`with (treatGzAsUncompressed=true)`
`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 的记录。

名称	类型	DESCRIPTION
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 中。身份验证使用分配给 Azure 中的 Azure Blob 存储的托管标识 ID（对象 ID）。有关详细信息，请参阅为存储容器创建托管标识。

.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 Storage

以下示例从 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=EXAMPLEKEY')
  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')

通过