Opnemen uit query (.set, .append, .set-or-append, .set-or-replace)

  • Artikel

Met deze opdrachten wordt een query of een beheeropdracht uitgevoerd en worden de resultaten van de query opgenomen in een tabel. Het verschil tussen deze opdrachten is hoe ze bestaande of niet-bestaande tabellen en gegevens behandelen.

Opdracht Als de tabel bestaat Als de tabel niet bestaat
.set De opdracht mislukt De tabel wordt gemaakt en de gegevens worden opgenomen
.append Gegevens worden toegevoegd aan de tabel De opdracht mislukt
.set-or-append Gegevens worden toegevoegd aan de tabel De tabel wordt gemaakt en de gegevens worden opgenomen
.set-or-replace Gegevens vervangen de gegevens in de tabel De tabel wordt gemaakt en de gegevens worden opgenomen

Zie cancel operationals u een opname van een queryopdracht wilt annuleren.

Notitie

Deze opnamemethode is bedoeld voor verkenning en prototypen. Gebruik het niet in productie- of scenario's met grote volumes.

Machtigingen

Als u verschillende acties op een tabel wilt uitvoeren, zijn specifieke machtigingen vereist:

  • Als u rijen wilt toevoegen aan een bestaande tabel met behulp van de .append opdracht, hebt u minimaal Ingestor-machtigingen voor tabellen nodig.
  • Als u een nieuwe tabel wilt maken met behulp van de verschillende .set opdrachten, hebt u minimaal machtigingen voor databasegebruikers nodig.
  • Als u rijen in een bestaande tabel wilt vervangen met behulp van de .set-or-replace opdracht, hebt u minimaal tabelmachtigingen voor Beheer nodig.

Zie Op rollen gebaseerd toegangsbeheer van Kusto voor meer informatie over machtigingen.

Syntax

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

Meer informatie over syntaxisconventies.

Parameters

Naam Type Vereist Beschrijving
Async string Als dit is opgegeven, retourneert de opdracht en gaat de opname op de achtergrond verder. Gebruik de geretourneerd OperationId met de .show operations opdracht om de voltooiingsstatus en resultaten van de opname op te halen.
tableName string ✔️ De naam van de tabel waarin gegevens moeten worden opgenomen. De tableName is altijd gerelateerd aan de database in context.
propertyName, propertyValue string Een of meer ondersteunde opname-eigenschappen die worden gebruikt om het opnameproces te beheren.
queryOrOpdracht string ✔️ De tekst van een query of een beheeropdracht waarvan de resultaten worden gebruikt als gegevens om op te nemen.

Notitie

Alleen .show beheeropdrachten worden ondersteund.

Ondersteunde opname-eigenschappen

Eigenschap Type Description
creationTime string De datum/tijd-waarde, opgemaakt als een ISO8601 tekenreeks, die moet worden gebruikt bij het maken van de opgenomen gegevensbereiken. Indien niet opgegeven, now() wordt gebruikt. Wanneer dit is opgegeven, moet u ervoor zorgen dat de Lookback eigenschap in het effectieve samenvoegbeleid van de doeltabel is afgestemd op de opgegeven waarde.
extend_schema bool Als true, kan de opdracht het schema van de tabel uitbreiden. De standaardinstelling is false. Deze optie is alleen van toepassing op .appendopdrachten , .set-or-appenden set-or-replace . Voor deze optie zijn ten minste tabelmachtigingen Beheer vereist.
recreate_schema bool Als true, kan de opdracht het schema van de tabel opnieuw maken. De standaardinstelling is false. Deze optie is alleen van toepassing op de .set-or-replace opdracht. Deze optie heeft voorrang op de extend_schema eigenschap als beide zijn ingesteld. Voor deze optie zijn ten minste tabelmachtigingen Beheer vereist.
folder string De map die aan de tabel moet worden toegewezen. Als de tabel al bestaat, overschrijft deze eigenschap de map van de tabel.
ingestIfNotExists string Als dit is opgegeven, mislukt de opname als de tabel al gegevens bevat die zijn getagd met een ingest-by: tag met dezelfde waarde. Zie ingest-by: tags voor meer informatie.
policy_ingestiontime bool Als true, wordt het opnametijdbeleid ingeschakeld voor de tabel. De standaardwaarde is true.
tags string Een JSON-tekenreeks die een lijst met tags vertegenwoordigt die moeten worden gekoppeld aan het gemaakte bereik.
docstring string Een beschrijving die wordt gebruikt om de tabel vast te leggen.
distributed bool Als true, neemt de opdracht op van alle knooppunten die de query parallel uitvoeren. De standaardinstelling is false. Zie tips voor prestaties.
persistDetails Een Booleaanse waarde die, indien opgegeven, aangeeft dat de opdracht de gedetailleerde resultaten moet behouden voor ophalen door de opdracht .show operation details . De standaardwaarde is false. with (persistDetails=true)

