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

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

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

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

Синтаксис

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 * результаты и должен быть явно выбран. Он содержит следующие поля:

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

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

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

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

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

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

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

Вывод схемы

Схема файлов может быть явно предоставлена 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.

Настройки

• Основные параметры
• Параметры, относящиеся к формату
• Параметры потоковой передачи

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

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

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

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

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

Примеры

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

Связанные статьи

• CREATE STREAMING TABLE
• табличное значение функции