Modo de compatibilidade

Importante

Esse recurso está em Visualização Pública.

Usando o Modo de Compatibilidade do Unity Catalog, você pode ler tabelas gerenciadas, visões materializadas e tabelas de streaming de sistemas externos, mantendo o desempenho ideal no Azure Databricks. Esse recurso gera automaticamente versões somente leitura de suas tabelas que podem ser acessadas por qualquer cliente Delta Lake ou Iceberg.

Visão geral

Quando habilitado em uma tabela gerenciada, tabela de streaming ou vista materializada, o Modo de Compatibilidade gera uma versão somente leitura da sua tabela em um local escolhido. Essa versão de compatibilidade inclui metadados v1 para os formatos Delta Lake e Iceberg, fornecendo os seguintes recursos:

Interoperabilidade com qualquer cliente Delta Lake: Leia suas tabelas gerenciadas, incluindo tabelas de streaming ou exibições materializadas, de clientes como Amazon Athena, Microsoft Fabric, Snowflake e Amazon Redshift diretamente do armazenamento ou por meio da API REST do Unity
Interoperabilidade com qualquer cliente Iceberg: leia suas tabelas gerenciadas, incluindo tabelas de streaming ou visões materializadas, de clientes Iceberg como Apache Spark, Apache Trino e Snowflake através do catálogo REST do Iceberg
Automação configurável e esquecível: Automatizar atualizações de dados e metadados para versões de compatibilidade, com a capacidade de configurar intervalos de atualização para praticamente em tempo real.

Pré-requisitos

Para habilitar o Modo de Compatibilidade em uma tabela, você deve estar usando o Catálogo do Unity. Há suporte apenas para tabelas de streaming do Catálogo do Unity, exibições materializadas do Catálogo do Unity e tabelas gerenciadas do Catálogo do Unity. Não há suporte para tabelas externas do Catálogo do Unity.

Além disso, verifique se você tem um local externo registrado no Catálogo do Unity com as configurações e permissões adequadas:

O local de destino deve existir em sua conta de armazenamento e estar vazio.
O local de destino ou qualquer uma de suas pastas pai deve ser registrado como uma localização externa no Unity Catalog.
Você deve ter CREATE EXTERNAL TABLE privilégios para o local externo.
O local de destino e as pastas pai ou filho não devem ter sido usados como um local do Modo de Compatibilidade para outra tabela nos últimos 7 dias.

Habilitar o Modo de Compatibilidade em tabelas

Para tabelas de streaming, exibições materializadas e clones rasos gerenciados, defina as seguintes propriedades de tabela no momento da criação da tabela:

CREATE [STREAMING TABLE | MATERIALIZED VIEW | TABLE] my_catalog.my_schema.my_table
TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Somente para tabelas gerenciadas do Catálogo do Unity, você também pode habilitar o Modo de Compatibilidade ao alterar uma tabela existente:

-- For existing managed tables
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>'
)

Leva até uma hora para gerar uma versão de compatibilidade pela primeira vez. Você pode atualizar manualmente a tabela imediatamente para confirmar se ela está funcionando.

Observação

Você deve especificar o nome completo da tabela de três partes (catalog.schema.table_name). Por exemplo, for users.john.my_table, usersé o catálogo e john é o esquema.

Verificar se o Modo de Compatibilidade está habilitado

Para verificar se o Modo de Compatibilidade está habilitado em sua tabela, verifique se a propriedade da delta.universalFormat.enabledFormats = 'compatibility' tabela existe. Você pode exibir essa propriedade na interface do usuário do Catalog Explorer na guia detalhes da tabela.

Você também pode executar os seguintes comandos SQL em um notebook:

DESC DETAIL my_catalog.my_schema.my_table
DESC EXTENDED my_catalog.my_schema.my_table

Procure estas propriedades na saída:

delta.universalFormat.enabledFormats: "compatibility" – Indica que o modo de compatibilidade está habilitado
delta.universalFormat.compatibility.location – Mostra o local da versão do Modo de Compatibilidade

Configurar intervalos de atualização

Para tabelas gerenciadas do Catálogo do Unity, você pode configurar com que frequência a versão do Modo de Compatibilidade é atualizada definindo o intervalo de atualização:

-- Evaluate whether a refresh is needed after every commit (fastest)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '0 MINUTES'
)

-- Refresh hourly (default)
ALTER TABLE my_catalog.my_schema.my_table SET TBLPROPERTIES(
  'delta.universalFormat.enabledFormats' = 'compatibility',
  'delta.universalFormat.compatibility.location' = '<location>',
  'delta.universalFormat.compatibility.targetRefreshInterval' = '1 HOUR'
)

