Sdílet prostřednictvím

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

  • Článek

Platí pro: ✅Microsoft Fabric✅Azure Data Explorer

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] [] toOutputDataFormat( 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 compressionTypevlastnost 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, jsona 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 může být zadán více než jeden 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á databáze. 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_shardje .
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 jednoho artefaktu úložiště zapsaného 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ů:

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ž do 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ého exportu příkaz automaticky opakuje. 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 exportu 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í rozdělení pro export do příkazů externí tabulky je per_node, což znamená, že souběžnost je počet uzlů.

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ě. Tyto chyby můžou překonat následující návrhy (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ě distribuuje 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 vlastnostiquery_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ů:

    .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 vlastnostiquery_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:

    .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 předchozích doporučení nefunguje, můžete distribuci úplně zakázat nastavením vlastnosti distributed 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Ý

Související obsah