Функция с табличным значением `read_files`

Статья
04/18/2024

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

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

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

Синтаксис

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

Аргументы

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

pathSTRING: с универсальным кодом ресурса (URI) расположения данных. Поддерживает чтение из Azure Data Lake Storage 2-го поколения ('abfss://'), S3 (s3://) и Google Cloud служба хранилища ('gs://'). Может содержать глобы. Дополнительные сведения см. в статье об обнаружении файлов.
option_key: имя параметра для настройки. Для параметров, содержащих точки (), необходимо использовать обратные знаки (.').
option_value: константное выражение для задания параметра. Принимает литералы и скалярные функции.

Возвраты

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

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

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

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

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

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

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

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

Вариант
`format` Тип: `String` Формат файла данных в исходном пути. Автоматическое вывод, если оно не указано. Допустимые значения: * `avro`: файл Avro * `binaryFile`: двоичный файл * `csv`: чтение и запись в CSV-файлы * `json`: JSON-файл * `orc`: ORC-файл * `parquet`: чтение файлов Parquet с помощью Azure Databricks * `text`: текстовые файлы * `xml`: чтение и запись XML-файлов Значение по умолчанию: нет
`inferColumnTypes` Тип: `Boolean` Следует ли выводить точные типы столбцов при использовании вывода схемы. По умолчанию столбцы выводятся при выводе наборов данных JSON и CSV. Дополнительные сведения см. в разделе Вывод схемы. Обратите внимание, что это противоположность по умолчанию автозагрузчика. Значение по умолчанию: `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` в столбце `operationMetrics` журнала Delta Lake. Доступно в 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` Следует ли пропустить вывод секции во время вывода схемы. Это не влияет на загрузку файлов. Значение по умолчанию: `false`

`JSON` options

Вариант
`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. Значение по умолчанию: нет
`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` не с плавающей или двойной тип, когда это возможно. Кроме того, необходимо использовать вывод схемы, включив его. `inferSchema` или используется `cloudFiles.inferColumnTypes` с автозагрузчиком. Значение по умолчанию: `false`
`primitivesAsString` Тип: `Boolean` Выводить ли примитивные типы, такие как числа и логические значения, как `StringType`. Значение по умолчанию: `false`
`readerCaseSensitive` Тип: `Boolean` Указывает поведение учета регистра при включении `rescuedDataColumn`. Если значение равно true, столбцы данных, имена которых отличаются по регистру от схемы, восстанавливаются; в противном случае данные считываются без учета регистра. Доступно в Databricks Runtime 13.3 и выше. Значение по умолчанию: `true`
`rescuedDataColumn` Тип: `String` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных или несоответствия схем (включая регистр столбцов), в отдельный столбец. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в разделе "Что такое столбец спасенных данных?". Значение по умолчанию: нет
`timestampFormat` Тип: `String` Формат для синтаксического анализа строк меток времени. Значение по умолчанию: `yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`
`timeZone` Тип: `String` Объект `java.time.ZoneId`, используемый при анализе меток времени и дат. Значение по умолчанию: нет

`CSV` options

Вариант
`badRecordsPath` Тип: `String` Путь для хранения файлов для записи сведений о неправильных записях CSV. Значение по умолчанию: нет
`charToEscapeQuoteEscaping` Тип: `Char` Символ, используемый для экранирования символа, используемого для экранирования кавычек. Например, для следующей записи: `[ " a\\", b ]`: * Если символ для экранирования `'\'` не определен, запись не будет проанализирована. Средство синтаксического анализа будет считывать символы: `[a],[\],["],[,],[ ],[b]` и вызывать ошибку, так как не сможет найти закрывающую кавычку. * Если символ для экранирования `'\'` определяется как `'\'`, запись будет считываться с 2 значениями: `[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` Занимает ли запись JSON несколько строк. Значение по умолчанию: `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` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных или несоответствия схем (включая регистр столбцов), в отдельный столбец. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в статье "Что такое столбец спасенных данных?". Значение по умолчанию: нет
`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` options

Вариант	Описание	Область действия
`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`	Настраиваемая строка формата метки времени, которая соответствует формату шаблона datetime. Это относится к типу `timestamp` . По умолчанию: `yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`.	чтение, запись
`timestampNTZFormat`	Строка настраиваемого формата для метки времени без часового пояса, которая соответствует формату шаблона datetime. Это относится к типу TimestampNTZType. По умолчанию: `yyyy-MM-dd'T'HH:mm:ss[.SSS]`	чтение, запись
`dateFormat`	Строка настраиваемого формата даты, которая соответствует формату шаблона datetime. Это относится к типу date. По умолчанию: `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`, `gziplz4snappy', and<br>`дефляция). Встроенные функции XML игнорируют этот параметр. По умолчанию: `none`.	запись
`validateName`	Если значение true, вызывает ошибку при проверке имени XML-элемента. Например, имена полей SQL могут иметь пробелы, но имена XML-элементов не могут. По умолчанию: `true`.	запись
`readerCaseSensitive`	Указывает поведение конфиденциальности регистра при включенном параметре rescuedDataColumn. Если значение равно true, столбцы данных, имена которых отличаются по регистру от схемы, восстанавливаются; в противном случае данные считываются без учета регистра. По умолчанию: `true`.	чтение
`rescuedDataColumn`	Следует ли собирать все данные, которые нельзя проанализировать из-за несоответствия типов данных и несоответствия схемы (включая регистр столбцов) отдельному столбцу. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в разделе "Что такое спасенных столбцов данных?". Значение по умолчанию: нет.	чтение

`PARQUET` options

Вариант
`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` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных или несоответствия схем (включая регистр столбцов), в отдельный столбец. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в статье "Что такое столбец спасенных данных?". Значение по умолчанию: нет

`AVRO` options

Вариант
`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` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных или несоответствия схем (включая регистр столбцов), в отдельный столбец. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в статье "Что такое столбец спасенных данных?". Значение по умолчанию: нет

`BINARYFILE` options

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

`TEXT` options

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

`ORC` options

Вариант
`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);

Поделиться через

Функция с табличным значением `read_files`

Синтаксис

Аргументы

Возвраты

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

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

Вывод схемы

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

Использование в таблицах потоковой передачи

Параметры

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

Универсальные параметры

`JSON` options

`CSV` options

`XML` options

`PARQUET` options

`AVRO` options

`BINARYFILE` options

`TEXT` options

`ORC` options

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

Примеры

Дополнительные ресурсы

Поделиться через

Функция с табличным значением read_files

Синтаксис

Аргументы

Возвраты

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

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

Вывод схемы

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

Использование в таблицах потоковой передачи

Параметры

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

Универсальные параметры

JSON options

CSV options

XML options

PARQUET options

AVRO options

BINARYFILE options

TEXT options

ORC options

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

Примеры

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

Дополнительные ресурсы

Функция с табличным значением `read_files`

`JSON` options

`CSV` options

`XML` options

`PARQUET` options

`AVRO` options

`BINARYFILE` options

`TEXT` options

`ORC` options