Schemaoverwegingen

  • .set-or-replace behoudt het schema, tenzij een van extend_schema of recreate_schema de opname-eigenschappen is ingesteld op true.
  • .set-or-append en .append opdrachten behouden het schema, tenzij de extend_schema opname-eigenschap is ingesteld op true.
  • Het aanpassen van het schema van de resultatenset aan dat van de doeltabel is gebaseerd op de kolomtypen. Kolomnamen komen niet overeen. Zorg ervoor dat de kolommen van het queryresultaatschema in dezelfde volgorde staan als de tabel, anders worden gegevens opgenomen in de verkeerde kolommen.

Waarschuwing

Als het schema wordt gewijzigd, gebeurt dit in een afzonderlijke transactie vóór de werkelijke gegevensopname. Dit betekent dat het schema kan worden gewijzigd, zelfs wanneer de gegevens niet kunnen worden opgenomen.

Tips voor prestaties

  • Gegevensopname is een resource-intensieve bewerking die van invloed kan zijn op gelijktijdige activiteiten op het cluster, waaronder het uitvoeren van query's. Vermijd het uitvoeren van te veel opnameopdrachten tegelijk.
  • Beperk de gegevens voor opname tot minder dan 1 GB per opnamebewerking. Gebruik indien nodig meerdere opnameopdrachten.
  • Stel de distributed vlag in op true als de hoeveelheid gegevens die door de query wordt geproduceerd, groot is, groter is dan 1 GB en geen serialisatie vereist. Vervolgens kunnen meerdere knooppunten parallel uitvoer produceren. Gebruik deze vlag niet wanneer de queryresultaten klein zijn, omdat er onnodig veel kleine gegevensshards kunnen worden gegenereerd.

Tekenbeperking

De opdracht mislukt als de query een entiteitsnaam met het $ teken genereert. De entiteitsnamen moeten voldoen aan de naamgevingsregels, dus het $ teken moet worden verwijderd om de opdracht opnemen te laten slagen.

In de volgende query genereert de search operator bijvoorbeeld een kolom $table. Als u de queryresultaten wilt opslaan, gebruikt u projectnaam wijzigen om de naam van de kolom te wijzigen.

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

Voorbeelden

Maak een nieuwe tabel met de naam RecentErrors in de database die hetzelfde schema heeft als LogsTable en alle foutrecords van het afgelopen uur bevat.

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

Maak een nieuwe tabel met de naam 'OldExtents' in de database met één kolom, 'ExtentId', en bevat de gebieds-id's van alle gebieden in de database die meer dan 30 dagen eerder is gemaakt. De database heeft een bestaande tabel met de naam 'MyExtents'. Omdat de gegevensset naar verwachting groter is dan 1 GB (meer dan ~1 miljoen rijen), gebruikt u de gedistribueerde vlag

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

Voeg gegevens toe aan een bestaande tabel met de naam 'OldExtents' in de huidige database die één kolom, 'ExtentId', bevat en de gebieds-id's bevat van alle gebieden in de database die meer dan 30 dagen eerder zijn gemaakt. Markeer het nieuwe gebied met tags tagA en tagB, op basis van een bestaande tabel met de naam 'MyExtents'.

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

Voeg gegevens toe aan de tabel 'OldExtents' in de huidige database of maak de tabel als deze nog niet bestaat. Tag het nieuwe gebied met ingest-by:myTag. Doe dit alleen als de tabel nog geen gebied bevat met ingest-by:myTagde tag , op basis van een bestaande tabel met de naam 'MyExtents'.

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

Vervang de gegevens in de tabel OldExtents in de huidige database of maak de tabel als deze nog niet bestaat. Tag het nieuwe gebied met ingest-by:myTag.

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

Voeg gegevens toe aan de tabel 'OldExtents' in de huidige database, terwijl u de gemaakte aanmaaktijd(en) instelt op een specifieke datum/tijd in het verleden.

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

Uitvoer retourneren

Retourneert informatie over de gebieden die zijn gemaakt vanwege de .set opdracht of .append .

Voorbeelduitvoer

ExtentId OriginalSize Omvang Gecomprimeerde grootte IndexGrootte RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563 1291 5882 1568 4314 10