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

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

命令	如果表存在	如果表不存在
.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	✔	其结果将用作要引入的数据的查询或管理命令的文本。

支持的引入属性

属性	类型​​	描述
creationTime	string	日期时间值，格式为 ISO8601 字符串，在创建引入的数据盘区时使用。 如果未指定，则使用 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 字符串，表示要与创建的盘区关联的标记的列表。
docstring	string	用于记录表的说明。
distributed	bool	如果为 true，则此命令将以并行方式从执行查询的所有节点引入。 默认值为 false。 请参阅性能提示。
persistDetails	一个布尔值，如果指定，则表示该命令应保留详细结果供 .show operation details 命令检索。 默认为 false。	with (persistDetails=true)

架构注意事项

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

性能提示

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

字符限制

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

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

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

示例

在数据库中创建名为 RecentErrors 的新表，该表与 LogsTable 具有相同的架构，并保存最近一小时的所有错误记录。

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

在数据库中创建一个名为“OldExtents”的新表，使该表包含单个列（即“ExtentId”），并保存数据库中已创建 30 天以上的所有盘区的盘区 ID。 数据库有一个名为“MyExtents”的现有表。 由于数据集预计大于 1 GB（超过约 100 万行），因此请使用 distributed 标志

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

在当前数据库中将数据追加到名为“OldExtents”的现有表，该表包含单个列（即“ExtentId”），并保存数据库中已创建 30 天以上的所有盘区的盘区 ID。 基于名为“MyExtents”的现有表，用标记 tagA 和 tagB 来标记新盘区。

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

在当前数据库中将数据追加到“OldExtents”表，或者创建该表（如果不存在）。 使用 ingest-by:myTag 标记新盘区。 只有在表尚未包含使用 ingest-by:myTag 标记的盘区的情况下，才应当基于名为“MyExtents”的现有表来进行标记。

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

在当前数据库中替换“OldExtents”表中的数据，或者创建该表（如果不存在）。 使用 ingest-by:myTag 标记新盘区。

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

在当前数据库中将数据追加到“OldExtents”表，并将已创建盘区的创建时间设置为过去的某个具体日期/时间。

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

返回输出

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

示例输出

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