Freigeben über

.export to storage

Gilt für: ✅Microsoft Fabric✅Azure Data Explorer

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[] [asynccompressed] toOutputDataFormat( StorageConnectionString [, ...] ) [ PropertyNamewith( [=, ...] ] )<|Frage

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name Type Erforderlich Beschreibung
asynchrone string Wenn angegeben, wird der Befehl im asynchronen Modus ausgeführt. Siehe asynchronen Modus.
komprimierte bool Wenn angegeben, werden die Ausgabespeicherartefakte in dem format komprimiert, das durch die compressionTypeunterstützte Eigenschaftangegeben wird.
OutputDataFormat string ✔️ Das Datenformat der Vom Befehl geschriebenen Speicherartefakte. Unterstützte Werte: csv, tsv, json und parquet.
StorageConnectionString string Mindestens eine Speicherverbindungszeichenfolgen, die angeben, in welchen Speicher die Daten geschrieben werden sollen. Für skalierbare Schreibvorgänge können mehrere Speicherverbindungszeichenfolgen 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.
Wenn Sie Daten mithilfe eines DFS-Endpunkts in CSV-Dateien exportieren, durchlaufen die Daten einen vom DFS verwalteten privaten Endpunkt.
Wenn Sie Daten in Parkettdateien exportieren, durchlaufen die Daten einen blobverwalteten privaten Endpunkt.
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 in derselben Region wie die Datenbank selbst zugeordnet ist. 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 Type 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 Der Teil der Erweiterung des Speicherartefaktes (z. B. .csv oder .tsv). Wenn komprimierung verwendet wird, .gz wird ebenfalls angefügt.
namePrefix string Das Präfix, das jedem generierten Speicherartefaktenamen hinzugefügt werden soll. Ein zufälliges Präfix wird verwendet, wenn links nicht angegeben.
encoding string Die Codierung für Text. Mögliche Werte sind: UTF8NoBOM (Standard) oder UTF8BOM.
compressionType string Der zu verwendende Komprimierungstyp. Bei Nicht-Parkett-Dateien ist nur gzip zulässig. Für Parkettdateien sind mögliche Werte gzip, snappy, lz4_raw, brotliund zstd. Der Standardwert ist gzip.
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 Wenn true, behält der Befehl seine Ergebnisse bei (siehe async Flag). Standardwerte für true asynchrone Ausführung, können aber deaktiviert werden, wenn der Aufrufer die Ergebnisse nicht erfordert. false Standardmäßig werden synchrone Ausführungen ausgeführt, können aber aktiviert werden.
sizeLimit long Die Größenbeschränkung in Bytes eines einzelnen Speicherartefaktes, das vor der Komprimierung geschrieben wurde. 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 oder aktivieren Sie den verteilten Export. Die Einstellung auf "false" entspricht dem single Verteilungshinweis. Der Standardwert ist korrekt.
parquetDatetimePrecision string Die Genauigkeit, 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 Storage-Blobdaten 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:

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 einen oder mehrere komprimierte CSV-Blobs, 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. fortlaufenden Export den Befehl automatisch erneut ausführen. Reguläre Exportbefehle (Export in Speicher, Export in externe Tabelle) führen keine Wiederholungen durch.

  • Wenn der Exportbefehl fehlschlägt, werden bereits in den Speicher geschriebene Artefakte 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 möglicherweise 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 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 Tabellebereitgestellt 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 Clientanforderungseigenschaftquery_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 Knoten 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 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 auf 50 % auf jeden der Knoten 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 keines der vorherigen Empfehlungen funktioniert, können Sie die Verteilung vollständig deaktivieren, indem Sie die eigenschaft distributed auf "false" festlegen. Es wird jedoch nicht empfohlen, dies zu tun, da sie sich 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 Verbindungszeichenfolgen für den Speicher.

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

Verwandte Inhalte