Udostępnij za pośrednictwem


Pozyskiwanie z zapytania (.set, .append, .set-or-append, .set-or-replace)

Dotyczy: ✅Microsoft Fabric✅Azure Data Explorer

Te polecenia wykonują zapytanie lub polecenie zarządzania i pozyskując wyniki zapytania w tabeli. Różnica między tymi poleceniami polega na tym, jak traktują istniejące lub nieistniejących tabel i danych.

Polecenie Jeśli tabela istnieje Jeśli tabela nie istnieje
.set Polecenie kończy się niepowodzeniem Tabela jest tworzona, a dane są pozyskiwane
.append Dane są dołączane do tabeli Polecenie kończy się niepowodzeniem
.set-or-append Dane są dołączane do tabeli Tabela jest tworzona, a dane są pozyskiwane
.set-or-replace Dane zastępują dane w tabeli Tabela jest tworzona, a dane są pozyskiwane

Aby anulować pozyskiwanie z polecenia zapytania, zobacz cancel operation.

Uwaga

Pozyskiwanie z zapytania jest bezpośrednim pozyskiwaniem. W związku z tym nie obejmuje automatycznych ponownych prób. Automatyczne ponawianie prób jest dostępne podczas pozyskiwania za pośrednictwem usługi zarządzania danymi. Użyj dokumentu przeglądu pozyskiwania, aby zdecydować, która opcja pozyskiwania jest najbardziej odpowiednia dla danego scenariusza.

Uprawnienia

Aby wykonać różne akcje w tabeli, wymagane są określone uprawnienia:

  • Aby dodać wiersze do istniejącej tabeli przy użyciu .append polecenia , potrzebujesz co najmniej uprawnień narzędzia Table Ingestor.
  • Aby utworzyć nową tabelę przy użyciu różnych .set poleceń, musisz mieć co najmniej uprawnienia użytkownika bazy danych.
  • Aby zastąpić wiersze w istniejącej tabeli za pomocą .set-or-replace polecenia , musisz mieć co najmniej uprawnienia administratora tabeli.

Aby uzyskać więcej informacji na temat uprawnień, zobacz Kusto role-based access control (Kontrola dostępu oparta na rolach w usłudze Kusto).

Składnia

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

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko Type Wymagania opis
async string Jeśli zostanie określony, polecenie zwraca natychmiast i kontynuuje pozyskiwanie w tle. Użyj zwróconego OperationId polecenia , .show operations aby pobrać stan ukończenia pozyskiwania i wyniki.
tableName string ✔️ Nazwa tabeli do pozyskiwania danych. Nazwa _tabeli jest zawsze powiązana z bazą danych w kontekście.
propertyName, propertyValue string Co najmniej jedna obsługiwana właściwości pozyskiwania używana do kontrolowania procesu pozyskiwania.
queryOrCommand string ✔️ Tekst zapytania lub polecenia zarządzania, którego wyniki są używane jako dane do pozyskiwania. Obsługiwane są tylko .show polecenia zarządzania.

Wskazówki dotyczące wydajności

  • distributed Ustaw właściwość na true wartość , jeśli ilość danych generowanych przez zapytanie jest duża, przekracza 1 GB i nie wymaga serializacji. Następnie wiele węzłów może generować dane wyjściowe równolegle. Nie używaj tej flagi, gdy wyniki zapytania są małe, ponieważ może niepotrzebnie generować wiele małych fragmentów danych.
  • Pozyskiwanie danych to operacja intensywnie korzystająca z zasobów, która może mieć wpływ na współbieżne działania w bazie danych, w tym uruchamianie zapytań. Unikaj uruchamiania zbyt wielu poleceń pozyskiwania w tym samym czasie.
  • Ogranicz dane pozyskiwania do mniej niż 1 GB na operację pozyskiwania. W razie potrzeby użyj wielu poleceń pozyskiwania.

Obsługiwane właściwości pozyskiwania

