Ingestování z dotazu (.set, .append, .set-or-append, .set-or-replace)

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer

Tyto příkazy spustí dotaz nebo příkaz pro správu a ingestuje výsledky dotazu do tabulky. Rozdíl mezi těmito příkazy spočívá v tom, jak pracují s existujícími nebo neexistujícími tabulkami a daty.

Příkaz	Pokud tabulka existuje	Pokud tabulka neexistuje
.set	Příkaz selže.	Tabulka se vytvoří a data se ingestují.
.append	Data se připojují k tabulce.	Příkaz selže.
.set-or-append	Data se připojují k tabulce.	Tabulka se vytvoří a data se ingestují.
.set-or-replace	Data nahradí data v tabulce.	Tabulka se vytvoří a data se ingestují.

Pokud chcete zrušit ingestování z příkazu dotazu, přečtěte si téma cancel operation.

Poznámka:

Příjem dat z dotazu je přímý příjem dat. Proto neobsahuje automatické opakování. Při příjmu prostřednictvím služby pro správu dat jsou k dispozici automatické opakování. V dokumentu s přehledem příjmu dat se můžete rozhodnout, která možnost příjmu dat je pro váš scénář nejvhodnější.

Oprávnění

K provádění různých akcí v tabulce se vyžadují konkrétní oprávnění:

• Pokud chcete přidat řádky do existující tabulky pomocí .append příkazu, potřebujete minimálně oprávnění Ingestoru tabulky.
• Pokud chcete vytvořit novou tabulku pomocí různých .set příkazů, potřebujete minimálně oprávnění uživatele databáze.
• Pokud chcete nahradit řádky v existující tabulce pomocí .set-or-replace příkazu, potřebujete minimálně oprávnění správce tabulky.

Další informace o oprávněních najdete v tématu Řízení přístupu na základě role Kusto.

Syntaxe

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

Přečtěte si další informace o konvencích syntaxe.

Parametry

Název	Type	Požadováno	Popis
async	string		Pokud je zadáno, příkaz se okamžitě vrátí a pokračuje v příjmu dat na pozadí. Pomocí vráceného OperationId .show operations příkazu načtěte stav a výsledky dokončení příjmu dat.
tableName	string	✔️	Název tabulky pro příjem dat do. TableName vždy souvisí s databází v kontextu.
propertyName, propertyValue	string		Jedna nebo více podporovaných vlastností příjmu dat sloužících k řízení procesu příjmu dat.
queryOrCommand	string	✔️	Text dotazu nebo příkazu pro správu, jehož výsledky se používají jako data k ingestování. Podporují se jenom .show příkazy pro správu.

Tipy týkající se výkonu

• distributed Nastavte vlastnost tak, aby true byla velikost dat vytvořená dotazem velká, překročila 1 GB a nevyžaduje serializaci. Pak může několik uzlů vytvořit výstup paralelně. Tento příznak nepoužívejte, pokud jsou výsledky dotazu malé, protože může zbytečně generovat mnoho malých datových horizontálních oddílů.
• Příjem dat je operace náročná na prostředky, která může ovlivnit souběžné aktivity v databázi, včetně spuštěných dotazů. Vyhněte se spouštění příliš mnoha příkazů pro příjem dat najednou.
• Omezte data pro příjem dat na méně než 1 GB na operaci příjmu dat. V případě potřeby použijte několik příkazů pro příjem dat.

Podporované vlastnosti příjmu dat

