Export dat do cloudového úložiště

Článek
07/03/2024

Spustí dotaz a zapíše první sadu výsledků do externího cloudového úložiště určeného připojovací řetězec úložiště.

Oprávnění

Ke spuštění tohoto příkazu musíte mít alespoň oprávnění prohlížeče databáze.

Syntaxe

.export[asynccompressed] [] to OutputDataFormat ( StorageConnectionString [, ...] ) [with ( PropertyName = PropertyValue [, ...] ] <| )Dotaz

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

Parametry

Název	Type	Požadováno	Popis
`async`	`string`		Pokud je zadaný, příkaz se spustí v asynchronním režimu. Viz asynchronní režim.
`compressed`	`string`		Pokud je zadáno, zkomprimují se výstupní artefakty úložiště jako `.gz` soubory. Podívejte se na podporovanou `compressionType` vlastnost pro komprimaci souborů Parquet jako snappy.
OutputDataFormat	`string`	✔️	Označuje formát dat artefaktů úložiště zapsaných příkazem. Podporované hodnoty jsou: `csv`, `tsv`, `json`a `parquet`.
StorageConnectionString	`string`		Jeden nebo více připojovací řetězec úložiště označující, do kterého úložiště se mají data zapisovat. Pro škálovatelné zápisy je možné zadat více připojovací řetězec úložiště. Každý takový připojovací řetězec musí označovat přihlašovací údaje, které se mají použít při zápisu do úložiště. Například při zápisu do služby Azure Blob Storage můžou být přihlašovací údaje klíčem účtu úložiště nebo sdíleným přístupovým klíčem (SAS) s oprávněními ke čtení, zápisu a výpisu objektů blob.
PropertyName, PropertyValue	`string`		Čárkami oddělený seznam párů vlastností klíč-hodnota. Viz podporované vlastnosti.

Poznámka:

Důrazně doporučujeme exportovat data do úložiště, které se nachází ve stejné oblasti jako samotný cluster. To zahrnuje data, která se exportují, aby je bylo možné přenést do jiné cloudové služby v jiných oblastech. Zápisy by se měly provádět místně, zatímco čtení může probíhat vzdáleně.

Podporované vlastnosti

Vlastnost	Type	Popis
`includeHeaders`	`string`	Pro `csv`/`tsv` výstup určuje generování záhlaví sloupců. Může to být jedna z `none` hodnot (výchozí, nevygenerují se žádné řádky záhlaví), `all` (vygenerují řádek záhlaví do každého artefaktu úložiště) nebo `firstFile` (vygeneruje řádek záhlaví pouze do prvního artefaktu úložiště).
`fileExtension`	`string`	Označuje část "rozšíření" artefaktu úložiště (například `.csv` `.tsv`). Pokud se použije komprese, `.gz` připojí se také.
`namePrefix`	`string`	Označuje předponu, která se má přidat ke každému vygenerovanému názvu artefaktu úložiště. Pokud není zadána levostranná předpona, použije se náhodná předpona.
`encoding`	`string`	Určuje, jak kódovat text: `UTF8NoBOM` (výchozí) nebo `UTF8BOM`.
`compressionType`	`string`	Určuje typ komprese, která se má použít. Možné hodnoty jsou `gzip` nebo `snappy`. Výchozí hodnota je `gzip`. `snappy` lze (volitelně) použít pro `parquet` formát.
`distribution`	`string`	Distribuční tip (`single`, `per_node`, `per_shard`). Pokud se hodnota rovná `single`, jedno vlákno zapíše do úložiště. Jinak exportuje zápisy ze všech uzlů, které spouští dotaz paralelně. Viz operátor vyhodnocovat modul plug-in. Výchozí hodnota `per_shard`je .
`persistDetails`	`bool`	Označuje, že příkaz by měl zachovat výsledky (viz `async` příznak). Výchozí nastavení `true` je v asynchronních spuštěních, ale je možné ho vypnout, pokud volající nevyžaduje výsledky). Výchozí nastavení `false` je v synchronních spuštěních, ale můžete je také zapnout.
`sizeLimit`	`long`	Omezení velikosti v bajtech zapisovaných artefaktů úložiště (před kompresí) Platný rozsah: 100 MB (výchozí) až 4 GB.
`parquetRowGroupSize`	`int`	Relevantní pouze v případech, kdy je formát dat Parquet. Určuje velikost skupiny řádků v exportovaných souborech. Výchozí velikost skupiny řádků je 100 000 záznamů.
`distributed`	`bool`	Zakažte nebo povolte distribuovaný export. Nastavení na hodnotu false je ekvivalentem nápovědy k `single` distribuci. Výchozí hodnota je true.
`parquetDatetimePrecision`	`string`	Určuje přesnost, která se má použít při exportu `datetime` hodnot do Parquet. Možné hodnoty jsou milisekundy a mikrosekundy. Výchozí hodnota je milisekund.

Ověřování a autorizace

Metoda ověřování je založená na zadaném připojovací řetězec a požadovaná oprávnění se liší v závislosti na metodě ověřování.

Následující tabulka uvádí podporované metody ověřování a oprávnění potřebná k exportu dat do externího úložiště podle typu úložiště.

Metoda ověřování	Azure Blob Storage / Data Lake Storage Gen2	Data Lake Storage Gen1
Zosobnění	Přispěvatel dat objektů blob úložiště	Přispěvatel
Token sdíleného přístupu (SAS)	Write	Write
Přístupový token Microsoft Entra	Nevyžaduje se žádná další oprávnění.	Nevyžaduje se žádná další oprávnění.
Přístupový klíč účtu úložiště	Nevyžaduje se žádná další oprávnění.	Nevyžaduje se žádná další oprávnění.

