Erfassen aus Abfrage (.set, .append, .set-or-append, .set-or-replace)

  • Artikel

Diese Befehle führen eine Abfrage oder einen Verwaltungsbefehl aus und erfassen die Ergebnisse der Abfrage in einer Tabelle. Der Unterschied zwischen diesen Befehlen besteht darin, wie sie vorhandene oder nicht vorhandene Tabellen und Daten behandeln.

Befehl Wenn die Tabelle vorhanden ist Wenn die Tabelle nicht vorhanden ist
.set Der Befehl schlägt fehl. Die Tabelle wird erstellt, und die Daten werden erfasst.
.append Daten werden an die Tabelle angehängt. Der Befehl schlägt fehl.
.set-or-append Daten werden an die Tabelle angehängt. Die Tabelle wird erstellt, und die Daten werden erfasst.
.set-or-replace Daten ersetzen die Daten in der Tabelle. Die Tabelle wird erstellt, und die Daten werden erfasst.

Informationen zum Abbrechen eines Abfragebefehls für die Erfassung finden Sie unter cancel operation.

Hinweis

Diese Erfassungsmethode ist für die Untersuchung und Prototyperstellung vorgesehen. Verwenden Sie es nicht in Produktions- oder großvolumigen Szenarien.

Berechtigungen

Um verschiedene Aktionen für eine Tabelle auszuführen, sind bestimmte Berechtigungen erforderlich:

  • Zum Hinzufügen von Zeilen zu einer vorhandenen Tabelle mit dem .append Befehl benötigen Sie mindestens Table Ingestor-Berechtigungen.
  • Zum Erstellen einer neuen Tabelle mit den verschiedenen .set Befehlen benötigen Sie mindestens Datenbankbenutzerberechtigungen.
  • Um Zeilen in einer vorhandenen Tabelle mithilfe des .set-or-replace Befehls zu ersetzen, benötigen Sie mindestens Tabellenberechtigungen Admin.

Weitere Informationen zu Berechtigungen finden Sie unter Rollenbasierte Zugriffssteuerung in Kusto.

Syntax

(.set.append.set-or-append | .set-or-replace | | ) [async] tableName [with(propertyName= propertyValue [, ...]] <|)queryOrCommand

Erfahren Sie mehr über Syntaxkonventionen.

Parameter

Name Typ Erforderlich BESCHREIBUNG
async string Wenn angegeben, wird der Befehl zurückgegeben und die Erfassung im Hintergrund fortgesetzt. Verwenden Sie den mit dem .show operations Befehl zurückgegebenenOperationId, um die Erfassungsabschluss-status und Ergebnisse abzurufen.
tableName string ✔️ Der Name der Tabelle, in der Daten erfasst werden sollen. TableName bezieht sich immer auf die Datenbank im Kontext.
propertyName, propertyValue string Mindestens eine unterstützte Erfassungseigenschaft , die zum Steuern des Erfassungsprozesses verwendet wird.
queryOrCommand string ✔️ Der Text einer Abfrage oder eines Verwaltungsbefehls, deren Ergebnisse als Daten zur Erfassung verwendet werden.

Hinweis

Es werden nur .show Verwaltungsbefehle unterstützt.

Unterstützte Erfassungseigenschaften

Eigenschaft Typ BESCHREIBUNG
creationTime string Der als ISO8601-Zeichenfolge formatierte datetime-Wert, der zum Zeitpunkt der Erstellung der erfassten Datenerweiterungen verwendet werden soll. Wenn keine Angabe erfolgt, wird now() verwendet. Achten Sie bei Angabe eines Werts darauf, dass die Eigenschaft Lookback in der effektiven Richtlinie für die Zusammenführung von Blöcken der Zieltabelle auf den angegebenen Wert abgestimmt ist.
extend_schema bool Wenn true, kann der Befehl das Schema der Tabelle erweitern. Der Standardwert ist false. Diese Option betrifft nur .append-, .set-or-append- und set-or-replace-Befehle. Für diese Option sind mindestens Tabellenberechtigungen Admin erforderlich.
recreate_schema bool Wenn true, kann der Befehl das Schema der Tabelle neu erstellen. Der Standardwert ist false. Diese Option betrifft nur den Befehl .set-or-replace. Diese Option hat Vorrang vor der extend_schema -Eigenschaft, wenn beide festgelegt sind. Für diese Option sind mindestens Tabellenberechtigungen Admin erforderlich.
folder string Der Ordner, der der Tabelle zugewiesen werden soll. Wenn die Tabelle bereits vorhanden ist, überschreibt diese Eigenschaft den Ordner der Tabelle.
ingestIfNotExists string Falls angegeben, schlägt die Erfassung fehl, wenn die Tabelle bereits Daten enthält, die mit einem ingest-by: Tag mit demselben Wert markiert sind. Weitere Informationen finden Sie unter ingest-by: Tags.
policy_ingestiontime bool Wenn true, wird die Erfassungszeitrichtlinie für die Tabelle aktiviert. Der Standardwert lautet true.
tags string Eine JSON-Zeichenfolge, die eine Liste von Tags darstellt, die dem erstellten Bereich zugeordnet werden sollen.
docstring string Eine Beschreibung, die zum Dokumentieren der Tabelle verwendet wird.
distributed bool Wenn true, erfasst der Befehl alle Knoten, die die Abfrage parallel ausführen. Der Standardwert ist false. Weitere Informationen finden Sie unter Leistungstipps.
persistDetails Ein boolescher Wert, der, falls angegeben, angibt, dass der Befehl die detaillierten Ergebnisse für den Abruf durch den Befehl .show operation details beibehalten soll. Wird standardmäßig auf false festgelegt. with (persistDetails=true)

