Exportieren von Daten in Cloudspeicher

Artikel
03/05/2024

Führt eine Abfrage aus und schreibt das erste Resultset in einen externen Cloudspeicher, der von einem Speicher Verbindungszeichenfolge angegeben wird.

Berechtigungen

Sie benötigen mindestens Datenbank-Viewer-Berechtigungen , um diesen Befehl ausführen zu können.

Syntax

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

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Typ	Erforderlich	BESCHREIBUNG
`async`	`string`		Falls angegeben, wird der Befehl im asynchronen Modus ausgeführt. Siehe asynchroner Modus.
`compressed`	`string`		Falls angegeben, werden die Ausgabespeicherartefakte als `.gz` Dateien komprimiert. Sehen Sie sich die `compressionType`unterstützte Eigenschaft zum Komprimieren von Parquet-Dateien als snappy an.
OutputDataFormat	`string`	✔️	Gibt das Datenformat der vom Befehl geschriebenen Speicherartefakte an. Unterstützte Werte: `csv`, `tsv`, `json` und `parquet`.
StorageConnectionString	`string`		Mindestens eine Speicherverbindungszeichenfolge , die angibt, in welchen Speicher die Daten geschrieben werden sollen. Für skalierbare Schreibvorgänge können mehrere Speicher Verbindungszeichenfolge angegeben werden. Jede dieser Verbindungszeichenfolge muss die Anmeldeinformationen angeben, die beim Schreiben in den Speicher verwendet werden sollen. Wenn Sie beispielsweise in Azure Blob Storage schreiben, können die Anmeldeinformationen der Speicherkontoschlüssel oder ein freigegebener Zugriffsschlüssel (SAS) mit den Berechtigungen zum Lesen, Schreiben und Auflisten von Blobs sein.
PropertyName, PropertyValue	`string`		Eine durch Trennzeichen getrennte Liste von Schlüssel-Wert-Eigenschaftspaaren. Weitere Informationen finden Sie unter unterstützte Eigenschaften.

Hinweis

Es wird dringend empfohlen, Daten in einen Speicher zu exportieren, der sich in derselben Region wie der Cluster selbst befindet. Dies schließt Daten ein, die exportiert werden, damit sie an einen anderen Clouddienst in anderen Regionen übertragen werden können. Schreibvorgänge sollten lokal erfolgen, während Lesevorgänge remote erfolgen können.

Unterstützte Eigenschaften

Eigenschaft	Typ	BESCHREIBUNG
`includeHeaders`	`string`	Steuert `csv`/`tsv` für die Ausgabe die Generierung von Spaltenheadern. Kann eine von `none` (Standard; keine Headerzeilen ausgegeben), `all` (eine Headerzeile in jedes Speicherartefakt ausgeben) oder `firstFile` (eine Headerzeile nur in das erste Speicherartefakt ausgeben).
`fileExtension`	`string`	Gibt den Erweiterungsteil des Speicherartefakts an (z. B `.csv` . oder `.tsv`). Wenn Komprimierung verwendet wird, `.gz` wird ebenfalls angefügt.
`namePrefix`	`string`	Gibt ein Präfix an, das jedem generierten Speicherartefaktnamen hinzugefügt werden soll. Wenn nicht angegeben wird, wird ein zufälliges Präfix verwendet.
`encoding`	`string`	Gibt an, wie der Text codiert werden soll: `UTF8NoBOM` (Standard) oder `UTF8BOM`.
`compressionType`	`string`	Gibt den Typ der zu verwendenden Komprimierung an. Mögliche Werte sind `gzip` oder `snappy`. Der Standardwert ist `gzip`. `snappy` kann (optional) für das `parquet` Format verwendet werden.
`distribution`	`string`	Verteilungshinweis (`single`, `per_node`, `per_shard`). Wenn der Wert gleich ist `single`, schreibt ein einzelner Thread in den Speicher. Exportieren Sie andernfalls Schreibvorgänge von allen Knoten, die die Abfrage parallel ausführen. Weitere Informationen finden Sie unter Auswerten des Plug-In-Operators. Wird standardmäßig auf `per_shard` festgelegt.
`persistDetails`	`bool`	Gibt an, dass der Befehl seine Ergebnisse beibehalten soll (siehe `async` Flag). Standardmäßig wird `true` in asynchronen Ausführungen festgelegt, kann jedoch deaktiviert werden, wenn der Aufrufer die Ergebnisse nicht benötigt. Standardmäßig wird in `false` synchronen Ausführungen festgelegt, kann aber auch in diesen aktiviert werden.
`sizeLimit`	`long`	Die Größenbegrenzung in Bytes eines einzelnen Speicherartefakts, das (vor der Komprimierung) geschrieben wird. Gültiger Bereich: 100 MB (Standard) bis 4 GB.
`parquetRowGroupSize`	`int`	Nur relevant, wenn das Datenformat Parquet ist. Steuert die Zeilengruppengröße in den exportierten Dateien. Die Standardgröße der Zeilengruppe beträgt 100.000 Datensätze.
`distributed`	`bool`	Deaktivieren/aktivieren Sie den verteilten Export. Die Einstellung auf false entspricht dem `single` Verteilungshinweis. Der Standardwert ist "true".
`parquetDatetimePrecision`	`string`	Gibt die Genauigkeit an, die beim Exportieren von `datetime` Werten nach Parquet verwendet werden soll. Mögliche Werte sind Millisekunde und Mikrosekunde. Der Standardwert ist Millisekunden.

