Modo de Compatibilidade

Usando o Modo de Compatibilidade, você pode ler tabelas gerenciadas do Catálogo Unity, exibiçõ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 ativado numa tabela gerida, tabela de streaming ou vista materializada, o Modo de Compatibilidade gera uma versão só de leitura da sua tabela num local escolhido. Esta 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 visualizações materializadas, de clientes como Amazon Athena, Microsoft Fabric, Snowflake e Amazon Redshift diretamente do armazenamento ou por meio da API REST Unity
• Interoperabilidade com qualquer cliente Iceberg: Leia suas tabelas gerenciadas, incluindo tabelas de streaming ou visualizações materializadas, de clientes Iceberg como Apache Spark, Apache Trino e Snowflake através do catálogo Iceberg REST
• Automação de 'definir e esquecer': automatizar atualizações de dados e metadados para versões de compatibilidade, com a capacidade de configurar intervalos de atualização próximo de tempo real

Pré-requisitos

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

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

• O local de destino deve existir na sua conta de armazenamento e estar vazio.
• O local de destino ou qualquer uma das suas pastas pai tem de ser registado como um local externo no Unity Catalog.
• Você deve ter CREATE EXTERNAL TABLE privilégio no local externo.
• O local de destino e quaisquer pastas associadas, como pai ou filho, não devem ter sido utilizado como um local do Modo de Compatibilidade para outra tabela nos 7 dias anteriores.

Ativar o Modo de Compatibilidade em tabelas

Para tabelas de streaming, exibições materializadas e clones superficiais 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 Unity Catalog, você também pode ativar 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.

Verificar se o Modo de Compatibilidade está ativado

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

Você também pode executar os seguintes comandos SQL em um bloco de anotações:

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á ativado
• delta.universalFormat.compatibility.location – Mostra a localização da versão do Modo de Compatibilidade

Configurar intervalos de atualização

Para tabelas gerenciadas do Unity Catalog, você pode configurar a frequência com que 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. Definir o intervalo de atualização abaixo de 1 hora não é recomendado 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 streaming de tabelas e exibições materializadas, não é necessário um intervalo de atualização. 0 MINUTES é o valor padrão.

Atualização manual

Para acionar 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 esteja up-todata 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 Unity Catalog, a geração ocorre por hora por padrão ou com base no intervalo de atualização configurado. Para tabelas de streaming e visões materializadas, a geração ocorre após as atualizações da tabela, quando há novas confirmações.

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

1. Use DESCRIBE HISTORY para encontrar a versão mais recente da sua tabela de origem:

   DESC HISTORY my_catalog.my_schema.my_table
   

   

   Este comando retorna o histórico de atualizações para o Modo de Compatibilidade, incluindo a versão Delta Lake e o carimbo de data/hora. A linha superior contém a versão mais recente e o carimbo de data/hora.

2. Use DESCRIBE EXTENDED para encontrar a versão correspondente do Modo de Compatibilidade:

   DESC EXTENDED my_catalog.my_schema.my_table
   

   

   Procure campos em Informações de compatibilidade uniforme:

   • Última versão atualizada: A versão 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.

3. Use DESC HISTORY na própria versão de compatibilidade:

   DESC HISTORY delta.\`<compatibility_location>\`
   

   

4. No Gerenciador de Catálogos, exiba os campos de metadados da versão de compatibilidade. Modo de Compatibilidade está atualizado se a versão Delta Lake corresponder à versão encontrada na etapa 3.

   

Monitorizar os custos

A Otimização Preditiva lida com o cluster de computação que faz atualizações automáticas para o Modo de Compatibilidade. Para visualizar os custos associados, consulte as tabelas de faturamento 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;

Esta consulta reporta o uso apenas para atualizações automáticas. Os custos de atualizações manuais estão associados à sua computação e não há uma maneira direta de acompanhar separadamente esses custos. Geralmente, o custo de um gatilho manual é proporcional ao custo da operação de gravação inicial para a tabela original.

Remover ficheiros de dados não utilizados

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

VACUUM delta.'<compatibility_mode_location_path>';

Para localizar o caminho de localização do Modo de Compatibilidade, utilize o comando em Verificar se o DESCRIBE EXTENDEDModo de Compatibilidade está ativado. Na saída, o valor para delta.universalFormat.compatibility.location indica 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

1. 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')
   

2. Leia a tabela:

   SELECT * FROM <table_name>
   

Leitor Snowflake Delta Lake

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

2. 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;
   

3. Atualize a tabela (a atualização automática não é suportada para o formato Delta Lake no Snowflake):

   ALTER EXTERNAL TABLE <table_name> REFRESH;
   

4. Leia a tabela:

   SELECT * FROM <table_name>;
   

Microsoft Fabric

1. Crie uma capacidade Fabric, espaço de trabalho e notebook Synapse.

2. Crie uma casa de lago com dados no local de compatibilidade.

3. Leia os arquivos como uma tabela Delta Lake:

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

Leitura de versões de compatibilidade da API REST Unity

As tabelas com o Modo de Compatibilidade ativado podem ser lidas pelo nome através da API REST 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

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

As tabelas com o Modo de Compatibilidade ativado podem ser lidas a partir de qualquer cliente Iceberg usando o catálogo REST do Iceberg. O Modo de Compatibilidade funciona automaticamente para os formatos de tabela Delta Lake e Iceberg.

Requisitos de configuração

1. Habilite o acesso a dados externos no metastore.
2. Conceda EXTERNAL USE SCHEMA permissão ao esquema.
3. Crie um Token de Acesso Pessoal (PAT) 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 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>';

Desativar o Modo de Compatibilidade

Para desativar o Modo de Compatibilidade, desative a propriedade da 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' = '')

Limitações

• Acesso somente leitura: A versão de compatibilidade é de acesso somente leitura. Não é possível escrever na versão de compatibilidade.
• Sem suporte a RLS/CLS: não é possível ativar o Modo de Compatibilidade em tabelas com Segurança Row-Level (RLS) ou Segurança Column-Level (CLS).
• Sem renomeação de coluna de partição: a renomeação de coluna de partição não é suportada em tabelas com o Modo de Compatibilidade ativado. Há suporte para a renomeação de colunas de dados.
• Recursos de tabela limitados: Os seguintes recursos não estão disponíveis na versão de compatibilidade:
  • Colunas de agrupamento
  • Chaves primárias
  • Viagem no tempo
  • Alterar feed de dados
  • Nomes de colunas com caracteres especiais (serão renomeados)