Návraty

Příkazy vrátí tabulku, která popisuje vygenerované artefakty úložiště. Každý záznam popisuje jeden artefakt a zahrnuje cestu k úložišti k artefaktu a počet záznamů, které obsahuje.

Cesta	NumRecords
http://storage1.blob.core.windows.net/containerName/export_1_d08afcae2f044c1092b279412dcb571b.csv	10
http://storage1.blob.core.windows.net/containerName/export_2_454c0f1359e24795b6529da8a0101330.csv	15

Asynchronní režim

async Pokud je příznak zadán, příkaz se spustí v asynchronním režimu. V tomto režimu příkaz okamžitě vrátí ID operace a export dat pokračuje na pozadí až do dokončení. ID operace vrácené příkazem lze použít ke sledování jeho průběhu a nakonec k jeho výsledkům pomocí následujících příkazů:

.show operations: Sledujte průběh.
.show operation details: Získejte výsledky dokončení.

Po úspěšném dokončení můžete například načíst výsledky pomocí:

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

Příklady

V tomto příkladu Kusto spustí dotaz a pak exportuje první sadu záznamů vytvořenou dotazem do jednoho nebo více komprimovaných objektů blob CSV až 1 GB před kompresí. Popisky názvů sloupců se přidají jako první řádek každého objektu blob.

.export
  async compressed
  to csv (
    h@"https://storage1.blob.core.windows.net/containerName;secretKey",
    h@"https://storage1.blob.core.windows.net/containerName2;secretKey"
  ) with (
    sizeLimit=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

Selhání při exportu příkazů

Příkazy exportu můžou během provádění přechodně selhat. Průběžný export automaticky zopakuje příkaz. Běžné příkazy exportu (export do úložiště, export do externí tabulky) neprovádějí žádné opakování.

Když příkaz pro export selže, artefakty, které už byly zapsány do úložiště, se neodstraní. Tyto artefakty zůstanou v úložišti. Pokud příkaz selže, předpokládejme, že export není úplný, i když byly zapsány některé artefakty.
Nejlepší způsob, jak sledovat dokončení příkazu i artefakty exportované po úspěšném dokončení, je použití .show operations příkazů a .show operation details příkazů.

Selhání úložiště

Ve výchozím nastavení jsou příkazy pro export distribuovány tak, aby do úložiště mohlo existovat mnoho souběžných zápisů. Úroveň distribuce závisí na typu příkazu exportu:

Výchozí rozdělení pro běžný .export příkaz je per_shard, což znamená, že všechny rozsahy , které obsahují data pro souběžný export zápisu do úložiště.
Výchozí distribuce exportu do příkazů externí tabulky je per_node, což znamená, že souběžnost je počet uzlů v clusteru.

Pokud je počet rozsahů a uzlů velký, může to vést k vysokému zatížení úložiště, které vede k omezování úložiště nebo přechodným chybám úložiště. Následující návrhy mohou tyto chyby překonat (podle pořadí priorit):

Zvyšte počet účtů úložiště zadaných pro příkaz pro export nebo do definice externí tabulky (zatížení se rovnoměrně rozdělí mezi účty).
Snižte souběžnost nastavením nápovědy k per_node distribuci (viz vlastnosti příkazu).
Snižte souběžnost počtu uzlů exportovaných nastavením vlastnosti query_fanout_nodes_percent požadavku klienta na požadovanou souběžnost (procento uzlů). Vlastnost lze nastavit jako součást exportovacího dotazu. Následující příkaz například omezuje počet uzlů, které se zapisují do úložiště souběžně, na 50 % uzlů clusteru:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Snižte souběžnost počtu vláken exportovaných v každém uzlu při použití jednotlivých exportů horizontálních oddílů nastavením vlastnosti query_fanout_threads_percent požadavku klienta na požadovanou souběžnost (procento vláken). Vlastnost lze nastavit jako součást exportovacího dotazu. Následující příkaz například omezuje počet vláken zapisovaných do úložiště souběžně na 50 % na každém uzlu clusteru:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
Pokud exportujete do dělené externí tabulky, nastavení spread/concurrency vlastností může snížit souběžnost (viz podrobnosti ve vlastnostech příkazu.
Pokud žádná z výše uvedených možností nefunguje, můžete distribuci úplně zakázat nastavením distributed vlastnosti na false. Nedoporučujeme to ale, protože to může výrazně ovlivnit výkon příkazu.

Selhání autorizace

K selhání ověřování nebo autorizace během příkazů exportu může dojít v případě, že přihlašovací údaje zadané v úložišti připojovací řetězec nejsou povolené pro zápis do úložiště. Pokud pro příkaz exportu používáte impersonate token SAS delegovaný uživatelem, je k zápisu do účtu úložiště potřeba role Přispěvatel dat objektů blob služby Storage. Další informace najdete v tématu Připojovací řetězec úložiště.

Mapování datových typů

Mapování datových typů Parquet

Při exportu se datové typy Kusto mapují na datové typy Parquet pomocí následujících pravidel:

Datový typ Kusto	Datový typ Parquet	Anotace Parquet	Komentáře
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	Serializováno jako řetězec JSON
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Uložený jako ticks (počet 100 nanosekundových jednotek)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DESETINNÝ

Sdílet prostřednictvím