read_files таблично-значная функция

Область применения:флажок Databricks SQL флажок Databricks Runtime 13.3 LTS и выше

Считывает файлы в заданном расположении и возвращает данные в табличной форме.

Поддерживает чтениеJSON, CSV, XMLTEXTBINARYFILEPARQUETAVROи ORC форматы файлов. Может автоматически обнаруживать формат файла и выводить единую схему во всех файлах.

Примечание.

Доступно в бета-версии, с установкой format => 'file' на возврат FILE ссылки для каждого файла вместо чтения содержимого файла. Смотрите FILE тип и Inget файлы как тип FILE.

Синтаксис

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

Аргументы

Для этой функции требуется вызов с использованием именованных параметров для ключей опций.

  • path: Объект STRING с URI, указывающим на расположение данных. Поддерживает чтение из Azure Data Lake Storage ('abfss://'), S3 (s3://) и Google Cloud Storage ('gs://'). Может содержать глобы. Дополнительные сведения см. в статье об обнаружении файлов.
  • option_key: имя параметра для настройки. Необходимо использовать обратные кавычки () for options that contain dots (.`).
  • option_value: константное выражение для задания параметра. Принимает литералы и скалярные функции.

Возвраты

Таблица, содержащая данные из файлов, считываемой в заданном виде path. Схема зависит от формата файла:

  • BINARYFILE: возвращает фиксированную схему:

    колонна Тип Описание
    path STRING Полный путь к файлу.
    modificationTime TIMESTAMP Время последнего изменения файла.
    length LONG Размер файла в байтах.
    content BINARY Двоичное содержимое файла. Используется * EXCEPT (content) для исключения двоичного содержимого при запросе метаданных файла.

  • TEXT: возвращает фиксированную схему с одним value (STRING) столбцом.

  • Все остальные форматы (JSON, CSV, XML, PARQUET, AVRO, ORC): схема выводится из содержимого файла или предоставляется явно с помощью schema параметра.

_metadata Столбца

read_files предоставляет _metadata столбец с метаданными уровня файла. Этот столбец не включается в SELECT * результаты и должен быть явно выбран. Он содержит следующие поля:

Поле Тип Описание
file_path STRING Полный путь к исходному файлу.
file_name STRING Имя исходного файла.
file_size LONG Размер исходного файла в байтах.
file_modification_time TIMESTAMP Время последнего изменения исходного файла.
file_block_start LONG Начало блока считываемого файла.
file_block_length LONG Длина блока считываемого файла.

Чтобы включить _metadata результаты, выберите его явным образом:

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

Обнаружение файлов

read_files может считывать отдельный файл или считывать файлы в предоставленном каталоге. read_files обнаруживает все файлы в предоставленном каталоге рекурсивно, если не указан глоб, который указывает read_files выполнять рекурсию в соответствующий шаблон директории.

Фильтрация каталогов или файлов с помощью шаблонов glob

Для фильтрации каталогов и файлов можно использовать глоб-шаблоны, если они указаны в пути.

Расписание Описание
? Соответствует любому одиночному символу
* Соответствует нулю или более символам
[abc] Соответствует одиночному символу из кодировки {a, b, c}.
[a-z] Соответствует одиночному символу из диапазона символов {a…z}.
[^a] Соответствует одиночному символу, который не относится к кодировке или диапазону символов {a}. Обратите внимание, что символ ^ должен стоять непосредственно справа от открывающей скобки.
{ab,cd} Соответствует строке из набора строк {ab, cd}.
{ab,c{de, fh}} Соответствует строке из набора строк {ab, cde, cfh}.

read_files при обнаружении файлов с помощью глобов используется строгий глобер автозагрузчика. Это настраивается параметром useStrictGlobber . Если строгий глоббер отключен, конечные косые черты (/) удаляются, и шаблон со звездочкой, такой как /*/, может расшириться при обнаружении нескольких каталогов. Ознакомьтесь с приведенными ниже примерами, чтобы увидеть разницу в поведении.

Расписание Путь к файлу Строгий режим глоббера отключен Включен строгий шаблонный фильтр
/a/b /a/b/c/file.txt Да Да
/a/b /a/b_dir/c/file.txt Нет Нет
/a/b /a/b.txt Нет Нет
/a/b/ /a/b.txt Нет Нет
/a/*/c/ /a/b/c/file.txt Да Да
/a/*/c/ /a/b/c/d/file.txt Да Да
/a/*/d/ /a/b/c/d/file.txt Да Нет
/a/*/c/ /a/b/x/y/c/file.txt Да Нет
/a/*/c /a/b/c_file.txt Да Нет
/a/*/c/ /a/b/c_file.txt Да Нет
/a/*/c /a/b/cookie/file.txt Да Нет
/a/b* /a/b.txt Да Да
/a/b* /a/b/file.txt Да Да
/a/{0.txt,1.txt} /a/0.txt Да Да
/a/*/{0.txt,1.txt} /a/0.txt Нет Нет
/a/b/[cde-h]/i/ /a/b/c/i/file.txt Да Да

Вывод схемы

Схема файлов может быть явно предоставлена read_files с помощью параметра schema. Если схема не указана, read_files пытается определить единую схему в обнаруженных файлах, которая требует считывания всех файлов, если LIMIT инструкция не используется. Даже при использовании запроса LIMIT, может быть прочитан больший набор файлов, чем требуется, для получения более репрезентативной схемы данных. Databricks автоматически добавляет инструкцию LIMIT для SELECT запросов в записных книжках и редакторе SQL, если пользователь не предоставил его.

Этот schemaHints параметр можно использовать для исправления подмножеств выводимой схемы. Дополнительные сведения см. в разделе Переопределение определения схемы с помощью подсказок схемы.

По умолчанию rescuedDataColumn предоставляется для восстановления любых данных, которые не соответствуют схеме. Дополнительные сведения см. в разделе "Что такое спасённые столбцы данных?" Вы можете удалить rescuedDataColumn, задав параметр schemaEvolutionMode => 'none'.

Вывод схемы секционирования

read_files также может выводить столбцы секционирования, если файлы хранятся в секционированных каталогах в стиле Hive, то есть /column_name=column_value/. Если предоставлено schema, обнаруженные столбцы разделов используют типы, указанные в schema. Если столбцы разделов не являются частью предоставленного schema, то определяемые столбцы разделов игнорируются.

Если столбец существует как в схеме секции, так и в столбцах данных, значение, считываемое из значения секции, используется вместо значения данных. Если вы хотите игнорировать значения, поступающие из каталога, и использовать столбец данных, можно указать список столбцов секций в разделенном запятыми списке с параметром partitionColumns .

Этот partitionColumns параметр также можно использовать для указания read_files того, какие обнаруженные столбцы должны включаться в окончательную выводную схему. Предоставление пустой строки игнорирует все столбцы секционирования.

Также можно указать опцию schemaHints, чтобы переопределить выведенную схему для столбца секционирования.

У TEXT и BINARYFILE форматов есть фиксированная схема, но read_files и пытается определить секционирование для этих форматов, когда это возможно.

Проверка подлинности для облачного хранилища

read_files считывает файлы из внешних расположений каталога Unity или томов каталога Unity (как управляемых, так и внешних). У вас должна быть READ FILES привилегия во внешнем расположении или READ VOLUME привилегии тома, содержащего файлы, которые требуется прочитать. См. статью "Подключение к облачному хранилищу объектов" с помощью каталога Unity или томов каталога Unity?.

Использование в потоковых таблицах

read_files можно использовать в потоковых таблицах для импорта файлов в Delta Lake. read_files использует Auto Loader в запросе потоковой таблицы. Необходимо использовать ключевое слово STREAM с read_files. Дополнительные сведения см. в разделе "Что такое автозагрузчик".

При использовании в потоковом запросе read_files используется образец данных для вывода схемы и может развивать схему по мере обработки дополнительных данных. Дополнительные сведения см. в разделе Настройка конфигурации вывода и процесса эволюции схемы в Auto Loader.

Настройки

Основные параметры

Вариант Тип Описание Значение по умолчанию
format String Формат файла данных в исходном пути. Автоматически выводится, если опущено. Допустимые значения включают avro, binaryFile, csv, file (Beta), json, orc, parquettext, и xml. Нет
schema String Схема считываемых файлов. Закажите строку схемы в формате DDL, например 'id int, ts timestamp, event string'. Если опущено, то read_files попытки вывести единую схему для обнаруженных файлов. Нет
inferColumnTypes Boolean Следует ли выводить точные типы столбцов при использовании вывода схемы. По умолчанию столбцы определяются при интерпретации наборов данных JSON и CSV. Это противоположно стандартному поведению Auto Loader. См. выведение схемы. true
partitionColumns String Список столбцов разделов в стиле Hive, разделённый по запятой, для вывода из структуры каталогов файлов. Столбцы в стиле улья — это пары ключ-значение, объединённые знаком равенства, например <base-path>/a=x/b=1/c=y/file.format. В этом примере столбцы секционирования представляют собой a, b и c. Если вы используете схемный вывод и передаёте <base-path> данные для загрузки, эти столбцы автоматически добавляются в вашу схему. Если указать схему, автозагрузчик ожидает, что эти столбцы будут включены в схему. Если вы не хотите, чтобы эти столбцы были частью вашей схемы, уточните "" , что нужно их игнорировать. Эту опцию также можно использовать для вывода столбцов из пути к файлу в сложных структурах каталогов. Например, для следующих файлов указано cloudFiles.partitionColumns как year,month,day возврат year=2022 для file1.csv, но month столбцы и day — .null month и day правильно анализируются для file2.csv и 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		 Нет
schemaHints String Информация о схеме, которую вы передаёте Auto Loader во время инференции схемы. Дополнительные сведения см. в разделе Указания для схемы. Нет
useStrictGlobber Boolean Следует ли использовать строгий режим глоббинга, соответствующий поведению глоббинга других источников файлов по умолчанию в Apache Spark. См. об общих шаблонах загрузки данных для получения дополнительных сведений. Доступно в Databricks Runtime 12.2 LTS и более поздних версиях. Это противоположно стандартному режиму Auto Loader. true

Параметры, относящиеся к формату

Параметры, относящиеся к каждому формату файла (JSON, CSV, XML, Parquet, Avro, text, ORC и двоичному файлу), см. в параметрах DataFrameReader.

Параметры потоковой передачи

Эти параметры применяются при использовании read_files внутри потоковой таблицы или потокового запроса.

Вариант Тип Описание Значение по умолчанию
allowOverwrites Boolean Стоит ли перерабатывать файлы, которые изменяются после обнаружения. При обновлении read_files обрабатывает файл, если он был изменён после последнего успешного обновления. false
includeExistingFiles Boolean Следует ли включать существующие файлы во входной путь обработки потоковой передачи или обрабатывать только новые файлы, поступающие после первоначальной настройки. Этот параметр оценивается только при первом запуске потока. Изменение этого параметра после перезапуска потока не даст результата. true
maxBytesPerTrigger Byte String Максимальное количество новых байт для обработки в каждом триггере. Можно указать строку байтов, например 10g, чтобы ограничить каждый микробатч до 10 ГБ данных. Это мягкое ограничение. Если у вас есть файлы размером 3 ГБ, Azure Databricks обрабатывает 12 ГБ в микробатче. При использовании вместе с maxFilesPerTrigger Azure Databricks используется до нижнего предела maxFilesPerTrigger или maxBytesPerTrigger. Для потоковых таблиц, созданных на серверных SQL-хранилищах, не устанавливайте эту опцию или maxFilesPerTrigger, чтобы использовать динамический контроль допуска. Нет
maxFilesPerTrigger Integer Максимальное количество новых файлов для обработки в каждом триггере. При использовании вместе с maxBytesPerTrigger Azure Databricks используется до нижнего предела maxFilesPerTrigger или maxBytesPerTrigger. Для потоковых таблиц, созданных на серверных SQL-хранилищах, не устанавливайте эту опцию или maxBytesPerTrigger, чтобы использовать динамический контроль допуска. 1000
schemaEvolutionMode String Режим для развития схемы по мере обнаружения в данных новых столбцов. По умолчанию столбцы выводятся как строки при выводе наборов данных JSON. Дополнительные сведения см. в разделе Развитие схемы. Этот параметр не применяется к text файлам и binaryFile файлам. "addNewColumns" без схемы — "none" иначе.
schemaLocation String Расположение для хранения выводимой схемы и последующих изменений. Дополнительные сведения см. в разделе Вывод схемы. Местоположение схемы не требуется при использовании в запросе таблицы потоков. Нет

Примеры

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

Работа с неструктурированными файлами

В следующих примерах используется BINARYFILE формат для чтения и фильтрации неструктурированных файлов, хранящихся в томах каталога Unity, а также объединения read_files с функциями ИИ для обработки содержимого файла.

Вывод списка всех файлов в томе: используйте * EXCEPT (content) для возврата метаданных файла без загрузки двоичного содержимого и явно выберите _metadata для включения полей метаданных уровня файла.

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

Список файлов изображений, отфильтрованных по размеру: используйте fileNamePattern для назначения определенных типов файлов изображений и фильтрации _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;

Вывод списка PDF-файлов, измененных в течение последнего дня: используйте fileNamePattern для назначения PDF-файлов и фильтрации 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;

Запустите функцию ИИ в файлах изображений: используйте ai_query для обработки файлов изображений, считываемого из пути к облачному хранилищу. Фильтрация по _metadata полям для целевых файлов.

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

Анализ документов, соответствующих шаблону имени файла: используется ai_parse_document для извлечения структурированного содержимого из PDF-файлов и изображений. Фильтруйте по целевым _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%';

Присоединение файлов к структурированной таблице: неструктурированные рабочие процессы часто требуют объединения структурированных данных, хранящихся в таблицах с неструктурированными файлами. В следующем примере файлы объединяются в путь к облачному хранилищу с двумя структурированными таблицами, фильтрация по размеру файла и атрибуту пользователя. Соединение user_files выполняется путем извлечения идентификатора файла из пути к файлу с помощью split и 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