Schemaüberlegungen

  • .set-or-replace behält das Schema bei, es sei denn, eine der extend_schemarecreate_schema Erfassungseigenschaften oder ist auf truefestgelegt.
  • .set-or-append und .append Befehle behalten das Schema bei, es sei denn, die extend_schema Erfassungseigenschaft ist auf truefestgelegt.
  • Das Abgleichen des Resultsetschemas mit dem schema der Zieltabelle basiert auf den Spaltentypen. Es erfolgt kein Abgleichen der Spaltennamen. Stellen Sie sicher, dass sich die Spalten des Abfrageergebnisschemas in der gleichen Reihenfolge wie die Tabelle befinden, andernfalls werden Daten in den falschen Spalten erfasst.

Achtung

Wenn das Schema geändert wird, erfolgt dies in einer separaten Transaktion vor der eigentlichen Datenerfassung. Dies bedeutet, dass das Schema auch dann geändert werden kann, wenn die Daten nicht erfasst werden.

Leistungstipps

  • Eine Datenerfassung ist ein ressourcenintensiver Vorgang, der sich auf gleichzeitige Aktivitäten im Cluster auswirken kann, so auch auf das Ausführen von Abfragen. Vermeiden Sie es, zu viele Erfassungsbefehle gleichzeitig auszuführen.
  • Beschränken Sie die Daten für die Erfassung auf weniger als 1 GB pro Erfassungsvorgang. Verwenden Sie bei Bedarf mehrere Erfassungsbefehle.
  • Legen Sie das distributed Flag auf fest true , wenn die von der Abfrage erzeugte Datenmenge groß ist, 1 GB überschreitet und keine Serialisierung erforderlich ist. Anschließend können mehrere Knoten die Ausgabe parallel erzeugen. Verwenden Sie dieses Flag nicht, wenn die Abfrageergebnisse klein sind, da es unnötigerweise viele kleine Datenshards generiert.

Zeicheneinschränkung

Der Befehl schlägt fehl, wenn die Abfrage einen Entitätsnamen mit dem $ Zeichen generiert. Die Entitätsnamen müssen den Benennungsregeln entsprechen. Daher muss das $ Zeichen entfernt werden, damit der Erfassungsbefehl erfolgreich ist.

In der folgenden Abfrage generiert der search Operator beispielsweise eine Spalte $table. Um die Abfrageergebnisse zu speichern, verwenden Sie projektumbenen , um die Spalte umzubenennen.

.set Texas <| search State has 'Texas' | project-rename tableName=$table

Beispiele

Erstellen Sie eine neue Tabelle namens RecentErrors in der Datenbank, die dasselbe Schema wie LogsTable hat und alle Fehlerdatensätze der letzten Stunde enthält.

.set RecentErrors <|
   LogsTable
   | where Level == "Error" and Timestamp > now() - time(1h)

Erstellen Sie eine neue Tabelle namens „OldExtents“ in der Datenbank, die eine einzige Spalte namens „ExtentId“ hat und die Block-IDs aller Blöcke (Extents) in der Datenbank enthält, die vor mehr als 30 Tagen erstellt wurden. Die Datenbank enthält eine Tabelle namens „MyExtents“. Da das Dataset voraussichtlich größer als 1 GB (mehr als 1 Million Zeilen) sein soll, verwenden Sie das verteilte Flag.

.set async OldExtents with(distributed=true) <|
   MyExtents 
   | where CreatedOn < now() - time(30d)
   | project ExtentId

Fügen Sie Daten an die vorhandene Tabelle „OldExtents“ in der aktuellen Datenbank an, die eine einzige Spalte namens „ExtentId“ hat und die Block-IDs aller Blöcke in der Datenbank enthält, die vor mehr als 30 Tagen erstellt wurden. Markieren Sie den neue Block mit den Tags tagA und tagB, basierend auf der vorhandenen Tabelle „MyExtents“.

.append OldExtents with(tags='["TagA","TagB"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Fügen Sie Daten an die Tabelle „OldExtents“ in der aktuellen Datenbank an, oder erstellen Sie die Tabelle, wenn sie noch nicht vorhanden ist. Kennzeichnen Sie den neuen Block mit ingest-by:myTag. Führen Sie diesen Schritt nur aus, wenn die Tabelle noch keinen mit ingest-by:myTag gekennzeichneten Block enthält, basierend auf der vorhandenen Tabelle „MyExtents“.

.set-or-append async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <|
   MyExtents
   | where CreatedOn < now() - time(30d)
   | project ExtentId

Ersetzen Sie die Daten in der Tabelle „OldExtents“ in der aktuellen Datenbank an, oder erstellen Sie die Tabelle, wenn sie noch nicht vorhanden ist. Kennzeichnen Sie den neuen Block mit ingest-by:myTag.

.set-or-replace async OldExtents with(tags='["ingest-by:myTag"]', ingestIfNotExists='["myTag"]') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Fügen Sie Daten an die Tabelle „OldExtents“ in der aktuellen Datenbank an, wozu Sie die Erstellungszeit für die erstellten Blöcke auf einen bestimmten Zeitpunkt in der Vergangenheit festlegen.

.append async OldExtents with(creationTime='2017-02-13T11:09:36.7992775Z') <| 
   MyExtents 
   | where CreatedOn < now() - time(30d) 
   | project ExtentId

Zurückgegebene Ausgabe

Gibt Informationen zu den Erweiterungen zurück, die aufgrund des .set- oder .append-Befehls erstellt wurden.

Beispielausgabe

ExtentId OriginalSize ExtentSize CompressedSize IndexSize RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563 1.291 5882 1568 4314 10