Mengekspor data ke penyimpanan

Artikel
06/23/2022
5 menit untuk membaca

Menjalankan kueri dan menulis tataan hasil yang diatur ke penyimpanan eksternal, yang ditentukan oleh string koneksi penyimpanan.

Sintaks

.export [async] [compressed] toOutputDataFormat(StorageConnectionString [, ...] ) [with(PropertyName=PropertyValue [, ...] )] <|Query

Argumen

async: Jika ditentukan, menunjukkan bahwa perintah berjalan dalam mode asinkron. Lihat di bawah untuk detail selengkapnya tentang perilaku dalam mode ini.
compressed: Jika ditentukan, penyimpanan output dikompresi sebagai file .gz. Lihat compressionType untuk mengompresi file Parquet sebagai snappy.
OutputDataFormat: Menunjukkan format data artefak penyimpanan yang ditulis oleh perintah. Nilai yang didukung adalah csv, tsv, json, dan parquet.
StorageConnectionString: Menentukan satu atau beberapa string koneksi penyimpanan yang menunjukkan penyimpanan mana yang akan ditulis datanya. (Lebih dari satu string koneksi penyimpanan yang dapat ditentukan untuk penulisan yang scalable.) Setiap string koneksi tersebut harus menunjukkan kredensial yang akan digunakan saat menulis ke penyimpanan. Misalnya, saat menulis ke Azure Blob Storage, kredensial dapat menjadi kunci akun penyimpanan atau kunci akses bersama (SAS) dengan izin untuk membaca, menulis, dan mencantumkan blob.

Catatan

Sebaiknya ekspor data ke penyimpanan yang berada di wilayah yang sama dengan kluster Kusto itu sendiri. Tindakan ini mencakup data yang diekspor sehingga dapat ditransfer ke layanan cloud lain di wilayah lainnya. Tulis harus dilakukan secara lokal, sementara baca bisa terjadi dari jarak jauh.

PropertyName/PropertyValue: Nol atau beberapa properti ekspor opsional:

Properti	Jenis	Deskripsi
`includeHeaders`	`string`	Mengontrol pembuatan header kolom untuk output `csv`/`tsv`. Bisa menjadi salah satu dari `none` (default; tidak ada garis header yang ditampilkan), `all` (menampilkan garis header ke setiap artefak penyimpanan), atau `firstFile` (hanya menampilkan garis header ke artefak penyimpanan pertama).
`fileExtension`	`string`	Menunjukkan bagian "ekstensi" dari artefak penyimpanan (contoh, `.csv` atau `.tsv`). Jika kompresi digunakan, `.gz` juga akan ditambahkan.
`namePrefix`	`string`	Menunjukkan awalan yang akan ditambahkan ke setiap nama artefak penyimpanan yang dihasilkan. Awalan acak akan digunakan jika dibiarkan tidak ditentukan.
`encoding`	`string`	Menunjukkan cara mengenkode teks: `UTF8NoBOM` (default) atau `UTF8BOM`.
`compressionType`	`string`	Menunjukkan jenis kompresi yang akan digunakan. Nilai yang mungkin adalah `gzip` atau `snappy`. Defaultnya adalah `gzip`. `snappy` dapat (secara opsional) digunakan untuk format `parquet`.
`distribution`	`string`	Petunjuk distribusi (`single`, `per_node`, `per_shard`). Jika nilai sama dengan `single`, satu alur akan menulis ke penyimpanan. Jika tidak, ekspor akan menulis dari semua node yang menjalankan kueri secara paralel. Lihat mengevaluasi operator plugin. Default ke `per_shard`.
`persistDetails`	`bool`	Menunjukkan bahwa perintah harus mempertahankan hasilnya (lihat bendera `async`). Menetapkan secara default ke `true` dalam eksekusi asinkron, tetapi dapat dinonaktifkan jika pemanggil tidak memerlukan hasilnya). Menetapkan secara default ke `false` dalam eksekusi sinkron, tetapi juga dapat diaktifkan pada eksekusi tersebut.
`sizeLimit`	`long`	Batas ukuran dalam byte pada artefak penyimpanan tunggal yang ditulis (sebelum kompresi). Rentang yang diizinkan adalah 100 MB (default) hingga 1 GB.
`parquetRowGroupSize`	`int`	Hanya relevan jika format data adalah Parquet. Mengontrol ukuran grup baris dalam file yang diekspor. Ukuran grup baris default adalah 100.000 catatan.
`distributed`	`bool`	Nonaktifkan/aktifkan ekspor terdistribusi. Pengaturan ke false sama dengan petunjuk distribusi `single`. Defaultnya adalah true.

Hasil

Perintah menampilkan tabel yang mendeskripsikan artefak penyimpanan yang dibuat. Setiap catatan mendeskripsikan satu artefak serta menyertakan jalur penyimpanan ke artefak dan jumlah rekaman data yang dimilikinya.

Jalur	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

Mode asinkron

