Modede compatibilidade

info

Visualização

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

Usando Mode de Compatibilidade, você pode ler tabelas de gerenciamento Unity Catalog , visualizações materializadas e tabelas de transmissão de sistemas externos, mantendo o desempenho ideal no Databricks. Este 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 gerenciar, tabela transmissão ou view materializada, Mode de Compatibilidade gera uma versão somente leitura da sua tabela em um 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 de gerenciamento, incluindo tabelas de transmissão ou visualização materializada, 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 de gerenciamento, incluindo tabelas de transmissão ou visualizações materializadas, de clientes Iceberg como Apache Spark, Apache Trino e Snowflake por meio do catálogo REST Iceberg
Automação de configuração e esquecimento : automatize a atualização de dados e metadados para versões de compatibilidade, com a capacidade de configurar intervalos refresh para um ritmo quase real

Pré-requisitos

Para habilitar Mode de Compatibilidade em uma tabela, você deve usar Unity Catalog. Somente tabelas de transmissão Unity Catalog , visualizações materializadas Unity Catalog e tabelas de gerenciamento Unity Catalog são suportadas. Tabelas externas do Unity Catalog não são suportadas.

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

O local de destino deve existir na sua account de armazenamento e estar vazio.
O local de destino ou qualquer uma de suas pastas pai deve ser registrado como um local externo no Unity Catalog.
Você deve ter privilégio CREATE EXTERNAL TABLE para o local externo.
O local de destino e quaisquer pastas pai ou filho não devem ter sido usados como um local Mode Compatibilidade para outra tabela nos últimos 7 dias.

Habilitar Mode de Compatibilidade em tabelas

Para tabelas de transmissão, visualizações materializadas e clones superficiais de gerenciamento, defina as seguintes propriedades de tabela no momento da criação da tabela:

SQL
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 de gerenciamento Unity Catalog , você também pode habilitar Mode de Compatibilidade ao alterar uma tabela existente:

SQL
-- 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 refreshmanualmente a tabela imediatamente para confirmar se ela está funcionando.

nota

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

Verifique se Mode de Compatibilidade está ativado

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

Você também pode executar o seguinte comando SQL em um Notebook:

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

Procure essas propriedades na saída:

delta.universalFormat.enabledFormats: "compatibility" – Indica que Mode de Compatibilidade está ativado
delta.universalFormat.compatibility.location – Mostra a localização da versão do Mode de Compatibilidade

Configurar intervalos de refresh

Para tabelas de gerenciamento Unity Catalog , você pode configurar a frequência com que a versão Mode Compatibilidade é atualizada definindo o intervalo refresh :

SQL
-- 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 refresh default é 1 HOUR. Definir o intervalo refresh abaixo de 1 hora não é recomendado e não fará com que a atualização ocorra com mais frequência. A exceção é quando você define o intervalo de refresh como 0 MINUTES. Nesse caso, Databricks verifica se há alterações após cada commit e aciona uma refresh , se necessário.

Para tabelas de transmissão e visualizações materializadas, um intervalo refresh não é necessário. 0 MINUTES é o valor default .

nota

Alterações que impactam significativamente os tempos refresh (como renomeação de colunas ou ativação de ampliação de tipos) são executadas a cada hora, independentemente do intervalo de refresh de destino.

refreshmanual

Para acionar manualmente uma refresh da versão de compatibilidade:

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

refresh manual é útil para testar se o Mode de Compatibilidade está funcionando corretamente ou para garantir que sua versão de compatibilidade esteja atualizada antes de uma leitura subsequente. No entanto, esperar pela atualização automática pode ser mais econômico.

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

Mode de Compatibilidade gera dados e metadados de forma automática e assíncrona. Para tabelas de gerenciamento Unity Catalog , a geração ocorre a cada hora por default ou com base no intervalo de refresh configurado. Para tabelas de transmissão e visualizações materializadas, a geração ocorre após atualizações de tabelas quando há novos commits.

Para verificar se os dados e metadados foram gerados com sucesso:

Use DESCRIBE HISTORY para encontrar a versão mais recente da sua tabela de origem:
SQL
```
DESC HISTORY my_catalog.my_schema.my_table
```
Este comando retorna o histórico de atualização para Mode de Compatibilidade, incluindo a versão e o registro de data e hora Delta Lake . A linha superior contém a versão mais recente e o registro de data e hora.
Use DESCRIBE EXTENDED para encontrar a versão correspondente do Mode de Compatibilidade:
SQL
```
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 Modede Compatibilidade
- Última atualização : o registro de data e hora da última refresh
Mode de Compatibilidade estará atualizado se a versão da tabela corresponder à versão encontrada no passo 1.
Use DESC HISTORY na própria versão de compatibilidade:
SQL
```
DESC HISTORY delta.\`<compatibility_location>\`
```
No Catalog Explorer, view os campos de metadados para a versão de compatibilidade. Mode de Compatibilidade estará atualizado se a versão Delta Lake corresponder à versão encontrada no passo 3.

