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

Přepněte služby pomocí rozevíracího seznamu Verze . Přečtěte si další informace o navigaci.
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í.

Oprávnění

Pokud chcete v tabulce provádět různé akce, potřebujete 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 | .append | .set-or-append | .set-or-replace) [async] tableName [with( propertyName= propertyValue [, ...]] )<|queryOrCommand

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

Parametry

Název	Typ	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 jeden gigabajt (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ž jednu GB na každou 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	Typ	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 ISO8601 string, 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 trueje v tabulce povolená zásada času příjmu dat. Výchozí hodnota je true.
tags	string	JSON string , 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

Návraty

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

Příklady

Vytvoření a aktualizace tabulky ze zdroje dotazů

Následující dotaz vytvoří RecentErrors tabulku se stejným schématem jako LogsTable. RecentErrors Aktualizuje se všemi protokoly chyb za LogsTable poslední hodinu.

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

Vytvoření a aktualizace tabulky ze zdroje dotazu pomocí distribuovaného příznaku

Následující příklad vytvoří novou tabulku volanou OldExtents v databázi asynchronně. Očekává se, že datová sada bude větší než jedna GB (více než jeden milion řádků), takže se použije distribuovaný příznak. Aktualizuje OldExtents se o ExtentId položky z MyExtents tabulky vytvořené před více než 30 dny.

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

Připojení dat k tabulce

Následující příklad filtruje ExtentId položky v MyExtents tabulce, které byly vytvořeny před více než 30 dny a připojí položky k OldExtents tabulce s přidruženými značkami.

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

Vytvoření nebo připojení tabulky s pravděpodobně existujícími označenými daty

Následující příklad buď připojí nebo vytvoří OldExtents tabulku asynchronně. Filtruje ExtentId položky v MyExtents tabulce vytvořené před více než 30 dny a určuje značky, které mají být připojeny k novým rozsahům s ingest-by:myTag. Parametr ingestIfNotExists zajišťuje, že k příjmu dat dojde pouze v případě, že data v tabulce se zadanou značkou ještě neexistují.

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

Vytvoření tabulky nebo nahrazení dat přidruženými daty

Následující dotaz nahradí data v OldExtents tabulce nebo vytvoří tabulku, pokud ještě neexistuje, položkami ExtentId v MyExtents tabulce, které byly vytvořeny před více než 30 dny. Označte nový rozsah, ingest-by:myTag pokud data v tabulce ještě neexistují, pomocí zadané značky.

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

Připojení dat s přidruženými daty

Následující příklad asynchronně připojí data k OldExtents tabulce pomocí ExtentId položek z MyExtents tabulky, které byly vytvořeny před více než 30 dny. Nastaví konkrétní čas vytvoření pro nové rozsahy.

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

Ukázkový výstup

Následuje ukázka typu výstupu, který můžete vidět z dotazů.

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

Související obsah

• formáty dat podporované pro příjem dat
• Příjem vložených dat
• Příjem z úložiště