read_files tabulková hodnotová funkce

Platí pro:zaškrtnuto ano Databricks SQL zaškrtnuto ano Databricks Runtime 13.3 LTS a vyšší

Načte soubory v zadaném umístění a vrátí data v tabulkové podobě.

Podporuje čtení JSON, , CSV, XML, TEXT, BINARYFILEPARQUET, AVRO, a ORC formáty souborů. Dokáže automaticky rozpoznat formát souboru a odvodit jednotné schéma napříč všemi soubory.

Note

Dostupný v beta verzi, nastavený format => 'file' tak, aby vracel referenci FILE pro každý soubor místo čtení obsahu souboru. FILE viz jako typ SOUBORU.

Syntaxe

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

Argumenty

Tato funkce vyžaduje vyvolání pojmenovaného parametru pro klíče možností.

  • path: A STRING s URI jako identifikátorem umístění dat. Podporuje čtení z Azure Data Lake Storage ('abfss://'), S3 (s3://) a Google Cloud Storage ('gs://'). Může obsahovat globy. Další podrobnosti najdete v tématu Zjišťování souborů.
  • option_key: Název možnosti konfigurace. Musíte použít zpětné apostrofy () for options that contain dots (.`).
  • option_value: Konstantní výraz, kterým se nastavuje možnost. Přijímá literály a skalární funkce.

Návraty

Tabulka obsahující data ze souborů načtených pod danou pathpoložkou . Schéma závisí na formátu souboru:

  • BINARYFILE: Vrátí pevné schéma:

    Sloupec Typ Popis
    path STRING Úplná cesta k souboru.
    modificationTime TIMESTAMP Čas poslední změny souboru.
    length LONG Velikost souboru v bajtech
    content BINARY Binární obsah souboru. Slouží * EXCEPT (content) k vyloučení binárního obsahu při dotazování metadat souboru.

  • TEXT: Vrátí pevné schéma s jedním value sloupcem (STRING).

  • Všechny ostatní formáty (JSON, CSV, XML, PARQUET, AVRO, ORC): Schéma se odvodí z obsahu souboru nebo explicitně použije tuto schema možnost.

_metadata Sloupec

read_files _metadata zveřejňuje sloupec s metadaty na úrovni souboru. Tento sloupec není součástí SELECT * výsledků a musí být explicitně vybrán. Obsahuje následující pole:

Pole Typ Popis
file_path STRING Úplná cesta ke zdrojovému souboru.
file_name STRING Název zdrojového souboru.
file_size LONG Velikost zdrojového souboru v bajtech
file_modification_time TIMESTAMP Čas poslední změny zdrojového souboru.
file_block_start LONG Začátek bloku souboru, který se čte.
file_block_length LONG Délka bloku souboru, který se čte.

Pokud chcete výsledky zahrnout _metadata , vyberte ho explicitně:

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

Zjišťování souborů

read_files může číst jednotlivé soubory nebo číst soubory v zadaném adresáři. read_files zjistí všechny soubory v zadaném adresáři rekurzivně, pokud není zadaný glob , který dává pokyn read_files , aby se znovu dostal do určitého vzoru adresáře.

Filtrování adresářů nebo souborů pomocí vzorů globu

Vzory globu lze použít pro filtrování adresářů a souborů, pokud jsou v cestě k dispozici.

Vzor Popis
? Odpovídá jakémukoli jednomu znaku.
* Odpovídá nule nebo více znaků
[abc] Odpovídá jednomu znaku ze znakové sady {a,b,c}.
[a-z] Odpovídá jednomu znaku z rozsahu znaků {a... z}.
[^a] Odpovídá jednomu znaku, který není ze znakové sady nebo rozsahu {a}. Všimněte si, že ^ znak musí nastat okamžitě napravo od levé závorky.
{ab,cd} Odpovídá řetězci ze sady řetězců {ab, cd}.
{ab,c{de, fh}} Odpovídá řetězci ze sady řetězců {ab, cde, cfh}.

read_files používá při zjišťování souborů pomocí globů striktní globber nástroje Auto Loader. Toto je nakonfigurováno pomocí možnosti useStrictGlobber. Když je striktní globber zakázaný, koncová lomítka (/) se zahodí a hvězdicový vzor, jako například /*/, se může rozšířit a umožnit nalézt více adresářů. Podívejte se na následující příklady a podívejte se na rozdíl v chování.

Vzor Cesta k souboru Striktní deaktivace globberu Povolen přísný režim globber
/a/b /a/b/c/file.txt Ano Ano
/a/b /a/b_dir/c/file.txt Ne Ne
/a/b /a/b.txt Ne Ne
/a/b/ /a/b.txt Ne Ne
/a/*/c/ /a/b/c/file.txt Ano Ano
/a/*/c/ /a/b/c/d/file.txt Ano Ano
/a/*/d/ /a/b/c/d/file.txt Ano Ne
/a/*/c/ /a/b/x/y/c/file.txt Ano Ne
/a/*/c /a/b/c_file.txt Ano Ne
/a/*/c/ /a/b/c_file.txt Ano Ne
/a/*/c /a/b/cookie/file.txt Ano Ne
/a/b* /a/b.txt Ano Ano
/a/b* /a/b/file.txt Ano Ano
/a/{0.txt,1.txt} /a/0.txt Ano Ano
/a/*/{0.txt,1.txt} /a/0.txt Ne Ne
/a/b/[cde-h]/i/ /a/b/c/i/file.txt Ano Ano

Odvozování schémat

Schéma souborů lze explicitně poskytnout pro read_files s možností schema. Pokud schéma není zadané, read_files se pokusí odvodit jednotné schéma ve zjištěných souborech, které vyžaduje čtení všech souborů, pokud se nepoužije příkaz LIMIT. I když používáte dotaz LIMIT, může se přečíst větší sada souborů, než je potřeba, aby se vrátilo reprezentativnější schéma dat. Databricks automaticky přidá LIMIT příkaz pro SELECT dotazy v poznámkových blocích a editoru SQL, pokud jej uživatel nezadá.

Možnost schemaHints lze použít k opravě podmnožin odvozeného schématu. Další podrobnosti najdete v tématu Přepis odvozování schématu pomocí nápovědy k schématu.

Ve výchozím nastavení je k dispozici funkce A rescuedDataColumn pro záchranu všech dat, která neodpovídají schématu. Podívejte se na Co je zachráněný datový sloupec? pro více podrobností. Možnost rescuedDataColumn můžete vyřadit nastavením volby schemaEvolutionMode => 'none'.

Odvození schématu oddílů

read_files lze také odvodit partiční sloupce, pokud jsou soubory uloženy v adresářích ve stylu Hive, tedy /column_name=column_value/. Pokud je k dispozici schema, zjištěné sloupce oddílů používají typy uvedené v schema. Pokud sloupce oddílů nejsou součástí poskytnutého schema, odvozované sloupce oddílů budou ignorovány.

Pokud sloupec existuje ve schématu oddílu i ve sloupcích dat, použije se hodnota načtená z hodnoty oddílu místo datové hodnoty. Pokud chcete ignorovat hodnoty pocházející z adresáře a použít datový sloupec, můžete zadat seznam sloupců oddílů v seznamu odděleném čárkami s možností partitionColumns.

Možnost partitionColumns lze také použít k instrukci read_files, které zjištěné sloupce mají být zahrnuty do konečného odvozeného schématu. Poskytnutí prázdného řetězce ignoruje všechny partiční sloupce.

Možnost schemaHints lze také poskytnout k přebití odvozeného schématu pro oddílový sloupec.

Formáty TEXT a BINARYFILE mají pevné schéma, ale read_files se také pokusí odvodit dělení těchto formátů, pokud je to možné.

Ověřování pro cloudové úložiště

read_files čte soubory z externích umístění katalogu Unity nebo svazků katalogu Unity (spravovaných i externích). Musíte mít READ FILES oprávnění k externímu umístění nebo READ VOLUME oprávnění na svazku, který obsahuje soubory, které chcete číst. Viz Připojení ke cloudovému úložišti objektů pomocí katalogu Unity nebo Co jsou svazky katalogu Unity?.

Použití v streamovaných tabulkách

read_files lze použít ve streamovaných tabulkách k ingestování souborů do Delta Lake. read_files využívá Auto Loader při použití v dotazu streamovací tabulky. Musíte použít STREAM klíčové slovo s read_files. Další podrobnosti najdete v tématu Co je automatický zavaděč?

Při použití v streamovacím dotazu read_files použije k odvození schématu ukázku dat a může vyvíjet schéma, protože zpracovává více dat. Další podrobnosti najdete v tématu Konfigurace odvozování schématu a vývoje v automatickém zavaděči.

Možnosti

Základní možnosti

Možnost Typ Popis Výchozí hodnota
format String Formát datového souboru ve zdrojové cestě. Automaticky odvozeno, pokud je vynecháno. Povolené hodnoty zahrnují avro, binaryFile, csv, ( file Beta), json, orc, parquet, , texta .xml None
schema String Schéma souborů, které se mají číst. Zadejte schématový řetězec pomocí DDL formátu, například 'id int, ts timestamp, event string'. Pokud je vynecháno, snaží se read_files odvodit jednotné schéma napříč objevenými soubory. None
inferColumnTypes Boolean Určuje, zda se mají při odvozování schématu odvozovat přesné typy sloupců. Ve výchozím nastavení se sloupce odvozují při odvození datových sad JSON a CSV. To je opak výchozího chování Auto Loaderu. Viz schématová inference. true
partitionColumns String Seznam sloupců oddílů ve stylu Hive oddělený čárkami pro odvoz ze struktury adresářů souborů. Sloupce rozdělení ve stylu Hive jsou páry klíč-hodnota spojené znaménkem rovnosti, například <base-path>/a=x/b=1/c=y/file.format. V tomto příkladu jsou sloupce oddílů a, b a c. Pokud použijete inferenci ze schématu a předáte data <base-path> pro načítání, tyto sloupce se automaticky přidají do vašeho schématu. Pokud zadáte schéma, automatický zavaděč očekává, že budou tyto sloupce zahrnuty do schématu. Pokud tyto sloupce nechcete mít součástí schématu, specifikujte "" jejich ignorování. Tuto možnost můžete také použít k odvození sloupců z cesty k souboru v složitých adresářových strukturách. Například pro následující soubory, specifikace cloudFiles.partitionColumns jako year,month,day vrací year=2022 , file1.csvale month sloupce a day jsou .null month a jsou day správně parsovány pro file2.csv a 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		 None
schemaHints String Informace o schématu, které předáte Auto Loaderu během inference schématu. Další podrobnosti najdete v nápovědě schématu . None
useStrictGlobber Boolean Zda použít přísný globber, který odpovídá standardnímu chování globbingu u jiných zdrojů souborů v Apache Spark. Další podrobnosti najdete v tématu Běžné vzorce načítání dat. K dispozici ve službě Databricks Runtime 12.2 LTS a vyšších verzích. To je opak výchozího nastavení pro Auto Loader. true

Možnosti specifické pro formát

Možnosti specifické pro každý formát souboru (JSON, CSV, XML, Parquet, Avro, text, ORC a binární soubor) najdete v tématu Možnosti DataFrameReader.

Možnosti streamování

Tyto možnosti platí při použití read_files uvnitř streamovací tabulky nebo streamovacího dotazu.

Možnost Typ Popis Výchozí hodnota
allowOverwrites Boolean Zda znovu zpracovat soubory, které se po zjištění zpracují. Při obnově read_files se soubor znovu zpracuje, pokud byl po posledním úspěšném obnovení upraven. false
includeExistingFiles Boolean Zda zahrnout existující soubory do vstupní cesty zpracování datového proudu nebo zpracovat pouze nové soubory přicházející po počátečním nastavení. Tato možnost se vyhodnotí jenom při prvním spuštění streamu. Změna této možnosti po restartování streamu nemá žádný vliv. true
maxBytesPerTrigger Byte String Maximální počet nových bajtů k zpracování v každém spouštěči. Můžete zadat bajtový řetězec, například 10g, který omezí jednotlivé mikrobatchy na 10 GB dat. Jedná se o měkké maximum. Pokud máte soubory, které jsou 3 GB, Azure Databricks zpracovává 12 GB v mikrobatchu. Při použití společně s maxFilesPerTrigger Azure Databricks spotřebuje až nižší limit maxFilesPerTrigger nebo maxBytesPerTrigger podle toho, co je dosaženo jako první. Pro streamovací tabulky vytvořené v serverless SQL skladech tuto možnost maxFilesPerTriggernenastavujte ani , abyste využili dynamickou kontrolu přijetí. None
maxFilesPerTrigger Integer Maximální počet nových souborů, které je třeba zpracovat v každém triggeru. Při použití společně s maxBytesPerTrigger Azure Databricks spotřebuje až nižší limit maxFilesPerTrigger nebo maxBytesPerTrigger podle toho, co je dosaženo jako první. Pro streamovací tabulky vytvořené v serverless SQL skladech tuto možnost maxBytesPerTriggernenastavujte ani , abyste využili dynamickou kontrolu přijetí. 1000
schemaEvolutionMode String Režim pro vývoj schématu, protože v datech jsou zjištěny nové sloupce. Ve výchozím nastavení se sloupce při odvozování datových sad JSON odvozují jako řetězce. Viz vývoj schématu pro více podrobností. Tato možnost se nevztahuje na text soubory a binaryFile soubory. "addNewColumns"Jinak bez schématu. "none"
schemaLocation String Umístění pro uložení odvozeného schématu a následných změn. Další podrobnosti najdete v části odvozování schématu. Umístění schématu není potřeba při dotazu do streamovací tabulky. None

Příklady

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

Práce s nestrukturovanými soubory

Následující příklady používají BINARYFILE formát ke čtení a filtrování nestrukturovaných souborů uložených ve svazcích katalogu Unity a kombinování read_files s funkcemi AI pro zpracování obsahu souborů.

Výpis všech souborů ve svazku: Slouží * EXCEPT (content) k vrácení metadat souborů bez načtení binárního obsahu a výběr _metadata explicitně zahrnout pole metadat na úrovni souboru.

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

Soubory obrázků seznamu filtrované podle velikosti: Slouží fileNamePattern k cílení na konkrétní typy souborů obrázků a filtrování, aby se vracely _metadata.file_size jenom soubory v daném rozsahu velikostí.

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;

Výpis souborů PDF upravených během posledního dne: Slouží fileNamePattern k cílení na soubory PDF a filtrování modificationTime , aby se v posledních dnech vrátily jenom soubory změněné.

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;

Spuštění funkce AI na souborech obrázků: Slouží ai_query ke zpracování souborů obrázků načtených z cesty cloudového úložiště. Vyfiltrujte pole tak _metadata , aby cílila na konkrétní soubory.

SELECT
  path AS file_path,
  ai_query(
    'system.ai.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%';

Parsování dokumentů odpovídajících vzoru názvu souboru: Slouží ai_parse_document k extrakci strukturovaného obsahu z souborů PDF a obrázků. Filtrujte podle _metadata.file_name cíle konkrétních souborů.

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

Spojení souborů se strukturovanou tabulkou: Nestrukturované pracovní postupy často vyžadují sloučení strukturovaných dat uložených v tabulkách s nestrukturovanými soubory. Následující příklad spojuje soubory v cestě cloudového úložiště se dvěma strukturovanými tabulkami, filtrování podle velikosti souboru a atributu uživatele. Spojení se user_files provádí extrahováním ID souboru z cesty k souboru pomocí split a 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;
  • Last updated on