`read_files` tabulková hodnotová funkce

Platí pro: zaškrtnuto ano Databricks SQL 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.

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.

Základní možnosti

Možnost
`format` Typ: `String` Formát datového souboru ve zdrojové cestě. Pokud není k dispozici, automaticky se odvodí. Mezi povolené hodnoty patří: `avro` `binaryFile` `csv` `json` `orc` `parquet` `text` `xml` Výchozí hodnota: None
`schema` Typ: `String` Schéma souborů, které se mají číst. Zadejte řetězec schématu pomocí formátu DDL, například `'id int, ts timestamp, event string'`. Pokud schéma není k dispozici, `read_files` pokusí se odvodit jednotné schéma ve zjištěných souborech. Výchozí hodnota: None
`inferColumnTypes` Typ: `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. Další podrobnosti najdete v části odvozování schématu. Všimněte si, že toto je opak výchozího nastavení Auto Loaderu. Výchozí hodnota: `true`
`partitionColumns` Typ: `String` Čárkami oddělený seznam sloupců oddílů stylu Hive, které byste chtěli odvodit z adresářové struktury souborů. Sloupce oddílů stylu Hive jsou páry klíč-hodnota zkombinované 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`. Ve výchozím nastavení se tyto sloupce automaticky přidají do vašeho schématu, pokud používáte odvozování schématu a poskytujete `<base-path>` pro načtení dat. Pokud zadáte schéma, Auto Loader očekává, že tyto sloupce budou zahrnuty do schématu. Pokud nechcete, aby tyto sloupce byly součástí schématu, můžete tyto sloupce ignorovat `""` . Tuto možnost můžete použít také v případě, že chcete, aby sloupce odvodily cestu k souboru ve složitých adresářových strukturách, například v následujícím příkladu: `<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` Specifikace `cloudFiles.partitionColumns` jako `year,month,day` vrátí `year=2022` pro `file1.csv`, ale `monthday` sloupce budou `null`. `month` a `day` bude správně analyzován pro `file2.csv` a `file3.csv`. Výchozí hodnota: None
`schemaHints` Typ: `String` Při odvozování schématu poskytujete automatickému zavaděči informace o schématu. Další podrobnosti najdete v nápovědě schématu . Výchozí hodnota: None
`useStrictGlobber` Typ: `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. Všimněte si, že toto je opak výchozího nastavení automatického zavaděče. Výchozí hodnota: `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
`allowOverwrites` Typ: `Boolean` Zda se mají po zjišťování znovu zpracovat soubory, které byly změněny. Nejnovější dostupná verze souboru se zpracuje během aktualizace, pokud byla změněna od posledního úspěšného spuštění dotazu aktualizace. Výchozí hodnota: `false`
`includeExistingFiles` Typ: `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. Výchozí hodnota: `true`
`maxBytesPerTrigger` Typ: `Byte String` Maximální počet nových bajtů zpracovaných při každém spuštění. 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í. Poznámka: U streamovaných tabulek vytvořených v bezserverových skladech SQL by tato možnost a `maxFilesPerTrigger` neměly být nastaveny tak, aby využívaly dynamické řízení přístupu, které se škáluje podle velikosti úloh a bezserverových výpočetních prostředků, abyste získali nejlepší latenci a výkon. Výchozí hodnota: None
`maxFilesPerTrigger` Typ: `Integer` Maximální počet nových souborů ke zpracování při každém spuštění. 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í. Poznámka: U streamovaných tabulek vytvořených v bezserverových skladech SQL by tato možnost a `maxBytesPerTrigger` neměly být nastaveny tak, aby využívaly dynamické řízení přístupu, které se škáluje podle velikosti úloh a bezserverových výpočetních prostředků, abyste získali nejlepší latenci a výkon. Výchozí hodnota: 1000
`schemaEvolutionMode` Typ: `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. Výchozí hodnota: `"addNewColumns"` pokud schéma není zadané. `"none"` jinak.
`schemaLocation` Typ: `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í vyžadováno při použití v dotazu tabulky streamování. Výchozí hodnota: 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(
    '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%';

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;

CREATE STREAMING TABLE
read_kafka tabulkově hodnotová funkce

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-10