Função com valor de tabela `read_files`

Artigo
11/07/2024

Aplica-se a: verificação marcada como sim SQL do Databricks Databricks Runtime 13.3 LTS e versões posteriores

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 detectar o formato de arquivo automaticamente e inferir um esquema unificado em todos os arquivos.

Sintaxe

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

Argumentos

Essa função requer invocação de parâmetro nomeada para as chaves de opção.

path: um STRING com o URI do local dos dados. Dá suporte à leitura de Azure Data Lake Storage Gen2 ('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 backticks (') para opções que contêm ponto (.).
option_value: uma expressão constante para a qual definir a opção. Aceita literais e funções escalares.

Retorna

Uma tabela composta pelos dados de arquivos lidos no determinado path.

Descoberta de arquivos

read_files pode ler um arquivo individual ou ler arquivos em um diretório fornecido. read_files descobre todos os arquivos no diretório fornecido recursivamente, a menos que um glob seja fornecido, o que instrui read_files a recursar em um padrão de diretório específico.

Filtrar diretórios ou arquivos usando padrões glob

Padrões glob podem ser usados para filtrar diretórios e arquivos quando fornecidos no caminho.

Padrão	Descrição
`?`	Corresponde a qualquer caractere único
`*`	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 do intervalo {a}. Observe que o caractere `^` deve ocorrer imediatamente à direita do colchete de abertura.
`{ab,cd}`	Corresponde a uma cadeia de caracteres do conjunto de cadeias de caracteres {ab, cd}.
`{ab,c{de, fh}}`	Corresponde a uma cadeia de caracteres do conjunto de cadeias de caracteres {ab, cde, cfh}.

