从查询引入（.set、.append、.set-or-append、.set-or-replace）

项目
12/28/2024

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

这些命令执行查询或管理命令，并将查询结果引入表中。这些命令之间的区别在于它们如何处理现有的或不存在的表和数据。

命令	如果表存在	如果表不存在
`.set`	命令失败。	将创建表并引入数据。
`.append`	数据将追加到表。	命令失败。
`.set-or-append`	数据将追加到表。	将创建表并引入数据。
`.set-or-replace`	数据将替换表中的数据。	将创建表并引入数据。

若要从查询命令取消引入，请参阅 cancel operation。

注意

从查询中引入是直接引入。因此，它不包括自动重试。在通过数据管理服务引入时，可使用自动重试。使用引入概述文档来确定哪种引入选项最适用于方案。

权限

若要对表执行不同的操作，需要特定权限：

若要使用 .append 命令将行添加到现有表，至少需要表引入器权限。
若要使用各种 .set 命令创建新表，至少需要数据库用户权限。
若要使用 .set-or-replace 命令替换现有表中的行，至少需要表管理员权限。

有关权限的详细信息，请参阅 Kusto 基于角色的访问控制。

语法

(.set | .append | .set-or-append | .set-or-replace) [async] tableName [with (propertyName = propertyValue [, ...])] <| queryOrCommand

详细了解语法约定。

参数

客户	类型	必需	说明
async	`string`		如果指定了此项，命令会立即返回，并继续在后台执行引入操作。将返回的 `OperationId` 与 `.show operations` 命令一起使用，以检索引入完成状态和结果。
tableName	`string`	✔️	要将数据引入到其中的表的名称。 tableName 始终与上下文中的数据库相关。
propertyName, propertyValue	`string`		一个或多个支持的引入属性，用于控制引入过程。
queryOrCommand	`string`	✔️	其结果将用作要引入的数据的查询或管理命令的文本。仅支持 `.show` 管理命令。

性能提示

如果查询产生的数据量较大，超过 1 GB，且不需要序列化，则将 distributed 属性设置为 true。然后，多个节点就可以并行产生输出。如果查询结果较小，请不要使用此标志，因为可能会不必要地生成很多小数据分片。
数据引入是一项资源密集型操作，可能会影响数据库上的并发活动，包括正在运行的查询。请避免同时运行过多的引入命令。
请将数据引入量限制为每个引入操作少于 1 GB。如有必要，请使用多个引入命令。

支持的引入属性

属性	类型	描述
`distributed`	`bool`	如果为 `true`，则此命令将以并行方式从执行查询的所有节点引入。默认值为 `false`。请参阅性能提示。
`creationTime`	`string`	`datetime` 值，格式为 ISO8601 `string`，在创建引入的数据盘区时使用。如果未指定，则使用 `now()`。指定时，请确保目标表的有效区合并策略中的 `Lookback` 属性与指定的值一致。
`extend_schema`	`bool`	如果为 `true`，该命令可能会扩展表的架构。默认值为 `false`。此选项仅适用于 `.append`、`.set-or-append` 和 `set-or-replace` 命令。此选项至少需要表管理员权限。
`recreate_schema`	`bool`	如果为 `true`，该命令可能会重新创建表的架构。默认值为 `false`。此选项仅适用于 `.set-or-replace` 命令。在同时设置的情况下，此选项优先于 `extend_schema` 属性。此选项至少需要表管理员权限。
`folder`	`string`	要分配给表的文件夹。如果表已存在，则此属性会替代表的文件夹。
`ingestIfNotExists`	`string`	如果指定了此项，则当表中已有使用相同值通过 `ingest-by:` 标记进行标记的数据时，引入会失败。有关详细信息，请参阅 ingest-by: tags。
`policy_ingestiontime`	`bool`	如果为 `true`，将在表上启用引入时间策略。默认为 `true`。
`tags`	`string`	一个 JSON `string`，表示要与创建的盘区关联的标记的列表。
`docstring`	`string`	用于记录表的说明。
`persistDetails`	一个布尔值，如果指定，则表示该命令应保留详细结果供 .show operation details 命令检索。默认为 `false`。	`with (persistDetails=true)`

架构注意事项

.set-or-replace 会保留架构，除非 extend_schema 或 recreate_schema 引入属性之一已设置为 true。
.set-or-append 和 .append 命令会保留架构，除非 extend_schema 引入属性已设置为 true。
将结果集架构与目标表的架构匹配是基于列类型进行的。不对列名进行匹配。确保查询结果架构列与表的顺序相同，否则数据会被引入到错误的列中。

注意

如果架构被修改，则这是在进行实际数据引入之前在单独的事务中进行的。这意味着，即使在引入数据失败的情况下，也可以修改架构。

字符限制

如果查询生成包含 $ 字符的实体名称，则命令会失败。实体名称必须符合命名规则，因此必须删除 $ 字符，引入命令才能成功。

例如，在下面的查询中，search 运算符会生成列 $table。若要存储查询结果，请使用 project-rename 重命名列。

.set Texas <| search State has 'Texas' | project-rename tableName=$table

返回通过 .set 或 .append 命令创建的盘区的信息。

示例

从查询源创建和更新表

以下查询创建与 RecentErrors 具有相同架构的 LogsTable 表。它会使用过去一小时内的来自 RecentErrors 的所有错误日志更新 LogsTable。

.set RecentErrors <|
   LogsTable
   | where Level == "Error" and Timestamp > now() - time(1h)

使用分布式标志从查询源创建和更新表

以下示例在数据库中以异步方式创建称为 OldExtents 的新表。数据集预计大于 1 GB（超过约 100 万行），因此请使用 distributed 标志。它使用 30 天前创建的 OldExtents 表中的 ExtentId 条目更新 MyExtents。

.set async OldExtents with(distributed=true) <|
   MyExtents 
   | where CreatedOn < now() - time(30d)
   | project ExtentId

将数据追加到表

以下示例筛选 30 天前创建的 ExtentId 表中的条目 MyExtents，并将这些条目追加到具有关联标记的 OldExtents 表中。

.append OldExtents with(tags='["TagA","TagB"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

创建或追加具有可能存在标记数据的表

以下示例以异步方式追加或创建 OldExtents 表。它筛选了 30 天前创建的 ExtentId 表中的 MyExtents 条目，并指定要追加到具有 ingest-by:myTag 的新盘区中的标记。 ingestIfNotExists 参数可确保仅当具有指定标记的表中尚不存在数据时，才会发生引入。

.set-or-append async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
   MyExtents
   | where CreatedOn < now() - time(30d)
   | project ExtentId

创建表或用关联数据替换数据

以下查询将 OldExtents 表中的数据替换为 30 天前创建的 ExtentId 表中的 MyExtents 条目，或者如果表尚不存在，则创建该表。如果数据尚不存在于具有特定标记的表中，使用 ingest-by:myTag 标记新盘区。

.set-or-replace async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

使用关联的数据追加数据

以下示例使用 30 多天前创建的 ExtentId 表中的 MyExtents 条目以异步形式将数据追加到 OldExtents 表中。它为新盘区设置特定的创建时间。

.append async OldExtents with(creationTime='2017-02-13T11:09:36.7992775Z') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

示例输出

下面是可从查询中看到的输出类型的示例。

ExtentId	OriginalSize	ExtentSize	CompressedSize	IndexSize	RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563	1291	5882	1568	4314	10

通过