Gegevens exporteren naar cloudopslag

Artikel
01/18/2024

Voert een query uit en schrijft de eerste resultatenset naar een externe cloudopslag, opgegeven door een opslag verbindingsreeks.

Machtigingen

U moet ten minste databaseviewermachtigingen hebben om deze opdracht uit te voeren.

Syntax

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

Meer informatie over syntaxisconventies.

Parameters

Naam	Type	Vereist	Beschrijving
`async`	`string`		Indien opgegeven, wordt de opdracht uitgevoerd in de asynchrone modus. Zie de asynchrone modus.
`compressed`	`string`		Indien opgegeven, worden de uitvoeropslagartefacten gecomprimeerd als `.gz` bestanden. Zie de `compressionType`ondersteunde eigenschap voor het comprimeren van Parquet-bestanden als snappy.
OutputDataFormat	`string`	✔️	Geeft de gegevensindeling aan van de opslagartefacten die zijn geschreven met de opdracht . Ondersteunde waarden zijn: `csv`, `tsv`, `json`en `parquet`.
StorageConnectionString	`string`		Een of meer opslagverbindingsreeksen die aangeven naar welke opslag de gegevens moeten worden geschreven. Er kunnen meer dan één opslag-verbindingsreeks worden opgegeven voor schaalbare schrijfbewerkingen. Elk van deze verbindingsreeks moet de referenties aangeven 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-eigenschappenparen. Zie ondersteunde eigenschappen.

Notitie

We raden u ten zeerste aan gegevens te exporteren naar opslag die zich in dezelfde regio bevindt als het cluster zelf. Dit omvat gegevens die worden geëxporteerd, zodat deze 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	Description
`includeHeaders`	`string`	Voor `csv`/`tsv` uitvoer bepaalt u het genereren van kolomkoppen. Kan een van `none` zijn (standaard; geen koptekstregels verzonden), `all` (een koptekstregel verzenden naar elk opslagartefact) of `firstFile` (alleen een koptekstregel verzenden naar het eerste opslagartefact).
`fileExtension`	`string`	Geeft het 'extensie'-gedeelte van het opslagartefact aan (bijvoorbeeld `.csv` of `.tsv`). Als compressie wordt gebruikt, `.gz` wordt ook toegevoegd.
`namePrefix`	`string`	Geeft een voorvoegsel aan dat moet worden toegevoegd aan de naam van elk gegenereerd opslagartefact. Er wordt een willekeurig voorvoegsel gebruikt als dit niet is opgegeven.
`encoding`	`string`	Geeft aan hoe de tekst moet worden gecodeerd: `UTF8NoBOM` (standaard) of `UTF8BOM`.
`compressionType`	`string`	Geeft het type compressie aan dat moet worden gebruikt. Mogelijke waarden zijn `gzip` en `snappy`. De standaardinstelling is `gzip`. `snappy` kan (optioneel) worden gebruikt voor `parquet` de indeling.
`distribution`	`string`	Distributiehint (`single`, `per_node`, `per_shard`). Als waarde gelijk is `single`aan , schrijft één thread naar de opslag. Anders exporteert u schrijfbewerkingen van alle knooppunten die de query parallel uitvoeren. Zie De operator voor de invoegtoepassing evalueren. De standaardwaarde is `per_shard`.
`persistDetails`	`bool`	Geeft aan dat de opdracht de resultaten moet behouden (zie `async` vlag). De standaardinstelling is `true` in asynchrone uitvoeringen, maar kan worden uitgeschakeld als de aanroeper de resultaten niet vereist). Standaard ingesteld op `false` in synchrone uitvoeringen, maar kan ook worden ingeschakeld in die uitvoeringen.
`sizeLimit`	`long`	De groottelimiet in bytes van één opslagartefact dat wordt geschreven (vóór compressie). Geldig bereik: 100 MB (standaard) tot 4 GB.
`parquetRowGroupSize`	`int`	Alleen relevant als de gegevensindeling Parquet is. Hiermee bepaalt u de grootte van de rijgroep in de geëxporteerde bestanden. De standaardgrootte van rijgroepen is 100.000 records.
`distributed`	`bool`	Gedistribueerde export uitschakelen/inschakelen. De instelling op false is gelijk aan `single` een distributiehint. De standaardwaarde is true.
`parquetDatetimePrecision`	`string`	Hiermee geeft u de precisie op die moet worden gebruikt bij het exporteren van `datetime` waarden naar Parquet. Mogelijke waarden zijn milliseconden en microseconden. De standaardwaarde is milliseconde.

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 Storage Blob-gegevens	Inzender
Sas-token (Shared Access)	Schrijven	Schrijven
Microsoft Entra toegangstoken	Geen extra machtigingen vereist	Geen extra machtigingen vereist
Toegangssleutel voor opslagaccount	Geen extra machtigingen vereist	Geen extra machtigingen vereist

