read_files fungsi bernilai tabel

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.

Catatan

Tersedia di Beta, diatur format => 'file' untuk mengembalikan FILE referensi untuk setiap file daripada membaca isi file. Lihat FILE tipe dan Ingest file sebagai tipe FILE.

Sintaks

read_files(path [, option_key => option_value ] [...])

Argumen

Fungsi ini memerlukan pemanggilan parameter bernama untuk kunci pilihan.

• path: A STRING dengan 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
  path	STRING	Jalur lengkap ke file.
  modificationTime	TIMESTAMP	Waktu modifikasi terakhir file.
  length	LONG	Ukuran file dalam satuan byte.
  content	BINARY	Konten biner file. Gunakan * EXCEPT (content) untuk mengecualikan konten biner saat mengkueri metadata file.

• TEXT: Mengembalikan skema tetap dengan satu value kolom (STRING).

• Semua format lainnya (JSON, CSV, XML, PARQUET, AVRO, ORC): Skema disimpulkan dari konten file, atau disediakan secara eksplisit menggunakan schema opsi .

_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 membaca file dari lokasi eksternal Katalog Unity atau volume Katalog Unity (baik terkelola maupun eksternal). Anda harus memiliki READ FILES hak istimewa pada lokasi eksternal atau READ VOLUME hak istimewa pada volume yang berisi file yang ingin Anda baca. Lihat Menyambungkan ke penyimpanan objek cloud menggunakan Katalog Unity atau Apa itu volume 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 khusus format
• Opsi streaming

Opsi dasar

Opsi	Tipe	Deskripsi	Nilai standar
format	String	Format file data di jalur sumber. Auto-inferenced jika dihilangkan. Nilai yang diizinkan meliputi avro, , , binaryFile( csv Beta), file, json, , orcparquet, , dan text. xml	Tidak
schema	String	Skema file yang akan dibaca. Tentukan string skema menggunakan format DDL, misalnya 'id int, ts timestamp, event string'. Jika dihilangkan, read_files berusaha menyimpulkan skema terpadu di antara file yang ditemukan.	Tidak
inferColumnTypes	Boolean	Apakah akan menyimpulkan tipe kolom yang tepat saat memanfaatkan inferensi skema. Secara default, kolom disimpulkan saat menyimpulkan himpunan data JSON dan CSV. Ini adalah kebalikan dari perilaku default Auto Loader. Lihat inferensi skema.	true
partitionColumns	String	Daftar kolom partisi gaya Hive yang dipisahkan dengan koma untuk menyimpulkan dari struktur direktori file. Kolom partisi gaya hive adalah pasangan kunci-nilai yang digabungkan dengan tanda kesetaraan, seperti <base-path>/a=x/b=1/c=y/file.format. Dalam contoh ini, kolom partisi adalah a, b, dan c. Jika Anda menggunakan inferensi skema dan mengirimkan <base-path> data untuk memuat darinya, kolom-kolom ini secara otomatis ditambahkan ke skema Anda. Jika Anda menentukan skema, Auto Loader mengharapkan kolom ini disertakan dalam skema. Jika Anda tidak ingin kolom-kolom ini menjadi bagian dari skema Anda, tentukan "" untuk mengabaikannya. Anda juga dapat menggunakan opsi ini untuk menyimpulkan kolom dari jalur file dalam struktur direktori yang kompleks. Misalnya, untuk file berikut, yang menentukan cloudFiles.partitionColumns sebagai year,month,day pengembalian year=2022 untuk file1.csv, tetapi month kolom dan day adalah null. month dan day dianalisis dengan benar untuk file2.csv dan file3.csv: <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.csv	Tidak
schemaHints	String	Informasi skema yang Anda teruskan ke Auto Loader selama inferensi skema. Lihat hint skema untuk detail selengkapnya.	Tidak
useStrictGlobber	Boolean	Apakah 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. Ini adalah kebalikan dari standar Auto Loader.	true

Opsi khusus format

Untuk opsi khusus untuk setiap format file (JSON, CSV, XML, Parquet, Avro, teks, ORC, dan biner), lihat opsi DataFrameReader.

Opsi streaming

Opsi ini berlaku saat menggunakan read_files di dalam tabel streaming atau kueri streaming.

Opsi	Tipe	Deskripsi	Nilai standar
allowOverwrites	Boolean	Apakah akan memproses ulang file yang berubah setelah penemuan. Saat refresh, read_files memproses ulang file jika telah dimodifikasi setelah refresh terakhir yang berhasil.	false
includeExistingFiles	Boolean	Apakah 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.	true
maxBytesPerTrigger	Byte String	Jumlah maksimum byte baru yang harus diproses di setiap trigger. 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. Untuk tabel streaming yang dibuat di gudang SQL tanpa server, jangan atur opsi ini atau maxFilesPerTrigger, untuk memanfaatkan kontrol masuk dinamis.	Tidak
maxFilesPerTrigger	Integer	Jumlah maksimum file baru yang harus diproses di setiap trigger. Ketika digunakan bersama dengan maxBytesPerTrigger, Azure Databricks mengonsumsi hingga batas bawah maxFilesPerTrigger atau maxBytesPerTrigger, mana yang tercapai terlebih dahulu. Untuk tabel streaming yang dibuat di gudang SQL tanpa server, jangan atur opsi ini atau maxBytesPerTrigger, untuk memanfaatkan kontrol masuk dinamis.	1000
schemaEvolutionMode	String	Mode 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 .	"addNewColumns" tanpa skema, "none" selain itu.
schemaLocation	String	Lokasi untuk menyimpan skema yang disimpulkan dan perubahan selanjutnya. Lihat inferensi skema untuk detail selengkapnya. Lokasi skema tidak diperlukan saat digunakan dalam kueri tabel streaming.	Tidak

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;

Fungsi terkait

• list_files fungsi nilai tabel

Artikel terkait

• CREATE STREAMING TABLE
• read_kafka fungsi nilai tabel