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.

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

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

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

Настройки

• Базовые параметры
• Универсальные параметры
• Параметры JSON
• Параметры CSV
• Параметры XML
• Параметры PARQUET
• Параметры AVRO
• Параметры BINARYFILE
• Параметры TEXT
• Параметры ORC
• Параметры потоковой передачи

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

Общие параметры

Следующие параметры применяются ко всем форматам файлов.

JSON варианты

CSV варианты

XML варианты

PARQUET варианты

AVRO варианты

BINARYFILE варианты

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

TEXT варианты

ORC варианты

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

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

Примеры

-- Reads the files available in the given path. Auto-detects the format and schema of the data.
> SELECT * FROM read_files('abfss://[email protected]/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://[email protected]/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);

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

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