Delen via

.export naar opslag

  • Artikel

Van toepassing op: ✅Microsoft Fabric✅Azure Data Explorer-

Voert een query uit en schrijft de eerste resultatenset naar een externe cloudopslag, die is opgegeven door een -opslagverbindingsreeks.

Machtigingen

U moet ten minste Database Viewer machtigingen hebben om deze opdracht uit te voeren.

Syntaxis

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

Meer informatie over syntaxisconventies.

Parameters

Naam Type Vereist Beschrijving
asynchrone string Indien opgegeven, wordt de opdracht uitgevoerd in asynchrone modus. Zie asynchrone modus.
gecomprimeerde bool Indien opgegeven, worden de uitvoeropslagartefacten gecomprimeerd in de indeling die is opgegeven door de compressionTypeondersteunde eigenschap.
OutputDataFormat- string ✔️ De gegevensindeling van de opslagartefacten die door de opdracht zijn geschreven. Ondersteunde waarden zijn: csv, tsv, jsonen parquet.
StorageConnectionString- string Een of meer opslagverbindingsreeksen die aangeven naar welke opslag de gegevens moeten worden geschreven. Er kunnen meer dan één opslagverbindingsreeks worden opgegeven voor schaalbare schrijfbewerkingen. Elke dergelijke verbindingsreeks moet de referenties opgeven die moeten worden gebruikt bij het schrijven naar de opslag. Wanneer u bijvoorbeeld naar Azure Blob Storage schrijft, kunnen de referenties de sleutel van het opslagaccount zijn of een SAS (Shared Access Key) met de machtigingen voor het lezen, schrijven en vermelden van blobs.
PropertyName, PropertyValue string Een door komma's gescheiden lijst met sleutel-waarde-eigenschapsparen. Zie ondersteunde eigenschappen.

Notitie

We raden u ten zeerste aan om gegevens te exporteren naar opslag die zich in dezelfde regio bevinden als de database zelf. Dit omvat gegevens die worden geëxporteerd, zodat ze kunnen worden overgedragen naar een andere cloudservice in andere regio's. Schrijfbewerkingen moeten lokaal worden uitgevoerd, terwijl leesbewerkingen op afstand kunnen plaatsvinden.

Ondersteunde eigenschappen

Eigenschap Type Beschrijving
includeHeaders string Voor csv/tsv uitvoer bepaalt u het genereren van kolomkoppen. Dit kan een van none (standaard; er worden geen koptekstlijnen verzonden), all (een koptekstregel naar elk opslagartefact verzenden) of firstFile (alleen een headerregel verzenden naar het eerste opslagartefact).
fileExtension string Het gedeelte 'extensie' van het opslagartefact (bijvoorbeeld .csv of .tsv). Als compressie wordt gebruikt, wordt .gz ook toegevoegd.
namePrefix string Het voorvoegsel dat moet worden toegevoegd aan elke gegenereerde naam van het opslagartefact. Er wordt een willekeurig voorvoegsel gebruikt als dit niet is opgegeven.
encoding string De codering voor tekst. Mogelijke waarden zijn: UTF8NoBOM (standaard) of UTF8BOM.
compressionType string Het type compressie dat moet worden gebruikt. Voor niet-Parquet-bestanden is alleen gzip toegestaan. Voor Parquet-bestanden zijn mogelijke waarden gzip, snappy, lz4_raw, brotlien zstd. De standaardwaarde is gzip.
distribution string Distributiehint (single, per_node, per_shard). Als de waarde gelijk is aan single, schrijft één thread naar de opslag. Anders exporteert u schrijfbewerkingen van alle knooppunten die de query parallel uitvoeren. Zie invoegtoepassingsoperator evalueren. Standaard ingesteld op per_shard.
persistDetails bool Als true, blijft de opdracht de resultaten behouden (zie async vlag). Standaard wordt true in asynchrone uitvoeringen, maar kan worden uitgeschakeld als de beller de resultaten niet nodig heeft. Standaard wordt false in synchrone uitvoeringen, maar kan ook worden ingeschakeld.
sizeLimit long De groottelimiet in bytes van één opslagartefact dat vóór compressie is geschreven. Geldig bereik: 100 MB (standaard) tot 4 GB.
parquetRowGroupSize int Alleen relevant wanneer de gegevensindeling Parquet is. Hiermee bepaalt u de grootte van de rijgroep in de geëxporteerde bestanden. De standaardgrootte van de rijgroep is 100.000 records.
distributed bool Gedistribueerde export uitschakelen of inschakelen. Instellen op onwaar is gelijk aan single distributiehint. De standaardwaarde is waar.
parquetDatetimePrecision string De precisie die moet worden gebruikt bij het exporteren van datetime waarden naar Parquet. Mogelijke waarden zijn milliseconden en microseconden. De standaardwaarde is milliseconden.