Retouren

De opdrachten retourneren een tabel 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 async vlag is opgegeven, wordt de opdracht uitgevoerd in de asynchrone modus. In deze modus wordt de opdracht onmiddellijk geretourneerd met een bewerkings-id en wordt het exporteren van gegevens op de achtergrond voortgezet totdat de bewerking is voltooid. De bewerkings-id die door de opdracht wordt geretourneerd, kan worden gebruikt om de voortgang en uiteindelijk de resultaten bij te houden via de volgende opdrachten:

.show operations: Houd de voortgang bij.
.show operation details: Voltooiingsresultaten ophalen.

Na een geslaagde voltooiing kunt u de resultaten bijvoorbeeld 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. Met 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 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 opdrachten en .show operation details .

Opslagfouten

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

De standaarddistributie voor de reguliere .export opdracht is per_shard, wat betekent dat alle gebieden die gegevens bevatten om schrijfbewerkingen gelijktijdig naar de opslag te exporteren.
De standaarddistributie voor exporteren naar externe tabelopdrachten is per_node, wat betekent dat de gelijktijdigheid het aantal knooppunten in het cluster is.

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

Verhoog het aantal opslagaccounts dat is opgegeven voor de exportopdracht of de definitie van de externe tabel (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 geëxporteerde knooppunten door de clientaanvraageigenschapquery_fanout_nodes_percent in te stellen op de gewenste gelijktijdigheid (percentage van knooppunten). De eigenschap kan worden ingesteld als onderdeel van de exportquery. Met de volgende opdracht wordt bijvoorbeeld het aantal knooppunten dat gelijktijdig naar de opslag wordt geschreven, beperkt tot 50% van de clusterknooppunten:
```
.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 in elk knooppunt wordt geëxporteerd bij gebruik van per shard-export door de clientaanvraageigenschapquery_fanout_threads_percent in te stellen op de gewenste gelijktijdigheid (percentage van threads). De eigenschap kan worden ingesteld als onderdeel van de exportquery. Met de volgende opdracht wordt bijvoorbeeld het aantal threads dat gelijktijdig naar de opslag wordt geschreven beperkt tot 50% op elk van de clusterknooppunten:
```
.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 de spread/concurrency gelijktijdigheid verminderen (zie de details in de opdrachteigenschappen).
Als geen van de bovenstaande opties werkt, kunt u de distributie volledig uitschakelen door de distributed eigenschap in te stellen op false. We raden dit echter niet aan, omdat dit de prestaties van de opdracht aanzienlijk kan beïnvloeden.

Autorisatiefouten

Verificatie- of autorisatiefouten tijdens exportopdrachten kunnen optreden wanneer de referenties in de opslag verbindingsreeks niet naar de opslag mogen schrijven. Als u impersonate een door de gebruiker gedelegeerd SAS-token gebruikt voor de exportopdracht, is de rol Inzender voor opslagblobgegevens vereist om naar het opslagaccount te schrijven. Zie Opslagverbindingsreeksen voor 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`		Opgeslagen als tikken (100 nanoseconden) aantal
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL

Delen via