Dela via

.export till lagring

  • Artikel

Gäller för: ✅Microsoft Fabric✅Azure Data Explorer

Kör en fråga och skriver det första resultatet till en extern molnlagring, som anges av en lagringsanslutningssträng.

Behörigheter

Du måste ha minst Database Viewer behörighet att köra det här kommandot.

Syntax

.export [async] [compressed] toOutputDataFormat(StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] )] <|Query

Läs mer om syntaxkonventioner.

Parametrar

Namn Typ Krävs Beskrivning
async string Om det anges körs kommandot i asynkront läge. Se asynkront läge.
compressed string Om det anges komprimeras utdatalagringsartefakterna som .gz filer. Se egenskapen compressionTypesom stöds för att komprimera Parquet-filer som snabba.
OutputDataFormat string ✔️ Anger dataformatet för lagringsartefakter som skrivits av kommandot. Värden som stöds är: csv, tsv, jsonoch parquet.
StorageConnectionString string En eller flera lagringsanslutningssträngar som anger vilken lagring som data ska skrivas till. Mer än en lagringsanslutningssträng kan anges för skalbara skrivningar. Varje sådan anslutningssträng måste ange de autentiseringsuppgifter som ska användas när du skriver till lagring. När du till exempel skriver till Azure Blob Storage kan autentiseringsuppgifterna vara lagringskontonyckeln eller en delad åtkomstnyckel (SAS) med behörighet att läsa, skriva och lista blobar.
PropertyName, PropertyValue string En kommaavgränsad lista över nyckel/värde-egenskapspar. Se egenskaper som stöds.

Not

Vi rekommenderar starkt att du exporterar data till lagring som är samlokaliserade i samma region som själva databasen. Detta inkluderar data som exporteras så att de kan överföras till en annan molntjänst i andra regioner. Skrivningar bör göras lokalt, medan läsningar kan ske via fjärranslutning.

Egenskaper som stöds

Egenskap Typ Beskrivning
includeHeaders string För csv/tsv utdata styr du genereringen av kolumnrubriker. Kan vara en av none (standard, inga rubrikrader som genereras), all (generera en rubrikrad i varje lagringsartefakt) eller firstFile (generera en rubrikrad endast till den första lagringsartefakten).
fileExtension string Anger "tilläggsdelen" i lagringsartefakten (till exempel .csv eller .tsv). Om komprimering används läggs även .gz till.
namePrefix string Anger ett prefix som ska läggas till i varje genererat lagringsartefaktnamn. Ett slumpmässigt prefix används om det lämnas ospecificerat.
encoding string Anger hur du kodar texten: UTF8NoBOM (standard) eller UTF8BOM.
compressionType string Anger vilken typ av komprimering som ska användas. Möjliga värden är gzip eller snappy. Standardvärdet är gzip. snappy kan (valfritt) användas för parquet format.
distribution string Distributionstips (single, per_node, per_shard). Om värdet är lika med singleskrivs en enda tråd till lagring. Annars exporterar du skrivningar från alla noder som kör frågan parallellt. Se utvärdera plugin-operatorn. Standardvärdet är per_shard.
persistDetails bool Anger att kommandot ska spara sina resultat (se async flagga). Standardvärdet är true i asynkrona körningar, men kan inaktiveras om anroparen inte kräver resultatet). Standardvärdet är att false i synkrona körningar, men kan även aktiveras i dessa.
sizeLimit long Storleksgränsen i byte för en enda lagringsartefakt som skrivits före komprimering. Giltigt intervall: 100 MB (standard) till 4 GB.
parquetRowGroupSize int Relevant endast när dataformatet är Parquet. Styr radgruppens storlek i de exporterade filerna. Standardstorleken för radgrupper är 100 000 poster.
distributed bool Inaktivera eller aktivera distribuerad export. Inställningen false motsvarar single distributionstips. Standardvärdet är sant.
parquetDatetimePrecision string Anger precisionen som ska användas vid export av datetime värden till Parquet. Möjliga värden är millisekunder och mikrosekunder. Standardvärdet är millisekunder.

Autentisering och auktorisering

Autentiseringsmetoden baseras på den angivna anslutningssträngen och de behörigheter som krävs varierar beroende på autentiseringsmetoden.

I följande tabell visas de autentiseringsmetoder som stöds och de behörigheter som krävs för att exportera data till extern lagring efter lagringstyp.

Autentiseringsmetod Azure Blob Storage/Data Lake Storage Gen2 Data Lake Storage Gen1
personifiering Storage Blob Data-deltagare Bidragsgivare
SAS-token (Shared Access) Skriva Skriva
Microsoft Entra-åtkomsttoken Inga extra behörigheter krävs Inga extra behörigheter krävs
Åtkomstnyckel för lagringskonto Inga extra behörigheter krävs Inga extra behörigheter krävs

