你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
从查询引入（.set、.append、.set-or-append、.set-or-replace）
适用于：✅Microsoft Fabric✅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 |
日期时间值，格式为 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 |
用于记录表的说明。 |
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
示例
在数据库中创建名为 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 |