Jika bendera async ditentukan, perintah akan berjalan dalam mode asinkron. Dalam mode ini, perintah segera ditampilkan dengan ID operasi, dan ekspor data berlanjut di latar belakang hingga selesai. ID operasi yang ditampilkan oleh perintah nantinya dapat digunakan untuk melacak perkembangan dan hasilnya melalui perintah berikut:

.show operations: Lacak perkembangan.
.show operation details: Dapatkan hasil penyelesaian.

Misalnya, setelah berhasil menyelesaikan, Anda dapat mengambil hasilnya menggunakan:

.show operation f008dc1e-2710-47d8-8d34-0d562f5f8615 details

Contoh

Dalam contoh ini, Kusto menjalankan kueri, lalu mengekspor perangkat rekam pertama yang dihasilkan oleh kueri ke satu atau beberapa blob CSV yang terkompresi. Label nama kolom ditambahkan sebagai baris pertama untuk setiap blob.

.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=100000,
    namePrefix=export,
    includeHeaders=all,
    encoding =UTF8NoBOM
  )
  <| myLogs | where id == "moshe" | limit 10000

Kegagalan selama perintah ekspor

Perintah ekspor dapat gagal sementara selama eksekusi. Ekspor berkelanjutan akan otomatis mencoba kembali perintah. Perintah ekspor reguler (ekspor ke penyimpanan, ekspor ke tabel eksternal) tidak menjalankan percobaan ulang apa pun.

Jika perintah ekspor gagal, artefak yang sudah ditulis ke penyimpanan tidak dihapus. Artefak ini akan tetap disimpan. Jika perintah gagal, anggaplah ekspor tersebut tidak lengkap, bahkan jika beberapa artefak ditulis.
Cara terbaik untuk melacak penyelesaian perintah dan artefak yang diekspor setelah berhasil diselesaikan adalah menggunakan perintah .show operations dan .show operation details.

Kegagalan penyimpanan

Secara default, perintah ekspor didistribusikan sedemikian rupa sehingga mungkin ada banyak penulisan serentak ke penyimpanan. Tingkat distribusi bergantung pada jenis perintah ekspor:

Distribusi default untuk perintah reguler .export adalah per_shard, yang berarti semua jangkauan yang berisi data untuk mengekspor tulis ke penyimpanan secara bersamaan.
Distribusi default untuk perintah ekspor ke tabel eksternal adalah per_node, yang berarti konkurensi adalah jumlah node dalam kluster.

Ketika jumlah jangkauan/node banyak, hal ini dapat menyebabkan beban tinggi pada penyimpanan yang menimbulkan pelambatan penyimpanan, atau kesalahan penyimpanan sementara. Saran berikut dapat mengatasi kesalahan ini (berdasarkan urutan prioritas):

Tingkatkan jumlah akun penyimpanan yang disediakan ke perintah ekspor atau ke definisi tabel eksternal (beban akan didistribusikan secara merata antarakun).
Kurangi konkurensi dengan mengatur petunjuk distribusi ke per_node (lihat properti perintah).
Kurangi konkurensi jumlah node yang mengekspor dengan menetapkan properti permintaan klienquery_fanout_nodes_percent ke konkurensi yang diinginkan (persentase node). Properti dapat diatur sebagai bagian dari kueri ekspor. Misalnya, perintah berikut akan membatasi jumlah node yang menulis ke penyimpanan secara bersamaan hingga 50% dari node kluster:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Jika mengekspor ke tabel eksternal yang dipartisi, mengatur properti spread/concurrency dapat mengurangi konkurensi (lihat detail di properti perintah.
Jika tidak satu pun dari pekerjaan di atas, Anda juga dapat sepenuhnya menonaktifkan distribusi dengan mengatur properti distributed ke false, tetapi ini tidak disarankan, karena dapat secara signifikan memengaruhi performa perintah.

Kegagalan otorisasi

Kegagalan autentikasi atau otorisasi selama perintah ekspor dapat terjadi ketika kredensial yang disediakan dalam string koneksi penyimpanan tidak diizinkan untuk menulis ke penyimpanan. Jika Anda menggunakan impersonate atau token SAS yang didelegasikan pengguna untuk perintah ekspor, peran Kontributor Data Blob Penyimpanan diperlukan untuk menulis ke akun penyimpanan. Untuk detail selengkapnya, lihat String koneksi penyimpanan.

Pemetaan jenis data

Pemetaan jenis data Parquet

Saat ekspor, jenis data Kusto dipetakan ke jenis data Parquet menggunakan aturan berikut:

Jenis Data Kusto	Jenis Data Parquet	Anotasi Parquet	Komentar
`bool`	`BOOLEAN`
`datetime`	`INT96`
`dynamic`	`BYTE_ARRAY`	UTF-8	Diserialisasi sebagai string JSON
`guid`	`BYTE_ARRAY`	UTF-8
`int`	`INT32`
`long`	`INT64`
`real`	`DOUBLE`
`string`	`BYTE_ARRAY`	UTF-8
`timespan`	`INT64`		Disimpan sebagai hitungan tick (unit 100 nanodetik)
`decimal`	`BYTE_ARRAY`	DESIMAL