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

Статья
09/25/2024

Область применения: ✅Microsoft Fabric ✅Azure Data Explorer

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

Команда	Если таблица существует	Если таблица не существует
`.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

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

Параметры

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

Советы по производительности

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

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

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

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

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

Например, в следующем запросе search оператор создает столбец $table. Чтобы сохранить результаты запроса, используйте переименование проекта для переименования столбца.

.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

Поделиться через