функция `read_files`table-valued

Статья
12/27/2024

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

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

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

Синтаксис

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

Аргументы

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

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

Возвраты

table состоит из данных из файлов, считываемых в соответствии с заданным path.

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

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

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

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

Расписание	Description
`?`	Соответствует любому одиночному знаку
`*`	Соответствует нескольким символам или их отсутствию
`[abc]`	Соответствует одному символу из символа set {a,b,c}.
`[a-z]`	Соответствует одиночному символу из диапазона символов {a…z}.
`[^a]`	Соответствует одному символу, который не является символом set и не входит в диапазон {a}. Обратите внимание, что символ `^` должен стоять непосредственно справа от открывающей скобки.
`{ab,cd}`	Соответствует строке из строки set {ab, cd}.
`{ab,c{de, fh}}`	Соответствует строке из строки set {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`	Да	Да

вывод Schema

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

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

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

вывод Partitionschema

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

Если column существует как в partitionschema, так и в columnsданных, то вместо значения данных используется значение, считываемое из значения partition. Если вы хотите игнорировать values, поступающие из каталога, и использовать данные column, можно указать listpartitioncolumns в разделенных запятыми list с параметром partitionColumns.

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

Можно также указать параметр schemaHints для переопределения выводимого schema для partitioncolumn.

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

Использование в трансляции tables

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

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

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

Вариант
`format` Тип: `String` Формат файла данных в исходном пути. Автоматическое вывод, если оно не указано. Допустимые values включают: - `avro`: файл Avro - `binaryFile`: двоичный файл - `csv`: чтение CSV-файлов - `json`: JSON-файл - `orc`: ORC-файл - `parquet`: чтение файлов Parquet с помощью Azure Databricks - `text`: текстовые файлы - `xml`: чтение и запись XML-файлов Значение по умолчанию: нет
`inferColumnTypes` Тип: `Boolean` Следует ли выводить точные типы column при использовании вывода schema. По умолчанию columns определяются при интерпретации наборов данных JSON и CSV. Подробнее см. в schema умозаключений. Обратите внимание, что это противоположность по умолчанию автозагрузчика. Значение по умолчанию: `true`
`partitionColumns` Тип: `String` Разделяемый запятыми list стиля Hive partitioncolumns, который вы хотите вывести из структуры каталогов файлов. Стиль Hive partitioncolumns представляют собой пары "ключ-значение", объединенные знаком равенства. `<base-path>/a=x/b=1/c=y/file.format`. В этом примере partitioncolumns являются `a`, `b`и `c`. По умолчанию эти columns будут автоматически добавлены в ваш schema, если вы используете инференцию schema и предоставляете `<base-path>` для загрузки данных. Если вы предоставляете schema, автоматический загрузчик ожидает, что эти columns будут включены в schema. Если вы не хотите, чтобы эти columns в составе schema, можно указать `""`, чтобы игнорировать эти columns. Кроме того, этот параметр можно использовать, если вы хотите, чтобы columns выводить путь к файлу в сложных структурах каталогов, как показано ниже: `<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`columns будут `null`. `month` и `day` будут правильно проанализированы для `file2.csv` и `file3.csv`. Значение по умолчанию: нет
`schemaHints` Тип: `String` Schema сведения, предоставляемые автозагрузчику во время вывода schema. Дополнительные сведения см. в подсказках schema. Значение по умолчанию: нет
`useStrictGlobber` Тип: `Boolean` Следует ли использовать строгий глоббер, соответствующий по умолчанию поведением глоббинга других источников файлов в Apache Spark. Дополнительные сведения см . в общих шаблонах загрузки данных. Доступно в Databricks Runtime 12.2 LTS и более поздних версиях. Обратите внимание, что это противоположность по умолчанию для автозагрузчика. Значение по умолчанию: `true`

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

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

Вариант
`ignoreCorruptFiles` Тип: `Boolean` Определяет, следует ли игнорировать поврежденные файлы. Если задано значение true, задания Spark будут продолжать выполняться при обнаружении поврежденных файлов, а прочитанное содержимое будет возвращено. Наблюдаемое как `numSkippedCorruptFiles` в `operationMetrics` column в истории 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` Следует ли пропускать вывод partition во время вывода schema. Это не влияет на загрузку файлов. Значение по умолчанию: `false`

`JSON` options

Вариант
`allowBackslashEscapingAnyCharacter` Тип: `Boolean` Разрешить ли обратные косые черты для экранирования любого символа, который следует за ними. Если параметр не включен, экранировать можно только те символы, которые явно указаны в спецификации JSON. Значение по умолчанию: `false`
`allowComments` Тип: `Boolean` Разрешить ли использование комментариев в стиле Java, C и C++ (видов `'/'`, `'*'` и `'//'`) в проанализированном содержимом. Значение по умолчанию: `false`
`allowNonNumericNumbers` Тип: `Boolean` Следует ли разрешать использование маркеров не-числа set (`NaN`) в качестве допустимых чисел с плавающей запятой values. Значение по умолчанию: `true`
`allowNumericLeadingZeros` Тип: `Boolean` Разрешить ли целочисленное число начинаться с дополнительных (игнорируемых) нули (например, `000001`). Значение по умолчанию: `false`
`allowSingleQuotes` Тип: `Boolean` Разрешено ли использовать одинарные кавычки (apostrophe, символ `'\'`) для кворирования строк (имен и строковых values). Значение по умолчанию: `true`
`allowUnquotedControlChars` Тип: `Boolean` Разрешить ли строкам JSON содержать неэкранированные управляющие символы (символы ASCII со значением меньше 32, включая символы табуляции и перевода строки). Значение по умолчанию: `false`
`allowUnquotedFieldNames` Тип: `Boolean` Разрешить ли использование имен полей, не заключенных в кавычки (которые разрешены в JavaScript, но не в спецификации JSON). Значение по умолчанию: `false`
`badRecordsPath` Тип: `String` Путь для хранения файлов для записи сведений о неправильных записях JSON. Значение по умолчанию: нет
`columnNameOfCorruptRecord` Тип: `String` column для хранения записей, которые неправильно сформированы и не могут быть проанализированы. Если `mode` для синтаксического анализа равен set как `DROPMALFORMED`, этот column будет пустым. Значение по умолчанию: `_corrupt_record`
`dateFormat` Тип: `String` Формат синтаксического анализа строк даты. Значение по умолчанию: `yyyy-MM-dd`
`dropFieldIfAllNull` Тип: `Boolean` Следует ли игнорировать columns всех пустых values или пустых массивов и структур во время вывода schema. Значение по умолчанию: `false`
`encoding` или `charset` Тип: `String` Имя кодировки файлов JSON. См. `java.nio.charset.Charset` для list вариантов. Нельзя использовать `UTF-16` и `UTF-32`, если `multiline` имеет значение `true`. Значение по умолчанию: `UTF-8`
`inferTimestamp` Тип: `Boolean` Попытаться ли вывести строки меток времени как `TimestampType`. Когда set до `true`, schema вывод может занять заметно больше времени. Необходимо включить `cloudFiles.inferColumnTypes` использование с автозагрузчиком. Значение по умолчанию: `false`
`lineSep` Тип: `String` Строка между двумя последовательными записями JSON. Значение по умолчанию None (Нет) охватывает `\r`, `\r\n` и `\n`.
`locale` Тип: `String` `java.util.Locale` identifier. Влияет на синтаксический анализ даты, метки времени и десятичного разделителя по умолчанию в JSON. Значение по умолчанию: `US`
`mode` Тип: `String` Режим средства синтаксического анализа для обработки неправильных записей. Возможные значения: `'PERMISSIVE'`, `'DROPMALFORMED'` или `'FAILFAST'`. Значение по умолчанию: `PERMISSIVE`
`multiLine` Тип: `Boolean` Занимает ли запись JSON несколько строк. Значение по умолчанию: `false`
`prefersDecimal` Тип: `Boolean` Пытается выводить строки как `DecimalType` не с плавающей или двойной тип, когда это возможно. Вы также должны использовать schema вывод, например, включая `inferSchema` или используется `cloudFiles.inferColumnTypes` с автозагрузчиком. Значение по умолчанию: `false`
`primitivesAsString` Тип: `Boolean` Выводить ли примитивные типы, такие как числа и логические значения, как `StringType`. Значение по умолчанию: `false`
`readerCaseSensitive` Тип: `Boolean` Указывает поведение учета регистра при включении `rescuedDataColumn`. Если значение true, восстановите данные columns, имена которых отличаются по регистру от schema; в противном случае считывайте данные без учета регистра. Доступно в Databricks Runtime 13.3 и выше. Значение по умолчанию: `true`
`rescuedDataColumn` Тип: `String` Следует ли собирать все данные, которые не удается обработать из-за несоответствия типа данных или несоответствия schema (включая несоответствие регистра column), в отдельный column. Эта column включена по умолчанию при использовании автозагрузчика. Дополнительные сведения см. в статье Что такое спасенные данные? column. Значение по умолчанию: нет
`singleVariantColumn` Тип: `String` Следует ли загрузить весь документ JSON, разобранный в один вариант column с заданной строкой в качестве имени column. Если этот параметр отключен, поля JSON будут включены в собственные columns. Значение по умолчанию: нет
`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 values: `[a\]` и `[b]`. Значение по умолчанию: `'\0'`
`columnNameOfCorruptRecord` Поддержка для автозагрузчика. Не поддерживается для `COPY INTO`. Тип: `String` column для хранения записей, которые неправильно сформированы и не могут быть проанализированы. Если `mode` для синтаксического анализа равно set, то `DROPMALFORMED`, этот column будет пустым. Значение по умолчанию: `_corrupt_record`
`comment` Тип: `Char` Определяет символ, обозначающий, что строка является комментарием, если он будет найден в начале строки текста. Используйте `'\0'`, чтобы отключить пропуск комментария. Значение по умолчанию: `'\u0000'`
`dateFormat` Тип: `String` Формат синтаксического анализа строк даты. Значение по умолчанию: `yyyy-MM-dd`
`emptyValue` Тип: `String` Строковое представление пустого значения. Значение по умолчанию: `""`
`encoding` или `charset` Тип: `String` Имя кодировки CSV-файлов. См. `java.nio.charset.Charset` для list вариантов. `UTF-16` и `UTF-32` использовать нельзя, если `multiline` имеет значение `true`. Значение по умолчанию: `UTF-8`
`enforceSchema` Тип: `Boolean` Следует ли принудительно применять указанные или выведенные schema к CSV-файлам. Если параметр включен, заголовки CSV-файлов игнорируются. Этот параметр игнорируется по умолчанию при использовании Auto Loader для восстановления данных и позволения эволюции schema. Значение по умолчанию: `true`
`escape` Тип: `Char` Escape-символ, используемый при анализе данных. Значение по умолчанию: `'\'`
`header` Тип: `Boolean` Содержат ли CSV-файлы заголовок. Автоматический загрузчик предполагает, что файлы содержат заголовки при определении schema. Значение по умолчанию: `false`
`ignoreLeadingWhiteSpace` Тип: `Boolean` Следует ли игнорировать начальные пробелы для каждого анализируемого значения. Значение по умолчанию: `false`
`ignoreTrailingWhiteSpace` Тип: `Boolean` Следует ли игнорировать конечные пробелы для каждого анализируемого значения. Значение по умолчанию: `false`
`inferSchema` Тип: `Boolean` Следует ли вывести типы данных проанализированных записей CSV или предположить, что все columns являются `StringType`. Требуется дополнительная передача данных, если set в `true`. Для автозагрузчика используйте `cloudFiles.inferColumnTypes` вместо этого. Значение по умолчанию: `false`
`lineSep` Тип: `String` Строка между двумя последовательными записями CSV. Значение по умолчанию None (Нет) охватывает `\r`, `\r\n` и `\n`.
`locale` Тип: `String` `java.util.Locale` identifier. Влияет на синтаксический анализ даты, метки времени и десятичного разделителя по умолчанию в CSV-файле. Значение по умолчанию: `US`
`maxCharsPerColumn` Тип: `Int` Максимальное число символов, ожидаемое в значении для синтаксического анализа. Можно использовать, чтобы избежать ошибок памяти. По умолчанию имеет значение `-1`, что означает отсутствие ограничений. Значение по умолчанию: `-1`
`maxColumns` Тип: `Int` Максимальное количество columns, которое может иметь запись - limit. Значение по умолчанию: `20480`
`mergeSchema` Тип: `Boolean` Нужно ли извлекать schema в нескольких файлах и объединять schema каждого файла. Включен по умолчанию для автозагрузчика при выводе schema. Значение по умолчанию: `false`
`mode` Тип: `String` Режим средства синтаксического анализа для обработки неправильных записей. Возможные значения: `'PERMISSIVE'`, `'DROPMALFORMED'` и `'FAILFAST'`. Значение по умолчанию: `PERMISSIVE`
`multiLine` Тип: `Boolean` Занимает ли запись JSON несколько строк. Значение по умолчанию: `false`
`nanValue` Тип: `String` Строковое представление значения, отличного от числа, при анализе `FloatType` и `DoubleType`columns. Значение по умолчанию: `"NaN"`
`negativeInf` Тип: `String` Строковое представление отрицательной бесконечности при анализе `FloatType` или `DoubleType`columns. Значение по умолчанию: `"-Inf"`
`nullValue` Тип: `String` Строковое представление значения NULL. Значение по умолчанию: `""`
`parserCaseSensitive` (не рекомендуется) Тип: `Boolean` При чтении файлов, следует ли выравнивать columns, объявленные в заголовке, с учетом регистра schema. Это значение равно `true` по умолчанию для Автозагрузчика. Columns, которые отличаются по регистру, будут сохранены в `rescuedDataColumn`, если это включено. Вместо этого параметра рекомендуется использовать `readerCaseSensitive`. Значение по умолчанию: `false`
`positiveInf` Тип: `String` Строковое представление положительной бесконечности при анализе `FloatType` или `DoubleType`columns. Значение по умолчанию: `"Inf"`
`preferDate` Тип: `Boolean` Пытается вывести строки как даты вместо метки времени, когда это возможно. Кроме того, необходимо использовать вывод schema либо путем включения `inferSchema`, либо другим способом. `cloudFiles.inferColumnTypes` с автозагрузчиком. Значение по умолчанию: `true`
`quote` Тип: `Char` Символ, используемый для экранирования разделителя полей valueswhere, является частью значения. Значение по умолчанию: `"`
`readerCaseSensitive` Тип: `Boolean` Указывает поведение учета регистра при включении `rescuedDataColumn`. Если истинно, восстановите данные columns, имена которых отличаются по регистру от schema; в противном случае читайте данные без учета регистра. Значение по умолчанию: `true`
`rescuedDataColumn` Тип: `String` Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных и несоответствия schema, включая регистр column, в отдельный column. Эта column включена по умолчанию при использовании Auto Loader. Дополнительные сведения см. в статье Что такое спасенные данные column?. Значение по умолчанию: нет
`sep` или `delimiter` Тип: `String` Строка разделителя между columnsи остальной частью текста. Значение по умолчанию: `","`
`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`. Если неисканные кавычки находятся во входных данных, содержимое, проанализированное для заданного значения, будет пропущено (пока не будет найдено следующее разделителя), а значение set в `nullValue` будет создано вместо этого. - `RAISE_ERROR`: если во входных данных обнаружены неэкранированные кавычки возникнет исключение `TextParsingException`. Значение по умолчанию: `STOP_AT_DELIMITER`

`XML` options

Вариант	Description	Область действия
`rowTag`	Тег строки XML-файлов, которые будут рассматриваться как строка. В примере XML `<books> <book><book>...<books>`соответствующее значение имеет значение `book`. Это обязательный параметр.	чтение
`samplingRatio`	Определяет долю строк, используемых для вывода schema. Встроенные функции XML игнорируют этот параметр. По умолчанию: `1.0`.	чтение
`excludeAttribute`	Следует ли исключать атрибуты в элементах. По умолчанию: `false`.	чтение
`mode`	Режим работы с поврежденными записями во время синтаксического анализа. `PERMISSIVE`: для поврежденных записей помещает недоформированную строку в поле, настроенное `columnNameOfCorruptRecord`и задает неправильно сформированные поля `null`. Чтобы сохранить поврежденные записи, можно set поле типа `string` с именем `columnNameOfCorruptRecord` в определяемом пользователем schema. Если schema не имеет поля, во время синтаксического анализа удаляются поврежденные записи. При выводе schemaсредство синтаксического анализа неявно добавляет поле `columnNameOfCorruptRecord` в выходной schema. `DROPMALFORMED`: игнорирует поврежденные записи. Этот режим не поддерживается для встроенных функций XML. `FAILFAST`: создает исключение, когда средство синтаксического анализа соответствует поврежденным записям.	чтение
`inferSchema`	Если `true`, пытается определить соответствующий тип для каждого результирующего columnкадра данных. Если `false`, все полученные columns имеют тип `string`. По умолчанию: `true`. Встроенные функции XML игнорируют этот параметр.	чтение
`columnNameOfCorruptRecord`	Позволяет переименовать новое поле, содержащее неправильно сформированную строку, созданную `PERMISSIVE` режим. По умолчанию: `spark.sql.columnNameOfCorruptRecord`.	чтение
`attributePrefix`	Префикс атрибутов для отличия атрибутов от элементов. Это будет префикс для имен полей. По умолчанию — `_`. Может быть пустым для чтения XML, но не для записи.	чтение, запись
`valueTag`	Тег, используемый для символьных данных в элементах, которые также имеют атрибуты или дочерние элементы. Пользователь может указать поле `valueTag` в schema, или оно будет добавлено автоматически во время вывода данных schema при наличии символьных данных в элементах с другими элементами или атрибутами. По умолчанию: `_VALUE`	чтение, запись
`encoding`	Для чтения декодирует XML-файлы по заданному типу кодирования. Для записи задает кодировку (charset) сохраненных XML-файлов. Встроенные функции XML игнорируют этот параметр. По умолчанию: `UTF-8`.	чтение, запись
`ignoreSurroundingSpaces`	Определяет, следует ли пропускать окружающие пробелы при чтении values. По умолчанию: `true`. Данные символов, доступные только для пробелов, игнорируются.	чтение
`rowValidationXSDPath`	Путь к необязательному XSD-файлу, который используется для проверки XML для каждой строки по отдельности. Строки, которые не удается проверить, обрабатываются как ошибки синтаксического анализа, как описано выше. XSD не влияет на предоставленные schema или вывод.	чтение
`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`	Строка пользовательского формата для временной метки без timezone, соответствующая шаблону формата даты и времени. Это относится к типу 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?>` записи. Замени Set на пустую строку, чтобы подавить. По умолчанию: `version="1.0"` `encoding="UTF-8" standalone="yes"`.	запись
`arrayElementName`	Имя XML-элемента, который заключает каждый элемент массива, имеющего значение column при записи. По умолчанию: `item`.	запись
`nullValue`	Задает строковое представление значения NULL. Значение по умолчанию: строка `null`. При этом `null`средство синтаксического анализа не записывает атрибуты и элементы для полей.	чтение, запись
`compression`	Код сжатия, используемый при сохранении в файл. Это может быть одно из известных имен без учета регистра (`none`, , `bzip2`, `gziplz4`и `snappy` `deflate`). Встроенные функции XML игнорируют этот параметр. По умолчанию: `none`.	запись
`validateName`	Если значение true, вызывает ошибку при проверке имени XML-элемента. Например, имена полей SQL могут иметь пробелы, но имена XML-элементов не могут. По умолчанию: `true`.	запись
`readerCaseSensitive`	Указывает поведение конфиденциальности регистра при включенном параметре rescuedDataColumn. Если это правда, сохраняйте данные columns, имена которых отличаются по регистру от schema; в противном случае считывайте данные без учета регистра. По умолчанию: `true`.	чтение
`rescuedDataColumn`	Следует ли собирать все данные, которые не удается обработать из-за несоответствия типов данных и несоответствия schema (включая разницу в регистре column), в отдельный column? Параметр column включен по умолчанию при использовании автозагрузчика. Дополнительные сведения см. в разделе Что такое спасенные данные column?. Значение по умолчанию: нет.	чтение

`PARQUET` options

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

`AVRO` options

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

`BINARYFILE` options

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

`TEXT` options

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

`ORC` options

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

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

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

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

Примеры

-- 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`table-valued

Синтаксис

Аргументы

Возвраты

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

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

вывод Schema

вывод Partitionschema

Использование в трансляции tables

Параметры

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

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

`JSON` options

`CSV` options

`XML` options

`PARQUET` options

`AVRO` options

`BINARYFILE` options

`TEXT` options

`ORC` options

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

Примеры

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

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

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

функция read_filestable-valued

Синтаксис

Аргументы

Возвраты

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

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

вывод Schema

вывод Partitionschema

Использование в трансляции tables

Параметры

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

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

JSON options

CSV options

XML options

PARQUET options

AVRO options

BINARYFILE options

TEXT options

ORC options

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

Примеры

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

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

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

функция `read_files`table-valued

`JSON` options

`CSV` options

`XML` options

`PARQUET` options

`AVRO` options

`BINARYFILE` options

`TEXT` options

`ORC` options