read_files função com valor de tabela

Aplica-se a: Databricks SQL Databricks Runtime 13.3 LTS e versões superiores

Lê arquivos em um local fornecido e retorna os dados em forma de tabela.

Suporta leitura JSON, CSV, XML, TEXT, BINARYFILE, PARQUET, AVRO, e ORC formatos de arquivo. Pode detetar o formato de arquivo automaticamente e inferir um esquema unificado em todos os arquivos.

Sintaxe

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

Argumentos

Esta função requer invocação de parâmetro nomeado para as chaves de opção.

• path: A STRING com o URI da localização dos dados. Suporta leitura do Azure Data Lake Storage ('abfss://'), S3 (s3://) e Google Cloud Storage ('gs://'). Pode conter globs. Consulte Descoberta de arquivos para obter mais detalhes.
• option_key: O nome da opção a ser configurada. Você precisa usar os backticks () for options that contain dots (.`).
• option_value: Uma expressão constante para definir a opção. Aceita literais e funções escalares.

Devoluções

Uma tabela composta pelos dados dos ficheiros lidos conforme o dado path.

Descoberta de arquivos

read_files É capaz de ler um arquivo individual ou ler arquivos em um diretório fornecido. read_files descobre todos os ficheiros no diretório fornecido de forma recursiva, exceto se for fornecido um glob, que especifica ao read_files para recursar num padrão específico de diretório.

Filtrando diretórios ou arquivos usando padrões glob

Os padrões de Glob podem ser usados para filtrar diretórios e arquivos quando fornecidos no caminho.

Padrão	Descrição
?	Corresponde a qualquer caractere
*	Corresponde a zero ou mais caracteres
[abc]	Corresponde a um único caractere do conjunto de caracteres {a,b,c}.
[a-z]	Corresponde a um único caractere do intervalo de caracteres {a... z}.
[^a]	Corresponde a um único caractere que não é do conjunto de caracteres ou intervalo {a}. Observe que o ^ caractere deve ocorrer imediatamente à direita do colchete de abertura.
{ab,cd}	Corresponde a uma string do conjunto de strings {ab, cd}.
{ab,c{de, fh}}	Corresponde a uma string do conjunto de strings {ab, cde, cfh}.

read_files usa o globber rigoroso do Auto Loader ao identificar ficheiros com globs. Isso é configurado pela useStrictGlobber opção. Quando o globber estrito é desativado, as barras finais (/) são descartadas e um padrão de asterisco como /*/ pode expandir-se para descobrir vários diretórios. Veja os exemplos abaixo para ver a diferença de comportamento.

Padrão	Caminho do ficheiro	Globber em modo estrito desativado	Globber rigoroso ativado
/a/b	/a/b/c/file.txt	Sim	Sim
/a/b	/a/b_dir/c/file.txt	Não	Não
/a/b	/a/b.txt	Não	Não
/a/b/	/a/b.txt	Não	Não
/a/*/c/	/a/b/c/file.txt	Sim	Sim
/a/*/c/	/a/b/c/d/file.txt	Sim	Sim
/a/*/d/	/a/b/c/d/file.txt	Sim	Não
/a/*/c/	/a/b/x/y/c/file.txt	Sim	Não
/a/*/c	/a/b/c_file.txt	Sim	Não
/a/*/c/	/a/b/c_file.txt	Sim	Não
/a/*/c	/a/b/cookie/file.txt	Sim	Não
/a/b*	/a/b.txt	Sim	Sim
/a/b*	/a/b/file.txt	Sim	Sim
/a/{0.txt,1.txt}	/a/0.txt	Sim	Sim
/a/*/{0.txt,1.txt}	/a/0.txt	Não	Não
/a/b/[cde-h]/i/	/a/b/c/i/file.txt	Sim	Sim

Inferência do esquema

O esquema dos ficheiros pode ser explicitamente fornecido a read_files com a opção schema. Quando o esquema não é fornecido, read_files tenta inferir um esquema unificado nos arquivos descobertos, o que requer a leitura de todos os arquivos, a menos que uma LIMIT instrução seja usada. Mesmo ao usar uma LIMIT consulta, um conjunto maior de arquivos do que o necessário pode ser lido para retornar um esquema mais representativo dos dados. O Databricks adiciona automaticamente uma LIMIT instrução para SELECT consultas em notebooks e no editor SQL, se um utilizador não tiver fornecido uma.

A schemaHints opção pode ser usada para corrigir subconjuntos do esquema inferido. Consulte Como substituir a inferência de esquema por dicas de esquema para obter mais detalhes.

A rescuedDataColumn é fornecido por padrão para recuperar quaisquer dados que não correspondam ao esquema. Consulte O que é a coluna de dados resgatados? para obter mais detalhes. Você pode soltar o rescuedDataColumn definindo a opção schemaEvolutionMode => 'none'.

Inferência de esquema de partição

read_files também pode inferir colunas de partição se os arquivos forem armazenados em diretórios particionados ao estilo Hive, ou seja /column_name=column_value/. Se um schema for fornecido, as colunas de partição descobertas usarão os tipos fornecidos no schema. Se as colunas de partição não fizerem parte do fornecido schema, as colunas de partição inferidas serão ignoradas.

Se existir uma coluna no esquema de partição e nas colunas de dados, o valor lido a partir do valor da partição será usado em vez do valor de dados. Se você quiser ignorar os valores provenientes do diretório e usar a coluna de dados, você pode fornecer a lista de colunas de partição em uma lista separada por vírgulas com a partitionColumns opção.

A partitionColumns opção também pode ser usada para instruir read_files sobre quais colunas descobertas devem ser incluídas no esquema inferido final. Fornecer uma cadeia de caracteres vazia ignora todas as colunas de partição.

A schemaHints opção também pode ser fornecida para substituir o esquema inferido para uma coluna de partição.

Os TEXT formatos e BINARYFILE têm um esquema fixo, mas read_files também tentam inferir particionamento para esses formatos quando possível.

Uso em tabelas de streaming

read_files pode ser usado em tabelas de streaming para ingerir arquivos no Delta Lake. read_files tira partido do Auto Loader quando usado numa consulta de tabela de streaming. Você deve usar a STREAM palavra-chave com read_files. Consulte O que é o Auto Loader? para obter mais detalhes.

Quando usado em uma consulta de streaming, read_files usa uma amostra dos dados para inferir o esquema e pode evoluir o esquema à medida que processa mais dados. Consulte Configurar inferência e evolução de esquema no Auto Loader para obter mais detalhes.

Opções

• Opções básicas
• Opções genéricas
• JSON Opções
• CSV Opções
• XML Opções
• PARQUET Opções
• AVRO Opções
• BINARYFILE Opções
• TEXT Opções
• ORC Opções
• Opções de streaming

Opções básicas

Opção
format Tipo: String O formato de ficheiro de dados no caminho de origem. Inferido automaticamente se não for fornecido. Os valores permitidos incluem: avro: Arquivo Avro binaryFile: Arquivo binário csv: Ler arquivos CSV json: arquivo JSON orc: Arquivo ORC parquet: Ler ficheiros Parquet usando Azure Databricks text: Arquivos de texto xml: Ler e escrever ficheiros XML Valor padrão: Nenhum
inferColumnTypes Tipo: Boolean Decidir se se deve inferir tipos exatos de coluna ao utilizar a inferência de esquema. Por padrão, as colunas são inferidas ao inferir conjuntos de dados JSON e CSV. Consulte inferência de esquema para obter mais detalhes. Observe que isso é o oposto do padrão do Auto Loader. Valor predefinido: true
partitionColumns Tipo: String Uma lista separada por vírgulas de colunas de partição no estilo Hive que você gostaria de inferir da estrutura de diretórios dos arquivos. As colunas de partição no estilo Hive são pares chave-valor ligados por um sinal de igualdade, como <base-path>/a=x/b=1/c=y/file.format. Neste exemplo, as colunas de partição são a, be c. Por padrão, estas colunas serão adicionadas automaticamente ao seu esquema se estiver a utilizar a inferência de esquema e fornecer o <base-path> de onde carregar dados. Se você fornecer um esquema, o Auto Loader espera que essas colunas sejam incluídas no esquema. Se você não quiser essas colunas como parte do seu esquema, você pode especificar "" para ignorar essas colunas. Além disso, podes usar esta opção quando pretenderes que as colunas determinem o caminho do ficheiro em diretórios complexos, como no exemplo abaixo: <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 Especificando cloudFiles.partitionColumns como year,month,day retornará year=2022 para file1.csv, mas as colunas month e day serão null. month e day será analisado corretamente para file2.csv e file3.csv. Valor padrão: Nenhum
schemaHints Tipo: String Informações de esquema que você fornece ao Auto Loader durante a inferência do esquema. Veja dicas do esquema para mais detalhes. Valor padrão: Nenhum
useStrictGlobber Tipo: Boolean Se deve utilizar um globber estrito que corresponda ao comportamento padrão de globbing de outras fontes de arquivos no Apache Spark. Consulte Padrões comuns de carregamento de dados para obter mais detalhes. Disponível no Databricks Runtime 12.2 LTS e superior. Observe que isso é o oposto do padrão para Auto Loader. Valor predefinido: true

Opções genéricas

As opções a seguir se aplicam a todos os formatos de arquivo.

Opção
ignoreCorruptFiles Tipo: Boolean Se deve ignorar arquivos corrompidos. Se verdadeiro, os trabalhos do Spark continuarão a ser executados ao encontrar arquivos corrompidos e o conteúdo que foi lido ainda será retornado. Observável como numSkippedCorruptFiles na operationMetrics coluna da história do Lago Delta. Disponível em Databricks Runtime 11.3 LTS e superior. Valor predefinido: false
ignoreMissingFiles Tipo: Boolean Devem ser ignorados ficheiros em falta? Se verdadeiro, os trabalhos do Spark continuarão a ser executados ao encontrar arquivos ausentes e o conteúdo que foi lido ainda será retornado. Disponível em Databricks Runtime 11.3 LTS e superior. Valor padrão: false para Auto Loader, true para COPY INTO (legado)
modifiedAfter Tipo: Timestamp String, por exemplo, 2021-01-01 00:00:00.000000 UTC+0 Um carimbo de data/hora opcional como filtro para processar apenas ficheiros com um carimbo de data/hora de modificação posterior ao fornecido. Valor padrão: Nenhum
modifiedBefore Tipo: Timestamp String, por exemplo, 2021-01-01 00:00:00.000000 UTC+0 Um carimbo de data/hora opcional como filtro para ingerir apenas arquivos que tenham um carimbo de data/hora de modificação antes do carimbo de data/hora fornecido. Valor padrão: Nenhum
pathGlobFilter ou fileNamePattern Tipo: String Um padrão de glob potencial a ser fornecido para a escolha de ficheiros. Equivalente a PATTERN em COPY INTO (legado). fileNamePattern pode ser usado em read_files. Valor padrão: Nenhum
recursiveFileLookup Tipo: Boolean Esta opção pesquisa diretórios aninhados, mesmo que seus nomes não sigam um esquema de nomenclatura de partição como date=2019-07-01. Valor predefinido: false

JSON Opções

Opção
allowBackslashEscapingAnyCharacter Tipo: Boolean Se deve permitir que as barras invertidas escapem de qualquer personagem que a consiga. Se não estiver ativada, apenas os caracteres explicitamente enumerados na especificação JSON poderão ser escapados. Valor predefinido: false
allowComments Tipo: Boolean Se deve permitir o uso de comentários de estilo Java, C e C++ ('/', '*'e '//' variedades) dentro do conteúdo analisado ou não. Valor predefinido: false
allowNonNumericNumbers Tipo: Boolean Permitir o conjunto de tokens não-é-número (NaN) como valores legais de números flutuantes. Valor predefinido: true
allowNumericLeadingZeros Tipo: Boolean Permitir ou não que números integrais comecem com zeros adicionais (ignorantes) (por exemplo, 000001). Valor predefinido: false
allowSingleQuotes Tipo: Boolean Se deve permitir o uso de aspas simples (apóstrofo, caractere '\') para citar cadeias de caracteres (nomes e valores String). Valor predefinido: true
allowUnquotedControlChars Tipo: Boolean Se as cadeias de caracteres JSON devem conter caracteres de controle sem escape (caracteres ASCII com valor inferior a 32, incluindo caracteres de tabulação e alimentação de linha) ou não. Valor predefinido: false
allowUnquotedFieldNames Tipo: Boolean Se deve permitir o uso de nomes de campos não citados (que são permitidos pelo JavaScript, mas não pela especificação JSON). Valor predefinido: false
badRecordsPath Tipo: String O caminho para armazenar ficheiros onde se registam as informações sobre registos JSON incorretos. Usar a badRecordsPath opção em uma fonte de dados baseada em arquivo tem as seguintes limitações: Não é transacional e pode levar a resultados inconsistentes. Os erros transitórios são tratados como falhas. Valor padrão: Nenhum
columnNameOfCorruptRecord Tipo: String A coluna para armazenar registros que estão malformados e não podem ser analisados. Se o mode para análise estiver definido como DROPMALFORMED, esta coluna estará vazia. Valor predefinido: _corrupt_record
dateFormat Tipo: String O formato para analisar cadeias de caracteres de data. Valor predefinido: yyyy-MM-dd
dropFieldIfAllNull Tipo: Boolean Se as colunas de todos os valores nulos ou matrizes e estruturas vazias devem ser ignoradas durante a inferência do esquema. Valor predefinido: false
encoding ou charset Tipo: String O nome da codificação dos arquivos JSON. Consulte java.nio.charset.Charset para lista de opções. Você não pode usar UTF-16 e UTF-32 quando multiline é true. Valor predefinido: UTF-8
inferTimestamp Tipo: Boolean Se se deve tentar inferir cadeias de caracteres de carimbos de data/hora como um TimestampType. Quando definido como true, a inferência do esquema pode levar visivelmente mais tempo. Deve ativar cloudFiles.inferColumnTypes para utilizar com o Auto Loader. Valor predefinido: false
lineSep Tipo: String Uma cadeia de caracteres entre dois registros JSON consecutivos. Valor padrão: Nenhum, que abrange \r, \r\ne \n
locale Tipo: String Um java.util.Locale identificador. Influencia a data padrão, a marcação de data/hora e a análise decimal no JSON. Valor predefinido: US
mode Tipo: String Modo de parser relativo ao tratamento de registros malformados. Um de PERMISSIVE, DROPMALFORMEDou FAILFAST. Valor predefinido: PERMISSIVE
multiLine Tipo: Boolean Se os registros JSON abrangem várias linhas. Valor predefinido: false
prefersDecimal Tipo: Boolean Tenta inferir cadeias como DecimalType em vez de float ou double quando possível. Você também deve usar a inferência de esquema, habilitando inferSchema ou usando cloudFiles.inferColumnTypes com Auto Loader. Valor predefinido: false
primitivesAsString Tipo: Boolean Decidir se deve inferir tipos primitivos, como números e booleanos, como StringType. Valor predefinido: false
readerCaseSensitive Tipo: Boolean Especifica o comportamento de sensibilidade a maiúsculas e minúsculas quando rescuedDataColumn está habilitado. Se verdadeiro, recupere as colunas de dados cujos nomes têm diferenças de maiúsculas e minúsculas em relação ao esquema; caso contrário, leia os dados sem distinguir entre maiúsculas e minúsculas. Disponível no Databricks Runtime 13.3 ou superior. Valor predefinido: true
rescuedDataColumn Tipo: String Determinar se todos os dados que não podem ser processados devido a uma incompatibilidade de tipo de dados ou incompatibilidade de esquema (incluindo o casing das colunas) devem ser recolhidos numa coluna separada. Esta coluna é incluída por padrão ao usar o Auto Loader. Para obter mais detalhes, consulte O que é a coluna de dados resgatados?. COPY INTO (legado) não suporta a coluna de dados resgatados porque não é possível definir manualmente o esquema usando COPY INTO. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão. Valor padrão: Nenhum
singleVariantColumn Tipo: String Ingerir o documento JSON inteiro, analisado e transformado numa única coluna do tipo Variant, utilizando a string fornecida como nome da coluna. Se desativado, os campos JSON serão ingeridos em suas próprias colunas. Valor padrão: Nenhum
timestampFormat Tipo: String O formato para interpretar carimbos de data/hora. Valor predefinido: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone Tipo: String O java.time.ZoneId a ser usado ao interpretar datas e horas. Valor padrão: Nenhum

CSV Opções

Opção
badRecordsPath Tipo: String O caminho para armazenar ficheiros para registar informações sobre registos CSV defeituosos. Valor padrão: Nenhum
charToEscapeQuoteEscaping Tipo: Char O personagem usado para escapar do personagem usado para escapar de citações. Por exemplo, para o seguinte registo: [ " a\\", b ] Se o caractere '\' a ser escapado estiver indefinido, o registro não será analisado. O analisador lerá caracteres: [a],[\],["],[,],[ ],[b] e lançará um erro porque não consegue encontrar uma citação de fechamento. Se o caractere para escapar do '\' for definido como '\', o registro será lido com 2 valores: [a\] e [b]. Valor predefinido: '\0'
columnNameOfCorruptRecord Suportado para Auto Loader. Não suportado para COPY INTO (legado). Tipo: String A coluna para armazenar registros que estão malformados e não podem ser analisados. Se o mode para análise estiver definido como DROPMALFORMED, esta coluna estará vazia. Valor predefinido: _corrupt_record
comment Tipo: Char Define o caractere que representa um comentário de linha quando encontrado no início de uma linha de texto. Use '\0' para desativar a opção de saltar comentários. Valor predefinido: '\u0000'
dateFormat Tipo: String O formato para analisar cadeias de caracteres de data. Valor predefinido: yyyy-MM-dd
emptyValue Tipo: String Representação de cadeia de caracteres de um valor vazio. Valor predefinido: ""
encoding ou charset Tipo: String O nome da codificação dos arquivos CSV. Veja java.nio.charset.Charset para a lista de opções. UTF-16 e UTF-32 não pode ser usado quando multiline é true. Valor predefinido: UTF-8
enforceSchema Tipo: Boolean Se deve aplicar à força o esquema especificado ou inferido aos arquivos CSV. Se a opção estiver ativada, os cabeçalhos dos arquivos CSV serão ignorados. Esta opção é ignorada por padrão ao usar o Auto Loader para resgatar dados e permitir a evolução do esquema. Valor predefinido: true
escape Tipo: Char O caractere de escape a ser usado ao analisar os dados. Valor predefinido: '\'
header Tipo: Boolean Se os arquivos CSV contêm um cabeçalho. O Auto Loader assume que os arquivos têm cabeçalhos ao inferir o esquema. Valor predefinido: false
ignoreLeadingWhiteSpace Tipo: Boolean Se os espaços em branco iniciais devem ser ignorados para cada valor analisado. Valor predefinido: false
ignoreTrailingWhiteSpace Tipo: Boolean Se deve ignorar espaços em branco à direita para cada valor analisado. Valor predefinido: false
inferSchema Tipo: Boolean Se é necessário inferir os tipos de dados dos registros CSV analisados ou assumir que todas as colunas são de StringType. Requer uma passagem adicional sobre os dados, se definido como true. Para “Auto Loader”, utilize cloudFiles.inferColumnTypes em vez. Valor predefinido: false
lineSep Tipo: String Uma cadeia de caracteres entre dois registros CSV consecutivos. Valor padrão: Nenhum, que abrange \r, \r\ne \n
locale Tipo: String Um java.util.Locale identificador. Influencia a data padrão, o carimbo de data/hora e a análise decimal dentro do CSV. Valor predefinido: US
maxCharsPerColumn Tipo: Int Número máximo de caracteres esperados de um valor a ser analisado. Pode ser usado para evitar erros de memória. Por predefinição, é -1, que significa ilimitado. Valor predefinido: -1
maxColumns Tipo: Int O limite rígido de quantas colunas um registro pode ter. Valor predefinido: 20480
mergeSchema Tipo: Boolean Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. Ativado por padrão para o Auto Loader ao inferir o esquema. Valor predefinido: false
mode Tipo: String Modo de parser relativo ao tratamento de registros malformados. Um dos 'PERMISSIVE', 'DROPMALFORMED', e 'FAILFAST'. Valor predefinido: PERMISSIVE
multiLine Tipo: Boolean Se os registros CSV abrangem várias linhas. Valor predefinido: false
nanValue Tipo: String A representação em forma de texto de um valor não numérico ao analisar as colunas FloatType e DoubleType. Valor predefinido: "NaN"
negativeInf Tipo: String A representação literal do infinito negativo ao analisar colunas FloatType ou DoubleType. Valor predefinido: "-Inf"
nullValue Tipo: String Representação de cadeia de caracteres de um valor nulo. Valor predefinido: ""
parserCaseSensitive (preterido) Tipo: Boolean Durante a leitura de arquivos, verificar se as colunas declaradas no cabeçalho devem ser alinhadas com o esquema considerando a diferenciação entre maiúsculas e minúsculas. Isso é true por padrão para o Auto Loader. As colunas que diferem pela diferença entre maiúsculas e minúsculas serão resgatadas no rescuedDataColumn se estiver ativado. Esta opção foi preterida em favor do readerCaseSensitive. Valor predefinido: false
positiveInf Tipo: String A representação em texto do infinito positivo ao interpretar as colunas FloatType ou DoubleType. Valor predefinido: "Inf"
preferDate Tipo: Boolean Tenta inferir cadeias de caracteres como datas em vez de timestamps quando possível. Você também deve usar a inferência de esquema, habilitando inferSchema ou usando cloudFiles.inferColumnTypes com Carregador Automático. Valor predefinido: true
quote Tipo: Char O caractere usado para escapar de valores onde o delimitador de campo é parte do valor. Valor predefinido: "
readerCaseSensitive Tipo: Boolean Especifica o comportamento de sensibilidade a maiúsculas e minúsculas quando rescuedDataColumn está habilitado. Se verdadeiro, recupere as colunas de dados cujos nomes têm diferenças de maiúsculas e minúsculas em relação ao esquema; caso contrário, leia os dados sem distinguir entre maiúsculas e minúsculas. Valor predefinido: true
rescuedDataColumn Tipo: String Se deve recolher todos os dados que não podem ser processados devido a: uma incompatibilidade de tipo de dados, e incompatibilidade de esquema (incluindo o uso de maiúsculas/minúsculas nos nomes das colunas) para uma coluna separada. Esta coluna é incluída por padrão ao usar o Auto Loader. Para obter mais detalhes, consulte O que é a coluna de dados resgatados?. COPY INTO (legado) não suporta a coluna de dados resgatados porque não é possível definir manualmente o esquema usando COPY INTO. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão. Valor padrão: Nenhum
sep ou delimiter Tipo: String A cadeia de caracteres separadora entre colunas. Valor predefinido: ","
skipRows Tipo: Int O número de linhas desde o início do arquivo CSV que devem ser ignoradas (incluindo linhas comentadas e vazias). Se header for verdadeiro, o cabeçalho será a primeira linha não ignorada e não comentada. Valor predefinido: 0
timestampFormat Tipo: String O formato para interpretar carimbos de data/hora. Valor predefinido: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]
timeZone Tipo: String O java.time.ZoneId a ser usado ao interpretar datas e horas. Valor padrão: Nenhum
unescapedQuoteHandling Tipo: String A estratégia para lidar com citações não escapadas. Opções permitidas: STOP_AT_CLOSING_QUOTE: Se forem encontradas aspas sem escape na entrada, acumule o caractere de aspa e prossiga analisando o valor como um valor entre aspas, até que uma aspa de fecho seja encontrada. BACK_TO_DELIMITER: Se forem encontradas cotações sem escape na entrada, considere o valor como um valor não cotado. Isso fará com que o analisador acumule todos os caracteres do valor analisado atual até que o delimitador definido por sep seja encontrado. Se nenhum delimitador for encontrado no valor, o analisador continuará acumulando caracteres da entrada até que um delimitador ou terminação de linha seja encontrado. STOP_AT_DELIMITER: Se forem encontradas cotações sem escape na entrada, considere o valor como um valor não cotado. Isso fará com que o analisador acumule todos os caracteres até que o delimitador definido por sep, ou uma terminação de linha seja encontrada na entrada. SKIP_VALUE: Se forem encontradas aspas sem escape na entrada, o conteúdo analisado para o valor dado será ignorado (até que o próximo delimitador seja encontrado) e o valor definido em nullValue será produzido. RAISE_ERROR: Se forem encontradas cotações sem escape na entrada, um TextParsingException será lançado. Valor predefinido: STOP_AT_DELIMITER

XML Opções

Opção	Descrição	Âmbito de aplicação
rowTag	A tag de linha dos ficheiros XML a serem tratados como uma linha. No exemplo XML <books> <book><book>...<books>, o valor apropriado é book. Esta é uma opção necessária.	ler
samplingRatio	Define uma fração de linhas usadas para inferência de esquema. As funções internas XML ignoram essa opção. Padrão: 1.0.	ler
excludeAttribute	Se os atributos devem ser excluídos em elementos. Padrão: false.	ler
mode	Modo para lidar com registros corrompidos durante a análise. PERMISSIVE: Para registros corrompidos, coloca a cadeia de caracteres malformada em um campo configurado por columnNameOfCorruptRecord, e define campos malformados como null. Para manter registros corrompidos, você pode definir um string campo de tipo nomeado columnNameOfCorruptRecord em um esquema definido pelo usuário. Se um esquema não tiver o campo, os registros corrompidos serão descartados durante a análise. Ao inferir um esquema, o analisador adiciona implicitamente um columnNameOfCorruptRecord campo em um esquema de saída. DROPMALFORMED: Ignora registros corrompidos. Este modo não é suportado para funções incorporadas XML. FAILFAST: Lança uma exceção quando o analisador encontra registros corrompidos.	ler
inferSchema	Se true, tenta inferir um tipo apropriado para cada coluna do DataFrame resultante. Se false, todas as colunas resultantes são do string tipo. Predefinição: true. As funções internas XML ignoram essa opção.	ler
columnNameOfCorruptRecord	Permite renomear o novo campo que contém uma cadeia de caracteres malformada criada por PERMISSIVE modo. Padrão: spark.sql.columnNameOfCorruptRecord.	ler
attributePrefix	O prefixo para atributos, usado para diferenciar atributos de elementos. Este será o prefixo para nomes de campos. A predefinição é _. Pode estar vazio para ler XML, mas não para escrever.	ler, escrever
valueTag	A tag usada para os dados de caractere dentro de elementos que também têm atributo(s) ou elemento(s) filho(s). O usuário pode especificar o valueTag campo no esquema ou ele será adicionado automaticamente durante a inferência do esquema quando os dados de caracteres estiverem presentes em elementos com outros elementos ou atributos. Predefinição: _VALUE	ler,escrever
encoding	Para leitura, decodifica os arquivos XML pelo tipo de codificação fornecido. Para escrever, especifica a codificação (charset) de arquivos XML salvos. As funções internas XML ignoram essa opção. Padrão: UTF-8.	ler, escrever
ignoreSurroundingSpaces	Define se os espaços em branco ao redor dos valores que estão sendo lidos devem ser ignorados. Padrão: true. Os dados de caracteres que contêm apenas espaços em branco são ignorados.	ler
rowValidationXSDPath	Caminho para um arquivo XSD opcional que é usado para validar o XML para cada linha individualmente. As linhas que não validam são tratadas como erros de análise como acima. O XSD não afeta de outra forma o esquema fornecido ou inferido.	ler
ignoreNamespace	Se true, os prefixos dos namespaces em elementos e atributos XML são ignorados. Tags <abc:author> e <def:author>, por exemplo, são tratadas como se ambas fossem apenas <author>. Os namespaces não podem ser ignorados no elemento rowTag, apenas os seus filhos que são lidos. A análise XML não reconhece namespace, mesmo que false. Padrão: false.	ler
timestampFormat	Formato de cadeia de caracteres de data/hora que segue o formato de padrão datetime personalizado. Isto aplica-se ao timestamp tipo. Padrão: yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX].	ler, escrever
timestampNTZFormat	Cadeia de caracteres de formato personalizado para timestamp sem fuso horário que segue o formato de padrão datetime. Isso se aplica ao tipo TimestampNTZType. Predefinição: yyyy-MM-dd'T'HH:mm:ss[.SSS]	ler, escrever
dateFormat	Formato de data personalizado que segue o padrão datetime. Isto aplica-se ao tipo de data. Padrão: yyyy-MM-dd.	ler, escrever
locale	Define uma localidade como uma marca de idioma no formato IETF BCP 47. Por exemplo, locale é usado durante a análise de datas e carimbos temporais. Padrão: en-US.	ler
rootTag	Marca raiz dos arquivos XML. Por exemplo, em <books> <book><book>...</books>, o valor apropriado é books. Você pode incluir atributos básicos especificando um valor como books foo="bar". Padrão: ROWS.	escreve
declaration	Conteúdo da declaração XML a ser gravado no início de cada ficheiro XML de saída, antes do rootTag. Por exemplo, um valor de foo faz com que <?xml foo?> seja gravado. Defina como uma cadeia de caracteres vazia para suprimir. Predefinição: version="1.0" encoding="UTF-8" standalone="yes".	escreve
arrayElementName	Nome do elemento XML que encerra cada elemento de uma coluna com valor matriz ao gravar. Padrão: item.	escreve
nullValue	Define a representação de cadeia de caracteres de um valor nulo. Padrão: string null. Quando isso é null, o analisador não escreve atributos e elementos para campos.	ler, escrever
compression	Código de compressão para usar ao salvar no arquivo. Este pode ser um dos nomes abreviados conhecidos insensíveis a maiúsculas (none, bzip2, gzip, lz4, snappy e deflate). As funções internas XML ignoram essa opção. Padrão: none.	escreve
validateName	Se for verdadeiro, lança um erro em caso de falha na validação do nome do elemento XML. Por exemplo, nomes de campo SQL podem ter espaços, mas nomes de elementos XML não. Predefinição: true.	escreve
readerCaseSensitive	Especifica o comportamento de diferenciação de maiúsculas e minúsculas quando rescuedDataColumn está habilitado. Se verdadeiro, recupere as colunas de dados cujos nomes têm diferenças de maiúsculas e minúsculas em relação ao esquema; caso contrário, leia os dados sem distinguir entre maiúsculas e minúsculas. Padrão: true.	ler
rescuedDataColumn	Se devem ser recolhidos todos os dados que não podem ser analisados devido a uma incompatibilidade de tipos de dados e de esquema (incluindo a capitalização das colunas) para uma coluna separada. Esta coluna é incluída por padrão ao usar o Auto Loader. Para obter mais detalhes, consulte O que é a coluna de dados resgatados?. COPY INTO (legado) não suporta a coluna de dados resgatados porque não é possível definir manualmente o esquema usando COPY INTO. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão. Padrão: Nenhum.	ler
singleVariantColumn	Especifica o nome da coluna de variante única. Se esta opção for especificada para leitura, processe todo o registo XML numa única coluna Variant, com o valor do parâmetro de opção fornecido como o nome da coluna. Se esta opção for fornecida, escreva o valor da única coluna Variant em ficheiros XML. Padrão: none.	ler, escrever

PARQUET Opções

Opção
datetimeRebaseMode Tipo: String Controla a rebase dos valores DATE e TIMESTAMP entre os calendários gregoriano Juliano e Proléptico. Valores permitidos: EXCEPTION, LEGACYe CORRECTED. Valor predefinido: LEGACY
int96RebaseMode Tipo: String Controla a rebase dos valores de carimbo de data/hora INT96 entre os calendários Juliano e Gregoriano Proléptico. Valores permitidos: EXCEPTION, LEGACYe CORRECTED. Valor predefinido: LEGACY
mergeSchema Tipo: Boolean Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. Valor predefinido: false
readerCaseSensitive Tipo: Boolean Especifica o comportamento de sensibilidade a maiúsculas e minúsculas quando rescuedDataColumn está habilitado. Se verdadeiro, recupere as colunas de dados cujos nomes têm diferenças de maiúsculas e minúsculas em relação ao esquema; caso contrário, leia os dados sem distinguir entre maiúsculas e minúsculas. Valor predefinido: true
rescuedDataColumn Tipo: String Se deve recolher todos os dados que não podem ser processados devido a: uma incompatibilidade de tipo de dados, e incompatibilidade de esquema (incluindo o uso de maiúsculas/minúsculas nos nomes das colunas) para uma coluna separada. Esta coluna é incluída por padrão ao usar o Auto Loader. Para obter mais detalhes, consulte O que é a coluna de dados resgatados?. COPY INTO (legado) não suporta a coluna de dados resgatados porque não é possível definir manualmente o esquema usando COPY INTO. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão. Valor padrão: Nenhum

AVRO Opções

Opção
avroSchema Tipo: String Esquema opcional fornecido por um usuário no formato Avro. Ao ler o Avro, essa opção pode ser definida como um esquema evoluído, que é compatível, mas diferente do esquema Avro real. O esquema de desserialização será consistente com o esquema evoluído. Por exemplo, se você definir um esquema evoluído contendo uma coluna adicional com um valor padrão, o resultado da leitura também conterá a nova coluna. Valor padrão: Nenhum
datetimeRebaseMode Tipo: String Controla a rebase dos valores DATE e TIMESTAMP entre os calendários gregoriano Juliano e Proléptico. Valores permitidos: EXCEPTION, LEGACYe CORRECTED. Valor predefinido: LEGACY
mergeSchema Tipo: Boolean Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. mergeSchema para Avro não flexibiliza tipos de dados. Valor predefinido: false
readerCaseSensitive Tipo: Boolean Especifica o comportamento de sensibilidade a maiúsculas e minúsculas quando rescuedDataColumn está habilitado. Se verdadeiro, recupere as colunas de dados cujos nomes têm diferenças de maiúsculas e minúsculas em relação ao esquema; caso contrário, leia os dados sem distinguir entre maiúsculas e minúsculas. Valor predefinido: true
rescuedDataColumn Tipo: String Se deve recolher todos os dados que não podem ser processados devido a: uma incompatibilidade de tipo de dados, e incompatibilidade de esquema (incluindo o uso de maiúsculas/minúsculas nos nomes das colunas) para uma coluna separada. Esta coluna é incluída por padrão ao usar o Auto Loader. COPY INTO (legado) não suporta a coluna de dados resgatados porque não é possível definir manualmente o esquema usando COPY INTO. A Databricks recomenda o uso do Auto Loader para a maioria dos cenários de ingestão. Para obter mais detalhes, consulte O que é a coluna de dados resgatados?. Valor padrão: Nenhum

BINARYFILE Opções

Os ficheiros binários não têm quaisquer opções de configuração adicionais.

TEXT Opções

Opção
encoding Tipo: String O nome da codificação do separador de linha do arquivo TEXT. Para obter uma lista de opções, consulte java.nio.charset.Charset. O conteúdo do ficheiro não é afetado por esta opção e é lido as-is. Valor predefinido: UTF-8
lineSep Tipo: String Uma cadeia de caracteres entre dois registros TEXT consecutivos. Valor padrão: Nenhum, que abrange \r, \r\n e \n
wholeText Tipo: Boolean Se um arquivo deve ser lido como um único registro. Valor predefinido: false

ORC Opções

Opção
mergeSchema Tipo: Boolean Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. Valor predefinido: false

Opções de streaming

Essas opções se aplicam ao usar read_files numa tabela ou consulta de transmissão.

Opção
allowOverwrites Tipo: Boolean Se os arquivos que foram modificados após a descoberta devem ser reprocessados. A versão mais recente disponível do arquivo será processada durante uma atualização se tiver sido modificada desde a última hora de início da consulta de atualização bem-sucedida. Valor predefinido: false
includeExistingFiles Tipo: Boolean Se deve incluir arquivos existentes no caminho de entrada de processamento de fluxo ou apenas processar novos arquivos que chegam após a configuração inicial. Essa opção é avaliada somente quando você inicia um fluxo pela primeira vez. Alterar essa opção depois de reiniciar o fluxo não tem efeito. Valor predefinido: true
maxBytesPerTrigger Tipo: Byte String O número máximo de novos bytes a serem processados em cada acionamento. Você pode especificar uma cadeia de caracteres de byte, como 10g para limitar cada microlote a 10 GB de dados. Este é um máximo suave. Se você tiver arquivos de 3 GB cada, o Azure Databricks processará 12 GB em um microlote. Quando usado em conjunto com maxFilesPerTrigger, o Azure Databricks consome até ao limite inferior de maxFilesPerTrigger ou maxBytesPerTrigger, aquele que for atingido primeiro. Nota: Para tabelas de streaming criadas em armazéns SQL sem servidor, esta opção e maxFilesPerTrigger não devem ser configurados para tirar proveito do controlo de admissão dinâmica, que se adapta ao tamanho da carga de trabalho e aos recursos de computação sem servidor para proporcionar a melhor latência e desempenho. Valor padrão: Nenhum
maxFilesPerTrigger Tipo: Integer O número máximo de novos arquivos a serem processados em cada gatilho. Quando usado em conjunto com maxBytesPerTrigger, o Azure Databricks consome até ao limite inferior de maxFilesPerTrigger ou maxBytesPerTrigger, aquele que for atingido primeiro. Nota: Para tabelas de streaming criadas em armazéns SQL sem servidor, esta opção e maxBytesPerTrigger não devem ser configurados para tirar proveito do controlo de admissão dinâmica, que se adapta ao tamanho da carga de trabalho e aos recursos de computação sem servidor para proporcionar a melhor latência e desempenho. Valor padrão: 1000
schemaEvolutionMode Tipo: String O modo para evoluir o esquema à medida que novas colunas são descobertas nos dados. Por padrão, as colunas são inferidas como cadeias de caracteres ao inferir conjuntos de dados JSON. Consulte a evolução do esquema para obter mais detalhes. Esta opção não se aplica a text e binaryFile ficheiros. Valor padrão: "addNewColumns" quando um esquema não é fornecido. "none" caso contrário.
schemaLocation Tipo: String O local para armazenar o esquema inferido e as alterações subsequentes. Consulte inferência de esquema para obter mais detalhes. O local do esquema não é necessário quando usado em uma consulta de tabela de streaming. Valor padrão: Nenhum

Exemplos

-- 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);

Artigos relacionados

• CREATE STREAMING TABLE
• read_kafka função com valor de tabela