tablo değerli fonksiyon `read_files`

Şunlar için geçerlidir: onay işareti evet olarak işaretlenmiş Databricks SQL Databricks Runtime 13.3 LTS ve üzeri

Sağlanan bir konum altındaki dosyaları okur ve verileri tablo biçiminde döndürür.

JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO ve ORC dosya biçimlerini okumayı destekler. Dosya biçimini otomatik olarak algılayabilir ve tüm dosyalar arasında birleşik bir şema çıkarsayabilirsiniz.

Söz dizimi

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

Argümanlar

Bu işlev, seçenek anahtarları için adlandırılmış parametre çağırması gerektirir.

path: Verilerin konumunun URI'sine sahip A STRING . Azure Data Lake Storage ('abfss://'), S3 (s3://) ve Google Cloud Storage 'dan ('gs://') okumayı destekler. Glob içerebilir. Diğer ayrıntılar için bkz . Dosya bulma .
option_key: Yapılandırılan seçeneğin adı. Backticks () for options that contain dots (.`) kullanmanız gerekir.
option_value: Seçeneğin ayarlanacağı sabit ifade . Sabitleri ve skaler işlevleri kabul eder.

İadeler

Verilen pathaltında okunan dosyalardan verileri içeren bir tablo. Şema, dosya biçimine bağlıdır:

BINARYFILE: Sabit bir şema döndürür:

Köşe yazısı	Türü	Açıklama
`path`	`STRING`	Dosyanın bulunduğu tam yol.
`modificationTime`	`TIMESTAMP`	Dosyanın son değişiklik zamanı.
`length`	`LONG`	Dosyanın bayt cinsinden boyutu.
`content`	`BINARY`	Dosyanın ikili içeriği. Dosya meta verilerini sorgularken ikili içeriği dışlamak için kullanın `* EXCEPT (content)` .

TEXT: Tek valueSTRING() sütunlu sabit bir şema döndürür.
Diğer tüm biçimler (JSON, CSV, XML, PARQUET, AVRO, ORC): Şema dosya içeriğinden çıkarılır veya açıkça seçeneği kullanılarak schema sağlanır.

`_metadata` Sütun

read_files dosya düzeyinde meta verileri olan bir _metadata sütunu kullanıma sunar. Bu sütun sonuçlara SELECT * dahil değildir ve açıkça seçilmelidir. Aşağıdaki alanları içerir:

Alan	Türü	Açıklama
`file_path`	`STRING`	Kaynak dosyanın tam yolu.
`file_name`	`STRING`	Kaynak dosyanın adı.
`file_size`	`LONG`	Kaynak dosyanın bayt cinsinden boyutu.
`file_modification_time`	`TIMESTAMP`	Kaynak dosyanın son değişiklik zamanı.
`file_block_start`	`LONG`	Okunan dosya bloğunun başlangıcı.
`file_block_length`	`LONG`	Okunan dosya bloğunun uzunluğu.

Sonuçlara eklemek _metadata için açıkça seçin:

SELECT * EXCEPT (content), _metadata
FROM read_files('/Volumes/my_catalog/my_schema/my_volume', format => 'binaryFile');

Dosya bulma

read_files tek bir dosyayı okuyabilir veya sağlanan bir dizin altındaki dosyaları okuyabilir. read_files sağlanan dizin altındaki tüm dosyaları özyinelemeli olarak bulur, ancak eğer bir glob sağlanırsa, read_files belirli bir dizin desenine özyineleme talimatı alır.

Glob desenlerini kullanarak dizinleri veya dosyaları filtreleme

Glob desenleri, yolda yer aldığında dizinleri ve dosyaları filtrelemek için kullanılabilir.

Desen	Açıklama
`?`	Herhangi bir tek karakterle eşleşir
`*`	Sıfır veya daha çok sayıda karakterle eşleşir
`[abc]`	{a,b,c} karakter kümesindeki tek bir karakterle eşleşir.
`[a-z]`	{a…z} aralığındaki tek bir karakterle eşleşir.
`[^a]`	{a} karakter kümesinden veya aralıktan olmayan tek bir karakterle eşleşir. Karakter `^` açılış ayraçının hemen sağında yer almalıdır, unutmayın.
`{ab,cd}`	{ab, cd} dize kümesindeki bir dizeyle eşleşir.
`{ab,c{de, fh}}`	{ab, cde, cfh} dize kümesindeki bir dizeyle eşleşir.

read_files glob içeren dosyaları keşfederken Otomatik Yükleyici'nin sıkı globber'ını kullanır. Bu, useStrictGlobber seçeneğiyle yapılandırılır. Katı globber devre dışı bırakıldığında, sondaki eğik çizgiler (/) görmezden gelinir ve /*/ gibi bir yıldız deseni birçok dizini keşfetmek için genişleyebilir. Davranış farkını görmek için aşağıdaki örneklere bakın.

Desen	Dosya yolu	Katı globber devre dışı	Sıkı globber modu etkinleştirildi
`/a/b`	`/a/b/c/file.txt`	Evet	Evet
`/a/b`	`/a/b_dir/c/file.txt`	Hayır	Hayır
`/a/b`	`/a/b.txt`	Hayır	Hayır
`/a/b/`	`/a/b.txt`	Hayır	Hayır
`/a/*/c/`	`/a/b/c/file.txt`	Evet	Evet
`/a/*/c/`	`/a/b/c/d/file.txt`	Evet	Evet
`/a/*/d/`	`/a/b/c/d/file.txt`	Evet	Hayır
`/a/*/c/`	`/a/b/x/y/c/file.txt`	Evet	Hayır
`/a/*/c`	`/a/b/c_file.txt`	Evet	Hayır
`/a/*/c/`	`/a/b/c_file.txt`	Evet	Hayır
`/a/*/c`	`/a/b/cookie/file.txt`	Evet	Hayır
`/a/b*`	`/a/b.txt`	Evet	Evet
`/a/b*`	`/a/b/file.txt`	Evet	Evet
`/a/{0.txt,1.txt}`	`/a/0.txt`	Evet	Evet
`/a/*/{0.txt,1.txt}`	`/a/0.txt`	Hayır	Hayır
`/a/b/[cde-h]/i/`	`/a/b/c/i/file.txt`	Evet	Evet

Şema çıkarımı

Dosyaların şeması, read_files'a schema seçeneği ile açıkça sağlanabilir. Şema sağlanmadığında, read_files bulunan dosyalar arasında birleşik bir şema çıkarsamaya çalışır ve bu da bir LIMIT deyimi kullanılmadığı sürece tüm dosyaların okunmasını gerektirir. LIMIT sorgusu kullanırken bile verilerin daha temsili bir şemasını döndürmek için gerekenden daha büyük bir dosya kümesi okunabilir. Databricks, bir kullanıcı sağlamıyorsa not defterleri ve SQL düzenleyicisindeki LIMIT sorguları için otomatik olarak bir SELECT deyim ekler.

schemaHints seçeneği, çıkarsanan şemanın alt kümelerini düzeltmek için kullanılabilir. Daha fazla ayrıntı için bkz. Şema çıkarımlarını şema ipuçlarıyla geçersiz kılma.

rescuedDataColumn varsayılan olarak, şemayla eşleşmeyen verileri kurtarmak amacıyla sağlanır. Bkz. Kurtarılan veri sütunu nedir? Daha fazla bilgi için. rescuedDataColumn seçeneğini ayarlayarak schemaEvolutionMode => 'none' öğesini bırakabilirsiniz.

Bölüm şeması çıkarımı

read_files dosyalar Hive stili bölümlenmiş dizinler altında veya depolanıyorsa, /column_name=column_value/ de çıkarabilir. Eğer bir schema sağlanırsa, tespit edilen bölüm sütunları schemaiçinde sağlanan türleri kullanır. Eğer bölümleme sütunları sağlanan schema'a dahil değilse, çıkarılan bölümleme sütunları göz ardı edilir.

Hem bölüm şemasında hem de veri sütunlarında bir sütun varsa, veri değeri yerine bölüm değerinden okunan değer kullanılır. Dizinden gelen değerleri yoksaymak ve veri sütununu kullanmak istiyorsanız, partitionColumns seçeneğiyle virgülle ayrılmış bir listedeki bölüm sütunlarının listesini sağlayabilirsiniz.

partitionColumns seçeneği, read_files'e hangi bulunan sütunların son çıkarılan şemaya dahil edileceğini belirtmek için de kullanılabilir. Boş bir dize sağlanması, tüm bölüm sütunlarını göz ardı eder.

schemaHints seçeneği, bir bölüm sütunu için belirlenen şemayı geçersiz kılmak amacıyla da sağlanabilir.

TEXT ve BINARYFILE biçimleri sabit bir şemaya sahiptir, ancak read_files mümkün olduğunda bu biçimler için bölümleme çıkarımını da dener.

Bulut depolama için kimlik doğrulaması

read_files Unity Kataloğu dış konumlarından veya Unity Kataloğu birimlerinden (hem yönetilen hem de dış) dosyaları okur. Dış konumda READ VOLUME veya okumak istediğiniz dosyaları içeren birimde ayrıcalığınız olmalıdırREAD FILES. Bkz. Unity Kataloğu'nu kullanarak bulut nesne depolamasına bağlanma veya Unity Kataloğu birimleri nedir?.

Akış tablolarında kullanım

read_files, dosyaları Delta Lake'e almak için akış tablolarında kullanılabilir. read_files akış tablosu sorgusunda kullanıldığında Otomatik Yükleyici'yi kullanır. anahtar sözcüğünü STREAM ile read_fileskullanmanız gerekir. Diğer ayrıntılar için bkz. Otomatik Yükleyici nedir?

Bir akış sorgusunda kullanıldığında, read_files şemayı çıkarsamak için verilerin bir örneğini kullanır ve daha fazla veri işledikçe şemayı geliştirebilir. Daha fazla bilgi için Otomatik Yükleyici'de şema çıkarımı ve evrimini yapılandırma hakkında 'a bakın.

Temel Seçenekler

Seçenek
`format` Tür: `String` Kaynak yoldaki veri dosyası biçimi. Sağlanmazsa otomatik olarak çıkarım yapılır. İzin verilen değerler şunlardır: `avro`: Avro dosyası `binaryFile`: İkili dosya `csv`: CSV dosyalarını okuma `json`: JSON dosyaları `orc`: ORC dosyalarıyla çalışma : Azure DatabricksRead Parquet dosyaları> `text`: Metin dosyaları `xml`: XML dosyalarını okuma ve yazma Varsayılan değer: Yok
`schema` Tür: `String` Okunacak dosyaların şeması. DDL biçimini kullanarak bir şema dizesi sağlayın, örneğin `'id int, ts timestamp, event string'`. Şema sağlanmadığında, `read_files` bulunan dosyalar arasında birleşik bir şema çıkarılmaya çalışılır. Varsayılan değer: Yok
`inferColumnTypes` Tür: `Boolean` Şema çıkarımı kullanıldığında tam sütun türlerinin çıkarılıp çıkarılmayacağı. Varsayılan olarak, JSON ve CSV veri kümeleri çıkarılırken sütunlar çıkarımlanır. Daha fazla bilgi için bkz. şema çıkarımı . Bunun Otomatik Yükleyici varsayılanının tersi olduğunu unutmayın. Varsayılan değer: `true`
`partitionColumns` Tür: `String` Dosya dizin yapısından çıkarımını yapmak istediğiniz Hive tarzı bölüm sütunlarının, virgülle ayrılmış bir listesini belirtiniz. Hive stili bölüm sütunları, anahtar-değer çiftlerinin eşitlik işaretiyle birleştirilmesi şeklindedir. `<base-path>/a=x/b=1/c=y/file.format`. Bu örnekte bölüm sütunları `a`, `b`ve `c`. Varsayılan olarak, şema çıkarımı kullanıyorsanız ve veri yüklemek için `<base-path>` sağlıyorsanız bu sütunlar şemanıza otomatik olarak eklenir. Bir şema sağlarsanız, Otomatik Yükleyici bu sütunların şemaya eklenmesini bekler. Bu sütunları şemanızın bir parçası olarak istemiyorsanız, bu sütunları yoksaymak için `""` belirtebilirsiniz. Ayrıca, aşağıdaki örnekte olduğu gibi sütunların karmaşık dizin yapılarında dosya yolunun çıkarılmasını istediğinizde bu seçeneği kullanabilirsiniz: `<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` `cloudFiles.partitionColumns` olarak belirtilmesi `year,month,day` döndürülecek `year=2022`için `file1.csv`, ama `month` ve `day` sütunları `null`olacak. `month` ve `dayfile2.csv` ve `file3.csv` için doğru şekilde ayrıştırılır. Varsayılan değer: Yok
`schemaHints` Tür: `String` Şema çıkarımı sırasında Otomatik Yükleyici'ye sağladığınız şema bilgileri. Daha fazla ayrıntı için bkz. şema ipuçları . Varsayılan değer: Yok
`useStrictGlobber` Tür: `Boolean` Apache Spark'taki diğer dosya kaynaklarının varsayılan globbing davranışıyla eşleşen katı bir globber kullanıp kullanmayacağınız. Diğer ayrıntılar için bkz . Yaygın veri yükleme desenleri . Databricks Runtime 12.2 LTS ve üzerinde kullanılabilir. Bunun Otomatik Yükleyici için varsayılanın tersi olduğunu unutmayın. Varsayılan değer: `true`

Biçime özgü seçenekler

Her dosya biçimine (JSON, CSV, XML, Parquet, Avro, metin, ORC ve ikili) özgü seçenekler için bkz. DataFrameReader seçenekleri.

Akış seçenekleri

Bu seçenekler, read_files veya akış sorgusu içinde kullanırken geçerlidir.

Seçenek
`allowOverwrites` Tür: `Boolean` Bulma işleminden sonra değiştirilmiş dosyaların yeniden işlenip işlenmeyeceği. Dosyanın kullanılabilir en son sürümü, son başarılı yenileme sorgusu başlangıç zamanından bu yana değiştirilmişse yenileme sırasında işlenir. Varsayılan değer: `false`
`includeExistingFiles` Tür: `Boolean` Mevcut dosyaların akış işleme giriş yoluna dahil edilip edilmeyeceği veya yalnızca ilk kurulumdan sonra gelen yeni dosyaların işlenmesi. Bu seçenek yalnızca bir akışı ilk kez başlattığınızda değerlendirilir. Akışı yeniden başlattıktan sonra bu seçeneğin değiştirilmesinin hiçbir etkisi olmaz. Varsayılan değer: `true`
`maxBytesPerTrigger` Tür: `Byte String` Her tetikleyicide işlenecek yeni bayt sayısı üst sınırı. Her mikrobatch değerini 10 GB veriyle sınırlamak için `10g` gibi bir bayt dizesi belirtebilirsiniz. Bu geçici bir maksimum değerdir. Her birinde 3 GB olan dosyalarınız varsa, Azure Databricks bir mikrobatch içinde 12 GB işler. `maxFilesPerTrigger` ile birlikte kullanıldığında, Azure Databricks `maxFilesPerTrigger` veya `maxBytesPerTrigger` alt sınırına kadar (hangisi önce ulaşılırsa) tüketir. Not: Sunucusuz SQL ambarlarında oluşturulan akış tabloları için bu seçenek ve `maxFilesPerTrigger`, size en iyi gecikme süresini ve performansı sağlamak için iş yükü boyutuna ve sunucusuz işlem kaynaklarına göre ölçeklendirilen dinamik erişim denetiminden yararlanacak şekilde ayarlanmamalıdır. Varsayılan değer: Yok
`maxFilesPerTrigger` Tür: `Integer` Her tetikleyicide işlenecek en fazla yeni dosya sayısı. `maxBytesPerTrigger` ile birlikte kullanıldığında, Azure Databricks `maxFilesPerTrigger` veya `maxBytesPerTrigger` alt sınırına kadar (hangisi önce ulaşılırsa) tüketir. Not: Sunucusuz SQL ambarlarında oluşturulan akış tabloları için bu seçenek ve `maxBytesPerTrigger`, size en iyi gecikme süresini ve performansı sağlamak için iş yükü boyutuna ve sunucusuz işlem kaynaklarına göre ölçeklendirilen dinamik erişim denetiminden yararlanacak şekilde ayarlanmamalıdır. Varsayılan değer: 1000
`schemaEvolutionMode` Tür: `String` Verilerde yeni sütunlar keşfedildikçe şemayı geliştirme modu. Varsayılan olarak, JSON veri kümeleri çıkarılırken sütunlar dize olarak çıkarılır. Daha fazla bilgi için bkz. şema evrimi . Bu seçenek `text` ve `binaryFile` dosyaları için geçerli değildir. Varsayılan değer: Şema sağlanmadığında `"addNewColumns"`. `"none"` yoksa.
`schemaLocation` Tür: `String` Çıkarsanan şemayı ve sonraki değişiklikleri depolama konumu. Daha fazla bilgi için bkz. şema çıkarımı . Akış tablosu sorgusunda kullanıldığında şema konumu gerekli değildir. Varsayılan değer: Yok

Örnekler

-- 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);

Yapılandırılmamış dosyalarla çalışma

Aşağıdaki örneklerde, Unity Kataloğu birimlerinde depolanan yapılandırılmamış dosyaları okumak ve filtrelemek ve dosya içeriğini işlemek için yapay zeka işlevleriyle birleştirmek BINARYFILE için biçim kullanılırread_files.

Bir birimdeki tüm dosyaları listeleme: İkili içerik yüklemeden dosya meta verilerini döndürmek için kullanın * EXCEPT (content) ve dosya düzeyinde meta veri alanlarını dahil etmek için açıkça seçin _metadata .

SELECT
  * EXCEPT (content),
  _metadata
FROM read_files(
  '/Volumes/<catalog>/<schema>/<volume>',
  format => 'binaryFile'
);

Boyuta göre filtrelenmiş görüntü dosyalarını listele: Belirli görüntü dosya türlerini hedeflemek için kullanın fileNamePattern ve yalnızca belirli bir boyut aralığındaki dosyaları döndürmek için filtreleyin _metadata.file_size .

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;

Geçen gün içinde değiştirilen PDF dosyalarını listele: PDF dosyalarını hedeflemek için kullanın fileNamePattern ve yalnızca geçen gün içinde değiştirilen dosyaları döndürecek şekilde filtreleyin modificationTime .

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;

Görüntü dosyalarında yapay zeka işlevi çalıştırma: Bulut depolama yolundan okunan görüntü dosyalarını işlemek için kullanın ai_query . _metadata Belirli dosyaları hedeflemek için alanları filtreleyin.

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%';

Dosya adı deseni ile eşleşen belgeleri ayrıştırma: PDF'lerden ve görüntülerden yapılandırılmış içeriği ayıklamak için kullanın ai_parse_document . Belirli dosyaları hedeflemek için filtre ölçütü _metadata.file_name .

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%';

Yapılandırılmış tabloyla dosyaları birleştirme: Yapılandırılmamış iş akışları genellikle yapılandırılmamış dosyalarla tablolarda depolanan yapılandırılmış verilerin birleştirilmesini gerektirir. Aşağıdaki örnek, dosyaları dosya boyutuna ve kullanıcı özniteliğine göre filtreleyerek iki yapılandırılmış tablo içeren bir bulut depolama yolunda birleştirir. ile user_files birleştirme işlemi, ve splitkullanılarak element_at dosya yolundan dosya kimliği ayıklanarak yapılır.

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;

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-06-01