Penyerapan dari kueri (.set, .append, .set-or-append, .set-or-replace)

  • Artikel

Perintah ini menjalankan kueri atau perintah manajemen dan menyerap hasil kueri ke dalam tabel. Perbedaan antara perintah ini adalah bagaimana mereka memperlakukan tabel dan data yang ada atau tidak ada.

Perintah Jika tabel ada Jika tabel tidak ada
.set Perintah gagal Tabel dibuat dan data diserap
.append Data ditambahkan ke tabel Perintah gagal
.set-or-append Data ditambahkan ke tabel Tabel dibuat dan data diserap
.set-or-replace Data menggantikan data dalam tabel Tabel dibuat dan data diserap

Untuk membatalkan penyerapan dari perintah kueri, lihat cancel operation.

Catatan

Metode penyerapan ini ditujukan untuk eksplorasi dan prototipe. Jangan gunakan dalam skenario produksi atau volume tinggi.

Izin

Untuk melakukan tindakan yang berbeda pada tabel, diperlukan izin tertentu:

  • Untuk menambahkan baris ke tabel yang sudah ada menggunakan .append perintah , Anda memerlukan minimal izin Table Ingestor.
  • Untuk membuat tabel baru menggunakan berbagai .set perintah, Anda memerlukan minimal izin Pengguna Database.
  • Untuk mengganti baris dalam tabel yang sudah ada menggunakan .set-or-replace perintah , Anda memerlukan minimal izin Admin Tabel.

Untuk informasi selengkapnya tentang izin, lihat Kontrol akses berbasis peran Kusto.

Sintaks

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

Pelajari selengkapnya tentang konvensi sintaksis.

Parameter

Nama Jenis Diperlukan Deskripsi
async string Jika ditentukan, perintah akan kembali dan melanjutkan penyerapan di latar belakang. Gunakan yang dikembalikan OperationId dengan .show operations perintah untuk mengambil status dan hasil penyelesaian penyerapan.
tableName string ✔️ Nama tabel untuk menyerap data. tableName selalu terkait dengan database dalam konteks.
propertyName, propertyValue string Satu atau beberapa properti penyerapan yang didukung digunakan untuk mengontrol proses penyerapan.
queryOrCommand string ✔️ Teks kueri atau perintah manajemen yang hasilnya digunakan sebagai data untuk diserap.

Catatan

Hanya .show perintah manajemen yang didukung.

Properti penyerapan yang didukung

Properti Jenis Deskripsi
creationTime string Nilai datetime, diformat sebagai string ISO8601, untuk digunakan pada saat pembuatan jangkauan data yang diserap. Jika tidak ditentukan, now() digunakan. Ketika ditentukan, pastikan properti Lookback dalam Kebijakan penggabungan jangkauan efektif milik tabel target selaras dengan nilai yang ditentukan.
extend_schema bool Jika true, perintah dapat memperluas skema tabel. Defaultnya adalah false. Opsi hanya berlaku untuk perintah .append, .set-or-append, dan set-or-replace. Opsi ini memerlukan setidaknya izin Admin Tabel.
recreate_schema bool Jika true, perintah dapat membuat ulang skema tabel. Defaultnya adalah false. Opsi ini hanya berlaku untuk .set-or-replace perintah . Opsi ini lebih diutamakan daripada extend_schema properti jika keduanya diatur. Opsi ini memerlukan setidaknya izin Admin Tabel.
folder string Folder yang akan ditetapkan ke tabel. Jika tabel sudah ada, properti ini akan menimpa folder tabel.
ingestIfNotExists string Jika ditentukan, penyerapan gagal jika tabel sudah memiliki data yang ingest-by: ditandai dengan tag dengan nilai yang sama. Untuk informasi selengkapnya, lihat ingest-by: tag.
policy_ingestiontime bool Jika true, Kebijakan Waktu Penyerapan akan diaktifkan pada tabel. Default adalah true.
tags string String JSON yang mewakili daftar tag untuk dikaitkan dengan jangkauan yang dibuat.
docstring string Deskripsi yang digunakan untuk men dokumentasikan tabel.
distributed bool Jika true, perintah menyerap dari semua simpul yang menjalankan kueri secara paralel. Defaultnya adalah false. Lihat tips performa.
persistDetails Nilai Boolean yang, jika ditentukan, menunjukkan bahwa perintah harus mempertahankan hasil terperinci untuk pengambilan oleh perintah detail operasi .show . Default ke false. with (persistDetails=true)