Właściwość Type Opis
distributed bool Jeśli truepolecenie jest pozyskiwane ze wszystkich węzłów wykonujących zapytanie równolegle. Wartość domyślna to false. Zobacz porady dotyczące wydajności.
creationTime string Wartość daty/godziny sformatowana jako ciąg ISO8601 do użycia w czasie tworzenia pozyskanych zakresów danych. Jeśli nie określono, now() jest używany. Po określeniu Lookback upewnij się, że właściwość w obowiązujących zasadach scalania zakresów tabeli docelowej jest zgodna z określoną wartością.
extend_schema bool Jeśli truepolecenie , może rozszerzyć schemat tabeli. Wartość domyślna to false. Ta opcja dotyczy tylko .appendpoleceń , .set-or-appendi set-or-replace . Ta opcja wymaga co najmniej uprawnień administratora tabeli.
recreate_schema bool Jeśli truepolecenie może odtworzyć schemat tabeli. Wartość domyślna to false. Ta opcja ma zastosowanie tylko do .set-or-replace polecenia . Ta opcja ma pierwszeństwo przed właściwością extend_schema , jeśli obie są ustawione. Ta opcja wymaga co najmniej uprawnień administratora tabeli.
folder string Folder do przypisania do tabeli. Jeśli tabela już istnieje, ta właściwość zastępuje folder tabeli.
ingestIfNotExists string Jeśli zostanie określony, pozyskiwanie nie powiedzie się, jeśli tabela zawiera już dane oznaczone tagiem ingest-by: o tej samej wartości. Aby uzyskać więcej informacji, zobacz ingest-by: tags (Pozyskiwanie według tagów).
policy_ingestiontime bool Jeśli truezasady czasu pozyskiwania zostaną włączone w tabeli. Wartość domyślna to true.
tags string Ciąg JSON reprezentujący listę tagów do skojarzenia z utworzonym zakresem.
docstring string Opis używany do dokumentowania tabeli.
persistDetails Wartość logiczna, która, jeśli została określona, wskazuje, że polecenie powinno utrwalić szczegółowe wyniki pobierania przez polecenie .show operation details . Wartość domyślna to false. with (persistDetails=true)

Zagadnienia dotyczące schematu

  • .set-or-replacezachowuje schemat, chyba że ustawiono truejedną z właściwości pozyskiwania extend_schema lub recreate_schema .
  • .set-or-append polecenia i .append zachowują schemat, chyba że właściwość pozyskiwania extend_schema jest ustawiona na true.
  • Dopasowanie schematu zestawu wyników do tabeli docelowej jest oparte na typach kolumn. Nie ma pasujących nazw kolumn. Upewnij się, że kolumny schematu wyników zapytania są w tej samej kolejności co tabela, inne dane zostaną pozyskane do nieprawidłowych kolumn.

Uwaga

Jeśli schemat zostanie zmodyfikowany, nastąpi to w oddzielnej transakcji przed rzeczywistym pozyskiwaniem danych. Oznacza to, że schemat może zostać zmodyfikowany nawet wtedy, gdy nie można pozyskać danych.

Ograniczenie znaków

Polecenie kończy się niepowodzeniem, jeśli zapytanie generuje nazwę jednostki z znakiem $ . Nazwy jednostek muszą być zgodne z regułami nazewnictwa, więc $ znak musi zostać usunięty, aby polecenie pozyskiwania powiodło się.

Na przykład w poniższym zapytaniu search operator generuje kolumnę $table. Aby zapisać wyniki zapytania, użyj nazwy projektu, aby zmienić nazwę kolumny.

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

Przykłady

Utwórz nową tabelę o nazwie RecentErrors w bazie danych, która ma ten sam schemat co LogsTable i przechowuje wszystkie rekordy błędów z ostatniej godziny.

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

Utwórz nową tabelę o nazwie "OldExtents" w bazie danych, która ma jedną kolumnę "ExtentId" i przechowuje identyfikatory zakresu wszystkich zakresów w bazie danych, które zostały utworzone ponad 30 dni temu. Baza danych ma istniejącą tabelę o nazwie "MyExtents". Ponieważ zestaw danych powinien być większy niż 1 GB (więcej niż ok. 1 milion wierszy), użyj flagi rozproszonej

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

Dołącz dane do istniejącej tabeli o nazwie "OldExtents" w bieżącej bazie danych zawierającej jedną kolumnę "ExtentId" i przechowują identyfikatory zakresu wszystkich zakresów w bazie danych, które zostały utworzone ponad 30 dni wcześniej. Oznacz nowy zakres tagami tagA i tagB, na podstawie istniejącej tabeli o nazwie "MyExtents".

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

Dołącz dane do tabeli "OldExtents" w bieżącej bazie danych lub utwórz tabelę, jeśli jeszcze nie istnieje. Otaguj nowy zakres za pomocą polecenia ingest-by:myTag. Zrób to tylko wtedy, gdy tabela nie zawiera jeszcze zakresu oznaczonego tagiem ingest-by:myTag, na podstawie istniejącej tabeli o nazwie "MyExtents".

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

Zastąp dane w tabeli "OldExtents" w bieżącej bazie danych lub utwórz tabelę, jeśli jeszcze nie istnieje. Otaguj nowy zakres za pomocą polecenia ingest-by:myTag.

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

Dołącz dane do tabeli "OldExtents" w bieżącej bazie danych, ustawiając czas tworzenia zakresów na określoną datę/godzinę w przeszłości.

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

Zwracanie danych wyjściowych

Zwraca informacje o zakresach utworzonych z .set powodu polecenia lub .append .

Przykładowe dane wyjściowe

ExtentId OriginalSize Rozmiar zakresu Skompresowany rozmiar IndexSize RowCount
23a05ed6-376d-4119-b1fc-6493bcb05563 1291 5882 1568 4314 10