Configurar a inferência e a evolução do esquema no Auto Loader
Você pode configurar o Auto Loader para detectar automaticamente o esquema dos dados carregados, permitindo que você inicialize tabelas sem declarar explicitamente o esquema dos dados e adapte o esquema da tabela à medida que novas colunas são introduzidas. Isso elimina a necessidade de rastrear manualmente e aplicar alterações de esquema ao longo do tempo.
Auto Loader também pode "resgatar" dados inesperados (por exemplo, de tipos de dados diferentes) em uma coluna JSON blob, que você pode optar por view posteriormente usando as APIsde acesso a dados semiestruturados.
O Auto Loader suporta os seguintes formatos para inferência e evolução de esquemas:
Formato de arquivo | Versões compatíveis |
|---|---|
| Todas as versões |
| Todas as versões |
| Databricks Runtime 14.3 LTS e acima |
| Databricks Runtime 10.4 LTS e acima |
| Databricks Runtime 11.3 LTS e acima |
| Sem compatibilidade |
| Não aplicável (esquema fixo) |
| Não aplicável (esquema fixo) |
Sintaxe para inferência e evolução de esquemas
Especificar um diretório de destino para a opção cloudFiles.schemaLocation permite a inferência e evolução do esquema. Você pode optar por usar o mesmo diretório que especificou para o checkpointLocation. Se você usar o pipeline declarativoLakeFlow Spark, Databricks gerenciará automaticamente a localização do esquema e outras informações de ponto de verificação.
Se você tiver mais de uma localização de dados de origem sendo carregada na tabela de destino, cada carga de trabalho de ingestão do Auto Loader requer um ponto de verificação de transmissão separado.
O exemplo a seguir usa parquet para cloudFiles.format. Use csv, avro ou json para outras fontes de arquivo. Todas as outras configurações de leitura e escrita permanecem iguais às configurações padrão para cada formato.
- Python
- Scala
(spark.readStream.format("cloudFiles")
.option("cloudFiles.format", "parquet")
# The schema location directory keeps track of your data schema over time
.option("cloudFiles.schemaLocation", "<path-to-schema>")
.load("<path-to-source-data>")
.writeStream
.option("checkpointLocation", "<path-to-checkpoint>")
.start("<path-to-target>")
)
spark.readStream.format("cloudFiles")
.option("cloudFiles.format", "parquet")
// The schema location directory keeps track of your data schema over time
.option("cloudFiles.schemaLocation", "<path-to-schema>")
.load("<path-to-source-data>")
.writeStream
.option("checkpointLocation", "<path-to-checkpoint>")
.start("<path-to-target>")
Como funciona a inferência de esquema do Auto Loader?
Para deduzir o esquema na primeira leitura dos dados, o Auto Loader amostra os primeiros 50 GB ou 1000 arquivos que encontra, o que acontecer primeiro.O Auto Loader armazena as informações de esquema em um _schemas de diretório no cloudFiles.schemaLocation configurado para controlar as alterações de esquema nos dados de entrada ao longo do tempo.
Para alterar o tamanho da amostra utilizada, defina as configurações de SQL:
spark.databricks.cloudFiles.schemaInference.sampleSize.numBytes
(string de bytes, por exemplo 10gb)
e
spark.databricks.cloudFiles.schemaInference.sampleSize.numFiles
(inteiro)
Por default, a inferência de esquema Auto Loader busca evitar problemas de evolução do esquema devido a incompatibilidades de tipo. Para formatos que não codificam tipos de dados (JSON, CSV e XML), o Auto Loader infere todas as colunas como strings (incluindo campos aninhados em arquivos JSON). Para formatos com esquema tipado (Parquet e Avro), Auto Loader seleciona um subconjunto de arquivos e mescla os esquemas dos arquivos individuais. A tabela a seguir resume esse comportamento.
Formato de arquivo | Tipo de dados inferidos padrão |
|---|---|
| String |
| String |
| String |
| Tipos codificados no esquema Avro |
| Tipos codificados no esquema de Parquet |
O Apache Spark DataFrameReader usa um comportamento diferente para inferência de esquema, selecionando tipos de dados para colunas em fontes JSON, CSV e XML com base em dados de amostra. Para ativar esse comportamento com o Auto Loader, defina a opção cloudFiles.inferColumnTypes como true.
Ao inferir o esquema para dados CSV, o Auto Loader assume que os arquivos contêm cabeçalhos. Se seus arquivos CSV não contiverem cabeçalhos, forneça a opção .option("header", "false"). Além disso, o site Auto Loader mescla os esquemas de todos os arquivos da amostra para criar um esquema global. O Auto Loader pode então ler cada arquivo de acordo com seu cabeçalho e analisar o CSV corretamente.
Quando uma coluna possui tipos de dados diferentes em dois arquivos Parquet, o Auto Loader escolhe o tipo mais amplo. Você pode usar schemaHints para substituir essa escolha. Ao especificar dicas de esquema, o Auto Loader não converte a coluna para o tipo especificado, mas sim instrui o leitor Parquet a ler a coluna como o tipo especificado. Em caso de incompatibilidade, o Auto Loader recupera a coluna, inserindo os dados na coluna de dados recuperados.
Como funciona a evolução do esquema do Auto Loader?
O Auto Loader detecta a adição de novas colunas à medida que processa seus dados. Quando o Auto Loader detecta uma nova coluna, o fluxo para com um UnknownFieldException. Antes que sua transmissão gere esse erro, o Auto Loader realiza a inferência de esquema no último micro lote de dados e atualiza a localização do esquema com o esquema mais recente, mesclando novas colunas no final do esquema.Os tipos de dados das colunas existentes permanecem inalterados.
Databricks recomenda configurar a transmissão Auto Loader com LakeFlow Jobs para reiniciar automaticamente após essas alterações de esquema.
Auto Loader suporta os seguintes modos para evolução do esquema, que você define na opção cloudFiles.schemaEvolutionMode :
Mode | Comportamento na leitura de nova coluna |
|---|---|
| A transmissão da falha. Novas colunas são adicionadas ao esquema. As colunas existentes não desenvolvem tipos de dados. |
| Auto Loader nunca altera o esquema e a transmissão não falha devido a mudanças no esquema. O Auto Loader registra todas as novas colunas na coluna de dados recuperados. |
| A transmissão falhou. A transmissão não será reiniciada a menos que você atualize o esquema fornecido ou remova o arquivo de dados problemático. |
| Não evolui o esquema, novas colunas são ignoradas e os dados não são resgatados a menos que a opção |
addNewColumns é o default quando um esquema não é fornecido, mas none é o default quando o senhor fornece um esquema. addNewColumns não é permitido quando o esquema da transmissão é fornecido, mas funciona se o senhor fornecer o seu esquema como uma dica de esquema.
Como funcionam as partições com o Auto Loader?
O Auto Loader tenta inferir as colunas de partição a partir da estrutura de diretórios subjacente dos dados, caso os dados estejam organizados em um particionamento no estilo Hive. Por exemplo, o caminho do arquivo base_path/event=click/date=2021-04-01/f0.json resulta na inferência de date e event como colunas de partição. Se a estrutura de diretórios subjacente contiver partições Hive conflitantes ou não contiver particionamento no estilo Hive, o Auto Loader ignorará as colunas de partição.
Os formatos de arquivo binário (binaryFile) e text têm esquemas de dados fixos, mas são compatíveis com inferência de coluna de partição. O Databricks recomenda configurar o cloudFiles.schemaLocation para estes formatos de arquivo. Isso evita possíveis erros ou perda de informações e impede a inferência de colunas de partições sempre que um Auto Loader começa.
O Auto Loader não considera colunas de partição para a evolução do esquema. Se você tinha uma estrutura de diretório inicial como base_path/event=click/date=2021-04-01/f0.json e então começa a receber novos arquivos como base_path/event=click/date=2021-04-01/hour=01/f1.json, Auto Loader ignora a coluna de hora. Para capturar informações para novas colunas de partição, defina cloudFiles.partitionColumns como event,date,hour.
A opção cloudFiles.partitionColumns aceita uma lista de nomes de colunas separados por vírgulas. O Auto Loader analisa apenas colunas que existem como pares key=value na sua estrutura de diretórios.
O que é a coluna de dados resgatada?
Quando Auto Loader infere o esquema, Auto Loader adiciona automaticamente uma coluna de dados recuperados ao seu esquema como _rescued_data. Você pode renomear a coluna ou incluí-la ao fornecer um esquema definindo a opção rescuedDataColumn .
A coluna de dados recuperados garante que o Auto Loader recupere as colunas que não correspondem ao esquema, em vez de descartá-las. A coluna de dados recuperados contém quaisquer dados que não foram analisados pelos seguintes motivos:
- A coluna está ausente no esquema.
- Incompatibilidades de tipos.
- Incompatibilidades de casos.
A coluna de dados recuperados contém um objeto JSON com as colunas recuperadas e o caminho do arquivo de origem do registro.
Os analisadores JSON e CSV suportam três modos ao analisar registros: PERMISSIVE, DROPMALFORMED e FAILFAST. Quando usado em conjunto com rescuedDataColumn, as incompatibilidades de tipo de dados não fazem com que o Auto Loader descarte registros no modo DROPMALFORMED ou lance um erro no modo FAILFAST . Somente registros corrompidos falham ou geram erros, como JSON ou CSV incompletos ou malformados. Se você usar badRecordsPath ao analisar JSON ou CSV, o Auto Loader não tratará incompatibilidades de tipo de dados como registros inválidos ao usar rescuedDataColumn. O Auto Loader armazena apenas registros JSON ou CSV incompletos e malformados em badRecordsPath.
Alterar o comportamento com distinção entre maiúsculas e
A menos que a diferenciação entre maiúsculas e minúsculas esteja ativada, o Auto Loader considera as colunas abc, Abc e ABC como a mesma coluna para fins de inferência de esquema. O Auto Loader escolhe o caso arbitrariamente com base nos dados amostrados. Você pode usar dicas de esquema para determinar qual caixa deve ser usada. Após o Auto Loader fazer uma seleção e inferir o esquema, ele não considera as variantes de maiúsculas e minúsculas que não foram selecionadas de acordo com o esquema.
Quando a coluna de dados recuperados está habilitada, o Auto Loader carrega campos nomeados em uma caixa diferente daquela do esquema para a coluna _rescued_data . Altere esse comportamento definindo a opção readerCaseSensitive como falsa, caso em que o Auto Loader lê os dados sem distinção entre maiúsculas e minúsculas.
Substitua a inferência de esquema por dicas de esquema
Você pode usar dicas de esquema para aplicar as informações de esquema que você conhece e espera em um esquema inferido. Quando você sabe que uma coluna possui um tipo de dado específico, ou se deseja escolher um tipo de dado mais genérico (por exemplo, um double ao invés de um integer), você pode fornecer um número arbitrário de dicas para tipos de dados de coluna como uma string usando a sintaxe de especificação de esquema SQL, como o seguinte:
.option("cloudFiles.schemaHints", "tags map<string,string>, version int")
Para obter a lista de tipos de dados suportados, consulte Mapeamentos de idioma.
Se uma coluna não estiver presente no início da transmissão, você também pode usar sugestões de esquema para adicionar essa coluna ao esquema inferido.
O exemplo a seguir mostra um esquema inferido e o resultado da aplicação de dicas de esquema.
Esquema inferido:
|-- date: string
|-- quantity: int
|-- user_info: struct
| |-- id: string
| |-- name: string
| |-- dob: string
|-- purchase_options: struct
| |-- delivery_address: string
Especificando as seguintes dicas de esquema:
.option("cloudFiles.schemaHints", "date DATE, user_info.dob DATE, purchase_options MAP<STRING,STRING>, time TIMESTAMP")
você obtém:
|-- date: string -> date
|-- quantity: int
|-- user_info: struct
| |-- id: string
| |-- name: string
| |-- dob: string -> date
|-- purchase_options: struct -> map<string,string>
|-- time: timestamp
O suporte a dicas de esquema de matriz e mapa está disponível em Databricks Runtime 9.1 LTS e acima.
O exemplo a seguir mostra um esquema inferido com tipos de dados complexos e o resultado da aplicação de dicas de esquema.
Esquema inferido:
|-- products: array<string>
|-- locations: array<string>
|-- users: array<struct>
| |-- users.element: struct
| | |-- id: string
| | |-- name: string
| | |-- dob: string
|-- ids: map<string,string>
|-- names: map<string,string>
|-- prices: map<string,string>
|-- discounts: map<struct,string>
| |-- discounts.key: struct
| | |-- id: string
| |-- discounts.value: string
|-- descriptions: map<string,struct>
| |-- descriptions.key: string
| |-- descriptions.value: struct
| | |-- content: int
Especificando as seguintes dicas de esquema:
.option("cloudFiles.schemaHints", "products ARRAY<INT>, locations.element STRING, users.element.id INT, ids MAP<STRING,INT>, names.key INT, prices.value INT, discounts.key.id INT, descriptions.value.content STRING")
você obtém:
|-- products: array<string> -> array<int>
|-- locations: array<int> -> array<string>
|-- users: array<struct>
| |-- users.element: struct
| | |-- id: string -> int
| | |-- name: string
| | |-- dob: string
|-- ids: map<string,string> -> map<string,int>
|-- names: map<string,string> -> map<int,string>
|-- prices: map<string,string> -> map<string,int>
|-- discounts: map<struct,string>
| |-- discounts.key: struct
| | |-- id: string -> int
| |-- discounts.value: string
|-- descriptions: map<string,struct>
| |-- descriptions.key: string
| |-- descriptions.value: struct
| | |-- content: int -> string
O Auto Loader usa dicas de esquema somente se você não fornecer um esquema. Você pode usar dicas de esquema para verificar se cloudFiles.inferColumnTypes está habilitado ou desabilitado.