O intervalo de atualização padrão é 1 HOUR. Não é recomendável definir o intervalo de atualização abaixo de 1 hora e não fará com que as atualizações ocorram com mais frequência. A exceção é quando você define o intervalo de atualização como 0 MINUTES. Nesse caso, o Azure Databricks verifica se há alterações após cada confirmação e dispara uma atualização, se necessário.

Para tabelas de streaming e exibições materializadas, um intervalo de atualização não é necessário. 0 MINUTES é o valor padrão.

Observação

As alterações que afetam significativamente os tempos de atualização (como renomeação de coluna ou ampliação de tipo de habilitação) são executadas por hora, independentemente do intervalo de atualização de destino.

Atualização manual

Para disparar manualmente uma atualização da versão de compatibilidade:

REFRESH [TABLE | STREAMING TABLE | MATERIALIZED VIEW] my_catalog.my_schema.my_table SYNC UNIFORM

A atualização manual é útil para testar se o Modo de Compatibilidade está funcionando corretamente ou para garantir que sua versão de compatibilidade seja up-to-date antes de uma leitura subsequente. No entanto, esperar pelas atualizações automáticas pode ser mais econômico.

Monitorar o status de geração de dados e metadados

O Modo de Compatibilidade gera dados e metadados de forma automática e assíncrona. Para tabelas gerenciadas do Catálogo do Unity, a geração ocorre por hora por padrão ou com base no intervalo de atualização configurado. Para tabelas de streaming e exibições materializadas, a geração ocorre após atualizações de tabela quando há novas confirmações.

Para verificar se os dados e metadados foram gerados com êxito:

Use DESCRIBE HISTORY para localizar a versão mais recente da tabela de origem:
```
DESC HISTORY my_catalog.my_schema.my_table
```
Esse comando retorna o histórico de atualizações para o Modo de Compatibilidade, incluindo a versão do Delta Lake e o carimbo de data/hora. A linha superior contém a versão mais recente e o carimbo de data/hora.
Use DESCRIBE EXTENDED para localizar a versão correspondente do Modo de Compatibilidade:
```
DESC EXTENDED my_catalog.my_schema.my_table
```
Procure campos em Informações uniformes de compatibilidade:
- Última versão atualizada: a versão do Delta Lake que foi atualizada pela última vez com o modo de compatibilidade
- Última atualização: o carimbo de data/hora da última atualização
O Modo de Compatibilidade é up-to-date se a versão da tabela corresponder à versão encontrada na etapa 1.
Utilize DESC HISTORY na versão de compatibilidade propriamente dita:
```
DESC HISTORY delta.\`<compatibility_location>\`
```
No Gerenciador de Catálogos, exiba os campos de metadados para a versão de compatibilidade. O Modo de Compatibilidade será up-to-date se a versão do Delta Lake corresponder à versão encontrada na etapa 3.

Monitorar custos

A Otimização Preditiva manipula o cluster de computação que faz atualizações automáticas para o Modo de Compatibilidade. Para exibir os custos associados, consulte as tabelas de cobrança do sistema:

SELECT
  DATE_TRUNC('DAY', start_time) AS day,
  SUM(usage_quantity) AS dbus
FROM
  system.storage.predictive_optimization_operations_history
WHERE
  operation_type = "COMPATIBILITY_MODE_REFRESH"
GROUP BY 1
ORDER BY 1 DESC;

Essa consulta relata apenas o uso das atualizações automáticas. Os custos de atualizações manuais são associados à sua computação e não há uma maneira direta de controlar separadamente esses custos. Em geral, o custo de um gatilho manual é proporcional ao custo da operação de gravação inicial para a tabela original.

Remover arquivos de dados não utilizados

Para remover arquivos de dados não utilizados na versão de compatibilidade da tabela, use VACUUM:

VACUUM delta.'<compatibility_mode_location_path>';

Para localizar o caminho de localização do Modo de Compatibilidade, use o DESCRIBE EXTENDED comando em Verificar se o Modo de Compatibilidade está habilitado. Na saída, o valor de delta.universalFormat.compatibility.location é a localização.

Ler versões de compatibilidade de clientes externos

Você pode usar qualquer cliente Delta Lake ou Iceberg para ler dados de versões de compatibilidade. Veja abaixo exemplos de Amazon Athena, Snowflake (leitor Delta) e Fabric.

Amazon Athena

No Editor de Consultas do Athena, crie uma tabela externa com o local especificado:

CREATE EXTERNAL TABLE <table_name>
LOCATION '<compatibility_location>'
TBLPROPERTIES ('table_type' = 'DELTA')

Leia a tabela:
```
SELECT * FROM <table_name>
```

Leitor do Lago Delta do Floco de Neve

Crie uma integração de armazenamento para acessar o local de armazenamento (consulte a documentação do Snowflake).

Crie uma tabela externa com o formato Delta Lake:

