Exportieren von Daten in Cloudspeicher

Artikel
07/04/2024

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

Berechtigungen

Zum Ausführen dieses Befehls benötigen Sie mindestens Die Berechtigungen für den Datenbank-Viewer .

Syntax

.export[] [compressedasync] to OutputDataFormat ( StorageConnectionString [, ...] ) [ PropertyName = PropertyValue [, ( with ...] ] <| )Frage

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name	Type	Erforderlich	Beschreibung
`async`	`string`		Wenn angegeben, wird der Befehl im asynchronen Modus ausgeführt. Siehe asynchronen Modus.
`compressed`	`string`		Wenn angegeben, werden die Ausgabespeicherartefakte als `.gz` Dateien komprimiert. Siehe die `compressionType` unterstützte Eigenschaft zum Komprimieren von Parkettdateien als andockig.
OutputDataFormat	`string`	✔️	Gibt das Datenformat der Vom Befehl geschriebenen Speicherartefakte an. Unterstützte Werte: `csv`, `tsv`, `json` und `parquet`.
StorageConnectionString	`string`		Mindestens ein Speicher Verbindungszeichenfolge, der angibt, in welchen Speicher die Daten geschrieben werden sollen. Für skalierbare Schreibvorgänge können mehrere Speicher-Verbindungszeichenfolge angegeben werden. Jede solche 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 Listen-BLOB sein.
PropertyName, PropertyValue	`string`		Eine durch Trennzeichen getrennte Liste von Schlüsselwert-Eigenschaftspaaren. Siehe unterstützte Eigenschaften.

Hinweis

Es wird dringend empfohlen, Daten in den Speicher zu exportieren, der sich in derselben Region wie der Cluster selbst befindet. Dazu gehören Daten, die exportiert werden, damit sie in andere Regionen in einen anderen Clouddienst ü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 Spaltenüberschriften. Dies kann eine von `none` (Standard; keine ausgegebenen Kopfzeilen `all` ), (geben Sie eine Kopfzeile in jedes Speicherartefakt aus), oder `firstFile` (geben Sie eine Kopfzeile nur in das erste Speicherartefakt aus).
`fileExtension`	`string`	Gibt den Erweiterungsteil des Speicherartefaktes 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 Speicherartefaktenamen hinzugefügt werden soll. Ein zufälliges Präfix wird verwendet, wenn links nicht angegeben.
`encoding`	`string`	Gibt an, wie der Text codiert werden soll: `UTF8NoBOM` (Standard) oder `UTF8BOM`.
`compressionType`	`string`	Gibt den zu verwendenden Komprimierungstyp an. Mögliche Werte sind `gzip` oder `snappy`. Der Standardwert ist `gzip`. `snappy` kann (optional) für `parquet` das 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. Siehe 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). Standardwert ist in asynchronen Ausführungen `true` , kann jedoch deaktiviert werden, wenn der Aufrufer die Ergebnisse nicht erfordert). Standardwert ist `false` in synchronen Ausführungen, kann aber auch in diesen aktiviert werden.
`sizeLimit`	`long`	Die Größenbeschränkung in Bytes eines einzelnen Speicherartefaktes, das geschrieben wird (vor der Komprimierung). Gültiger Bereich: 100 MB (Standard) bis 4 GB.
`parquetRowGroupSize`	`int`	Nur relevant, wenn das Datenformat "Parkett" ist. Steuert die Zeilengruppengröße in den exportierten Dateien. Die Standardgröße der Zeilengruppe beträgt 100.000 Datensätze.
`distributed`	`bool`	Deaktivieren/Aktivieren des verteilten Exports. Die Einstellung auf "false" entspricht dem `single` Verteilungshinweis. Der Standardwert ist korrekt.
`parquetDatetimePrecision`	`string`	Gibt die Genauigkeit an, die beim Exportieren von `datetime` Werten nach Parkett verwendet werden soll. Mögliche Werte sind Millisekunden und Mikrosekunden. Der Standardwert ist Millisekunden.

Authentifizierung und Autorisierung

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

In der folgenden Tabelle sind die unterstützten Authentifizierungsmethoden und die Zum Exportieren von Daten in externen Speicher nach Speichertyp erforderlichen Berechtigungen aufgeführt.

Authentifizierungsmethode	Azure Blob Storage / Data Lake Storage Gen2	Data Lake Storage Gen1
Identitätswechsel	Mitwirkender an Speicherblobdaten	Mitwirkender
Token für gemeinsamen Zugriff (SAS)	Schreiben	Schreiben
Microsoft Entra-Zugriffstoken	Keine zusätzlichen Berechtigungen erforderlich	Keine zusätzlichen Berechtigungen erforderlich
Zugriffsschlüssel für das Speicherkonto	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 wie viele Datensätze es enthält.

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 gibt der Befehl sofort mit einer Vorgangs-ID zurück, und der Datenexport wird bis zum Abschluss im Hintergrund fortgesetzt. Die vom Befehl zurückgegebene Vorgangs-ID kann verwendet werden, um den Fortschritt und letztendlich die Ergebnisse über die folgenden Befehle nachzuverfolgen:

