Imposição de esquema

O Azure Databricks valida a qualidade dos dados aplicando o esquema durante a gravação em tabelas do Delta Lake. A imposição de esquema não se aplica a tabelas que usam formatos não Delta, como arquivos CSV ou JSON no armazenamento em nuvem.

Imposição de esquema para operações INSERT

O Azure Databricks impõe as seguintes regras ao inserir dados em uma tabela:

• Todas as colunas inseridas devem existir na tabela de destino.
• Todos os tipos de dados de coluna devem corresponder aos tipos de dados de coluna na tabela de destino.

INSERT Exemplos

Os exemplos a seguir escrevem em uma tabela gerenciada do Delta Lake chamada enforce_demo. Para criá-la, execute o seguinte:

CREATE OR REPLACE TABLE main.default.enforce_demo (id INT, name STRING, amount BIGINT);

O seguinte INSERT falha porque unknown_column não existe em enforce_demo. Azure Databricks retorna o erro UNRESOLVED_COLUMN.WITH_SUGGESTION (SQLSTATE 42703) que sugere nomes de colunas válidos:

INSERT INTO main.default.enforce_demo (id, unknown_column) VALUES (1, 'value');

O seguinte INSERT é bem-sucedido. O Azure Databricks converte com segurança o inteiro 42 para o tipo BIGINT da coluna amount:

INSERT INTO main.default.enforce_demo (id, amount) VALUES (1, 42);

Imposição de esquema para operações MERGE

O Azure Databricks impõe as seguintes regras ao inserir ou atualizar dados como parte de uma MERGE operação:

• Se o tipo de dados na instrução de origem não corresponder à coluna de destino, MERGE tenta converter tipos de dados de coluna com segurança para corresponder à tabela de destino.
• As colunas de destino de uma ação UPDATE ou INSERT devem existir na tabela de destino.
• Ao usar INSERT * ou UPDATE SET *:
  • O conjunto de dados de origem deve ter todas as colunas presentes na tabela de destino.
  • A aplicação ignora colunas no conjunto de dados de origem que não estão na tabela de destino.

MERGE Exemplos

Os exemplos a seguir reutilizam a enforce_demo tabela da seção anterior, junto com uma tabela fonte chamada enforce_source que possui uma coluna extra. Para criar a tabela de origem, execute o seguinte:

CREATE OR REPLACE TABLE main.default.enforce_source (id INT, name STRING, amount BIGINT, extra_col STRING);

INSERT INTO main.default.enforce_source VALUES (1, 'Alice', 100, 'x'), (2, 'Bob', 200, 'y');

O seguinte MERGE falha porque atribui a unknown_column, que não existe em enforce_demo. O Azure Databricks retorna um DELTA_MERGE_UNRESOLVED_EXPRESSION erro que nomeia as colunas que ele pode resolver:

MERGE INTO main.default.enforce_demo AS t
USING main.default.enforce_source AS s
ON t.id = s.id
WHEN MATCHED THEN UPDATE SET t.unknown_column = s.name
WHEN NOT MATCHED THEN INSERT (id, unknown_column) VALUES (s.id, s.name);

A enforce_source tabela inclui uma extra_col coluna que enforce_demo não tem. O seguinte MERGE com INSERT * tem sucesso porque a fonte contém todas as colunas de destino. A fiscalização ignora extra_col:

MERGE INTO main.default.enforce_demo AS t
USING main.default.enforce_source AS s
ON t.id = s.id
WHEN NOT MATCHED THEN INSERT *;

Modificar um esquema de tabela

Você pode atualizar o esquema de uma tabela usando instruções explícitas ALTER TABLE ou evolução automática do esquema. Consulte Esquemas de tabela de atualização com evolução do esquema.

Por exemplo, para adicionar uma coluna explicitamente:

ALTER TABLE catalog.schema.table_name ADD COLUMN new_column STRING;

Para habilitar a evolução automática do esquema para uma operação de gravação, defina a opção mergeSchema :

SQL

SET spark.databricks.delta.schema.autoMerge.enabled = true;
INSERT INTO catalog.schema.table_name SELECT * FROM source_table;

Python

df.write.option("mergeSchema", "true").mode("append").saveAsTable("catalog.schema.table_name")

A evolução do esquema tem semântica especial para as operações INSERT e MERGE. Consulte Habilitar a evolução do esquema.

Tabelas externas

Se você modificar os metadados de uma tabela externa diretamente com clientes externos fora Azure Databricks ou usando o acesso baseado em caminho, o Catálogo do Unity não sincroniza automaticamente as atualizações com o esquema. Isso pode impedir que a validação do esquema seja aplicada corretamente.

Execute MSCK REPAIR TABLE <table-name> SYNC METADATA para sincronizar o esquema com o Catálogo do Unity. Consulte REPAIR TABLE.