.export ke penyimpanan

2025-03-05

Berlaku untuk: ✅Microsoft Fabric ✅Azure Data Explorer

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

Izin

Anda harus memiliki setidaknya izin Penampil Database untuk menjalankan perintah ini.

Sintaks

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

Pelajari selengkapnya tentang konvensi sintaksis.

Parameter

Nama	Tipe	Wajib	Deskripsi
asinkron	`string`		Jika ditentukan, perintah berjalan dalam mode asinkron. Lihat mode asinkron.
terkompresi	`bool`		Jika ditentukan, artefak penyimpanan output dikompresi dalam format yang ditentukan oleh properti yang didukung `compressionType`.
OutputDataFormat	`string`	✔️	Format data artefak penyimpanan yang ditulis oleh perintah . Nilai yang didukung adalah `csv`, `tsv`, `json`, dan `parquet`.
StorageConnectionString	`string`		Satu atau beberapa string koneksi penyimpanan yang menentukan penyimpanan mana yang akan ditulis datanya. Lebih dari satu string koneksi penyimpanan mungkin ditentukan untuk penulisan yang dapat diskalakan. Setiap string koneksi tersebut harus menentukan 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. Saat Anda mengekspor data ke file CSV menggunakan titik akhir DFS, data melewati titik akhir privat yang dikelola DFS. Saat Anda mengekspor data ke file parket, data melewati titik akhir privat yang dikelola blob.
PropertyName, PropertyValue	`string`		Daftar pasangan properti kunci-nilai yang dipisahkan koma. Lihat properti yang didukung.

Catatan

Kami sangat menyarankan untuk mengekspor data ke penyimpanan yang terletak di wilayah yang sama dengan database 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.

Properti yang didukung