CREATE OR REPLACE EXTERNAL TABLE <table_name>
WITH LOCATION = @<my_location>
FILE_FORMAT = (TYPE = PARQUET)
TABLE_FORMAT = DELTA
AUTO_REFRESH = false
REFRESH_ON_CREATE = false;

Atualize a tabela (não há suporte para atualização automática para o formato Delta Lake no Snowflake):
```
ALTER EXTERNAL TABLE <table_name> REFRESH;
```
Leia a tabela:
```
SELECT * FROM <table_name>;
```

Microsoft Fabric

Crie uma capacidade do Fabric, um espaço de trabalho e um notebook do Synapse.
Crie um lakehouse com dados no local de compatibilidade.

Leia os arquivos como uma tabela Delta Lake.

spark.read.format("delta").load("Files/<path_to_data>")

Lendo versões de compatibilidade da API REST do Unity

Tabelas com modo de compatibilidade habilitado podem ser lidas por nome por meio da API REST do Unity com parâmetros especiais. Para tabelas de streaming, defina o seguinte parâmetro de API:

GET /api/2.1/unity-catalog/tables/{full_name}?read_streaming_table_as_managed=true

Para exibições materializadas, defina o seguinte parâmetro de API:

GET /api/2.1/unity-catalog/tables/{full_name}?read_materialized_view_as_managed=true

Lendo versões de compatibilidade do catálogo REST do Iceberg

Tabelas com modo de compatibilidade habilitado podem ser lidas de qualquer cliente Iceberg usando o catálogo REST do Iceberg. O Modo de Compatibilidade funciona automaticamente para formatos de tabela Delta Lake e Iceberg.

Requisitos de Configuração

Habilite o acesso a dados externos no metastore.
Conceda EXTERNAL USE SCHEMA privilégio no esquema.
Crie um PAT (Token de Acesso Pessoal) do Azure Databricks.

Configuração do Apache Spark

bin/spark-sql --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-azure-bundle:1.8.0 \
  --conf "spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions" \
  --conf spark.sql.catalog.catalog_name=org.apache.iceberg.spark.SparkCatalog \
  --conf spark.sql.catalog.catalog_name.type=rest \
  --conf spark.sql.catalog.catalog_name.uri=<workspace-url>/api/2.1/unity-catalog/iceberg-rest \
  --conf spark.sql.catalog.catalog_name.token=<PAT> \
  --conf spark.sql.catalog.catalog_name.warehouse=<uc-catalog-name>

Para obter mais informações, consulte Usar tabelas do Iceberg com o Apache Spark.

Configuração do Snowflake

CREATE OR REPLACE CATALOG INTEGRATION my_uc_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<uc-schema-name>'
  REST_CONFIG = (
    CATALOG_URI = '<workspace-url>/api/2.1/unity-catalog/iceberg-rest'
    CATALOG_NAME = '<uc-catalog-name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<PAT>'
  )
  ENABLED = TRUE;

CREATE OR REPLACE ICEBERG TABLE my_table
  CATALOG = 'my_uc_int'
  CATALOG_TABLE_NAME = '<uc-st/mv-name>';

Desabilitar o modo de compatibilidade

Para desabilitar o Modo de Compatibilidade, desative a propriedade de tabela correspondente:

-- For UC managed tables
ALTER TABLE my_table UNSET TBLPROPERTIES('delta.universalFormat.enabledFormats')

-- For streaming tables and materialized views
CREATE OR REPLACE [STREAMING TABLE | MATERIALIZED VIEW] my_table
TBLPROPERTIES('delta.universalFormat.enabledFormats' = '')

Aviso

Desativar o Modo de Compatibilidade interrompe imediatamente a geração de dados e metadados. Após 7 dias, os dados e metadados associados serão excluídos. Nesse período de 7 dias, você pode restaurar os dados e os metadados habilitando novamente o Modo de Compatibilidade na mesma tabela.

Limitações

Acesso somente leitura: a versão de compatibilidade é somente leitura. Você não pode gravar na versão de compatibilidade.
Sem suporte para RLS/CLS: não é possível habilitar o Modo de Compatibilidade em tabelas com Row-Level Security (RLS) ou CLS (Column-Level Security).
Nenhuma renomeação de coluna de partição: não há suporte para renomeação de coluna de partição em tabelas com o Modo de Compatibilidade habilitado. Há suporte para renomeação de coluna de dados.
Recursos de tabela limitados: os seguintes recursos não estão disponíveis na versão de compatibilidade:
- Colunas de collation
- Chaves primárias
- Viagem no tempo
- Alterar feed de dados
- Nomes de coluna com caracteres especiais (serão renomeados)

Comentários

Esta página foi útil?

Last updated on 2025-12-03