Verificatie en autorisatie

De verificatiemethode is gebaseerd op de opgegeven verbindingsreeks en de vereiste machtigingen variëren, afhankelijk van de verificatiemethode.

De volgende tabel bevat de ondersteunde verificatiemethoden en de machtigingen die nodig zijn voor het exporteren van gegevens naar externe opslag per opslagtype.

Verificatiemethode Azure Blob Storage/Data Lake Storage Gen2 Data Lake Storage Gen1
imitatie Inzender voor opslagblobgegevens Donateur
SAS-token (Shared Access) Schrijven Schrijven
Microsoft Entra-toegangstoken Er zijn geen extra machtigingen vereist Er zijn geen extra machtigingen vereist
toegangssleutel voor opslagaccounts Er zijn geen extra machtigingen vereist Er zijn geen extra machtigingen vereist

Retourneert

Met de opdrachten wordt een tabel geretourneerd waarin de gegenereerde opslagartefacten worden beschreven. Elke record beschrijft één artefact en bevat het opslagpad naar het artefact en het aantal records dat het bevat.

Pad 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

Asynchrone modus

Als de vlag async is opgegeven, wordt de opdracht uitgevoerd in de asynchrone modus. In deze modus retourneert de opdracht onmiddellijk met een bewerkings-id en wordt de gegevensexport op de achtergrond voortgezet totdat deze is voltooid. De bewerkings-id die door de opdracht wordt geretourneerd, kan worden gebruikt om de voortgang en uiteindelijk de resultaten ervan bij te houden via de volgende opdrachten:

Na een geslaagde voltooiing kunt u bijvoorbeeld de resultaten ophalen met behulp van:

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

Voorbeelden

In dit voorbeeld voert Kusto de query uit en exporteert vervolgens de eerste recordset die door de query wordt geproduceerd naar een of meer gecomprimeerde CSV-blobs, tot 1 GB vóór compressie. Kolomnaamlabels worden toegevoegd als de eerste rij voor elke 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"

Fouten tijdens exportopdrachten

Exportopdrachten kunnen tijdelijk mislukken tijdens de uitvoering. continue export wordt de opdracht automatisch opnieuw uitgevoerd. Normale exportopdrachten (exporteren naar opslag, exporteren naar externe tabel) voeren geen nieuwe pogingen uit.

  • Wanneer de exportopdracht mislukt, worden artefacten die al naar de opslag zijn geschreven, niet verwijderd. Deze artefacten blijven in de opslag. Als de opdracht mislukt, wordt ervan uitgegaan dat de export onvolledig is, zelfs als sommige artefacten zijn geschreven.
  • De beste manier om zowel de voltooiing van de opdracht als de artefacten bij te houden die na een geslaagde voltooiing zijn geëxporteerd, is met behulp van de .show operations- en .show operation details-opdrachten.

Opslagfouten