Authentifizierung und Autorisierung

Die Authentifizierungsmethode basiert auf dem bereitgestellten Verbindungszeichenfolge, und die erforderlichen Berechtigungen variieren je nach Authentifizierungsmethode.

In der folgenden Tabelle sind die unterstützten Authentifizierungsmethoden und die Berechtigungen aufgeführt, die zum Exportieren von Daten in einen externen Speicher nach Speichertyp erforderlich sind.

Authentifizierungsmethode	Azure Blob Storage/Data Lake Storage Gen2	Data Lake Storage Gen1
Identitätswechsel	Mitwirkender an Storage-Blobdaten	Beitragender
SAS-Token (Shared Access)	Schreiben	Schreiben
Microsoft Entra Zugriffstoken	Keine zusätzlichen Berechtigungen erforderlich	Keine zusätzlichen Berechtigungen erforderlich
Speicherkonto-Zugriffsschlüssel	Keine zusätzlichen Berechtigungen erforderlich	Keine zusätzlichen Berechtigungen erforderlich

Gibt zurück

Die Befehle geben eine Tabelle zurück, die die generierten Speicherartefakte beschreibt. Jeder Datensatz beschreibt ein einzelnes Artefakt und enthält den Speicherpfad zum Artefakt und die Anzahl der Datensätze, die darin enthalten sind.

Pfad	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

Asynchroner Modus

Wenn das async Flag angegeben ist, wird der Befehl im asynchronen Modus ausgeführt. In diesem Modus wird der Befehl sofort mit einer Vorgangs-ID zurückgegeben, und der Datenexport wird bis zum Abschluss im Hintergrund fortgesetzt. Die vom Befehl zurückgegebene Vorgangs-ID kann verwendet werden, um seinen Fortschritt und letztendlich seine Ergebnisse über die folgenden Befehle zu verfolgen:

.show operations: Nachverfolgen des Fortschritts.
.show operation details: Abrufen von Vervollständigungsergebnissen

Beispielsweise können Sie nach einem erfolgreichen Abschluss die Ergebnisse mit abrufen:

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

Beispiele

In diesem Beispiel führt Kusto die Abfrage aus und exportiert dann das erste von der Abfrage erzeugte Recordset in ein oder mehrere komprimierte CSV-Blobs, bis zu 1 GB vor der Komprimierung. Spaltennamensbezeichnungen werden als erste Zeile für jedes Blob hinzugefügt.

.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"

Fehler bei Exportbefehlen

Exportbefehle können während der Ausführung vorübergehend fehlschlagen. Beim fortlaufenden Export wird der Befehl automatisch wiederholt. Bei regulären Exportbefehlen (Export in den Speicher, Exportieren in eine externe Tabelle) werden keine Wiederholungen ausgeführt.

