Catatan
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba masuk atau mengubah direktori.
Akses ke halaman ini memerlukan otorisasi. Anda dapat mencoba mengubah direktori.
Beralih layanan menggunakan daftar drop-down Versi . Pelajari selengkapnya tentang navigasi.
Berlaku untuk: ✅ Microsoft Fabric ✅ Azure Data Explorer
Perintah .ingest into menyerap data ke dalam tabel dengan "menarik" data dari satu atau beberapa file penyimpanan cloud.
Misalnya, perintah dapat mengambil 1.000 blob berformat CSV dari Azure Blob Storage, mengurainya, dan menyerapnya bersama-sama ke dalam satu tabel target.
Data ditambahkan ke tabel tanpa memengaruhi rekaman yang ada, dan tanpa memodifikasi skema tabel.
Nota
Metode penyerapan ini ditujukan untuk eksplorasi dan prototipe. Jangan gunakan dalam skenario produksi atau volume tinggi.
Izin
Anda harus memiliki setidaknya izin Table Ingestor untuk menjalankan perintah ini.
Sintaksis
.ingest [async] intotableTableNameSourceDataLocator [with(IngestionPropertyName=IngestionPropertyValue [, ...] )]
Pelajari selengkapnya tentang konvensi sintaks .
Parameter
| Nama | Jenis | Diperlukan | Deskripsi |
|---|---|---|---|
async |
string |
Jika ditentukan, perintah akan segera kembali dan melanjutkan penyerapan di latar belakang. Hasil perintah mencakup nilai OperationId yang kemudian dapat digunakan dengan perintah .show operation untuk mengambil status dan hasil penyelesaian penyerapan. |
|
| TableName | string |
✔️ | Nama tabel untuk menyerap data. Nama tabel selalu relatif terhadap database dalam konteks. Jika tidak ada objek pemetaan skema yang disediakan, skema database dalam konteks digunakan. |
| |
string |
✔️ | Daftar string koneksi penyimpanan yang dipisahkan koma atau tunggal. String koneksi tunggal harus merujuk ke satu file yang dihosting oleh akun penyimpanan. Penyerapan beberapa file dapat dilakukan dengan menentukan beberapa string koneksi, atau dengan menyerap dari kueri tabel eksternal . |
Nota
Sebaiknya gunakan
Properti penyerapan
Penting
Dalam data penyerapan antrean di-batch menggunakan properti Penyerapan. Semakin berbeda properti pemetaan penyerapan yang digunakan, seperti nilai ConstValue yang berbeda, semakin terfragmentasi penyerapannya, yang dapat menyebabkan penurunan performa.
Tabel berikut ini mencantumkan dan menjelaskan properti yang didukung, dan menyediakan contoh:
| Harta benda | Deskripsi | Contoh |
|---|---|---|
ingestionMapping |
Nilai string yang menunjukkan cara memetakan data dari file sumber ke kolom aktual dalam tabel. Tentukan nilai format dengan jenis pemetaan yang relevan. Lihat pemetaan data . |
with (format="json", ingestionMapping = "[{\"column\":\"rownumber\", \"Properties\":{\"Path\":\"$.RowNumber\"}}, {\"column\":\"rowguid\", \"Properties\":{\"Path\":\"$.RowGuid\"}}]")(tidak digunakan lagi: avroMapping, csvMapping, jsonMapping) |
ingestionMappingReference |
Nilai string yang menunjukkan cara memetakan data dari file sumber ke kolom aktual dalam tabel menggunakan objek kebijakan pemetaan bernama. Tentukan nilai format dengan jenis pemetaan yang relevan. Lihat pemetaan data . |
with (format="csv", ingestionMappingReference = "Mapping1")(tidak digunakan lagi: avroMappingReference, csvMappingReference, jsonMappingReference) |
archiveBestEffort |
Nilai Boolean yang, jika diatur ke true, menunjukkan bahwa penyerapan dari arsip ZIP harus terus diproses bahkan jika beberapa entri dalam arsip kosong atau rusak, alih-alih menggagalkan seluruh penyerapan. Properti ini hanya berlaku untuk arsip ZIP. Secara default, false diasumsikan. Penyerapan berhasil jika setidaknya satu entri berhasil diproses dan menghasilkan rekaman. Penyerapan gagal jika semua entri dalam arsip kosong atau rusak. |
with (archiveBestEffort=true) |
creationTime |
Nilai tanggalwaktu (diformat sebagai string ISO8601) untuk digunakan pada waktu pembuatan tingkat data yang diserap. Jika tidak ditentukan, nilai saat ini (now()) digunakan. Mengambil alih default berguna saat menyerap data yang lebih lama, sehingga kebijakan penyimpanan diterapkan dengan benar. Jika ditentukan, pastikan properti Lookback dalam kebijakan penggabungan Extents efektif tabel target selaras dengan nilai yang ditentukan. |
with (creationTime="2017-02-13") |
extend_schema |
Nilai Boolean yang, jika ditentukan, menginstruksikan perintah untuk memperluas skema tabel (default ke false). Opsi ini hanya berlaku untuk perintah .append dan .set-or-append. Satu-satunya ekstensi skema yang diizinkan memiliki lebih banyak kolom yang ditambahkan ke tabel di akhir. |
Jika skema tabel asli (a:string, b:int), ekstensi skema yang valid akan (a:string, b:int, c:datetime, d:string), tetapi (a:string, c:datetime) tidak akan valid |
folder |
Untuk perintah ingest-from-query |
with (folder="Tables/Temporary") |
format |
Format data (lihat format data yang didukung). | with (format="csv") |
ingestIfNotExists |
Nilai string yang, jika ditentukan, mencegah penyerapan berhasil jika tabel sudah memiliki data yang ditandai dengan tag ingest-by: dengan nilai yang sama. Ini memastikan penyerapan data idempotensi. Untuk informasi selengkapnya, lihat ingest-by: tag. |
Properti with (ingestIfNotExists='["Part0001"]', tags='["ingest-by:Part0001"]') menunjukkan bahwa jika data dengan tag ingest-by:Part0001 sudah ada, maka jangan selesaikan penyerapan saat ini. Jika belum ada, penyerapan baru ini harus memiliki kumpulan tag ini (jika penyerapan di masa mendatang mencoba menyerap data yang sama lagi.) |
ignoreFirstRecord |
Nilai Boolean yang, jika diatur ke true, menunjukkan bahwa penyerapan harus mengabaikan rekaman pertama dari setiap file. Properti ini berguna untuk file dalam format CSVdan serupa, jika rekaman pertama dalam file adalah nama kolom. Secara default, false diasumsikan. |
with (ignoreFirstRecord=false) |
policy_ingestiontime |
Nilai Boolean yang, jika ditentukan, menjelaskan apakah akan mengaktifkan kebijakan waktu penyerapan pada tabel yang dibuat oleh perintah ini. Defaultnya adalah true. |
with (policy_ingestiontime=false) |
recreate_schema |
Nilai Boolean yang, jika ditentukan, menjelaskan apakah perintah dapat membuat ulang skema tabel. Properti ini hanya berlaku untuk perintah .set-or-replace. Properti ini lebih diutamakan daripada properti extend_schema jika keduanya ditetapkan. |
with (recreate_schema=true) |
tags |
Daftar tag untuk dikaitkan dengan data yang diserap, diformat sebagai string JSON | with (tags="['Tag1', 'Tag2']") |
TreatGzAsUncompressed |
Nilai Boolean yang, jika diatur ke true, menunjukkan bahwa file dengan ekstensi .gz tidak dikompresi. Bendera ini terkadang diperlukan saat menyerap dari Amazon AWS S3. |
with (treatGzAsUncompressed=true) |
validationPolicy |
String JSON yang menunjukkan validasi mana yang akan dijalankan selama penyerapan data yang diwakili menggunakan format CSV. Lihat penyerapan data |
with (validationPolicy='{"ValidationOptions":1, "ValidationImplications":1}') (ini adalah kebijakan default) |
zipPattern |
Gunakan properti ini saat menyerap data dari penyimpanan yang memiliki arsip ZIP. Ini adalah nilai string yang menunjukkan ekspresi reguler untuk digunakan saat memilih file mana dalam arsip ZIP yang akan diserap. Semua file lain dalam arsip diabaikan. | with (zipPattern="*.csv") |
Penting
Keberhasilan yang dilaporkan untuk arsip ZIP yang diserap dengan archiveBestEffort=true tidak menjamin bahwa setiap file dalam arsip diserap. Karena kegagalan per entri ditekan, gunakan properti ini hanya ketika penyerapan konten arsip tidak lengkap dapat diterima.
Autentikasi dan otorisasi
Setiap string koneksi penyimpanan menunjukkan metode otorisasi yang akan digunakan untuk akses ke penyimpanan. Tergantung pada metode otorisasi, prinsipal mungkin perlu diberikan izin pada penyimpanan eksternal untuk melakukan penyerapan.
Tabel berikut mencantumkan metode autentikasi yang didukung dan izin yang diperlukan untuk menyerap data dari penyimpanan eksternal.
Kembali
Hasil dari perintah adalah tabel dengan rekaman sebanyak ada shard data ("extents") yang dihasilkan oleh perintah . Jika tidak ada shard data yang dihasilkan, satu rekaman dikembalikan dengan ID tingkat kosong (nilai nol).
| Nama | Jenis | Deskripsi |
|---|---|---|
| ExtentId | guid |
Pengidentifikasi unik untuk shard data yang dihasilkan oleh perintah . |
| Item Dimuat | string |
Satu atau beberapa file penyimpanan yang terkait dengan rekaman ini. |
| Durasi | timespan |
Berapa lama waktu yang dibutuhkan untuk melakukan penyerapan. |
| HasErrors | bool |
Apakah rekaman ini mewakili kegagalan penyerapan atau tidak. |
| OperationId | guid |
ID unik yang mewakili operasi. Dapat digunakan dengan perintah .show operation. |
Nota
Perintah ini tidak mengubah skema tabel yang sedang diserap. Jika perlu, data "dipaksa" ke dalam skema ini selama penyerapan, bukan sebaliknya (kolom tambahan diabaikan, dan kolom yang hilang diperlakukan sebagai nilai null).
Nota
archiveBestEffort Jika properti penyerapan diatur ke true, perintah dapat kembali HasErrors=false bahkan ketika beberapa entri kosong atau rusak dalam arsip ZIP dilewati. Hasil yang berhasil tidak menjamin bahwa setiap file dalam arsip diserap.
Contoh
Azure Blob Storage dengan tanda tangan akses bersama
Contoh berikut menginstruksikan database Anda untuk membaca dua blob dari Azure Blob Storage sebagai file CSV, dan menyerap kontennya ke dalam tabel T.
... mewakili tanda tangan akses bersama (SAS) Azure Storage yang memberikan akses baca ke setiap blob. String yang dikaburkan (h di depan nilai string) digunakan untuk memastikan bahwa SAS tidak pernah direkam.
.ingest into table T (
h'https://contoso.blob.core.windows.net/container/file1.csv?...',
h'https://contoso.blob.core.windows.net/container/file2.csv?...'
)
Azure Blob Storage dengan identitas terkelola
Contoh berikut menunjukkan cara membaca file CSV dari Azure Blob Storage dan menyerap kontennya ke dalam tabel T menggunakan autentikasi identitas terkelola. Autentikasi menggunakan ID identitas terkelola (ID objek) yang ditetapkan ke Azure Blob Storage di Azure. Untuk informasi selengkapnya, lihat Membuat identitas terkelola untuk kontainer penyimpanan.
.ingest into table T ('https://StorageAccount.blob.core.windows.net/Container/file.csv;managed_identity=802bada6-4d21-44b2-9d15-e66b29e4d63e')
Azure Data Lake Storage Gen 2
Contoh berikut adalah untuk menyerap data dari Azure Data Lake Storage Gen 2 (ADLSv2). Kredensial yang digunakan di sini (...) adalah kredensial akun penyimpanan (kunci bersama), dan kami menggunakan obfuscation string hanya untuk bagian rahasia dari string koneksi.
.ingest into table T (
'abfss://myfilesystem@contoso.dfs.core.windows.net/path/to/file1.csv;...'
)
Azure Data Lake Storage
Contoh berikut menyerap satu file dari Azure Data Lake Storage (ADLS). Ini menggunakan kredensial pengguna untuk mengakses ADLS (jadi tidak perlu memperlakukan URI penyimpanan sebagai berisi rahasia). Ini juga menunjukkan cara menentukan properti penyerapan.
.ingest into table T ('adl://contoso.azuredatalakestore.net/Path/To/File/file1.ext;impersonate')
with (format='csv')
Amazon S3 dengan kunci akses
Contoh berikut menyerap satu file dari Amazon S3 menggunakan ID kunci akses dan kunci akses rahasia.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/path/to/file.csv;AwsCredentials=EXAMPLEKEY')
with (format='csv')
Amazon S3 dengan URL yang telah ditetapkan sebelumnya
Contoh berikut menyerap satu file dari Amazon S3 menggunakan URL preSigned.
.ingest into table T ('https://bucketname.s3.us-east-1.amazonaws.com/file.csv?<<pre signed string>>')
with (format='csv')
Konten terkait
- format data didukung untuk penyerapan
- .ingest inline
- Menyerap dari kueri (.set, .append, .set-or-append, .set-or-replace)
- perintah kegagalan penyerapan
- .show pemetaan penyerapan