Monitorar custos

A Otimização Preditiva gerencia o cluster compute que faz a atualização automática para Mode de Compatibilidade. Para view os custos associados, consulte as tabelas de faturamento do sistema:

SQL
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 relata o uso somente para atualização automática. Os custos de atualização manual estão associados ao seu compute e não há uma maneira direta de rastrear esses custos separadamente. Geralmente, o custo de um gatilho manual é proporcional ao custo das operações de gravação iniciais na tabela original.

Remover arquivos de dados não utilizados

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

SQL
VACUUM delta.'<compatibility_mode_location_path>';

Para encontrar o caminho do local Mode de Compatibilidade, use o comando DESCRIBE EXTENDED em Verificar se Mode de Compatibilidade está habilitado. Na saída, o valor de delta.universalFormat.compatibility.location é o local.

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 para Amazon Athena, Snowflake (leitor Delta) e Fabric.

Amazon Atena

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

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

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

Snowflake Delta Lake 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 formato Delta Lake:

SQL
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;

atualizar a tabela ( refresh automática não é suportada para o formato Delta Lake no Snowflake):
SQL
```
ALTER EXTERNAL TABLE <table_name> REFRESH;
```
Leia a tabela:
SQL
```
SELECT * FROM <table_name>;
```

Tecido Microsoft

Crie uma capacidade de Fabric, workspace e Synapse Notebook.
Crie um lakehouse com dados no local de compatibilidade.

Leia os arquivos como uma tabela Delta Lake:

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

Lendo versões de compatibilidade da API REST do Unity

Tabelas com Mode Compatibilidade ativado podem ser lidas por nome por meio da API REST do Unity com parâmetros especiais. Para tabelas de transmissão, configure o seguinte parâmetro API :

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

Para visualização materializada, defina o seguinte parâmetro 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 Mode de Compatibilidade ativado podem ser lidas de qualquer cliente Iceberg usando o catálogo REST Iceberg . Mode de Compatibilidade funciona automaticamente para os formatos de tabela Delta Lake e Iceberg .

Requisitos de configuração

Habilite o acesso a dados externos no metastore.
Conceda privilégio EXTERNAL USE SCHEMA no esquema.
Crie um token de acesso pessoal (PAT) Databricks .

Configuração do Apache Spark

Bash
bin/spark-sql --packages org.apache.iceberg:iceberg-spark-runtime-3.5_2.12:1.8.0,org.apache.iceberg:iceberg-aws-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 mais informações, consulte Usar tabelas Iceberg com Apache Spark.

ConfiguraçãoSnowflake

SQL
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 Modede compatibilidade

Para desabilitar Mode de Compatibilidade, desmarque a propriedade da tabela correspondente:

SQL
-- 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' = '')

atenção

Desativar Mode de Compatibilidade interrompe imediatamente a geração de dados e metadados. Após 7 dias, os dados e metadados associados serão excluídos. Dentro desse período de 7 dias, você pode restaurar os dados e metadados reativando Mode 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 a RLS/CLS : você não pode habilitar Mode de Compatibilidade em tabelas com Segurança em Nível de Linha (RLS) ou Segurança em Nível de Coluna (CLS).
Sem renomeação de coluna de partição : a renomeação de coluna de partição não é suportada em tabelas com Mode de Compatibilidade ativado. A renomeação de colunas de dados é suportada.
Recurso de tabela limitado : Os seguintes recursos não estão disponíveis na versão de compatibilidade:
- Colunas de agrupamento
- Chave primária
- viagem do tempo
- Alterar feed de dados
- Nomes de colunas com caracteres especiais (serão renomeados)

Visão geral​

Pré-requisitos​

Habilitar Mode de Compatibilidade em tabelas​

Verifique se Mode de Compatibilidade está ativado​

Configurar intervalos de refresh​

refreshmanual​

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

Monitorar custos​

Remover arquivos de dados não utilizados​

Ler versões de compatibilidade de clientes externos​

Amazon Atena​

Snowflake Delta Lake de Neve​

Tecido Microsoft​

Lendo versões de compatibilidade da API REST do Unity​

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

Requisitos de configuração​

Configuração do Apache Spark​

ConfiguraçãoSnowflake​

Desativar Modede compatibilidade​

Limitações​