Функция с табличным значением read_files
Область применения: Databricks SQL Databricks Runtime 13.3 LTS и выше
Считывает файлы в заданном расположении и возвращает данные в табличной форме.
Поддерживает чтениеJSON
, CSV
, XML
PARQUET
AVRO
TEXT
BINARYFILE
и ORC
форматы файлов.
Может автоматически обнаруживать формат файла и выводить единую схему во всех файлах.
Синтаксис
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
: константное выражение для задания параметра. Принимает литералы и скалярные функции.
Возвраты
Таблица, состоящая из данных из файлов, считываемых в заданном виде 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
используется образец данных для вывода схемы и может развивать схему по мере обработки дополнительных данных. Дополнительные сведения см. в статье Настройка развития и вывода схемы в автозагрузчике.
Параметры
- Базовые параметры
- Универсальные параметры
- Параметры
JSON
- Параметры
CSV
- Параметры
XML
- Параметры
PARQUET
- Параметры
AVRO
- Параметры
BINARYFILE
- Параметры
TEXT
- Параметры
ORC
- Параметры потоковой передачи
Основные параметры
Вариант |
---|
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 Runtime13.3 и выше. Значение по умолчанию: true |
rescuedDataColumn Тип: String Следует ли собирать все данные, которые не могут быть проанализированы из-за несоответствия типов данных или несоответствия схем (включая регистр столбцов), в отдельный столбец. Этот столбец включен по умолчанию при использовании Автозагрузчика. Дополнительные сведения см. в разделе "Что такое столбец спасенных данных?". Значение по умолчанию: нет |
singleVariantColumn Тип: String Следует ли принять весь документ JSON, проанализированный в один столбец Variant с заданной строкой в качестве имени столбца. При отключении поля JSON будут приема в собственные столбцы. Значение по умолчанию: нет |
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 , gzip lz4 и snappy deflate ). Встроенные функции 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);