Pertimbangan skema

  • .set-or-replace mempertahankan skema kecuali salah satu dari extend_schema atau recreate_schema properti penyerapan diatur ke true.
  • .set-or-append dan .append perintah mempertahankan skema kecuali extend_schema properti penyerapan diatur ke true.
  • Mencocokkan skema tataan hasil dengan tabel target didasarkan pada jenis kolom. Tidak ada pencocokan nama kolom. Pastikan bahwa kolom skema hasil kueri berada dalam urutan yang sama dengan tabel, data lain akan diserap ke dalam kolom yang salah.

Perhatian

Jika skema dimodifikasi, itu terjadi dalam transaksi terpisah sebelum penyerapan data aktual. Ini berarti skema dapat dimodifikasi bahkan ketika ada kegagalan untuk menyerap data.

Tips performa

  • Penyerapan data adalah operasi intensif sumber daya yang dapat memengaruhi aktivitas bersamaan pada kluster, termasuk menjalankan kueri. Hindari menjalankan terlalu banyak perintah penyerapan secara bersamaan.
  • Batasi data untuk penyerapan menjadi kurang dari 1 GB per operasi penyerapan. Jika perlu, gunakan beberapa perintah penyerapan.
  • Atur distributed bendera ke true jika jumlah data yang dihasilkan oleh kueri besar, melebihi 1 GB, dan tidak memerlukan serialisasi. Kemudian, beberapa simpul dapat menghasilkan output secara paralel. Jangan gunakan bendera ini saat hasil kueri kecil, karena mungkin tidak perlu menghasilkan banyak pecahan data kecil.

Batasan karakter

Perintah akan gagal jika kueri menghasilkan nama entitas dengan $ karakter . Nama entitas harus mematuhi aturan penamaan, sehingga $ karakter harus dihapus agar perintah penyerapan berhasil.

Misalnya, dalam kueri berikut, search operator menghasilkan kolom $table. Untuk menyimpan hasil kueri, gunakan project-rename untuk mengganti nama kolom.

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

Contoh

Buat tabel baru bernama RecentErrors dalam database yang memiliki skema LogsTable yang sama dengan dan menyimpan semua rekaman kesalahan dari jam terakhir.

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

Buat tabel baru bernama "OldExtents" dalam database yang memiliki satu kolom, "ExtentId", dan menyimpan ID jangkauan dari semua jangkauan dalam database yang telah dibuat lebih dari 30 hari sebelumnya. Database sudah memiliki tabel bernama "MyExtents". Karena himpunan data diperkirakan lebih besar dari 1 GB (lebih dari ~ 1 juta baris) menggunakan bendera terdistribusi

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

Tambahkan data ke tabel bernama "OldExtents" yang sudah ada dalam database saat ini yang memiliki satu kolom, "ExtentId", dan menyimpan ID jangkauan dari semua jangkauan dalam database yang telah dibuat lebih dari 30 hari sebelumnya. Tandai jangkauan baru dengan tag tagA dan tagB, berdasarkan tabel bernama "MyExtents" yang sudah ada.

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

Tambahkan data ke tabel "OldExtents" dalam database saat ini, atau buat tabel jika belum ada. Beri tag jangkauan baru dengan ingest-by:myTag. Lakukan ini hanya jika tabel belum berisi jangkauan yang diberi tag ingest-by:myTag, berdasarkan tabel bernama "MyExtents" yang sudah ada.

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

Ganti data dalam tabel "OldExtents" dalam database saat ini, atau buat tabel jika belum ada. Beri tag jangkauan baru dengan ingest-by:myTag.

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

Tambahkan data ke tabel "OldExtents" dalam database saat ini, sambil mengatur waktu pembuatan jangkauan yang dibuat ke datetime tertentu sebelumnya.

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

Mengembalikan output

Menampilkan informasi tentang jangkauan yang dibuat karena perintah .set atau .append.

Contoh output

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