Wenn der Exportbefehl fehlschlägt, werden Artefakte, die bereits in den Speicher geschrieben wurden, nicht gelöscht. Diese Artefakte verbleiben im Speicher. Wenn der Befehl fehlschlägt, gehen Sie davon aus, dass der Export unvollständig ist, auch wenn einige Artefakte geschrieben wurden.
Die beste Möglichkeit, sowohl den Abschluss des Befehls als auch die nach erfolgreicher Fertigstellung exportierten Artefakte nachzuverfolgen, besteht darin, die .show operations Befehle und .show operation details zu verwenden.

Speicherfehler

Exportbefehle werden standardmäßig so verteilt, dass viele gleichzeitige Schreibvorgänge in den Speicher erfolgen können. Die Verteilungsebene hängt vom Typ des Exportbefehls ab:

Die Standardverteilung für reguläre .export Befehle ist per_shard. Dies bedeutet, dass alle Blöcke, die Daten enthalten, die schreibvorgänge in den Speicher gleichzeitig exportiert werden sollen.
Die Standardverteilung für den Export in externe Tabellenbefehle ist per_node, was bedeutet, dass die Parallelität die Anzahl der Knoten im Cluster ist.

Wenn die Anzahl der Blöcke/Knoten groß ist, kann dies zu einer hohen Speicherauslastung führen, die zu einer Speicherdrosselung oder vorübergehenden Speicherfehlern führt. Die folgenden Vorschläge können diese Fehler (nach Prioritätsreihenfolge) beheben:

Erhöhen Sie die Anzahl der Speicherkonten, die für den Exportbefehl oder die Definition der externen Tabelle bereitgestellt werden (die Last wird gleichmäßig auf die Konten verteilt).
Verringern Sie die Parallelität, indem Sie den Verteilungshinweis auf per_node festlegen (siehe Befehlseigenschaften).
Reduzieren Sie die Parallelität der Anzahl von Knoten, die exportiert werden, indem Sie die Clientanforderungseigenschaftquery_fanout_nodes_percent auf die gewünschte Parallelität (Prozentsatz der Knoten) festlegen. Die -Eigenschaft kann als Teil der Exportabfrage festgelegt werden. Der folgende Befehl begrenzt beispielsweise die Anzahl der Knoten, die gleichzeitig in den Speicher schreiben, auf 50 % der Clusterknoten:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Reduzieren Sie die Parallelität der Anzahl von Threads, die in jeden Knoten exportiert werden, wenn Sie pro Shardexport verwenden, indem Sie die Clientanforderungseigenschaftquery_fanout_threads_percent auf die gewünschte Parallelität (Prozent der Threads) festlegen. Die -Eigenschaft kann als Teil der Exportabfrage festgelegt werden. Der folgende Befehl begrenzt beispielsweise die Anzahl der Threads, die gleichzeitig in den Speicher schreiben, auf jedem clusterknoten auf 50 %:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
Beim Exportieren in eine partitionierte externe Tabelle kann das Festlegen der Eigenschaften die spread/concurrency Parallelität verringern (siehe Details in den Befehlseigenschaften).
Wenn keines der oben genannten Elemente funktioniert, können Sie die Verteilung vollständig deaktivieren, indem Sie die distributed -Eigenschaft auf false festlegen. Es wird jedoch nicht empfohlen, dies zu tun, da dies die Befehlsleistung erheblich beeinträchtigen kann.

Autorisierungsfehler

Authentifizierungs- oder Autorisierungsfehler bei Exportbefehlen können auftreten, wenn die im Speicher Verbindungszeichenfolge bereitgestellten Anmeldeinformationen nicht in den Speicher schreiben dürfen. Wenn Sie oder ein vom Benutzer delegiertes SAS-Token für den Exportbefehl verwenden impersonate , ist die Rolle Mitwirkender an Storage-Blobdaten erforderlich, um in das Speicherkonto zu schreiben. Weitere Informationen finden Sie unter Speicherverbindungszeichenfolgen.

Datentypzuordnung

Parquet-Datentypzuordnung

Beim Export werden Kusto-Datentypen parquet-Datentypen mithilfe der folgenden Regeln zugeordnet:

Kusto-Datentyp	Parquet-Datentyp	Parquet-Anmerkung	Kommentare
`bool`	`BOOLEAN`
`datetime`	`INT64`	TIMESTAMP_MICROS
`dynamic`	`BYTE_ARRAY`	UTF-8	Serialisiert als JSON-Zeichenfolge
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Gespeichert als Ticks (100 Nanosekundeneinheiten)
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL