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

Поле	Тип	Описание
`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. У вас должна быть привилегия READ FILES во внешнем расположении, в котором содержатся файлы, которые требуется прочитать. См. статью "Подключение к облачному хранилищу объектов" с помощью каталога Unity.

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

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

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

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

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

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

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

Вариант
`ignoreCorruptFiles` Тип: `Boolean` Определяет, следует ли игнорировать поврежденные файлы. Если задано значение true, задания Spark будут продолжать выполняться при обнаружении поврежденных файлов, а прочитанное содержимое будет возвращено. Наблюдаемое в виде `numSkippedCorruptFiles` в в столбце истории Delta Lake `operationMetrics`. Доступно в Databricks Runtime 11.3 LTS и более поздних версиях. Значение по умолчанию: `false`
`ignoreMissingFiles` Тип: `Boolean` Определяет, следует ли игнорировать отсутствующие файлы. Если задано значение true, задания Spark будут продолжать выполняться при обнаружении отсутствующих файлов, а прочитанное содержимое будет возвращено. Доступно в Databricks Runtime 11.3 LTS и более поздних версиях. Значение по умолчанию: `false` для автозагрузчика `true` для `COPY INTO` (устаревшая версия)
`modifiedAfter` Тип: `Timestamp String`, например `2021-01-01 00:00:00.000000 UTC+0`. Необязательная метка времени в качестве фильтра для приема только файлов с меткой времени изменения после указанной метки времени. Значение по умолчанию: нет
`modifiedBefore` Тип: `Timestamp String`, например `2021-01-01 00:00:00.000000 UTC+0`. Необязательная метка времени в качестве фильтра для приема только файлов с меткой времени изменения до указанной метки времени. Значение по умолчанию: нет
`pathGlobFilter` или `fileNamePattern` Тип: `String` Потенциальный глобальный шаблон для выбора файлов. Эквивалентно `PATTERN` в `COPY INTO` (устаревшая версия). `fileNamePattern` можно использовать в `read_files`. Значение по умолчанию: нет
`recursiveFileLookup` Тип: `Boolean` Этот параметр выполняет поиск по вложенным каталогам, даже если их имена не соответствуют схеме именования секций, например date=2019-07-01. Значение по умолчанию: `false`

`JSON` варианты

Вариант
`allowBackslashEscapingAnyCharacter` Тип: `Boolean` Разрешить ли обратную косую черту для экранирования любого символа, который следует за ней. Если параметр не активирован, экранировать можно только те символы, которые эксплицитно указаны в спецификации JSON. Значение по умолчанию: `false`
`allowComments` Тип: `Boolean` Следует ли разрешать использование комментариев стиля Java, C и C++ (`'/'`, `'*'` и `'//'` разновидностей) в пределах проанализированного содержимого или нет. Значение по умолчанию: `false`
`allowNonNumericNumbers` Тип: `Boolean` Разрешить ли использование набора токенов, представляющих нечисловые значения (`NaN`), как законные числовые значения с плавающей запятой. Значение по умолчанию: `true`
`allowNumericLeadingZeros` Тип: `Boolean` Разрешить ли целочисленное число начинаться с дополнительных (игнорируемых) нули (например, `000001`). Значение по умолчанию: `false`
`allowSingleQuotes` Тип: `Boolean` Разрешить ли использование одиночных кавычек (апостроф, символ `'\'`) для цитирования строк (имен и строковых значений). Значение по умолчанию: `true`
`allowUnquotedControlChars` Тип: `Boolean` Разрешено ли строкам JSON содержать неэкранированные символы управления (символы ASCII со значением меньше 32, включая символы табуляции и перевода строки)? Значение по умолчанию: `false`
`allowUnquotedFieldNames` Тип: `Boolean` Разрешить ли использование имен полей, не заключенных в кавычки (которые разрешены в JavaScript, но не в спецификации JSON). Значение по умолчанию: `false`
`badRecordsPath` Тип: `String` Путь для хранения файлов для записи сведений о неправильных записях JSON. `badRecordsPath` Использование параметра в источнике данных на основе файлов имеет следующие ограничения: Она не является транзакционной и может привести к несогласованным результатам. Временные ошибки рассматриваются как сбои. Значение по умолчанию: нет
`columnNameOfCorruptRecord` Тип: `String` Столбец для хранения записей, которые имеют неправильный формат и не могут быть проанализированы. Если в качестве `mode` для синтаксического анализа задано значение `DROPMALFORMED`, этот столбец будет пустым. Значение по умолчанию: `_corrupt_record`
`dateFormat` Тип: `String` Формат синтаксического анализа строк даты. Значение по умолчанию: `yyyy-MM-dd`
`dropFieldIfAllNull` Тип: `Boolean` Игнорировать ли столбцы, в которых все значения равны NULL, пустые массивы и структуры во время вывода схемы. Значение по умолчанию: `false`
`encoding` или `charset` Тип: `String` Имя кодировки файлов JSON. Список вариантов см. в `java.nio.charset.Charset`. Нельзя использовать `UTF-16` и `UTF-32`, если `multiline` имеет значение `true`. Значение по умолчанию: `UTF-8`
`inferTimestamp` Тип: `Boolean` Следует ли попытаться распознать строки меток времени как `TimestampType`. Когда настроено на... `true`, вывод схемы может занять заметно больше времени. Необходимо включить `cloudFiles.inferColumnTypes`, чтобы использовать с автозагрузчиком. Значение по умолчанию: `false`
`lineSep` Тип: `String` Строка между двумя последовательными записями JSON. Значение по умолчанию None (Нет) охватывает `\r`, `\r\n` и `\n`.
`locale` Тип: `String` Идентификатор `java.util.Locale`. Влияет на разбор даты, метки времени и десятичных чисел по умолчанию в JSON. Значение по умолчанию: `US`
`mode` Тип: `String` Режим парсера для обработки некорректных записей. Один из `PERMISSIVE`, `DROPMALFORMED`, или `FAILFAST`. Значение по умолчанию: `PERMISSIVE`
`multiLine` Тип: `Boolean` Занимает ли запись JSON несколько строк. Значение по умолчанию: `false`
`prefersDecimal` Тип: `Boolean` Пытается интерпретировать строки как `DecimalType`, а не как тип float или double, когда это возможно. Также необходимо использовать автоматическое определение схемы, например, путем его включения. `inferSchema` или использование `cloudFiles.inferColumnTypes` с автозагрузчиком. Значение по умолчанию: `false`
`primitivesAsString` Тип: `Boolean` Следует ли рассматривать примитивные типы, такие как числа и логические значения, как `StringType`. Значение по умолчанию: `false`
`readerCaseSensitive` Тип: `Boolean` Задает параметры поведения в отношении чувствительности к регистру при активации `rescuedDataColumn`. Если значение true, сохраните столбцы данных, имена которых отличаются по регистру от имен в схеме; в противном случае считывайте данные без учета регистра. Доступно в Databricks Runtime 13.3 и выше. Значение по умолчанию: `true`
`rescuedDataColumn` Тип: `String` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных или несоответствия схем (включая регистр столбцов), в отдельный столбец. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в разделе "Что такое столбец спасенных данных?". `COPY INTO` (устаревшая версия) не поддерживает спасательный столбец данных, так как невозможно вручную задать схему с помощью `COPY INTO`. Databricks рекомендует использовать Auto Loader для большинства сценариев загрузки. Значение по умолчанию: нет
`singleVariantColumn` Тип: `String` Следует ли импортировать весь документ JSON, обработанный в один столбец типа Variant, с заданной строкой в качестве имени столбца. Если отключено, поля JSON будут загружены в отдельные столбцы. Значение по умолчанию: нет
`timestampFormat` Тип: `String` Формат для синтаксического анализа строк меток времени. Значение по умолчанию: `yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`
`timeZone` Тип: `String` Объект `java.time.ZoneId`, который следует использовать для анализа меток времени и дат. Значение по умолчанию: нет