Standaard worden exportopdrachten gedistribueerd, zodat er mogelijk veel gelijktijdige schrijfbewerkingen naar de opslag zijn. Het distributieniveau is afhankelijk van het type exportopdracht:

  • De standaarddistributie voor reguliere .export opdracht is per_shard, wat betekent dat alle gebieden die gegevens bevatten voor het gelijktijdig exporteren van schrijfbewerking naar opslag.

  • De standaarddistributie voor exporteren naar externe tabel opdrachten is per_node, wat betekent dat de gelijktijdigheid het aantal knooppunten is.

Wanneer het aantal gebieden/knooppunten groot is, kan dit leiden tot een hoge belasting van de opslag die resulteert in opslagbeperking of tijdelijke opslagfouten. De volgende suggesties kunnen deze fouten oplossen (op volgorde van prioriteit):

  • Verhoog het aantal opslagaccounts dat is opgegeven voor de exportopdracht of de externe tabeldefinitie. De belasting wordt gelijkmatig verdeeld over de accounts.

  • Verminder de gelijktijdigheid door de distributiehint in te stellen op per_node (zie opdrachteigenschappen).

  • Verminder de gelijktijdigheid van het aantal knooppunten dat wordt geëxporteerd door de eigenschap clientaanvraag in te stellenquery_fanout_nodes_percent op de gewenste gelijktijdigheid (procent van de knooppunten). De eigenschap kan worden ingesteld als onderdeel van de exportquery. Met de volgende opdracht wordt bijvoorbeeld het aantal knooppunten dat naar de opslag wordt geschreven, beperkt tot 50% van de knooppunten:

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

  • Verminder de gelijktijdigheid van het aantal threads dat wordt geëxporteerd in elk knooppunt wanneer u per shard-export gebruikt, door de eigenschap clientaanvraag in te stellenquery_fanout_threads_percent op de gewenste gelijktijdigheid (percentage threads). De eigenschap kan worden ingesteld als onderdeel van de exportquery. Met de volgende opdracht wordt bijvoorbeeld het aantal threads dat naar de opslag wordt geschreven, beperkt tot 50% op elk van de knooppunten:

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

  • Als u exporteert naar een gepartitioneerde externe tabel, kan het instellen van de eigenschappen van de spread/concurrency gelijktijdigheid verminderen (zie de details in de opdrachteigenschappen.

  • Als geen van de vorige aanbevelingen werkt, kunt u distributie volledig uitschakelen door de eigenschap distributed in te stellen op false. We raden u echter niet aan dit te doen, omdat dit van invloed kan zijn op de opdrachtprestaties.

Autorisatiefouten

Verificatie- of autorisatiefouten tijdens exportopdrachten kunnen optreden wanneer de referenties die zijn opgegeven in de opslagverbindingsreeks, niet naar de opslag mogen schrijven. Als u impersonate of een door de gebruiker gedelegeerd SAS-token gebruikt voor de exportopdracht, is de rol Bijdrager voor opslagblobgegevens rol vereist om naar het opslagaccount te schrijven. Zie Storage-verbindingsreeksenvoor meer informatie.

Toewijzing van gegevenstypen

Toewijzing van Parquet-gegevenstypen

Bij het exporteren worden Kusto-gegevenstypen toegewezen aan Parquet-gegevenstypen met behulp van de volgende regels:

Kusto-gegevenstype Parquet-gegevenstype Parquet-aantekening Opmerkingen
bool BOOLEAN
datetime INT64 TIMESTAMP_MICROS
dynamic BYTE_ARRAY UTF-8 Geserialiseerd als JSON-tekenreeks
guid BYTE_ARRAY UTF-8
int INT32
long INT64
real DOUBLE
string BYTE_ARRAY UTF-8
timespan INT64 Aantal tikken opgeslagen als tikken (aantal van 100 nanoseconden)
decimal FIXED_LENGTH_BYTE_ARRAY DECIMAAL

Verwante inhoud