Returnerar

Kommandona returnerar en tabell som beskriver de genererade lagringsartefakterna. Varje post beskriver en enskild artefakt och innehåller lagringssökvägen till artefakten och hur många poster den innehåller.

Stig 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

Asynkront läge

Om flaggan async anges körs kommandot i asynkront läge. I det här läget returnerar kommandot omedelbart med ett åtgärds-ID, och dataexporten fortsätter i bakgrunden tills den är klar. Åtgärds-ID:t som returneras av kommandot kan användas för att spåra dess förlopp och slutligen dess resultat via följande kommandon:

Efter ett lyckat slutförande kan du till exempel hämta resultaten med hjälp av:

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

Exempel

I det här exemplet kör Kusto frågan och exporterar sedan den första postuppsättningen som skapas av frågan till en eller flera komprimerade CSV-blobar, upp till 1 GB före komprimering. Kolumnnamnetiketter läggs till som den första raden för varje 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"

Fel vid exportkommandon

Exportkommandon kan misslyckas tillfälligt under körningen. Kontinuerlig export automatiskt försöker köra kommandot igen. Vanliga exportkommandon (exportera till lagring, exportera till extern tabell) utför inga återförsök.

  • När exportkommandot misslyckas tas inte artefakter som redan har skrivits till lagring bort. Dessa artefakter finns kvar i lagringen. Om kommandot misslyckas antar du att exporten är ofullständig, även om vissa artefakter har skrivits.
  • Det bästa sättet att spåra både slutförandet av kommandot och artefakterna som exporterades när det lyckades är genom att använda kommandona .show operations och .show operation details.

Lagringsfel

Som standard distribueras exportkommandon så att det kan finnas många samtidiga skrivningar till lagringen. Distributionsnivån beror på typen av exportkommando:

  • Standarddistributionen för vanliga .export kommando är per_shard, vilket innebär att alla utsträckningar som innehåller data för att exportera skrivning till lagring samtidigt.

  • Standardfördelningen för exportera till extern tabell kommandon är per_node, vilket innebär att samtidigheten är antalet noder.

När antalet omfattningar/noder är stort kan det leda till hög belastning på lagringen som resulterar i lagringsbegränsning eller tillfälliga lagringsfel. Följande förslag kan lösa dessa fel (efter prioritetsordning):

  • Öka antalet lagringskonton som anges i exportkommandot eller till externa tabelldefinitionen. Belastningen fördelas jämnt mellan kontona.

  • Minska samtidigheten genom att ange distributionstipset till per_node (se kommandoegenskaper).

  • Minska samtidigheten för antalet noder som exporteras genom att ange egenskapen klientbegäranquery_fanout_nodes_percent till önskad samtidighet (procent av noderna). Egenskapen kan anges som en del av exportfrågan. Följande kommando begränsar till exempel antalet noder som skrivs till lagring samtidigt till 50% av noderna:

    .export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery

  • Minska samtidigheten för antalet trådar som exporteras i varje nod när du använder per shardexport genom att ange egenskapen klientbegäranquery_fanout_threads_percent till önskad samtidighet (procent av trådarna). Egenskapen kan anges som en del av exportfrågan. Följande kommando begränsar till exempel antalet trådar som skrivs till lagring samtidigt till 50% på var och en av noderna:

    .export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery

  • Om du exporterar till en partitionerad extern tabell kan spread/concurrency egenskaper minska samtidigheten (se information i kommandoegenskaper.

  • Om ingen av de tidigare rekommendationerna fungerar kan du helt inaktivera distributionen genom att ange egenskapen distributed till false. Vi rekommenderar dock inte att du gör det, eftersom det kan påverka kommandoprestandan avsevärt.

Auktoriseringsfel

Autentiserings- eller auktoriseringsfel under exportkommandon kan inträffa när de autentiseringsuppgifter som anges i lagringsanslutningssträngen inte tillåts skriva till lagring. Om du använder impersonate eller en användardelegerings-SAS-token för exportkommandot krävs Storage Blob Data Contributor roll för att skriva till lagringskontot. Mer information finns i Storage-anslutningssträngar.

Mappning av datatyper

Parquet-datatyper mappning

Vid export mappas Kusto-datatyper till Parquet-datatyper med hjälp av följande regler:

Kusto-datatyp Parquet-datatyp Parquet-anteckning Kommentarer
bool BOOLEAN
datetime INT64 TIMESTAMP_MICROS
dynamic BYTE_ARRAY UTF-8 Serialiserad som JSON-sträng
guid BYTE_ARRAY UTF-8
int INT32
long INT64
real DOUBLE
string BYTE_ARRAY UTF-8
timespan INT64 Lagrade som fästingar (antal 100 nanosekunder)
decimal FIXED_LENGTH_BYTE_ARRAY DECIMAL

Relaterat innehåll