Прием из запроса (.set, .append, .set-or-append, .set-or-replace)

Статья
07/13/2023

Эти команды выполняют запрос или команду управления и помечают результаты запроса в таблицу. Разница между этими командами заключается в том, как они обрабатывают существующие или несуществующие таблицы и данные.

Команда	Если таблица существует	Если таблица не существует
`.set`	Команда завершается со сбоем	Таблица создается, а данные принимаются
`.append`	Данные добавляются в таблицу	Команда завершается со сбоем
`.set-or-append`	Данные добавляются в таблицу	Таблица создается, а данные принимаются
`.set-or-replace`	Данные заменяют данные в таблице	Таблица создается, а данные принимаются

Сведения об отмене приема из команды запроса см. в разделе cancel operation.

Примечание

Этот метод приема предназначен для исследования и создания прототипов. Не используйте его в рабочих или больших объемах сценариев.

Разрешения

Для выполнения различных действий с таблицей требуются определенные разрешения:

Чтобы добавить строки в существующую таблицу .append с помощью команды , вам потребуется минимум разрешений Ingestor таблицы.
Чтобы создать таблицу с помощью различных .set команд, требуется минимум разрешений пользователя базы данных.
Чтобы заменить строки в существующей таблице с помощью .set-or-replace команды , требуется минимум разрешений Администратор таблиц.

Дополнительные сведения о разрешениях см. в разделе Управление доступом на основе ролей Kusto.

Синтаксис

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

Дополнительные сведения о соглашениях о синтаксисе.

Параметры

Имя	Тип	Обязательно	Описание
async	`string`		Если этот параметр указан, команда вернет и продолжит прием в фоновом режиме. Используйте возвращаемый `OperationId` с командой `.show operations` , чтобы получить состояние завершения приема и результаты.
tableName	`string`	✔️	Имя таблицы для приема данных. TableName всегда связан с базой данных в контексте.
propertyName, propertyValue	`string`		Одно или несколько поддерживаемых свойств приема, используемых для управления процессом приема.
queryOrCommand	`string`	✔️	Текст запроса или команды управления, результаты которых используются в качестве данных для приема.

Примечание

Поддерживаются только .show команды управления.

Поддерживаемые свойства приема

Свойство	Тип	Описание
`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:.
`policy_ingestiontime`	`bool`	Если `true`задано значение , для таблицы будет включена политика времени приема . Значение по умолчанию — `true`.
`tags`	`string`	Строка JSON, представляющая список тегов , которые необходимо связать с созданным экстентом.
`docstring`	`string`	Описание, используемое для документирования таблицы.
`distributed`	`bool`	Если `true`задано значение , команда выполняется со всех узлов, выполняющих запрос параллельно. По умолчанию — `false`. См. советы по производительности.
`persistDetails`	Логическое значение, указывающее, что команда должна сохранять подробные результаты для получения командой .show operation details . По умолчанию — `false`.	`with (persistDetails=true)`

Советы по улучшению производительности

Прием данных — это ресурсоемкая операция, которая может повлиять на параллельные действия в кластере, в том числе на выполнение запросов. Избегайте одновременного выполнения слишком большого количества команд приема.
Ограничьте объем данных для приема менее 1 ГБ на операцию приема. При необходимости используйте несколько команд приема.
Установите для флага distributed значение , true если объем данных, создаваемых запросом, большой, превышает 1 ГБ и не требует сериализации. Затем несколько узлов могут создавать выходные данные параллельно. Не используйте этот флаг, если результаты запроса небольшие, так как он может создавать множество небольших сегментов данных.

Ограничение символов

Команда завершится ошибкой, если запрос создает имя сущности с символом $ . Имена сущностей должны соответствовать правилам именования, поэтому $ символ должен быть удален для успешного выполнения команды приема.

Например, в следующем запросе 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 дней назад. База данных включает таблицу с именем MyExtents. Так как набор данных должен быть больше 1 ГБ (более 1 миллиона строк), используйте флаг распределения .

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

Добавьте данные в существующую таблицу с именем OldExtents в текущей базе данных, содержащей один столбец ExtentId с идентификаторами всех экстентов в базе данных, которые были созданы более чем 30 дней назад. Присвойте новому экстенту теги tagA и tagB на основе существующей таблицы с именем MyExtents.

.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

Return output

Возвращает сведения об экстентах, созданных в результате выполнения команд .set или .append.

Пример выходных данных

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