.show operations: Nachverfolgen des Fortschritts.
.show operation details: Abrufen von Abschlussergebnissen.

Beispielsweise können Sie nach einem erfolgreichen Abschluss die Ergebnisse mithilfe von:

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

Beispiele

In diesem Beispiel führt Kusto die Abfrage aus und exportiert dann das erste Recordset, das von der Abfrage erstellt wird, in mindestens einen komprimierten CSV-Blob, bis zu 1 GB vor der Komprimierung. Spaltennamenbeschriftungen 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. Der fortlaufende Export wiederholt den Befehl automatisch. Reguläre Exportbefehle (Export in Speicher, Export in externe Tabelle) führen keine Wiederholungen durch.

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 zum Nachverfolgen des Abschlusses des Befehls und der Artefakte, die nach erfolgreichem Abschluss exportiert wurden, ist die Verwendung der .show operations Befehle und .show operation details Befehle.

Speicherfehler

Standardmäßig werden Exportbefehle so verteilt, dass es viele gleichzeitige Schreibvorgänge in den Speicher gibt. Die Verteilungsebene hängt vom Typ des Exportbefehls ab:

Die Standardverteilung für reguläre .export Befehle lautet per_shard, d. h. alle Soweit , die Daten enthalten, die Schreibvorgänge gleichzeitig in den Speicher exportieren.
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 Erweiterungen/Knoten groß ist, kann dies zu einer hohen Auslastung des Speichers führen, die zu Speichereinschränkungen oder vorübergehenden Speicherfehlern führt. Die folgenden Vorschläge können diese Fehler (nach Prioritätsreihenfolge) überwinden:

Erhöhen Sie die Anzahl der Speicherkonten, die dem Exportbefehl oder der Definition der externen Tabelle bereitgestellt werden (die Last wird gleichmäßig zwischen den Konten verteilt).
Verringern Sie die Parallelität, indem Sie den Verteilungshinweis auf per_node (siehe Befehlseigenschaften) festlegen.
Verringern Sie die Parallelität der Anzahl der exportierten Knoten, indem Sie die Clientanforderungseigenschaft query_fanout_nodes_percent auf die gewünschte Parallelität (Prozent der Knoten) festlegen. Die Eigenschaft kann als Teil der Exportabfrage festgelegt werden. Mit dem folgenden Befehl wird beispielsweise die Anzahl der Knoten beschränkt, die gleichzeitig auf 50 % der Clusterknoten geschrieben werden:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Verringern Sie die Parallelität der Anzahl der Threads, die in jedem Knoten exportiert werden, wenn sie pro Shardexport verwendet werden, indem Sie die Clientanforderungseigenschaft query_fanout_threads_percent auf die gewünschte Parallelität (Prozent der Threads) festlegen. Die Eigenschaft kann als Teil der Exportabfrage festgelegt werden. Mit dem folgenden Befehl wird beispielsweise die Anzahl der Threads beschränkt, die gleichzeitig auf 50 % auf jeden Clusterknoten geschrieben werden:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_percent = 50;
    ExportQuery
```
Wenn Sie in eine partitionierte externe Tabelle exportieren, können die Eigenschaften die spread/concurrency Parallelität reduzieren (siehe Details in den Befehlseigenschaften).
Wenn keine der oben genannten Arbeiten 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 sich dies erheblich auf die Befehlsleistung auswirken kann.

Autorisierungsfehler

Authentifizierungs- oder Autorisierungsfehler bei Exportbefehlen können auftreten, wenn die im Speicher bereitgestellten Anmeldeinformationen nicht in den Speicher schreiben dürfen Verbindungszeichenfolge. Wenn Sie ein benutzerdelegiertes SAS-Token für den Exportbefehl verwenden impersonate , muss die Rolle "Mitwirkender von Speicher-BLOB-Daten" in das Speicherkonto geschrieben werden. Weitere Informationen finden Sie unter "Storage Verbindungszeichenfolge s".

Zuordnung von Datentypen

Zuordnung von Parkettdatentypen

Beim Export werden Kusto-Datentypen unter Verwendung der folgenden Regeln den Datentypen "Parkett" zugeordnet:

Kusto-Datentyp	Parquet-Datentyp	Parkettanmerkung	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`		Als Teilstriche (100-Nanosekundeneinheiten) gespeichert
`decimal`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL

Freigeben über