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

  • Článek

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

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

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

Poznámka

Tato metoda příjmu dat je určená ke zkoumání a vytváření prototypů. Nepoužívejte ho v produkčních nebo velkoobsadových scénářích.

Oprávnění

K provádění různých akcí s tabulkou 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áva tabulky.

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

Syntax

(.set.append.set-or-append | | | .set-or-replace) [async] tableName [with(propertyNamepropertyValue= [, ...]] <|)dotaz nebo příkaz

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

Parametry

Název Typ Vyžadováno Popis
Asynchronní string Pokud je zadaný, příkaz vrátí a bude pokračovat v příjmu dat na pozadí. Pomocí vráceného OperationId příkazu s příkazem .show operations načtěte stav dokončení příjmu dat a výsledky.
Tablename string ✔️ Název tabulky, do které chcete ingestovat data. Tabulka tableName vždy souvisí s databází v kontextu.
propertyName, propertyValue string Jedna nebo více podporovaných vlastností příjmu dat , které slouží k řízení procesu příjmu dat.
dotaz nebo příkaz string ✔️ Text dotazu nebo příkazu pro správu, jehož výsledky se použijí jako data k ingestování.

Poznámka

Podporují se jenom .show příkazy pro správu.

Podporované vlastnosti příjmu dat

Vlastnost Typ Description
creationTime string Hodnota datetime formátovaná jako ISO8601 řetězec, který se použije při vytváření rozsahů přijatých dat. Pokud není zadán, now() použije se. Při zadání se ujistěte, že Lookback je vlastnost v efektivních zásadách sloučení Rozsahy cílové tabulky zarovnaná se zadanou hodnotou.
extend_schema bool Pokud true, příkaz může rozšířit schéma tabulky. Výchozí je false. Tato možnost platí jenom pro .appendpříkazy , .set-or-appenda set-or-replace . Tato možnost vyžaduje alespoň oprávnění Správa tabulky.
recreate_schema bool Pokud true, příkaz může znovu vytvořit schéma tabulky. Výchozí je false. Tato možnost platí jenom pro .set-or-replace příkaz . Tato možnost má přednost před vlastností, extend_schema pokud jsou nastaveny obě možnosti. Tato možnost vyžaduje alespoň oprávnění Správa 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 ingest-by: tags.
policy_ingestiontime bool Pokud true, zásada času příjmu dat bude povolena v tabulce. Výchozí formát 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 použitý k dokumentaci tabulky.
distributed bool Pokud true, příkaz ingestuje ze všech uzlů, které dotaz spouští paralelně. Výchozí je false. Podívejte se na tipy pro zvýšení výkonu.
persistDetails Logická hodnota, která, pokud je zadaná, označuje, že příkaz by měl zachovat podrobné výsledky pro načtení příkazem .show operation details . Výchozí hodnota je false. with (persistDetails=true)

Důležité informace o schématu

  • .set-or-replacezachová schéma, pokud některá z vlastností nebo recreate_schema příjmu extend_schema dat není nastavená na truehodnotu .
  • .set-or-append Příkazy a .append zachovávají schéma, pokud vlastnost příjmu extend_schema dat není nastavená na truehodnotu .
  • Porovnání schématu sady výsledků dotazu s schématem cílové tabulky 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, dojde k tomu 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í příjmu dat.

Tipy pro zvýšení výkonu

  • Příjem dat je operace náročná na prostředky, která může mít vliv na souběžné aktivity v clusteru, včetně spouštění dotazů. Vyhněte se spouštění příliš mnoha příkazů pro příjem dat najednou.
  • Omezte počet dat 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.
  • distributed Nastavte příznak na hodnotu true , pokud je množství dat vytvářených dotazem velké, překračuje 1 GB a nevyžaduje serializaci. Výstup pak může paralelně vytvářet více uzlů. Tento příznak nepoužívejte, pokud jsou výsledky dotazů malé, protože by mohly zbytečně generovat mnoho malých shardů dat.

Omezení znaků

Příkaz selže, pokud dotaz vygeneruje název entity se znakem $ . Názvy entit musí být v souladu s pravidly 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říkazu project-rename .

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

Příklady

Vytvořte v databázi novou tabulku s názvem RecentErrors , která má stejné schéma jako LogsTable a obsahuje všechny chybové záznamy 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á má jediný sloupec ExtentId a obsahuje ID rozsahů všech rozsahů v databázi, která byla vytvořena před více než 30 dny. Databáze obsahuje 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á má jeden sloupec ExtentId a obsahuje ID rozsahů všech rozsahů v databázi, které byly vytvořeny před více než 30 dny. 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. Nový rozsah označte pomocí ingest-by:myTag. Udělejte to jenom v případě, že tabulka ještě neobsahuje rozsah označený ingest-by:myTagpomocí , na 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. Nový rozsah označte pomocí 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 nastavujte čas vytvoř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

Vrácený výstup

Vrátí informace o rozsahech vytvořených příkazem .set nebo .append .

Příklad výstupu

Id rozsahu Původní velikost Velikost rozsahu CompressedSize Velikost indexu Rowcount
23a05ed6-376d-4119-b1fc-6493bcb05563 1291 5882 1568 4314 10