read_files usa o globber estrito do Carregador Automático ao descobrir arquivos com globs. Isso é configurado pela opção useStrictGlobber. Quando o globber estrito está desabilitado, as barras à direita (/) são descartadas e um padrão de star como /*/ pode se expandir para descobrir vários diretórios. Veja os exemplos abaixo para ver a diferença de comportamento.

Padrão	Caminho do arquivo	Globber estrito desabilitado	Globber estrito habilitado
`/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 de esquema

O esquema dos arquivos pode ser fornecido explicitamente read_files com a opção schema. Quando o esquema não é fornecido, read_files tenta inferir um esquema unificado entre os arquivos descobertos, o que requer a leitura de todos os arquivos, a menos que uma instrução LIMIT seja usada. Mesmo ao usar uma consulta LIMIT, 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 instrução LIMIT para SELECT consultas em notebooks e no editor de SQL se um usuário não tiver fornecido uma.

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

Um rescuedDataColumn é fornecido por padrão para resgatar os dados que não correspondem ao esquema. Confira Qual é a coluna de dados resgatados? para obter mais detalhes. Você pode remover o rescuedDataColumn definindo a opção schemaEvolutionMode => 'none'.

Inferência de esquema de partição

read_files também pode inferir colunas de particionamento se os arquivos forem armazenados em diretórios particionados no 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 do valor de 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, poderá fornecer a lista de colunas de partição em uma lista separada por vírgulas com a opção partitionColumns.

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

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

Os formatos TEXT e BINARYFILE têm um esquema fixo, mas read_files também tentam inferir o 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 aproveita o Carregador Automático quando usado em uma consulta de tabela de streaming. Você deve usar o STREAM palavra-chave com read_files. Confira O que é Carregador Automático? para obter mais detalhes.

Quando usado em uma consulta de streaming, read_files usa um exemplo dos dados para inferir o esquema e pode evoluir o esquema à medida que processa mais dados. Confira Configurar a inferência e a evolução de esquema no Carregador Automático para obter mais detalhes.

Opções básicas

Opção
`format` Digite: `String` O formato do arquivo de dados no caminho de origem. Inferido automaticamente se não for fornecido. Entre os valores permitidos estão: - `avro`: Arquivo Avro - `binaryFile`: Arquivo binário - `csv`: Carregar Arquivos CSV - `json`: Arquivo JSON - `orc`: Arquivo ORC - `parquet`: leitura de arquivos Parquet usando o Azure Databricks - `text`: Arquivos de texto - `xml`: Ler e gravar arquivos XML Valor padrão: nenhum
`inferColumnTypes` Digite: `Boolean` Para inferir os tipos de coluna exatos ao aproveitar a inferência de esquema ou não. Por padrão, as colunas são inferidas ao inferir conjuntos de dados JSON e CSV. Confira inferência de esquema para obter mais detalhes. Observe que isso é o oposto do padrão do Carregador Automático. Valor padrão: `true`
`partitionColumns` Digite: `String` Uma lista separada por vírgulas de colunas de partição de estilo hive que você gostaria de inferir da estrutura de diretório dos arquivos. Colunas de partição de estilo hive são pares chave-valor combinados 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`, `b` e `c`. Por padrão, essas colunas serão adicionadas automaticamente ao esquema se você estiver usando a inferência de esquema e fornecer o `<base-path>` para carregar dados. Se você fornecer um esquema, o Carregador automático espera que essas colunas sejam incluídas no esquema. Se você não quiser essas colunas no seu esquema, poderá especificar `""` para ignorar essas colunas. Além disso, é possível usar essa opção quando quiser que as colunas infiram o caminho do arquivo em estruturas de diretório complexas, como o exemplo a seguir: `<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` Especificar `cloudFiles.partitionColumns` as `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` Digite: `String` Informações de esquema que você fornece para o Carregador automático durante a inferência de esquema. Confira dicas de esquema para obter mais detalhes. Valor padrão: nenhum
`useStrictGlobber` Digite: `Boolean` Se é necessário usar um globber estrito que corresponda ao comportamento padrão de globbing de outras fontes de arquivo no Apache Spark. Confira Padrões comuns de carregamento de dados para obter mais detalhes. Disponível no Databricks Runtime 12.2 LTS e versões superiores. Observe que esse é o oposto do padrão para Carregador Automático. Valor padrão: `true`

Opções genéricas

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

Opção
`ignoreCorruptFiles` Digite: `Boolean` Se os arquivos corrompidos devem ser ignorados. Se for verdade, os trabalhos do Spark continuarão a ser executados ao encontrar arquivos corrompidos e o conteúdo lido ainda será retornado. Observável como `numSkippedCorruptFiles` no `operationMetrics` coluna de histórico do Delta Lake. Disponível no Databricks Runtime 11.3 LTS e versões superiores. Valor padrão: `false`
`ignoreMissingFiles` Digite: `Boolean` Se deve ignorar arquivos ausentes. Se for verdade, os trabalhos do Spark continuarão a ser executados ao encontrar arquivos ausentes e o conteúdo lido ainda será retornado. Disponível no Databricks Runtime 11.3 LTS e versões superiores. Valor padrão: `false` (`true` para `COPY INTO`)
`modifiedAfter` Digite: `Timestamp String`, por exemplo, `2021-01-01 00:00:00.000000 UTC+0` Um carimbo de data/hora opcional para ingerir arquivos que tenham um carimbo de data/hora de modificação após o carimbo de data/hora fornecido. Valor padrão: nenhum
`modifiedBefore` Digite: `Timestamp String`, por exemplo, `2021-01-01 00:00:00.000000 UTC+0` Um carimbo de data/hora opcional para ingerir 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` Digite: `String` Um padrão glob potencial a ser fornecido para escolher arquivos. Equivalente a `PATTERN` em `COPY INTO`. `fileNamePattern` pode ser usado em `read_files`. Valor padrão: nenhum
`recursiveFileLookup` Digite: `Boolean` Se deve ignorar a inferência de partição durante a inferência de esquema. Isso não afeta quais arquivos são carregados. Valor padrão: `false`

`JSON` options

Opção
`allowBackslashEscapingAnyCharacter` Digite: `Boolean` Se as barras invertidas devem ser permitidas para escapar qualquer caractere que tenha sucesso. Se não estiver habilitado, somente os caracteres listados explicitamente pela especificação JSON poderão ser ignorados. Valor padrão: `false`
`allowComments` Digite: `Boolean` Se deseja permitir o uso de comentários de estilo Java, C e C++ (variedades `'/'`, `'*'` e `'//'`) no conteúdo analisado ou não. Valor padrão: `false`
`allowNonNumericNumbers` Digite: `Boolean` Se o conjunto de tokens não-numéricos (`NaN`) deve ser permitido como valores de números flutuantes legais. Valor padrão: `true`
`allowNumericLeadingZeros` Digite: `Boolean` Indica se os números integrais podem ser iniciados com zeros adicionais (ignoráveis) (por exemplo, `000001`). Valor padrão: `false`
`allowSingleQuotes` Digite: `Boolean` Se o uso de aspas simples (apóstrofo, caractere `'\'`) deve ser permitido para cadeias de caracteres de cotação (nomes e valores de cadeia de caracteres). Valor padrão: `true`
`allowUnquotedControlChars` Digite: `Boolean` Se as cadeias de caracteres JSON devem ser permitidas (caracteres ASCII com valor inferior a 32, incluindo caracteres de guia e de alimentação de linha) ou não. Valor padrão: `false`
`allowUnquotedFieldNames` Digite: `Boolean` Se deseja permitir o uso de nomes de campo sem aspas (que são permitidos pelo JavaScript, mas não pela especificação JSON). Valor padrão: `false`
`badRecordsPath` Digite: `String` O caminho para armazenar arquivos para registrar as informações sobre registros JSON inválidos. Valor padrão: nenhum
`columnNameOfCorruptRecord` Digite: `String` A coluna para armazenar registros malformados e que não podem ser analisados. Se `mode` para análise for definida como `DROPMALFORMED`, essa coluna ficará vazia. Valor padrão: `_corrupt_record`
`dateFormat` Digite: `String` O formato para analisar cadeias de caracteres de data. Valor padrão: `yyyy-MM-dd`
`dropFieldIfAllNull` Digite: `Boolean` Se as colunas de todos os valores nulos ou matrizes e estruturas vazias devem ser ignoradas durante a inferência de esquema. Valor padrão: `false`
`encoding` ou `charset` Digite: `String` O nome da codificação dos arquivos JSON. Confira `java.nio.charset.Charset` para obter uma lista de opções. Você não poderá usar `UTF-16` e `UTF-32` quando `multiline` for `true`. Valor padrão: `UTF-8`
`inferTimestamp` Digite: `Boolean` Se deseja tentar e inferir as cadeias de carimbo de data/hora como um `TimestampType`. Quando definido como `true`. A inferência de esquema poderá ser notavelmente mais longa. Você deve habilitar `cloudFiles.inferColumnTypes` o uso com o Carregador Automático. Valor padrão: `false`
`lineSep` Digite: `String` Uma cadeia de caracteres entre dois registros JSON consecutivos. Valor padrão: Nenhum, que abrange `\r`, `\r\n` e `\n`
`locale` Digite: `String` Um identificador `java.util.Locale`. Influencia a data padrão, carimbo de data/hora e análise decimal no JSON. Valor padrão: `US`
`mode` Digite: `String` Modo analisador em torno do tratamento de registros malformados. Uma opção entre `'PERMISSIVE'`, `'DROPMALFORMED'` ou `'FAILFAST'`. Valor padrão: `PERMISSIVE`
`multiLine` Digite: `Boolean` Se os registros JSON se estenderem por várias linhas. Valor padrão: `false`
`prefersDecimal` Digite: `Boolean` Tenta inferir cadeias de caracteres como `DecimalType` em vez de flutuar ou tipo duplo quando possível. Você também deve usar a inferência de esquema, seja habilitando `inferSchema` ou usando `cloudFiles.inferColumnTypes` com o Carregador Automático. Valor padrão: `false`
`primitivesAsString` Digite: `Boolean` Se deve inferir tipos primitivos como números e boolianos como `StringType`. Valor padrão: `false`
`readerCaseSensitive` Digite: `Boolean` Especifica o comportamento de confidencialidade de caso quando `rescuedDataColumn` está habilitado. Se for verdadeiro, salve as colunas de dados cujos nomes diferem por caso do esquema; caso contrário, leia os dados de maneira que não diferencia maiúsculas de minúsculas. Disponível no Databricks Runtime 13.3 e superior. Valor padrão: `true`
`rescuedDataColumn` Digite: `String` É necessário coletar todos os dados que não podem ser analisados devido a uma incompatibilidade de tipo de dados ou incompatibilidade de esquema (incluindo maiúsculas e minúsculas) em uma coluna separada. Essa coluna é incluída por padrão ao usar o Carregador Automático. Para obter mais detalhes, confira Qual é a coluna dados resgatados?. Valor padrão: nenhum
`singleVariantColumn` Digite: `String` Se deve-se ingerir todo o documento JSON, analisado em uma única coluna Variante com a cadeia de caracteres fornecida como o nome da coluna. Se desabilitado, os campos JSON serão ingeridos em suas próprias colunas. Valor padrão: nenhum
`timestampFormat` Digite: `String` O formato para análise de cadeias de caracteres de data/hora. Valor padrão: `yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`
`timeZone` Digite: `String` O `java.time.ZoneId` a ser usado ao analisar carimbo de data/hora e datas. Valor padrão: nenhum

`CSV` options

Opção
`badRecordsPath` Digite: `String` O caminho para armazenar arquivos para registrar as informações sobre registros CSV incorretos. Valor padrão: nenhum
`charToEscapeQuoteEscaping` Digite: `Char` O caractere usado para escapar o caractere usado para escapar aspas. Por exemplo, para o seguinte registro: `[ " a\\", b ]`: - Se o caractere a ser ignorado `'\'` for indefinido, o registro não será analisado. O analisador lerá caracteres: `[a],[\],["],[,],[ ],[b]` e lançará um erro porque não consegue encontrar uma aspas de fechamento. - Se o caractere para escapar do `'\'` for definido como `'\'`, o registro será lido com dois valores: `[a\]` e `[b]`. Valor padrão: `'\0'`
`columnNameOfCorruptRecord` > [!OBSERVAÇÃO] >> Compatível com o Carregador Automático. Sem suporte para `COPY INTO`. Digite: `String` A coluna para armazenar registros malformados e que não podem ser analisados. Se `mode` para análise for definida como `DROPMALFORMED`, essa coluna ficará vazia. Valor padrão: `_corrupt_record`
`comment` Digite: `Char` Define o caractere que representa um comentário de linha quando encontrado no início de uma linha de texto. Use `'\0'` para desabilitar o ato de ignorar comentários. Valor padrão: `'\u0000'`
`dateFormat` Digite: `String` O formato para analisar cadeias de caracteres de data. Valor padrão: `yyyy-MM-dd`
`emptyValue` Digite: `String` Representação de cadeia de caracteres de um valor vazio. Valor padrão: `""`
`encoding` ou `charset` Digite: `String` O nome da codificação dos arquivos CSV. Confira `java.nio.charset.Charset` para obter a lista de opções. `UTF-16` e `UTF-32` não poderão ser usados quando `multiline` for `true`. Valor padrão: `UTF-8`
`enforceSchema` Digite: `Boolean` Se deve aplicar à força o esquema especificado ou inferido aos arquivos CSV. Se a opção estiver habilitada, os cabeçalhos de arquivos CSV serão ignorados. Essa opção será ignorada por padrão ao usar o Carregador Automático para resgatar dados e permitir a evolução do esquema. Valor padrão: `true`
`escape` Digite: `Char` O caractere de escape a ser usado ao analisar os dados. Valor padrão: `'\'`
`header` Digite: `Boolean` Se os arquivos CSV contiverem um cabeçalho. O Carregador Automático presume que os arquivos tenham cabeçalhos ao inferir o esquema. Valor padrão: `false`
`ignoreLeadingWhiteSpace` Digite: `Boolean` Se deve ignorar espaços em branco à frente para cada valor analisado. Valor padrão: `false`
`ignoreTrailingWhiteSpace` Digite: `Boolean` Se deve ignorar espaços em branco à parte final para cada valor analisado. Valor padrão: `false`
`inferSchema` Digite: `Boolean` Se inferir os tipos de dados dos registros CSV analisados ou assumir que todas as colunas são de `StringType`. Requer uma passagem adicional dos dados se definido como `true`. Para o Carregador Automático, use `cloudFiles.inferColumnTypes` em vez disso. Valor padrão: `false`
`lineSep` Digite: `String` Uma cadeia de caracteres entre dois registros CSV consecutivos. Valor padrão: Nenhum, que abrange `\r`, `\r\n` e `\n`
`locale` Digite: `String` Um identificador `java.util.Locale`. Influencia a data padrão, o carimbo de data/hora e a análise decimal dentro do CSV. Valor padrão: `US`
`maxCharsPerColumn` Digite: `Int` Número máximo de caracteres esperados de um valor a ser analisado. Pode ser usado para evitar erros de memória. O padrão é `-1`, que significa ilimitado. Valor padrão: `-1`
`maxColumns` Digite: `Int` O limite rígido de quantas colunas um registro pode ter. Valor padrão: `20480`
`mergeSchema` Digite: `Boolean` Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. Habilitado por padrão para o Carregador Automático ao inferir o esquema. Valor padrão: `false`
`mode` Digite: `String` Modo analisador em torno do tratamento de registros malformados. Uma opção entre `'PERMISSIVE'`, `'DROPMALFORMED'` e `'FAILFAST'`. Valor padrão: `PERMISSIVE`
`multiLine` Digite: `Boolean` Se os registros CSV se estenderem por várias linhas. Valor padrão: `false`
`nanValue` Digite: `String` A representação de cadeia de caracteres de um valor que não é um número ao analisar as colunas `FloatType` e `DoubleType`. Valor padrão: `"NaN"`
`negativeInf` Digite: `String` A representação de cadeia de caracteres de infinito negativo ao analisar as colunas `FloatType` ou `DoubleType`. Valor padrão: `"-Inf"`
`nullValue` Digite: `String` Representação de cadeia de caracteres de um valor nulo. Valor padrão: `""`
`parserCaseSensitive` (preterido) Digite: `Boolean` Durante a leitura de arquivos, se as colunas declaradas no cabeçalho devem ser alinhadas com o caso de esquema de forma sensível. Isso é `true` por padrão para o Carregador Automático. As colunas que diferirem por caso serão resgatadas no `rescuedDataColumn`, se habilitado. Essa opção foi preterida em favor de `readerCaseSensitive`. Valor padrão: `false`
`positiveInf` Digite: `String` A representação de cadeia de caracteres de infinito positivo ao analisar as colunas `FloatType` ou `DoubleType`. Valor padrão: `"Inf"`
`preferDate` Digite: `Boolean` Tenta inferir cadeias de caracteres como datas em vez de carimbo de data/hora quando possível. Você também deve usar a inferência de esquema, habilitando `inferSchema` ou usando `cloudFiles.inferColumnTypes` com o Carregador Automático. Valor padrão: `true`
`quote` Digite: `Char` O caractere usado para escapar valores em que o delimitador de campo faz parte do valor. Valor padrão: `"`
`readerCaseSensitive` Digite: `Boolean` Especifica o comportamento de confidencialidade de caso quando `rescuedDataColumn` está habilitado. Se for verdadeiro, salve as colunas de dados cujos nomes diferem por caso do esquema; caso contrário, leia os dados de maneira que não diferencia maiúsculas de minúsculas. Valor padrão: `true`
`rescuedDataColumn` Digite: `String` É necessário coletar todos os dados que não podem ser analisados devido a uma incompatibilidade de tipo de dados e incompatibilidade de esquema (incluindo maiúsculas e minúsculas) em uma coluna separada. Essa coluna é incluída por padrão ao usar o Carregador Automático. Para obter mais detalhes, confira Qual é a coluna dados resgatados?. Valor padrão: nenhum
`sep` ou `delimiter` Digite: `String` A cadeia de caracteres do separador entre colunas. Valor padrão: `","`
`skipRows` Digite: `Int` O número de linhas desde o início do arquivo CSV que devem ser ignoradas (incluindo linhas com comentários e vazias). Se `header` for verdadeiro, o cabeçalho será a primeira linha não mapeada e descompactada. Valor padrão: `0`
`timestampFormat` Digite: `String` O formato para análise de cadeias de caracteres de data/hora. Valor padrão: `yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`
`timeZone` Digite: `String` O `java.time.ZoneId` a ser usado ao analisar carimbo de data/hora e datas. Valor padrão: nenhum
`unescapedQuoteHandling` Digite: `String` A estratégia para lidar com aspas sem saída. Opções permitidas: - `STOP_AT_CLOSING_QUOTE`: se aspas sem escape forem encontradas na entrada, acumular o caractere de aspas e continuar analisando o valor como um valor entre aspas, até que uma aspa de fechamento seja encontrada. - `BACK_TO_DELIMITER`: se forem encontradas aspas sem escape na entrada, considere o valor como um valor sem aspas. Isso fará com que o analisador acumule todos os caracteres do valor atual analisado 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 uma terminação de linha seja encontrada. - `STOP_AT_DELIMITER`: se forem encontradas aspas sem escape na entrada, considere o valor como um valor sem aspas. Isso fará com que o analisador acumule todos os caracteres até que o delimitador definido por `sep` ou uma terminação de linha seja encontrado na entrada. - `SKIP_VALUE`: se forem encontradas aspas sem escape na entrada, o conteúdo analisado para o valor determinado será ignorado (até que o próximo delimitador seja encontrado) e, em vez disso, será produzido o valor definido em `nullValue`. - `RAISE_ERROR`: se forem encontradas aspas sem escape na entrada, uma `TextParsingException` será lançada. Valor padrão: `STOP_AT_DELIMITER`

`XML` options

Opção	Descrição	Escopo
`rowTag`	A marca de linha dos arquivos XML a serem tratadas como uma linha. No exemplo o XML `<books> <book><book>...<books>`, o valor apropriado é `book`. Trata-se de uma opção obrigatória.	read
`samplingRatio`	Define uma fração de linhas usadas para inferência de esquema. As funções internas do XML ignoram essa opção. Padrão: `1.0`.	read
`excludeAttribute`	Se deve excluir os atributos em elementos. Padrão: `false`.	read
`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 os campos malformados como `null`. Para manter os registros corrompidos, é possível definir um campo do tipo `string` denominado `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 campo `columnNameOfCorruptRecord` em um esquema de saída. `DROPMALFORMED`: ignora os registros corrompidos. Esse modo não dá suporte para funções internas de XML. `FAILFAST`: gera uma exceção quando o analisador encontra registros corrompidos.	read
`inferSchema`	Se `true`, tenta inferir um tipo apropriado para cada coluna DataFrame resultante. Se `false`, todas as colunas resultantes serão do tipo `string`. Padrão: `true`. As funções internas do XML ignoram essa opção.	read
`columnNameOfCorruptRecord`	Permite renomear o novo campo que contém uma cadeia de caracteres malformada criada pelo modo `PERMISSIVE`. Padrão: `spark.sql.columnNameOfCorruptRecord`.	read
`attributePrefix`	O prefixo de atributos para diferenciar atributos de elementos. Esse será o prefixo para nomes de campo. O padrão é `_`. Pode estar vazio para leitura de XML, mas não para gravação.	leitura, gravação
`valueTag`	A marca usada para os dados de caracteres dentro de elementos que também têm elementos de atributo(s) ou elemento(s) filho(s). O usuário pode especificar o campo `valueTag` 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. Padrão: `_VALUE`	leitura,gravação
`encoding`	Para leitura, decodifique os arquivos XML de acordo com o tipo de codificação fornecido. Para gravação, especifique a codificação (conjunto de caracteres) dos arquivos XML salvos. As funções internas do XML ignoram essa opção. Padrão: `UTF-8`.	leitura, gravação
`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 somente com espaços em branco são ignorados.	read
`rowValidationXSDPath`	Caminho para um arquivo XSD opcional usado para validar o XML de cada linha individualmente. As linhas que não são validadas são tratadas como erros de análise, conforme mostrado acima. O XSD não afeta de outra forma o esquema fornecido ou inferido.	read
`ignoreNamespace`	Se `true`, os prefixos de namespaces em elementos e atributos XML serão ignorados. As marcas `<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`, somente em seus elementos filhos de leitura. A análise de XML não tem reconhecimento de namespace, mesmo se `false`. Padrão: `false`.	read
`timestampFormat`	Cadeia de caracteres do formato de carimbo de data/hora personalizado que segue o formato padrão datetime. Isso se aplica ao tipo `timestamp`. Padrão: `yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]`.	leitura, gravação
`timestampNTZFormat`	Cadeia de caracteres de formato personalizado para carimbo de data/hora sem fuso horário que segue o formato padrão datetime. Isso se aplica ao tipo TimestampNTZType. Padrão: `yyyy-MM-dd'T'HH:mm:ss[.SSS]`	leitura, gravação
`dateFormat`	Cadeia de caracteres de formato de data personalizada que segue o formato padrão datetime. Isso se aplica ao tipo de data. Padrão: `yyyy-MM-dd`.	leitura, gravação
`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 de data/hora. Padrão: `en-US`.	read
`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`.	write
`declaration`	Conteúdo da declaração XML a ser gravada no início de cada arquivo XML de saída, antes de `rootTag`. Por exemplo, um valor de `foo` faz com que `<?xml foo?>` seja gravado. Defina como uma cadeia de caracteres vazia para suprimir. Padrão: `version="1.0"` `encoding="UTF-8" standalone="yes"`.	write
`arrayElementName`	Nome do elemento XML que envolve cada elemento de uma coluna com valor de matriz durante a gravação. Padrão: `item`.	write
`nullValue`	Define a representação em cadeia de caracteres de um valor nulo. Padrão: cadeia de caracteres `null`. Quando esse valor é `null`, o analisador não escreve atributos e elementos para campos.	leitura, gravação
`compression`	Código de compactação a ser usado ao salvar no arquivo. Pode ser um dos nomes abreviados conhecidos que não diferenciam maiúsculas de minúsculas (`none`, `bzip2`, `gzip`,`lz4`, `snappy`, e `deflate`). As funções internas do XML ignoram essa opção. Padrão: `none`.	write
`validateName`	Se verdadeiro, gera um erro em caso de falha na validação do nome do elemento XML. Por exemplo, os nomes de campos SQL podem ter espaços, mas os nomes de elementos XML não podem. Padrão: `true`.	write
`readerCaseSensitive`	Especifica o comportamento da diferenciação de maiúsculas e minúsculas quando rescuedDataColumn está habilitado. Se for verdadeiro, salve as colunas de dados cujos nomes diferem por caso do esquema; caso contrário, leia os dados de maneira que não diferencia maiúsculas de minúsculas. Padrão: `true`.	read
`rescuedDataColumn`	Se todos os dados que não podem ser analisados devido a uma incompatibilidade de tipo de dados e de esquema (incluindo maiúsculas e minúsculas da coluna) devem ser coletados em uma coluna separada. Essa coluna é incluída por padrão ao usar o Carregador Automático. Para obter mais detalhes, confira O que é a coluna de dados resgatados?. Padrão: nenhum.	read

`PARQUET` options

Opção
`datetimeRebaseMode` Digite: `String` Controla a nova base dos valores DATE e TIMESTAMP entre calendários Juliano e Gregoriano Proléptico. Valores permitidos: `EXCEPTION`, `LEGACY` e `CORRECTED`. Valor padrão: `LEGACY`
`int96RebaseMode` Digite: `String` Controla a nova base dos valores de carimbo de data/hora INT96 entre calendários Juliano e Gregoriano Proléptico. Valores permitidos: `EXCEPTION`, `LEGACY` e `CORRECTED`. Valor padrão: `LEGACY`
`mergeSchema` Digite: `Boolean` Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. Valor padrão: `false`
`readerCaseSensitive` Digite: `Boolean` Especifica o comportamento de confidencialidade de caso quando `rescuedDataColumn` está habilitado. Se for verdadeiro, salve as colunas de dados cujos nomes diferem por caso do esquema; caso contrário, leia os dados de maneira que não diferencia maiúsculas de minúsculas. Valor padrão: `true`
`rescuedDataColumn` Digite: `String` É necessário coletar todos os dados que não podem ser analisados devido a uma incompatibilidade de tipo de dados e incompatibilidade de esquema (incluindo maiúsculas e minúsculas) em uma coluna separada. Essa coluna é incluída por padrão ao usar o Carregador Automático. Para obter mais detalhes, confira Qual é a coluna dados resgatados?. Valor padrão: nenhum

`AVRO` options

Opção
`avroSchema` Digite: `String` Esquema opcional fornecido por um usuário no formato Avro. Ao ler Avro, essa opção pode ser definida como um esquema desenvolvido, que é compatível, mas diferente com o esquema Avro real. O esquema desserialização será consistente com o esquema desenvolvido. Por exemplo, se você definir um esquema desenvolvido contendo uma coluna adicional com um valor padrão, o resultado de leitura também conterá a nova coluna. Valor padrão: nenhum
`datetimeRebaseMode` Digite: `String` Controla a nova base dos valores DATE e TIMESTAMP entre calendários Juliano e Gregoriano Proléptico. Valores permitidos: `EXCEPTION`, `LEGACY` e `CORRECTED`. Valor padrão: `LEGACY`
`mergeSchema` Digite: `Boolean` Se deve inferir o esquema em vários arquivos e mesclar o esquema de cada arquivo. `mergeSchema` para Avro não flexibilizar tipos de dados. Valor padrão: `false`
`readerCaseSensitive` Digite: `Boolean` Especifica o comportamento de confidencialidade de caso quando `rescuedDataColumn` está habilitado. Se for verdadeiro, salve as colunas de dados cujos nomes diferem por caso do esquema; caso contrário, leia os dados de maneira que não diferencia maiúsculas de minúsculas. Valor padrão: `true`
`rescuedDataColumn` Digite: `String` É necessário coletar todos os dados que não podem ser analisados devido a uma incompatibilidade de tipo de dados e incompatibilidade de esquema (incluindo maiúsculas e minúsculas) em uma coluna separada. Essa coluna é incluída por padrão ao usar o Carregador Automático. Para obter mais detalhes, confira Qual é a coluna dados resgatados?. Valor padrão: nenhum

`BINARYFILE` options

Os arquivos binários não têm nenhuma opção de configuração adicional.

`TEXT` options

Opção
`encoding` Digite: `String` O nome da codificação dos arquivos TEXT. Confira `java.nio.charset.Charset` para obter uma lista de opções. Valor padrão: `UTF-8`
`lineSep` Digite: `String` Uma cadeia de caracteres entre dois registros TEXT consecutivos. Valor padrão: Nenhum, que abrange `\r`, `\r\n` e `\n`
`wholeText` Digite: `Boolean` Se um arquivo deve ser lido como um único registro. Valor padrão: `false`

`ORC` options

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

Opções de streaming

Essas opções se aplicam ao usar read_files dentro de uma tabela de streaming ou consulta de streaming.

Opção
`allowOverwrites` Digite: `Boolean` Se os arquivos que foram modificados após a descoberta devem ser processados novamente. A versão mais recente disponível do arquivo será processada durante uma atualização se tiver sido modificada desde a hora de início da última consulta de atualização bem-sucedida. Valor padrão: `false`
`includeExistingFiles` Digite: `Boolean` Para incluir arquivos existentes no caminho de entrada de processamento de fluxo ou somente para processar novos arquivos chegando 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 nenhum efeito. Valor padrão: `true`
`maxBytesPerTrigger` Digite: `Byte String` O número máximo de novos bytes a serem processados em cada gatilho. Você pode especificar uma cadeia de caracteres de byte, como `10g`, para limitar cada microlote a 10 GB de dados. O número máximo é flexível. Se você tiver arquivos que são de 3 GB cada, o Azure Databricks processará 12 GB em um microlote. Quando usado em conjunto com o `maxFilesPerTrigger`, o Azure Databricks consome até o limite inferior de `maxFilesPerTrigger` ou `maxBytesPerTrigger`, o que for atingido primeiro. Observação: para tabelas de streaming criadas em SQL warehouses sem servidor, essa opção e `maxFilesPerTrigger` não devem ser definidas para aproveitar o controle de admissão dinâmica, que é dimensionado por tamanho de carga de trabalho e recursos de computação sem servidor para oferecer a melhor latência e desempenho. Valor padrão: nenhum
`maxFilesPerTrigger` Digite: `Integer` Número máximo de novos bytes a serem processados em cada gatilho. Quando usado em conjunto com o `maxBytesPerTrigger`, o Azure Databricks consome até o limite inferior de `maxFilesPerTrigger` ou `maxBytesPerTrigger`, o que for atingido primeiro. Observação: para tabelas de streaming criadas em SQL warehouses sem servidor, essa opção e `maxBytesPerTrigger` não devem ser definidas para aproveitar o controle de admissão dinâmica, que é dimensionado por tamanho de carga de trabalho e recursos de computação sem servidor para oferecer a melhor latência e desempenho. Valor padrão: 1.000
`schemaEvolutionMode` Digite: `String` Modo para a evolução do 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. Confira a evolução do esquema para obter mais detalhes. Essa opção não se aplica aos arquivos `text` e `binaryFile`. Valor padrão: `"addNewColumns"` quando um esquema não é fornecido. Caso contrário, `"none"`.
`schemaLocation` Digite: `String` Local para armazenar o esquema deduzido e as alterações subsequentes. Confira 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);

Compartilhar via

Função com valor de tabela `read_files`

Sintaxe

Argumentos

Retorna

Descoberta de arquivos

Filtrar diretórios ou arquivos usando padrões glob

Inferência de esquema

Inferência de esquema de partição

Uso em tabelas de streaming

Opções

Opções básicas

Opções genéricas

`JSON` options

`CSV` options

`XML` options

`PARQUET` options

`AVRO` options

`BINARYFILE` options

`TEXT` options

`ORC` options

Opções de streaming

Exemplos

Comentários

Recursos adicionais

Compartilhar via

Função com valor de tabela read_files

Sintaxe

Argumentos

Retorna

Descoberta de arquivos

Filtrar diretórios ou arquivos usando padrões glob

Inferência de esquema

Inferência de esquema de partição

Uso em tabelas de streaming

Opções

Opções básicas

Opções genéricas

JSON options

CSV options

XML options

PARQUET options

AVRO options

BINARYFILE options

TEXT options

ORC options

Opções de streaming

Exemplos

Artigos relacionados

Comentários

Recursos adicionais

Função com valor de tabela `read_files`

`JSON` options

`CSV` options

`XML` options

`PARQUET` options

`AVRO` options

`BINARYFILE` options

`TEXT` options

`ORC` options