Vlastnost	Type	Popis
distributed	bool	Pokud truepříkaz ingestuje ze všech uzlů, které spouští dotaz paralelně. Výchozí hodnota je false. Podívejte se na tipy k výkonu.
creationTime	string	Hodnota datetime formátovaná jako řetězec ISO8601, která se má použít při vytváření ingestovaných rozsahů dat. Pokud není zadáno, now() použije se. Po zadání se ujistěte, že Lookback je vlastnost v efektivní zásadě sloučení rozsahů cílové tabulky zarovnaná se zadanou hodnotou.
extend_schema	bool	Pokud truepříkaz může rozšířit schéma tabulky. Výchozí hodnota je false. Tato možnost se vztahuje pouze na .appendpříkazy , .set-or-appenda set-or-replace příkazy. Tato možnost vyžaduje alespoň oprávnění správce tabulky.
recreate_schema	bool	Pokud truepříkaz může znovu vytvořit schéma tabulky. Výchozí hodnota je false. Tato možnost se vztahuje pouze na .set-or-replace příkaz. Tato možnost má přednost před extend_schema vlastností, pokud jsou obě nastaveny. Tato možnost vyžaduje alespoň oprávnění správce tabulky.
folder	string	Složka, která se má přiřadit k tabulce. Pokud tabulka již existuje, tato vlastnost přepíše složku tabulky.
ingestIfNotExists	string	Pokud je zadáno, příjem dat selže, pokud tabulka již obsahuje data označená značkou ingest-by: se stejnou hodnotou. Další informace najdete v tématu ingestování podle: značek.
policy_ingestiontime	bool	Pokud truese v tabulce povolí zásada času příjmu dat. Výchozí hodnota je true.
tags	string	Řetězec JSON, který představuje seznam značek , které se mají přidružit k vytvořenému rozsahu.
docstring	string	Popis, který se používá k dokumentaci tabulky.
persistDetails	Logická hodnota, která pokud je zadána, označuje, že příkaz by měl zachovat podrobné výsledky pro načtení příkazem .show podrobnosti operace. Výchozí hodnota falseje .	with (persistDetails=true)

Důležité informace o schématu

• .set-or-replace zachová schéma, pokud není nastavena jedna z extend_schema vlastností nebo recreate_schema vlastnost příjmu truedat .
• .set-or-append a .append příkazy zachová schéma, pokud není vlastnost příjmu extend_schema nastavena na true.
• Porovnávání schématu sady výsledků s cílovou tabulkou je založeno na typech sloupců. Názvy sloupců nejsou shodné. Ujistěte se, že sloupce schématu výsledků dotazu jsou ve stejném pořadí jako tabulka, jinak se data ingestují do nesprávných sloupců.

Upozornění

Pokud je schéma změněno, stane se v samostatné transakci před skutečným příjmem dat. To znamená, že schéma může být změněno, i když dojde k selhání ingestování dat.

Omezení znaků

Příkaz selže, pokud dotaz vygeneruje název entity se znakem $ . Názvy entit musí splňovat pravidla pojmenování, takže $ znak musí být odebrán, aby příkaz ingestování proběhl úspěšně.

Například v následujícím dotazu search operátor vygeneruje sloupec $table. Pokud chcete uložit výsledky dotazu, přejmenujte sloupec pomocí přejmenování projektu.

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

Příklady

Vytvořte novou tabulku volanou RecentErrors v databázi, která má stejné schéma jako LogsTable a obsahuje všechny záznamy chyb za poslední hodinu.

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

Vytvořte novou tabulku s názvem OldExtents v databázi, která obsahuje jeden sloupec ExtentId a obsahuje ID rozsahu všech rozsahů v databázi, které byly vytvořeny před více než 30 dny. Databáze má existující tabulku s názvem MyExtents. Vzhledem k tomu, že se očekává, že datová sada bude větší než 1 GB (více než přibližně 1 milion řádků), použijte distribuovaný příznak.

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

Připojte data k existující tabulce s názvem OldExtents v aktuální databázi, která obsahuje jeden sloupec ExtentId a obsahuje ID rozsahu všech rozsahů v databázi, které byly vytvořeny více než 30 dní dříve. Označte nový rozsah značkami tagA a tagBna základě existující tabulky s názvem "MyExtents".

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

Připojte data k tabulce OldExtents v aktuální databázi nebo vytvořte tabulku, pokud ještě neexistuje. Označte nový rozsah značkou ingest-by:myTag. Proveďte to pouze v případě, že tabulka ještě neobsahuje rozsah označený ingest-by:myTagna základě existující tabulky s názvem "MyExtents".

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

Nahraďte data v tabulce OldExtents v aktuální databázi nebo vytvořte tabulku, pokud ještě neexistuje. Označte nový rozsah značkou ingest-by:myTag.

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

Připojte data k tabulce OldExtents v aktuální databázi a současně nastavujte čas vytváření rozsahů na konkrétní datum a čas v minulosti.

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

Návratový výstup

Vrátí informace o rozsahech vytvořených z důvodu .set příkazu nebo .append příkazu.

Příklad výstupu

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