Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
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
: ASTRING
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:
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 , b e 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 naoperationMetrics 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:
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 comotrue , 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\n e \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 , DROPMALFORMED ou 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, habilitandoinferSchema 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 Runtime13.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 ]
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\n e \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 usandocloudFiles.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:
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 porPERMISSIVE 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 edeflate ). 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 , LEGACY eCORRECTED .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 , LEGACY eCORRECTED .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 , LEGACY eCORRECTED .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);