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.
Berlaku untuk:
Databricks SQL
Databricks Runtime 13.3 LTS ke atas
Membaca file di bawah lokasi yang disediakan dan mengembalikan data dalam bentuk tabular.
Mendukung format file JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO, dan ORC.
Dapat mendeteksi format file secara otomatis dan menyimpulkan skema terpadu di semua file.
Sintaks
read_files(path [, option_key => option_value ] [...])
Argumen
Fungsi ini memerlukan pemanggilan parameter bernama untuk kunci pilihan.
-
path: ASTRINGdengan URI lokasi data. Mendukung pembacaan dari Azure Data Lake Storage ('abfss://'), S3 (s3://) dan Google Cloud Storage ('gs://'). Dapat berisi glob. Lihat Penemuan File untuk lebih detail. -
option_key: Nama opsi untuk dikonfigurasi. Anda perlu menggunakan backticks () for options that contain dots (.`). -
option_value: Ekspresi konstanta untuk mengatur opsi ke. Menerima literal dan fungsi skalar.
Pengembalian
Tabel yang berisi data dari file yang dibaca di bawah yang diberikan path. Skema tergantung pada format file:
BINARYFILE: Mengembalikan skema tetap:kolom Tipe Deskripsi pathSTRINGJalur lengkap ke file. modificationTimeTIMESTAMPWaktu modifikasi terakhir file. lengthLONGUkuran file dalam satuan byte. contentBINARYKonten biner file. Gunakan * EXCEPT (content)untuk mengecualikan konten biner saat mengkueri metadata file.TEXT: Mengembalikan skema tetap dengan satuvaluekolom (STRING).Semua format lainnya (JSON, CSV, XML, PARQUET, AVRO, ORC): Skema disimpulkan dari konten file, atau disediakan secara eksplisit menggunakan
schemaopsi .
_metadata Kolom
read_files
_metadata mengekspos kolom dengan metadata tingkat file. Kolom ini tidak disertakan dalam SELECT * hasil dan harus dipilih secara eksplisit. Ini berisi bidang berikut:
| Ladang | Tipe | Deskripsi |
|---|---|---|
file_path |
STRING |
Jalur lengkap ke file sumber. |
file_name |
STRING |
Nama file sumber. |
file_size |
LONG |
Ukuran file sumber dalam byte. |
file_modification_time |
TIMESTAMP |
Waktu modifikasi terakhir file sumber. |
file_block_start |
LONG |
Awal blok file yang sedang dibaca. |
file_block_length |
LONG |
Panjang blok file yang sedang dibaca. |
Untuk menyertakan _metadata hasil, pilih secara eksplisit:
SELECT * EXCEPT (content), _metadata
FROM read_files('/Volumes/my_catalog/my_schema/my_volume', format => 'binaryFile');
Pencarian file
read_files dapat membaca file individual atau membaca file di bawah direktori yang disediakan.
read_files menemukan semua file di bawah direktori yang disediakan dengan cara rekursif, kecuali jika sebuah glob disediakan, yang menginstruksikan read_files untuk memasuki ulang pola direktori tertentu.
Memfilter direktori atau file menggunakan pola glob
Pola Glob dapat digunakan untuk memfilter direktori dan file jika disediakan dalam jalur.
| Pola | Deskripsi |
|---|---|
? |
Cocok dengan karakter tunggal apa pun |
* |
Cocok dengan nol atau lebih karakter |
[abc] |
Cocok dengan satu karakter dari kumpulan karakter {a,b,c}. |
[a-z] |
Cocok dengan satu karakter dari rentang karakter {a... z}. |
[^a] |
Mencocokkan karakter tunggal yang bukan dari set karakter atau rentang {a}. Perhatikan bahwa ^ karakter harus muncul segera di sebelah kanan tanda kurung pembuka. |
{ab,cd} |
Mencocokkan string dari sekumpulan string {ab, cd}. |
{ab,c{de, fh}} |
Mencocokkan string dari kumpulan string {ab, cde, cfh}. |
read_files menggunakan globber ketat Auto Loader saat menemukan file dengan glob. Ini dikonfigurasi oleh opsi useStrictGlobber. Ketika globber ketat dinonaktifkan, garis miring di akhir (/) dihilangkan dan pola bintang seperti /*/ dapat berkembang sehingga berbagai direktori dapat ditemukan. Lihat contoh di bawah ini untuk melihat perbedaan perilaku.
| Pola | Jalur file | Pengaturan globber ketat telah dinonaktifkan | Pengaktifan globber ketat |
|---|---|---|---|
/a/b |
/a/b/c/file.txt |
Ya | Ya |
/a/b |
/a/b_dir/c/file.txt |
Tidak | Tidak |
/a/b |
/a/b.txt |
Tidak | Tidak |
/a/b/ |
/a/b.txt |
Tidak | Tidak |
/a/*/c/ |
/a/b/c/file.txt |
Ya | Ya |
/a/*/c/ |
/a/b/c/d/file.txt |
Ya | Ya |
/a/*/d/ |
/a/b/c/d/file.txt |
Ya | Tidak |
/a/*/c/ |
/a/b/x/y/c/file.txt |
Ya | Tidak |
/a/*/c |
/a/b/c_file.txt |
Ya | Tidak |
/a/*/c/ |
/a/b/c_file.txt |
Ya | Tidak |
/a/*/c |
/a/b/cookie/file.txt |
Ya | Tidak |
/a/b* |
/a/b.txt |
Ya | Ya |
/a/b* |
/a/b/file.txt |
Ya | Ya |
/a/{0.txt,1.txt} |
/a/0.txt |
Ya | Ya |
/a/*/{0.txt,1.txt} |
/a/0.txt |
Tidak | Tidak |
/a/b/[cde-h]/i/ |
/a/b/c/i/file.txt |
Ya | Ya |
Inferensi skema
Skema file dapat secara eksplisit disediakan ke read_files dengan opsi schema. Ketika skema tidak disediakan, read_files berusaha menyimpulkan skema konsisten di antara file yang ditemukan, yang memerlukan pembacaan semua file kecuali LIMIT pernyataan digunakan. Bahkan saat menggunakan LIMIT kueri, sekumpulan file yang lebih besar dari yang diperlukan mungkin dibaca untuk mengembalikan skema data yang lebih representatif. Databricks secara otomatis menambahkan LIMIT pernyataan untuk SELECT kueri di notebook dan editor SQL jika pengguna belum menyediakannya.
Opsi schemaHints dapat digunakan untuk memperbaiki subset skema yang disimpulkan. Lihat Mengecualikan inferensi skema dengan petunjuk skema untuk detail selengkapnya.
rescuedDataColumn disediakan secara default untuk menyelamatkan data apa pun yang tidak cocok dengan skema. Lihat Apa kolom data yang diselamatkan? untuk detail selengkapnya. Anda dapat menghilangkan rescuedDataColumn dengan mengatur opsi schemaEvolutionMode => 'none'.
Inferensi skema pembagian
read_files juga dapat menyimpulkan kolom partisi jika file disimpan di bawah direktori yang dipartisi dengan gaya Hive, yaitu . Jika schema disediakan, kolom-kolom partisi yang ditemukan menggunakan jenis yang disediakan dalam schema. Jika kolom partisi bukan bagian dari yang disediakan schema, maka kolom partisi yang disimpulkan diabaikan.
Jika kolom ada di skema partisi dan di kolom data, nilai yang dibaca dari nilai partisi digunakan alih-alih nilai data. Jika Anda ingin mengabaikan nilai yang berasal dari direktori dan menggunakan kolom data, Anda bisa menyediakan daftar kolom partisi dalam daftar yang dipisahkan koma dengan partitionColumns opsi .
Opsi partitionColumns ini juga dapat digunakan untuk menginstruksikan read_files tentang kolom yang ditemukan yang harus disertakan dalam skema akhir yang disimpulkan. Memberikan string kosong akan mengabaikan semua kolom partisi.
Opsi ini schemaHints juga dapat disediakan untuk menggantikan skema yang disimpulkan untuk kolom partisi.
Format TEXT dan BINARYFILE memiliki skema yang tetap, tetapi read_files juga mencoba menyimpulkan partisi untuk format-format tersebut jika memungkinkan.
Autentikasi untuk penyimpanan cloud
read_files mengakses penyimpanan cloud melalui lokasi eksternal Unity Catalog. Anda harus memiliki READ FILES hak istimewa pada lokasi eksternal yang berisi file yang ingin Anda baca. Lihat Menyambungkan ke penyimpanan objek cloud menggunakan Katalog Unity.
Penggunaan dalam tabel streaming
read_files dapat digunakan dalam tabel streaming untuk menyerap file ke Delta Lake.
read_files memanfaatkan Auto Loader saat digunakan dalam kueri tabel streaming. Anda harus menggunakan kata kunci STREAM dengan read_files. Lihat Apa itu Auto Loader? untuk detail selengkapnya.
Saat digunakan dalam kueri streaming, read_files menggunakan sampel data untuk menyimpulkan skema, dan dapat mengembangkan skema saat memproses lebih banyak data. Lihat Mengonfigurasi inferensi dan evolusi skema di Auto Loader untuk detail selengkapnya.
Opsi
- Opsi Dasar
- Opsi generik
-
JSONopsi -
CSVopsi -
XMLopsi -
PARQUETopsi -
AVROopsi -
BINARYFILEopsi -
TEXTopsi -
ORCopsi - Opsi streaming
Opsi Dasar
| Opsi |
|---|
formatJenis: StringFormat file data di jalur sumber. Disimpulkan secara otomatis jika tidak disediakan. Nilai yang diizinkan meliputi:
Nilai default: Tidak ada |
schemaJenis: StringSkema file yang akan dibaca. Berikan string skema menggunakan format DDL, misalnya 'id int, ts timestamp, event string'. Ketika skema tidak disediakan, read_files upaya untuk menyimpulkan skema terpadu di seluruh file yang ditemukan.Nilai default: Tidak ada |
inferColumnTypesJenis: BooleanApakah akan menyimpulkan tipe kolom yang tepat saat memanfaatkan inferensi skema. Secara default, kolom disimpulkan saat menyimpulkan himpunan data JSON dan CSV. Lihat inferensi skema untuk detail selengkapnya. Perhatikan bahwa ini adalah kebalikan dari default Auto Loader. Nilai default: true |
partitionColumnsJenis: StringDaftar kolom partisi gaya Hive yang dipisahkan oleh koma yang ingin Anda inferensikan dari struktur direktori file. Kolom partisi gaya Hive adalah pasangan kunci-nilai yang dikombinasikan dengan tanda sama dengan seperti <base-path>/a=x/b=1/c=y/file.format. Dalam contoh ini, kolom partisi adalah a, b, dan c. Secara default kolom ini akan secara otomatis ditambahkan ke skema Anda jika Anda menggunakan inferensi skema dan menyediakan <base-path> untuk memuat data. Jika Anda memberikan skema, Auto Loader mengharapkan kolom ini disertakan dalam skema. Jika Anda tidak ingin kolom ini sebagai bagian dari skema Anda, Anda dapat menentukan "" untuk mengabaikan kolom ini. Selain itu, Anda dapat menggunakan opsi ini ketika Anda ingin kolom disimpulkan jalur file dalam struktur direktori yang kompleks, seperti contoh di bawah ini:<base-path>/year=2022/week=1/file1.csv<base-path>/year=2022/month=2/day=3/file2.csv<base-path>/year=2022/month=2/day=4/file3.csvMenentukan cloudFiles.partitionColumns sebagai year,month,day akan mengembalikanyear=2022 untuk file1.csv, tetapi kolom month dan day akan menjadi null.month dan day akan diurai dengan benar untuk file2.csv dan file3.csv.Nilai default: Tidak ada |
schemaHintsJenis: StringInformasi skema yang Anda berikan kepada Auto Loader selama inferensi skema. Lihat hint skema untuk detail selengkapnya. Nilai default: Tidak ada |
useStrictGlobberJenis: BooleanApakah akan menggunakan globber ketat yang sesuai dengan perilaku pengglobberan default dari sumber-sumber file lain pada Apache Spark. Lihat Pola pemuatan data umum untuk detail selengkapnya. Tersedia di Databricks Runtime 12.2 LTS ke atas. Perhatikan bahwa ini adalah kebalikan dari default untuk Auto Loader. Nilai default: true |
Opsi generik
Opsi berikut berlaku untuk semua format file.
| Opsi |
|---|
ignoreCorruptFilesJenis: BooleanApakah akan mengabaikan file yang rusak. Jika true, pekerjaan Spark akan terus berjalan ketika menemukan file yang rusak dan konten yang telah dibaca akan tetap dikembalikan. Dapat diamati sebagai numSkippedCorruptFiles dalamkolom operationMetrics dari riwayat Delta Lake. Tersedia di Databricks Runtime 11.3 LTS ke atas.Nilai default: false |
ignoreMissingFilesJenis: BooleanApakah mengabaikan file yang hilang. Jika true, pekerjaan Spark akan terus berjalan ketika menemukan file yang hilang dan konten yang telah dibaca akan tetap dikembalikan. Tersedia di Databricks Runtime 11.3 LTS ke atas. Nilai default: false untuk Auto Loader, true untuk COPY INTO (warisan) |
modifiedAfterKetik: Timestamp String, misalnya 2021-01-01 00:00:00.000000 UTC+0Tanda waktu opsional sebagai filter untuk hanya memasukkan file yang memiliki tanda waktu modifikasi setelah tanda waktu yang disediakan. Nilai default: Tidak ada |
modifiedBeforeKetik: Timestamp String, misalnya 2021-01-01 00:00:00.000000 UTC+0Cap waktu opsional sebagai filter untuk hanya memasukkan file yang memiliki cap waktu modifikasi sebelum cap waktu yang disediakan. Nilai default: Tidak ada |
pathGlobFilter atau fileNamePatternJenis: StringPola glob potensial untuk memilih file. Setara dengan PATTERN dalam COPY INTO (versi lama).
fileNamePattern dapat digunakan dalam read_files.Nilai default: Tidak ada |
recursiveFileLookupJenis: BooleanOpsi ini mencari melalui direktori berlapis bahkan jika namanya tidak mengikuti skema penamaan partisi seperti date=2019-07-01. Nilai default: false |
Opsi JSON
| Opsi |
|---|
allowBackslashEscapingAnyCharacterJenis: BooleanApakah akan mengizinkan backslash untuk menghindari karakter yang mengikutinya. Jika tidak diaktifkan, hanya karakter yang secara eksplisit terdaftar oleh spesifikasi JSON yang dapat lolos. Nilai default: false |
allowCommentsJenis: BooleanApakah akan mengizinkan penggunaan komentar gaya Java, C, dan C++ ( '/', '*', dan varietas '//') dalam konten yang diurai atau tidak.Nilai default: false |
allowNonNumericNumbersJenis: BooleanApakah akan mengizinkan sekumpulan token non-angka ( NaN) sebagai nilai bilangan desimal yang sah.Nilai default: true |
allowNumericLeadingZerosJenis: BooleanApakah akan mengizinkan angka integral dimulai dengan nol tambahan (dapat diabaikan) (misalnya, 000001).Nilai default: false |
allowSingleQuotesJenis: BooleanApakah akan mengizinkan penggunaan tanda kutip tunggal (apostrof, karakter '\') untuk mengutip string (nama dan nilai String).Nilai default: true |
allowUnquotedControlCharsJenis: BooleanApakah akan mengizinkan string JSON berisi karakter kontrol yang tidak di-escape (karakter ASCII dengan nilai kurang dari 32, termasuk karakter tab dan pengumpan baris) atau tidak. Nilai default: false |
allowUnquotedFieldNamesJenis: BooleanMengizinkan penggunaan nama bidang tanpa tanda kutip (yang diizinkan oleh JavaScript, tetapi tidak oleh standar JSON). Nilai default: false |
badRecordsPathJenis: StringJalur untuk menyimpan file untuk merekam informasi tentang rekaman JSON yang tidak valid. badRecordsPath Menggunakan opsi dalam sumber data berbasis file memiliki batasan berikut:
Nilai default: Tidak ada |
columnNameOfCorruptRecordJenis: StringKolom untuk menyimpan rekaman yang rusak dan tidak dapat diurai. Jika mode untuk penguraian diset sebagai DROPMALFORMED, kolom ini akan kosong.Nilai default: _corrupt_record |
dateFormatJenis: StringFormat untuk memproses string tanggal. Nilai default: yyyy-MM-dd |
dropFieldIfAllNullJenis: BooleanApakah akan mengabaikan kolom dengan semua nilai null atau array dan struktur kosong selama penarikan kesimpulan skema. Nilai default: false |
encoding atau charsetJenis: StringNama pengodean file JSON. Lihat java.nio.charset.Charset untuk daftar opsi. Anda tidak dapat menggunakan UTF-16 dan UTF-32 saat multiline adalah true.Nilai default: UTF-8 |
inferTimestampJenis: BooleanApakah ingin menyimpulkan string penanda waktu sebagai TimestampType. Ketika diatur ke dalam kondisi tertentutrue, inferensi skema mungkin memakan waktu jauh lebih lama. Anda harus mengaktifkan cloudFiles.inferColumnTypes untuk digunakan dengan Auto Loader.Nilai default: false |
lineSepJenis: StringString di antara dua catatan JSON yang berturut-turut. Nilai default: Tidak ada, yang mencakup \r, \r\n, dan \n |
localeJenis: StringSebuah java.util.Locale pengidentifikasi. Memengaruhi tanggal default, cap waktu, dan proses penguraian desimal dalam JSON.Nilai default: US |
modeJenis: StringModus pengurai dalam menangani catatan yang rusak. Salah satu dari PERMISSIVE, DROPMALFORMED, atau FAILFAST.Nilai default: PERMISSIVE |
multiLineJenis: BooleanApakah catatan JSON mencakup beberapa baris. Nilai default: false |
prefersDecimalJenis: BooleanMencoba menyimpulkan string sebagai DecimalType alih-alih tipe float atau double jika memungkinkan. Anda juga harus menggunakan inferensi skema, baik dengan mengaktifkan...inferSchema atau menggunakan cloudFiles.inferColumnTypes dengan Auto Loader.Nilai default: false |
primitivesAsStringJenis: BooleanApakah perlu menyimpulkan tipe data primitif seperti angka dan boolean sebagai StringType.Nilai default: false |
readerCaseSensitiveJenis: BooleanMenentukan perilaku sensitivitas huruf besar/kecil saat rescuedDataColumn diaktifkan. Jika benar, pulihkan kolom data yang namanya berbeda menurut huruf besar/kecil dari skema; jika tidak, baca data tanpa memerhatikan huruf besar/kecil. Tersedia di Databricks Runtime13.3 ke atas. Nilai default: true |
rescuedDataColumnJenis: StringApakah akan mengumpulkan semua data yang tidak dapat diurai karena ketidakcocokan jenis data atau ketidakcocokan skema (termasuk selubung kolom) ke kolom terpisah. Kolom ini disertakan secara default saat menggunakan Auto Loader. Untuk detail selengkapnya, lihat Apa itu kolom data yang diselamatkan?. COPY INTO (warisan) tidak mendukung kolom data yang diselamatkan karena Anda tidak dapat mengatur skema secara manual menggunakan COPY INTO. Databricks merekomendasikan penggunaan Auto Loader untuk sebagian besar skenario penyerapan.Nilai default: Tidak ada |
singleVariantColumnJenis: StringApakah akan memasukkan seluruh dokumen JSON, diurai ke dalam satu kolom Varian dengan string yang diberikan sebagai nama kolom. Jika dinonaktifkan, bidang JSON akan diserap ke dalam kolomnya sendiri. Nilai default: Tidak ada |
timestampFormatJenis: StringFormat untuk memproses string penanda waktu. Nilai default: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX] |
timeZoneJenis: Stringjava.time.ZoneId untuk digunakan saat menguraikan stempel waktu dan tanggal.Nilai default: Tidak ada |
Opsi CSV
| Opsi |
|---|
badRecordsPathJenis: StringJalur untuk menyimpan file untuk merekam informasi tentang rekaman CSV yang salah. Nilai default: Tidak ada |
charToEscapeQuoteEscapingJenis: CharKarakter yang digunakan untuk menghindari karakter yang digunakan untuk menghindari tanda kutip. Misalnya, untuk catatan berikut: [ " a\\", b ]:
Nilai default: '\0' |
columnNameOfCorruptRecordDidukung oleh Auto Loader. Tidak didukung untuk COPY INTO (versi lama).Jenis: StringKolom untuk menyimpan rekaman yang rusak dan tidak dapat diurai. Jika mode untuk penguraian diset sebagai DROPMALFORMED, kolom ini akan kosong.Nilai default: _corrupt_record |
commentJenis: CharMendefinisikan karakter yang mewakili komentar baris ketika ditemukan di awal baris teks. Gunakan '\0' untuk menonaktifkan pelompatan komentar.Nilai default: '\u0000' |
dateFormatJenis: StringFormat untuk memproses string tanggal. Nilai default: yyyy-MM-dd |
emptyValueJenis: StringRepresentasi string untuk nilai yang kosong. Nilai default: "" |
encoding atau charsetJenis: StringNama pengodean file CSV. Lihat java.nio.charset.Charset untuk daftar opsi.
UTF-16 dan UTF-32 tidak dapat digunakan saat multiline adalah true.Nilai default: UTF-8 |
enforceSchemaJenis: BooleanApakah akan menerapkan skema yang ditentukan atau disimpulkan secara paksa ke file CSV. Jika opsi diaktifkan, header file CSV akan diabaikan. Opsi ini diabaikan secara default saat menggunakan Auto Loader untuk menyelamatkan data dan memungkinkan evolusi skema. Nilai default: true |
escapeJenis: CharKarakter escape untuk digunakan saat mengurai data. Nilai default: '\' |
headerJenis: BooleanApakah file CSV berisi tajuk? Auto Loader menganggap bahwa file memiliki judul saat menyimpulkan skema. Nilai default: false |
ignoreLeadingWhiteSpaceJenis: BooleanApakah akan mengabaikan spasi awal untuk setiap nilai yang diurai. Nilai default: false |
ignoreTrailingWhiteSpaceJenis: BooleanApakah akan mengabaikan spasi di akhir untuk setiap nilai yang diparsing. Nilai default: false |
inferSchemaJenis: BooleanApakah akan menyimpulkan tipe data dari catatan CSV yang telah diurai atau mengasumsikan bahwa semua kolom berasal dari StringType. Memerlukan pemrosesan tambahan pada data jika diset ke true. Untuk Auto Loader, gunakan cloudFiles.inferColumnTypes sebagai gantinya.Nilai default: false |
lineSepJenis: StringString antara dua baris JSON berturut-turut. Nilai default: Tidak ada, yang mencakup \r, \r\n, dan \n |
localeJenis: StringSebuah java.util.Locale pengidentifikasi. Memengaruhi tanggal default, stempel waktu, dan penguraian desimal dalam CSV.Nilai default: US |
maxCharsPerColumnJenis: IntJumlah maksimum karakter yang diharapkan dari nilai untuk mem-parse. Dapat digunakan untuk menghindari kesalahan memori. Pengaturan awal adalah -1, yang berarti tidak terbatas.Nilai default: -1 |
maxColumnsJenis: IntBatas tegas jumlah kolom yang dapat dimiliki oleh sebuah rekaman. Nilai default: 20480 |
mergeSchemaJenis: BooleanApakah akan memperkirakan skema di beberapa file serta menggabungkan skema setiap file. Diaktifkan secara default untuk Auto Loader saat menginferr skema. Nilai default: false |
modeJenis: StringModus pengurai dalam menangani catatan yang rusak. Salah satu dari 'PERMISSIVE','DROPMALFORMED', dan 'FAILFAST'.Nilai default: PERMISSIVE |
multiLineJenis: BooleanApakah catatan CSV mencakup beberapa baris. Nilai default: false |
nanValueJenis: StringRepresentasi string dari nilai non-angka saat mengurai kolom FloatType dan DoubleType.Nilai default: "NaN" |
negativeInfJenis: StringRepresentasi string dari nilai negatif tak terhingga saat mengurai kolom FloatType atau DoubleType.Nilai default: "-Inf" |
nullValueJenis: StringRepresentasi string dari nilai null. Nilai default: "" |
parserCaseSensitive (tidak digunakan lagi)Jenis: BooleanSaat membaca file, apakah akan menyelaraskan kolom yang dideklarasikan di header dengan kasus skema secara sensitif. Ini adalah true secara bawaan untuk Auto Loader. Kolom yang berbeda menurut kasus akan disimpan di rescuedDataColumn jika diaktifkan. Opsi ini tidak digunakan lagi dan digantikan dengan readerCaseSensitive.Nilai default: false |
positiveInfJenis: StringRepresentasi string dari tak hingga positif saat mengurai kolom FloatType atau DoubleType.Nilai default: "Inf" |
preferDateJenis: BooleanMencoba menyimpulkan string sebagai tanggal alih-alih tanda waktu jika memungkinkan. Anda juga harus menggunakan inferensi skema, baik dengan mengaktifkan inferSchema atau menggunakancloudFiles.inferColumnTypes dengan Pengisi Otomatis.Nilai default: true |
quoteJenis: CharKarakter yang digunakan untuk menghindari nilai-nilai di mana pemisah bidang adalah bagian dari nilai tersebut. Nilai default: " |
readerCaseSensitiveJenis: BooleanMenentukan perilaku sensitivitas huruf besar/kecil saat rescuedDataColumn diaktifkan. Jika benar, pulihkan kolom data yang namanya berbeda menurut huruf besar/kecil dari skema; jika tidak, baca data tanpa memerhatikan huruf besar/kecil.Nilai default: true |
rescuedDataColumnJenis: StringApakah perlu mengumpulkan semua data yang tidak dapat diurai karena ketidakcocokan tipe data dan ketidakcocokan skema (termasuk pengejaan kolom) ke dalam kolom terpisah. Kolom ini disertakan secara default saat menggunakan Auto Loader. Untuk detail selengkapnya, lihat Apa itu kolom data yang diselamatkan?. COPY INTO (warisan) tidak mendukung kolom data yang diselamatkan karena Anda tidak dapat mengatur skema secara manual menggunakan COPY INTO. Databricks merekomendasikan penggunaan Auto Loader untuk sebagian besar skenario penyerapan.Nilai default: Tidak ada |
sep atau delimiterJenis: StringString pemisah antar kolom. Nilai default: "," |
skipRowsJenis: IntJumlah baris dari awal file CSV yang harus diabaikan (termasuk baris yang dikomentari dan kosong). Jika header benar, header akan menjadi baris pertama yang tidak dilewati atau dikomentari.Nilai default: 0 |
timestampFormatJenis: StringFormat untuk memproses string penanda waktu. Nilai default: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX] |
timeZoneJenis: Stringjava.time.ZoneId untuk digunakan saat menguraikan stempel waktu dan tanggal.Nilai default: Tidak ada |
unescapedQuoteHandlingJenis: StringStrategi untuk menangani tanda kutip yang tidak ter-escape. Opsi yang diizinkan:
Nilai default: STOP_AT_DELIMITER |
Opsi XML
| Opsi | Deskripsi | Ruang Lingkup |
|---|---|---|
rowTag |
Tag baris pada file XML untuk diperlakukan sebagai baris. Dalam contoh XML <books> <book><book>...<books>, nilai yang sesuai adalah book. Opsi ini wajib diisi. |
baca |
samplingRatio |
Menentukan sebagian kecil baris yang digunakan untuk inferensi skema. Fungsi bawaan XML mengabaikan opsi ini. Standar: 1.0. |
baca |
excludeAttribute |
Apakah akan mengecualikan atribut dalam elemen. Standar: false. |
baca |
mode |
Mode untuk menangani rekaman yang rusak selama penguraian.PERMISSIVE: Untuk data yang korup, menempatkan string cacat ke dalam bidang yang dikonfigurasi oleh columnNameOfCorruptRecord, dan menyetel bidang yang cacat ke null. Untuk menyimpan rekaman yang rusak, Anda bisa mengatur bidang dengan jenis string bernama columnNameOfCorruptRecord dalam skema yang ditentukan pengguna. Jika skema tidak memiliki bidang , rekaman yang rusak akan dihilangkan selama penguraian. Saat menyimpulkan skema, pengurai secara implisit menambahkan columnNameOfCorruptRecord bidang dalam skema output.DROPMALFORMED: Mengabaikan rekaman yang rusak. Mode ini tidak didukung untuk fungsi bawaan XML.FAILFAST: Melemparkan pengecualian ketika pengurai menemukan rekaman yang rusak. |
baca |
inferSchema |
Jika true, mencoba menyimpulkan jenis yang sesuai untuk setiap kolom DataFrame yang dihasilkan. Jika false, semua kolom yang dihasilkan berjenis string . Bawaantrue. Fungsi bawaan XML mengabaikan opsi ini. |
baca |
columnNameOfCorruptRecord |
Memungkinkan penggantian nama bidang baru yang berisi string cacat yang dibuat olehPERMISSIVE modus. Standar: spark.sql.columnNameOfCorruptRecord. |
baca |
attributePrefix |
Awalan untuk atribut untuk membedakan atribut dari elemen. Ini akan menjadi awalan untuk nama bidang. Defaultnya adalah _. Bisa kosong untuk membaca XML, tetapi tidak untuk menulis. |
baca, tulis |
valueTag |
Tag yang digunakan untuk data karakter dalam elemen yang juga memiliki elemen atribut atau elemen turunan. Pengguna dapat menentukan valueTag bidang dalam skema atau akan ditambahkan secara otomatis selama inferensi skema ketika data karakter ada dalam elemen dengan elemen atau atribut lain. Bawaan: _VALUE |
baca,tulis |
encoding |
Untuk membaca, dekode file XML dengan jenis pengodean yang diberikan. Untuk menulis, menentukan pengodean (charset) file XML yang disimpan. Fungsi bawaan XML mengabaikan opsi ini. Standar: UTF-8. |
baca, tulis |
ignoreSurroundingSpaces |
Menentukan apakah spasi putih di sekitarnya dari nilai yang dibaca harus dilewati. Standar: true. Data karakter yang hanya berupa spasi diabaikan. |
baca |
rowValidationXSDPath |
Jalur ke file XSD opsional yang digunakan untuk memvalidasi XML untuk setiap baris satu per satu. Baris yang gagal divalidasi diperlakukan seperti kesalahan parse seperti di atas. XSD tidak memengaruhi skema yang disediakan, atau disimpulkan, dalam hal lain. | baca |
ignoreNamespace |
Jika true, awalan namespace pada elemen dan atribut XML diabaikan. Tag <abc:author> dan <def:author>, misalnya, diperlakukan seolah-olah keduanya hanya <author>. Namespace tidak dapat diabaikan pada elemen rowTag, hanya pada anak elemen yang dibaca. Penguraian XML tidak mendukung namespace bahkan jika false. Standar: false. |
baca |
timestampFormat |
String format tanda waktu kustom yang mengikuti pola datetime format. Ini berlaku untuk jenis timestamp ini. Standar: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]. |
baca, tulis |
timestampNTZFormat |
String format kustom untuk stempel waktu tanpa zona waktu yang mengikuti format pola tanggal waktu. Ini berlaku untuk jenis TimestampNTZType. Bawaanyyyy-MM-dd'T'HH:mm:ss[.SSS] |
baca, tulis |
dateFormat |
String format tanggal kustom yang mengikuti format pola tanggal dan waktu. Ini berlaku untuk jenis tanggal. Standar: yyyy-MM-dd. |
baca, tulis |
locale |
Mengatur lokal sebagai tag bahasa dalam format IETF BCP 47. Misalnya, locale digunakan saat mengurai tanggal dan tanda waktu. Standar: en-US. |
baca |
rootTag |
Tag utama dari file XML. Misalnya, dalam <books> <book><book>...</books>, nilai yang sesuai adalah books. Anda dapat menyertakan atribut dasar dengan menentukan nilai seperti books foo="bar". Standar: ROWS. |
tulis |
declaration |
Konten deklarasi XML untuk ditulis di awal setiap file XML output, sebelum rootTag. Misalnya, nilai foo menyebabkan <?xml foo?> ditulis. Atur ke string kosong untuk menghilangkan. Bawaan: version="1.0"encoding="UTF-8" standalone="yes". |
tulis |
arrayElementName |
Nama elemen XML yang mengapit setiap elemen kolom bernilai array ketika melakukan penulisan. Standar: item. |
tulis |
nullValue |
Mengatur representasi string dari nilai null. Default: string null. Ketika ini adalah null, pengurai tidak menulis atribut dan elemen untuk bidang. |
baca, tulis |
compression |
Kode pemadatan yang akan digunakan saat menyimpan ke file. Ini bisa menjadi salah satu nama pendek yang tidak peka terhadap penggunaan huruf besar atau kecil yang sudah dikenal (none, bzip2, gzip, lz4, snappy, dandeflate). Fungsi bawaan XML mengabaikan opsi ini. Standar: none. |
tulis |
validateName |
Jika bernilai true, menghasilkan kesalahan pada kegagalan validasi nama elemen XML. Misalnya, nama bidang SQL dapat memiliki spasi, tetapi nama elemen XML tidak dapat. Bawaantrue. |
tulis |
readerCaseSensitive |
Menentukan perilaku sensitivitas kasus saat rescuedDataColumn diaktifkan. Jika benar, pulihkan kolom data yang namanya berbeda menurut huruf besar/kecil dari skema; jika tidak, baca data tanpa memerhatikan huruf besar/kecil. Standar: true. |
baca |
rescuedDataColumn |
Apakah akan mengumpulkan semua data yang tidak dapat diurai karena ketidakcocokan jenis data dan ketidakcocokan skema (termasuk casing kolom) ke kolom terpisah. Kolom ini disertakan secara default saat menggunakan Auto Loader. Untuk detail selengkapnya, lihat Apa itu kolom data yang diselamatkan?.COPY INTO (warisan) tidak mendukung kolom data yang diselamatkan karena Anda tidak dapat mengatur skema secara manual menggunakan COPY INTO. Databricks merekomendasikan penggunaan Auto Loader untuk sebagian besar skenario penyerapan.Default: Tidak ada secara default. |
baca |
singleVariantColumn |
Menentukan nama untuk kolom dengan satu varian. Jika opsi ini ditentukan untuk dibaca, uraikan seluruh catatan XML ke dalam satu kolom Varian dengan nilai string opsi yang diberikan sebagai nama kolom. Jika opsi ini disediakan untuk menulis, tulis nilai kolom Varian tunggal ke file XML. Standar: none. |
baca, tulis |
Opsi PARQUET
| Opsi |
|---|
datetimeRebaseModeJenis: StringMengontrol pembaruan nilai TANGGAL dan cap waktu antara kalender Julian dan Gregorian Proleptik. Nilai yang diizinkan: EXCEPTION, LEGACY, danCORRECTED.Nilai default: LEGACY |
int96RebaseModeJenis: StringMengontrol pengaturan ulang nilai stempel waktu INT96 antara kalender Julian dan Proleptik Gregorian. Nilai yang diizinkan: EXCEPTION, LEGACY, danCORRECTED.Nilai default: LEGACY |
mergeSchemaJenis: BooleanApakah akan memperkirakan skema di beberapa file serta menggabungkan skema setiap file. Nilai default: false |
readerCaseSensitiveJenis: BooleanMenentukan perilaku sensitivitas huruf besar/kecil saat rescuedDataColumn diaktifkan. Jika benar, pulihkan kolom data yang namanya berbeda menurut huruf besar/kecil dari skema; jika tidak, baca data tanpa memerhatikan huruf besar/kecil.Nilai default: true |
rescuedDataColumnJenis: StringApakah perlu mengumpulkan semua data yang tidak dapat diurai karena ketidakcocokan tipe data dan ketidakcocokan skema (termasuk pengejaan kolom) ke dalam kolom terpisah. Kolom ini disertakan secara default saat menggunakan Auto Loader. Untuk detail selengkapnya, lihat Apa itu kolom data yang diselamatkan?. COPY INTO (warisan) tidak mendukung kolom data yang diselamatkan karena Anda tidak dapat mengatur skema secara manual menggunakan COPY INTO. Databricks merekomendasikan penggunaan Auto Loader untuk sebagian besar skenario penyerapan.Nilai default: Tidak ada |
Opsi AVRO
| Opsi |
|---|
avroSchemaJenis: StringSkema opsional yang disediakan oleh pengguna dalam format Avro. Saat membaca Avro, opsi ini dapat diatur ke skema yang berevolusi, yang kompatibel tetapi berbeda dengan skema Avro yang sebenarnya. Skema deserialisasi akan konsisten dengan skema yang dikembangkan. Misalnya, jika Anda mengatur skema yang berevolusi yang berisi satu kolom tambahan dengan nilai default, hasil baca juga akan berisi kolom baru. Nilai default: Tidak ada |
datetimeRebaseModeJenis: StringMengontrol pembaruan nilai TANGGAL dan cap waktu antara kalender Julian dan Gregorian Proleptik. Nilai yang diizinkan: EXCEPTION, LEGACY, danCORRECTED.Nilai default: LEGACY |
mergeSchemaJenis: BooleanApakah akan memperkirakan skema di beberapa file serta menggabungkan skema setiap file. mergeSchema untuk Avro tidak melonggarkan jenis data.Nilai default: false |
readerCaseSensitiveJenis: BooleanMenentukan perilaku sensitivitas huruf besar/kecil saat rescuedDataColumn diaktifkan. Jika benar, pulihkan kolom data yang namanya berbeda menurut huruf besar/kecil dari skema; jika tidak, baca data tanpa memerhatikan huruf besar/kecil.Nilai default: true |
rescuedDataColumnJenis: StringApakah perlu mengumpulkan semua data yang tidak dapat diurai karena ketidakcocokan tipe data dan ketidakcocokan skema (termasuk pengejaan kolom) ke dalam kolom terpisah. Kolom ini disertakan secara default saat menggunakan Auto Loader. COPY INTO (warisan) tidak mendukung kolom data yang diselamatkan karena Anda tidak dapat mengatur skema secara manual menggunakan COPY INTO. Databricks merekomendasikan penggunaan Auto Loader untuk sebagian besar skenario penyerapan.Untuk detail selengkapnya, lihat Apa itu kolom data yang diselamatkan?. Nilai default: Tidak ada |
Opsi BINARYFILE
File biner tidak memiliki opsi konfigurasi tambahan.
Opsi TEXT
| Opsi |
|---|
encodingJenis: StringNama pengodean pemisah baris dalam file TEKS. Untuk daftar opsi, lihat java.nio.charset.Charset.Konten file tidak terpengaruh oleh opsi ini dan dibaca as-is. Nilai default: UTF-8 |
lineSepJenis: StringString antara dua catatan TEXT berurutan. Nilai default: Tidak ada, yang mencakup \r, \r\n, dan \n |
wholeTextJenis: BooleanApakah akan membaca file sebagai satu catatan. Nilai default: false |
Opsi ORC
| Opsi |
|---|
mergeSchemaJenis: BooleanApakah akan memperkirakan skema di beberapa file serta menggabungkan skema setiap file. Nilai default: false |
Opsi streaming
Opsi ini berlaku saat menggunakan read_files di dalam tabel streaming atau kueri streaming.
| Opsi |
|---|
allowOverwritesJenis: BooleanApakah akan memproses ulang file yang telah dimodifikasi setelah penemuan. Versi terbaru file yang tersedia akan diproses selama refresh jika telah dimodifikasi sejak waktu mulai kueri refresh terakhir yang berhasil. Nilai default: false |
includeExistingFilesJenis: BooleanApakah akan menyertakan file yang ada di jalur input pemrosesan aliran atau hanya memproses file baru yang tiba setelah pengaturan awal. Opsi ini dievaluasi hanya saat Anda memulai siaran untuk pertama kalinya. Mengubah opsi ini setelah memulai ulang aliran tidak berpengaruh. Nilai default: true |
maxBytesPerTriggerJenis: Byte StringJumlah maksimum byte baru yang akan diproses di setiap pemicu. Anda dapat menentukan string byte seperti 10g untuk membatasi setiap microbatch hingga 10 GB data. Ini adalah nilai maksimum yang bersifat fleksibel. Jika Anda memiliki file yang masing-masing 3 GB, Azure Databricks memproses 12 GB dalam mikrobatch. Ketika digunakan bersama dengan maxFilesPerTrigger, Azure Databricks mengonsumsi hingga batas bawah maxFilesPerTrigger atau maxBytesPerTrigger, mana yang tercapai terlebih dahulu.Catatan: Untuk tabel streaming yang dibuat pada gudang SQL tanpa server, opsi ini dan maxFilesPerTrigger tidak boleh diatur untuk memanfaatkan kontrol penerimaan dinamis, yang diskalakan berdasarkan ukuran beban kerja dan sumber daya komputasi tanpa server untuk memberi Anda latensi dan performa terbaik.Nilai default: Tidak ada |
maxFilesPerTriggerJenis: IntegerJumlah maksimum file baru yang akan diproses di setiap pemicu. Ketika digunakan bersama dengan maxBytesPerTrigger, Azure Databricks mengonsumsi hingga batas bawah maxFilesPerTrigger atau maxBytesPerTrigger, mana yang tercapai terlebih dahulu.Catatan: Untuk tabel streaming yang dibuat pada gudang SQL tanpa server, opsi ini dan maxBytesPerTrigger tidak boleh diatur untuk memanfaatkan kontrol penerimaan dinamis, yang diskalakan berdasarkan ukuran beban kerja dan sumber daya komputasi tanpa server untuk memberi Anda latensi dan performa terbaik.Nilai default: 1000 |
schemaEvolutionModeJenis: StringMode untuk memperbarui skema ketika kolom baru ditemukan dalam data. Secara default, kolom disimpulkan sebagai string saat menyimpulkan himpunan data JSON. Lihat evolusi skema untuk detail selengkapnya. Opsi ini tidak berlaku untuk text file dan binaryFile .Nilai default: "addNewColumns" saat skema tidak disediakan."none" jika tidak. |
schemaLocationJenis: StringLokasi untuk menyimpan skema yang disimpulkan dan perubahan selanjutnya. Lihat inferensi skema untuk detail selengkapnya. Lokasi skema tidak diperlukan saat digunakan dalam kueri tabel streaming. Nilai default: Tidak ada |
Contoh
-- Reads the files available in the given path. Auto-detects the format and schema of the data.
> SELECT * FROM read_files('abfss://container@storageAccount.dfs.core.windows.net/base/path');
-- Reads the headerless CSV files in the given path with the provided schema.
> SELECT * FROM read_files(
's3://bucket/path',
format => 'csv',
schema => 'id int, ts timestamp, event string');
-- Infers the schema of CSV files with headers. Because the schema is not provided,
-- the CSV files are assumed to have headers.
> SELECT * FROM read_files(
's3://bucket/path',
format => 'csv')
-- Reads files that have a csv suffix.
> SELECT * FROM read_files('s3://bucket/path/*.csv')
-- Reads a single JSON file
> SELECT * FROM read_files(
'abfss://container@storageAccount.dfs.core.windows.net/path/single.json')
-- Reads JSON files and overrides the data type of the column `id` to integer.
> SELECT * FROM read_files(
's3://bucket/path',
format => 'json',
schemaHints => 'id int')
-- Reads files that have been uploaded or modified yesterday.
> SELECT * FROM read_files(
'gs://my-bucket/avroData',
modifiedAfter => date_sub(current_date(), 1),
modifiedBefore => current_date())
-- Creates a Delta table and stores the source file path as part of the data
> CREATE TABLE my_avro_data
AS SELECT *, _metadata.file_path
FROM read_files('gs://my-bucket/avroData')
-- Creates a streaming table that processes files that appear only after the table's creation.
-- The table will most likely be empty (if there's no clock skew) after being first created,
-- and future refreshes will bring new data in.
> CREATE OR REFRESH STREAMING TABLE avro_data
AS SELECT * FROM STREAM read_files('gs://my-bucket/avroData', includeExistingFiles => false);
Bekerja dengan file yang tidak terstruktur
Contoh berikut menggunakan BINARYFILE format untuk membaca dan memfilter file yang tidak terstruktur yang disimpan dalam volume Katalog Unity, dan menggabungkan read_files dengan fungsi AI untuk memproses konten file.
Mencantumkan semua file dalam volume: Gunakan * EXCEPT (content) untuk mengembalikan metadata file tanpa memuat konten biner, dan pilih _metadata secara eksplisit untuk menyertakan bidang metadata tingkat file.
SELECT
* EXCEPT (content),
_metadata
FROM read_files(
'/Volumes/<catalog>/<schema>/<volume>',
format => 'binaryFile'
);
Mencantumkan file gambar yang difilter menurut ukuran: Gunakan fileNamePattern untuk menargetkan jenis file gambar tertentu dan memfilter _metadata.file_size untuk mengembalikan hanya file dalam rentang ukuran tertentu.
SELECT
* EXCEPT (content),
_metadata
FROM read_files(
'/Volumes/my_catalog/my_schema/my_volume',
format => 'binaryFile',
fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size BETWEEN 20000 AND 1000000;
Mencantumkan file PDF yang dimodifikasi dalam sehari terakhir: Gunakan fileNamePattern untuk menargetkan file PDF dan memfilter modificationTime untuk mengembalikan hanya file yang diubah dalam sehari terakhir.
SELECT
* EXCEPT (content),
_metadata
FROM read_files(
'/Volumes/my_catalog/my_schema/my_volume',
format => 'binaryFile',
fileNamePattern => '*.{pdf,PDF}'
)
WHERE modificationTime >= current_timestamp() - INTERVAL 1 DAY;
Jalankan fungsi AI pada file gambar: Gunakan ai_query untuk memproses file gambar yang dibaca dari jalur penyimpanan cloud. Filter pada _metadata bidang untuk menargetkan file tertentu.
SELECT
path AS file_path,
ai_query(
'databricks-llama-4-maverick',
'Describe this image in ten words or less: ',
files => content
) AS result
FROM read_files(
's3://my-s3-bucket/path/to/images/',
format => 'binaryFile',
fileNamePattern => '*.{jpg,jpeg,png,JPG,JPEG,PNG}'
)
WHERE _metadata.file_size < 1000000
AND _metadata.file_name LIKE '%robots%';
Mengurai dokumen yang cocok dengan pola nama file: Gunakan ai_parse_document untuk mengekstrak konten terstruktur dari PDF dan gambar. Filter menurut _metadata.file_name untuk menargetkan file tertentu.
SELECT
path AS file_path,
ai_parse_document(
content,
map('version', '2.0')
) AS result
FROM read_files(
'/Volumes/main/public/my_files/',
format => 'binaryFile',
fileNamePattern => '*.{jpg,jpeg,pdf,png}'
)
WHERE _metadata.file_name ILIKE '%receipt%';
Menggabungkan file dengan tabel terstruktur: Alur kerja yang tidak terstruktur sering memerlukan penggabungan data terstruktur yang disimpan dalam tabel dengan file yang tidak terstruktur. Contoh berikut menggabungkan file di jalur penyimpanan cloud dengan dua tabel terstruktur, pemfilteran menurut ukuran file dan atribut pengguna. Gabungan dengan dilakukan dengan user_files mengekstrak ID file dari jalur file menggunakan split dan element_at.
SELECT
users.user_id,
user_files.file_id,
files._metadata.file_name AS file_name,
files.* EXCEPT (content),
ai_parse_document(files.content, map('version', '2.0')) AS parsed_document
FROM read_files(
's3://my-bucket-name/files/',
format => 'binaryFile',
fileNamePattern => '*.{pdf,doc,docx,ppt,pptx,png,jpg,jpeg}'
) AS files
JOIN user_files
ON user_files.file_id = element_at(split(files.path, '/'), -2)
JOIN users
ON users.user_id = user_files.user_id
WHERE users.email LIKE '%@databricks.com'
AND files._metadata.file_size < 10000000;