Properti	Tipe	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`	Bagian "ekstensi" dari artefak penyimpanan (misalnya, `.csv` atau `.tsv`). Jika kompresi digunakan, `.gz` ditambahkan juga.
`namePrefix`	`string`	Awalan untuk ditambahkan ke setiap nama artefak penyimpanan yang dihasilkan. Awalan acak digunakan jika dibiarkan tidak ditentukan.
`encoding`	`string`	Pengodean untuk teks. Nilai yang mungkin termasuk: `UTF8NoBOM` (default) atau `UTF8BOM`.
`compressionType`	`string`	Jenis kompresi yang akan digunakan. Untuk file non-Parquet, hanya `gzip` yang diizinkan. Untuk file Parquet, nilai yang mungkin termasuk `gzip`, `snappy`, `lz4_raw`, `brotli`, dan `zstd`. Defaultnya adalah `gzip`.
`distribution`	`string`	Petunjuk distribusi (`single`, `per_node`, `per_shard`). Jika nilai sama dengan `single`, satu utas menulis ke penyimpanan. Jika tidak, ekspor tulisan dari semua simpul yang menjalankan kueri secara paralel. Lihat mengevaluasi operator plugin. Default ke `per_shard`.
`persistDetails`	`bool`	Jika `true`, perintah mempertahankan hasilnya (lihat bendera `async`). 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.
`sizeLimit`	`long`	Batas ukuran dalam byte dari artefak penyimpanan tunggal yang ditulis sebelum pemadatan. Rentang valid: 100 MB (default) hingga 4 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 rekaman.
`distributed`	`bool`	Nonaktifkan atau aktifkan ekspor terdistribusi. Pengaturan ke false sama dengan petunjuk distribusi `single`. Default-nya adalah true.
`parquetDatetimePrecision`	`string`	Presisi yang digunakan saat mengekspor nilai `datetime` ke Parquet. Nilai yang mungkin adalah milidetik dan mikro detik. Defaultnya adalah milidetik.

Autentikasi dan otorisasi

Metode autentikasi didasarkan pada string koneksi yang disediakan, dan izin yang diperlukan bervariasi tergantung pada metode autentikasi.

Tabel berikut mencantumkan metode autentikasi yang didukung dan izin yang diperlukan untuk mengekspor data ke penyimpanan eksternal menurut jenis penyimpanan.

Metode autentikasi	Azure Blob Storage / Data Lake Storage Gen2	Data Lake Storage Gen1
Penyamaran	Kontributor Data Blob Penyimpanan	Kontributor
Token Akses Bersama (SAS)	Write	Write
Token akses Microsoft Entra	Tidak diperlukan izin tambahan	Tidak diperlukan izin tambahan
Kunci akses akun penyimpanan	Tidak diperlukan izin tambahan	Tidak diperlukan izin tambahan

Mengembalikan

Perintah mengembalikan tabel yang menjelaskan artefak penyimpanan yang dihasilkan. Setiap rekaman menjelaskan satu artefak dan menyertakan jalur penyimpanan ke artefak dan berapa banyak rekaman yang disimpannya.

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 kumpulan rekaman pertama yang dihasilkan oleh kueri ke satu atau beberapa blob CSV terkompresi, hingga 1 GB sebelum pemadatan. 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=1000000000,
    namePrefix="export",
    includeHeaders="all",
    encoding="UTF8NoBOM"
  )
  <| 
  Logs | where id == "1234"

Kegagalan selama perintah ekspor

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

Ketika perintah ekspor gagal, artefak yang sudah ditulis ke penyimpanan tidak dihapus. Artefak ini tetap berada di penyimpanan. 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 sewaktu-waktu sehingga mungkin ada banyak penulisan bersamaan 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 ekspor ke perintah tabel eksternal adalah per_node, yang berarti konkurensi adalah jumlah simpul.

Ketika jumlah ekstensi/simpul besar, ini mungkin menyebabkan beban tinggi pada penyimpanan yang mengakibatkan pembatasan penyimpanan, atau kesalahan penyimpanan sementara. Saran berikut mungkin mengatasi kesalahan ini (berdasarkan urutan prioritas):

Tingkatkan jumlah akun penyimpanan yang disediakan untuk perintah ekspor atau ke definisi tabel eksternal . Beban didistribusikan secara merata di antara akun.
Kurangi konkurensi dengan mengatur petunjuk distribusi ke per_node (lihat properti perintah).
Kurangi konkurensi jumlah node yang diekspor dengan mengatur propertiquery_fanout_nodes_percent permintaan klien ke konkurensi yang diinginkan (persentase simpul). Properti dapat diatur sebagai bagian dari kueri ekspor. Misalnya, perintah berikut membatasi jumlah simpul yang menulis ke penyimpanan secara bersamaan hingga 50% dari simpul:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_node"
    ) 
    <| 
    set query_fanout_nodes_percent = 50;
    ExportQuery
```
Kurangi konkurensi jumlah utas yang diekspor di setiap simpul saat menggunakan per ekspor shard, dengan mengatur propertiquery_fanout_threads_percent permintaan klien ke konkurensi yang diinginkan (persentase utas). Properti dapat diatur sebagai bagian dari kueri ekspor. Misalnya, perintah berikut membatasi jumlah utas yang ditulis ke penyimpanan secara bersamaan hingga 50% pada setiap simpul:
```
.export async  to csv
    ( h@"https://storage1.blob.core.windows.net/containerName;secretKey" ) 
    with
    (
        distribution="per_shard"
    ) 
    <| 
    set query_fanout_threads_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 rekomendasi sebelumnya berfungsi, Anda dapat sepenuhnya menonaktifkan distribusi dengan mengatur properti distributed ke false. Namun, kami tidak menyarankan untuk melakukannya, karena mungkin 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 informasi 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`	`INT64`	TIMESTAMP_MICROS
`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`	`FIXED_LENGTH_BYTE_ARRAY`	DECIMAL

gambaran umum perintah manajemen
ekspor data berkelanjutan
.ingest ke dalam
.export ke tabel
.export ke SQL