`CSV` варианты

Вариант
`badRecordsPath` Тип: `String` Путь для хранения файлов с информацией о некорректных строках CSV. Значение по умолчанию: нет
`charToEscapeQuoteEscaping` Тип: `Char` Символ, используемый для экранирования символов, применяемых для экранирования кавычек. Например, для следующей записи: `[ " a\\", b ]`: Если символ для экранирования `'\'` не определен, запись не будет проанализирована. Средство синтаксического анализа будет считывать символы: `[a],[\],["],[,],[ ],[b]` и вызывать ошибку, так как не сможет найти закрывающую кавычку. Если символ для экранирования `'\'` задан как `'\'`, запись будет считываться с двумя значениями: `[a\]` и `[b]`. Значение по умолчанию: `'\0'`
`columnNameOfCorruptRecord` Поддержка для автозагрузчика. Не поддерживается для `COPY INTO` (устаревшая версия). Тип: `String` Столбец для хранения записей, которые имеют неправильный формат и не могут быть проанализированы. Если в качестве `mode` для синтаксического анализа задано значение `DROPMALFORMED`, этот столбец будет пустым. Значение по умолчанию: `_corrupt_record`
`comment` Тип: `Char` Определяет символ, представляющий строку комментария, если он находится в начале текстовой строки. Используйте `'\0'`, чтобы отключить пропуск комментариев. Значение по умолчанию: `'\u0000'`
`dateFormat` Тип: `String` Формат синтаксического анализа строк даты. Значение по умолчанию: `yyyy-MM-dd`
`emptyValue` Тип: `String` Строковое представление пустого значения. Значение по умолчанию: `""`
`encoding` или `charset` Тип: `String` Имя кодировки CSV-файлов. Смотрите `java.nio.charset.Charset` для списка вариантов. `UTF-16` и `UTF-32` использовать нельзя, если `multiline` имеет значение `true`. Значение по умолчанию: `UTF-8`
`enforceSchema` Тип: `Boolean` Следует ли принудительно применять указанную или выведенную схему к CSV-файлам. Если параметр включен, заголовки CSV-файлов игнорируются. Этот параметр игнорируется по умолчанию при использовании Автозагрузчика для восстановления данных и разрешения на развитие схемы. Значение по умолчанию: `true`
`escape` Тип: `Char` Escape-символ, используемый при анализе данных. Значение по умолчанию: `'\'`
`header` Тип: `Boolean` Содержат ли CSV-файлы заголовок. При выводе схемы Автозагрузчик предполагает, что файлы имеют заголовки. Значение по умолчанию: `false`
`ignoreLeadingWhiteSpace` Тип: `Boolean` Следует ли игнорировать начальные пробелы для каждого анализируемого значения. Значение по умолчанию: `false`
`ignoreTrailingWhiteSpace` Тип: `Boolean` Следует ли игнорировать пробелы в конце для каждого анализируемого значения. Значение по умолчанию: `false`
`inferSchema` Тип: `Boolean` Указывает, следует ли вычислять типы данных проанализированных записей CSV, или предполагается, что все столбцы имеют тип `StringType`. Требует дополнительного прохода по данным, если задано значение `true`. Для автозагрузчика используйте `cloudFiles.inferColumnTypes` вместо этого. Значение по умолчанию: `false`
`lineSep` Тип: `String` Строка между двумя последовательными записями CSV. Значение по умолчанию None (Нет) охватывает `\r`, `\r\n` и `\n`.
`locale` Тип: `String` Идентификатор `java.util.Locale`. Влияет на разбор даты, метки времени и десятичного разделителя в CSV-файле по умолчанию. Значение по умолчанию: `US`
`maxCharsPerColumn` Тип: `Int` Максимальное число символов, ожидаемое в значении для синтаксического анализа. Можно использовать, чтобы избежать ошибок памяти. По умолчанию имеет значение `-1`, что означает отсутствие ограничений. Значение по умолчанию: `-1`
`maxColumns` Тип: `Int` Фиксированное ограничение количества столбцов в записи. Значение по умолчанию: `20480`
`mergeSchema` Тип: `Boolean` Следует ли определять схему на основе нескольких файлов и объединять схемы каждого файла. По умолчанию включено для автозагрузчика при выведении схемы. Значение по умолчанию: `false`
`mode` Тип: `String` Режим парсера для обработки некорректных записей. Одно из `'PERMISSIVE'` `'DROPMALFORMED'` и `'FAILFAST'`. Значение по умолчанию: `PERMISSIVE`
`multiLine` Тип: `Boolean` Занимает ли запись CSV несколько строк. Значение по умолчанию: `false`
`nanValue` Тип: `String` Строковое представление значения, не являющегося числовым, при синтаксическом анализе столбцов `FloatType` и `DoubleType`. Значение по умолчанию: `"NaN"`
`negativeInf` Тип: `String` Строковое представление отрицательной бесконечности при синтаксическом анализе столбцов `FloatType` или `DoubleType`. Значение по умолчанию: `"-Inf"`
`nullValue` Тип: `String` Строковое представление значения NULL. Значение по умолчанию: `""`
`parserCaseSensitive` (не рекомендуется) Тип: `Boolean` Следует ли при чтении файлов выравнивать столбцы, указанные в заголовке, с учетом регистра в соответствии с схемой. Это значение равно `true` по умолчанию для Автозагрузчика. Столбцы, отличающиеся только регистром текста, будут сохранены в `rescuedDataColumn`, если эта функция включена. Вместо этого параметра рекомендуется использовать `readerCaseSensitive`. Значение по умолчанию: `false`
`positiveInf` Тип: `String` Строковое представление положительной бесконечности при синтаксическом анализе столбцов `FloatType` или `DoubleType`. Значение по умолчанию: `"Inf"`
`preferDate` Тип: `Boolean` Пытается интерпретировать строки как даты, а не как временные метки, если это возможно. Кроме того, необходимо использовать инференцию схемы, либо включив `inferSchema`, либо используя ее. `cloudFiles.inferColumnTypes` с автозагрузчиком. Значение по умолчанию: `true`
`quote` Тип: `Char` Символ, используемый для экранирования значений, где разделитель полей входит в состав значения. Значение по умолчанию: `"`
`readerCaseSensitive` Тип: `Boolean` Задает параметры поведения в отношении чувствительности к регистру при активации `rescuedDataColumn`. Если значение true, сохраните столбцы данных, имена которых отличаются по регистру от имен в схеме; в противном случае считывайте данные без учета регистра. Значение по умолчанию: `true`
`rescuedDataColumn` Тип: `String` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных и несоответствия схемы (включая регистр столбцов) отдельному столбцу. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в статье "Что такое столбец спасенных данных?". `COPY INTO` (устаревшая версия) не поддерживает спасательный столбец данных, так как невозможно вручную задать схему с помощью `COPY INTO`. Databricks рекомендует использовать Auto Loader для большинства сценариев загрузки. Значение по умолчанию: нет
`sep` или `delimiter` Тип: `String` Разделительная строка между столбцами. Значение по умолчанию: `","`
`skipRows` Тип: `Int` Количество строк с начала CSV-файла, которые следует игнорировать (включая комментарии и пустые строки). Если значение `header` равно true, заголовок будет первой не пропущенной и не закомментированной строкой. Значение по умолчанию: `0`
`timestampFormat` Тип: `String` Формат для синтаксического анализа строк меток времени. Значение по умолчанию: `yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`
`timeZone` Тип: `String` Объект `java.time.ZoneId`, который следует использовать для анализа меток времени и дат. Значение по умолчанию: нет
`unescapedQuoteHandling` Тип: `String` Стратегия обработки неэкранированных кавычек. Разрешенные варианты: `STOP_AT_CLOSING_QUOTE`: если во входных данных найдены неэкранированные кавычки, накопите символ кавычки и продолжайте анализировать значение как значение в кавычках, пока не будет найдена закрывающая кавычка. `BACK_TO_DELIMITER`: если во входных данных обнаружены неэкранированные кавычки, рассматривать значение как значение без кавычек. Это позволит средству синтаксического анализа накапливать все символы текущего анализируемого значения до тех пор, пока не будет найден разделитель, определенный в `sep`. Если в значении разделитель обнаружен не будет, то средство синтаксического анализа продолжит накапливать символы из входных данных до тех пор, пока не будет найден разделитель или конец строки. `STOP_AT_DELIMITER`: если во входных данных обнаружены неэкранированные кавычки, рассматривать значение как значение без кавычек. Это позволит средству синтаксического анализа накапливать все символы до тех пор, пока во входных данных не будет найден разделитель, определенный в `sep`, или символ конца строки. `SKIP_VALUE`: если во входных данных обнаружены неэкранированные кавычки, содержимое, анализируемое для данного значения, будет пропущено (пока не будет найден следующий разделитель), и будет выдано значение из `nullValue`. `RAISE_ERROR`: если неискаченные кавычки находятся в входных данных, `TextParsingException` будет выброшено. Значение по умолчанию: `STOP_AT_DELIMITER`

`XML` варианты

Вариант	Описание	Область действия
`rowTag`	Тег строки в XML-файлах, который следует рассматривать как строку. В примере XML `<books> <book><book>...<books>`соответствующее значение имеет значение `book`. Это обязательный параметр.	читай
`samplingRatio`	Определяет долю строк, используемых для вывода схемы. Встроенные функции XML игнорируют этот параметр. По умолчанию: `1.0`.	читай
`excludeAttribute`	Следует ли исключать атрибуты в элементах. По умолчанию: `false`.	читай
`mode`	Режим работы с поврежденными записями во время синтаксического анализа. `PERMISSIVE`: для поврежденных записей помещает недоформированную строку в поле, настроенное `columnNameOfCorruptRecord`и задает неправильно сформированные поля `null`. Чтобы сохранить поврежденные записи, можно задать `string` поле типа с именем `columnNameOfCorruptRecord` в определяемой пользователем схеме. Если в схеме нет поля, во время синтаксического анализа удаляются поврежденные записи. При определении схемы средство синтаксического анализа неявно добавляет `columnNameOfCorruptRecord` поле в выходную схему. `DROPMALFORMED`: игнорирует поврежденные записи. Этот режим не поддерживается для встроенных функций XML. `FAILFAST`: вызывает исключение, когда средство синтаксического анализа сталкивается с поврежденными записями.	читай
`inferSchema`	Если `true`, пытается определить соответствующий тип для каждого результирующего столбца DataFrame. Если `false`, все результирующие столбцы имеют тип `string`. По умолчанию: `true`. Встроенные функции XML игнорируют этот параметр.	читай
`columnNameOfCorruptRecord`	Даёт возможность переименовать новое поле, содержащее неправильно сформированную строку, созданную `PERMISSIVE` режим. По умолчанию: `spark.sql.columnNameOfCorruptRecord`.	читай
`attributePrefix`	Префикс атрибутов для отличия атрибутов от элементов. Это будет префикс для имен полей. По умолчанию — `_`. Может быть пустым для чтения XML, но не для записи.	чтение, запись
`valueTag`	Тег, используемый для символьных данных в элементах, которые также имеют атрибуты или дочерние элементы. Пользователь может указать поле `valueTag` в схеме, или оно будет добавлено автоматически во время определения схемы, если символьные данные присутствуют в элементах вместе с другими элементами или атрибутами. По умолчанию: `_VALUE`	чтение, запись
`encoding`	Для чтения декодирует XML-файлы по заданному типу кодирования. Для записи задает кодировку (charset) сохраненных XML-файлов. Встроенные функции XML игнорируют этот параметр. По умолчанию: `UTF-8`.	чтение, запись
`ignoreSurroundingSpaces`	Определяет, следует ли пропускать окружающие пробелы из считываемых значений. По умолчанию: `true`. Данные, состоящие исключительно из пробелов, игнорируются.	читай
`rowValidationXSDPath`	Путь к необязательному XSD-файлу, который используется для проверки XML для каждой строки по отдельности. Строки, которые не удается проверить, обрабатываются как ошибки синтаксического анализа, как описано выше. XSD иным образом не влияет на предоставленную или выведенную схему.	читай
`ignoreNamespace`	Если `true`, префиксы пространств имен для XML-элементов и атрибутов игнорируются. Теги `<abc:author>` и `<def:author>`, например, рассматриваются как если бы оба были просто `<author>`. Пространства имен нельзя игнорировать в элементе `rowTag`, можно игнорировать только читаемые дочерние элементы. Синтаксический анализ XML не учитывает пространство имен, даже если `false`. По умолчанию: `false`.	читай
`timestampFormat`	Настраиваемая строка формата временной метки, которая соответствует формату шаблона даты и времени. Это относится к типу `timestamp` . По умолчанию: `yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`.	чтение, запись
`timestampNTZFormat`	Строка настраиваемого формата для метки времени без часового пояса, которая соответствует формату шаблона datetime. Это относится к типу TimestampNTZType. По умолчанию: `yyyy-MM-dd'T'HH:mm:ss[.SSS]`	чтение, запись
`dateFormat`	Строка пользовательского формата даты, которая следует формату datetime pattern. Это относится к типу даты. По умолчанию: `yyyy-MM-dd`.	чтение, запись
`locale`	Устанавливает локаль как языковой тег в формате IETF BCP 47. Например, `locale` используется при анализе дат и меток времени. По умолчанию: `en-US`.	читай
`rootTag`	Корневой тег XML-файлов. Например, в `<books> <book><book>...</books>` соответствующее значение — это `books`. Можно включить базовые атрибуты, указав значение, подобное `books foo="bar"`. По умолчанию: `ROWS`.	написать
`declaration`	Содержимое объявления XML для записи в начале каждого выходного XML-файла, перед `rootTag`. Например, значение `foo` приводит к тому, что `<?xml foo?>` записывается. Задайте для подавления пустую строку. По умолчанию: `version="1.0"` `encoding="UTF-8" standalone="yes"`.	написать
`arrayElementName`	Имя XML-элемента, который заключает каждый элемент столбца со значением массива в процессе записи. По умолчанию: `item`.	написать
`nullValue`	Задает строковое представление значения NULL. Значение по умолчанию: строка `null`. Когда это `null`, средство синтаксического анализа не записывает атрибуты и элементы для полей.	чтение, запись
`compression`	Код сжатия, используемый при сохранении в файл. Это может быть одно из известных имен без учета регистра (`none`, `bzip2`, `gzip`, `lz4`, и `snappy`) `deflate`"). Встроенные функции XML игнорируют этот параметр. По умолчанию: `none`.	написать
`validateName`	При значении true вызывается ошибка при проверке имени элемента XML. Например, имена полей SQL могут иметь пробелы, но имена XML-элементов не могут. По умолчанию: `true`.	написать
`readerCaseSensitive`	Указывает поведение конфиденциальности регистра при включенном параметре rescuedDataColumn. Если значение true, сохраните столбцы данных, имена которых отличаются по регистру от имен в схеме; в противном случае считывайте данные без учета регистра. По умолчанию: `true`.	читай
`rescuedDataColumn`	Следует ли собирать все данные, которые нельзя проанализировать из-за несоответствия типов данных и несоответствия схемы (включая регистр столбцов) отдельному столбцу. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в разделе "Что такое столбец спасённых данных?". `COPY INTO` (устаревшая версия) не поддерживает спасательный столбец данных, так как невозможно вручную задать схему с помощью `COPY INTO`. Databricks рекомендует использовать Auto Loader для большинства сценариев загрузки. Значение по умолчанию: нет.	читай
`singleVariantColumn`	Указывает имя одного варианта столбца. Если эта опция указана для чтения, выполнить разбор всей записи XML в один столбец типа Variant, используя заданное строковое значение опции в качестве его названия. Если этот параметр предоставляется для записи, напишите значение одного столбца Variant в XML-файлы. По умолчанию: `none`.	чтение, запись

`PARQUET` варианты

Вариант
`datetimeRebaseMode` Тип: `String` Управляет изменением базы значений DATE и TIMESTAMP между юлианским и пролептическим григорианским календарями. Допустимые значения: `EXCEPTION`, `LEGACY`и `CORRECTED`. Значение по умолчанию: `LEGACY`
`int96RebaseMode` Тип: `String` Управляет пересчетом значений временной метки INT96 между юлианским и пролептическим григорианским календарями. Допустимые значения: `EXCEPTION`, `LEGACY`и `CORRECTED`. Значение по умолчанию: `LEGACY`
`mergeSchema` Тип: `Boolean` Следует ли определять схему на основе нескольких файлов и объединять схемы каждого файла. Значение по умолчанию: `false`
`readerCaseSensitive` Тип: `Boolean` Задает параметры поведения в отношении чувствительности к регистру при активации `rescuedDataColumn`. Если значение true, сохраните столбцы данных, имена которых отличаются по регистру от имен в схеме; в противном случае считывайте данные без учета регистра. Значение по умолчанию: `true`
`rescuedDataColumn` Тип: `String` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных и несоответствия схемы (включая регистр столбцов) отдельному столбцу. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в статье "Что такое столбец спасенных данных?". `COPY INTO` (устаревшая версия) не поддерживает спасательный столбец данных, так как невозможно вручную задать схему с помощью `COPY INTO`. Databricks рекомендует использовать Auto Loader для большинства сценариев загрузки. Значение по умолчанию: нет

`AVRO` варианты

Вариант
`avroSchema` Тип: `String` Необязательная схема в формате Avro, предоставляемая пользователем. При чтении Avro для этого параметра можно задать развитую схему, которая совместима, но отличается от фактической схемы Avro. Схема десериализации будет соответствовать изменённой схеме. Например, если задать развитую схему, содержащую один дополнительный столбец со значением по умолчанию, то результат чтения будет содержать новый столбец. Значение по умолчанию: нет
`datetimeRebaseMode` Тип: `String` Управляет изменением базы значений DATE и TIMESTAMP между юлианским и пролептическим григорианским календарями. Допустимые значения: `EXCEPTION`, `LEGACY`и `CORRECTED`. Значение по умолчанию: `LEGACY`
`mergeSchema` Тип: `Boolean` Следует ли определять схему на основе нескольких файлов и объединять схемы каждого файла. `mergeSchema` для Avro не позволяет ослаблять типы данных. Значение по умолчанию: `false`
`readerCaseSensitive` Тип: `Boolean` Задает параметры поведения в отношении чувствительности к регистру при активации `rescuedDataColumn`. Если значение true, сохраните столбцы данных, имена которых отличаются по регистру от имен в схеме; в противном случае считывайте данные без учета регистра. Значение по умолчанию: `true`
`rescuedDataColumn` Тип: `String` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных и несоответствия схемы (включая регистр столбцов) отдельному столбцу. Этот столбец включен по умолчанию при использовании Автозагрузчика. `COPY INTO` (устаревшая версия) не поддерживает спасательный столбец данных, так как невозможно вручную задать схему с помощью `COPY INTO`. Databricks рекомендует использовать Auto Loader для большинства сценариев загрузки. Дополнительные сведения см. в статье "Что такое столбец спасенных данных?". Значение по умолчанию: нет

`BINARYFILE` варианты

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

`TEXT` варианты

Вариант
`encoding` Тип: `String` Имя кодировки разделителя строк текстовых файлов. Список параметров см. в разделе `java.nio.charset.Charset`. Содержимое файла не затрагивается этим параметром и считывается as-is. Значение по умолчанию: `UTF-8`
`lineSep` Тип: `String` Строка между двумя последовательными текстовыми записями. Значение по умолчанию None (Нет) охватывает `\r`, `\r\n` и `\n`.
`wholeText` Тип: `Boolean` Следует ли считывать файл как одну запись. Значение по умолчанию: `false`

`ORC` варианты

Вариант
`mergeSchema` Тип: `Boolean` Следует ли определять схему на основе нескольких файлов и объединять схемы каждого файла. Значение по умолчанию: `false`

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

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

Вариант
`allowOverwrites` Тип: `Boolean` Следует ли повторно обрабатывать файлы, которые были изменены после обнаружения. Последняя доступная версия файла будет обработана во время обновления, если она была изменена с момента последнего успешного запуска запроса обновления. Значение по умолчанию: `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;

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

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-04-20

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