Pular para o conteúdo principal
Última atualização em

Habilitar acesso a dados externos a tabelas de transmissão e views materializadas

Se você habilitou o acesso a dados externos ao Unity Catalog, você pode adicionar acesso a dados externos a views materializadas e tabelas de transmissão gerenciadas por pipeline e autônomas. Isso permite que clientes externos Delta e Iceberg acessem seus datasets através das APIs REST do Unity Catalog e do catálogo Iceberg, sem exigir uma cópia completa dos dados.

O acesso a dados externos funciona para datasets gerenciados por LakeFlow Pipelines e para views materializadas e tabelas de transmissão independentes.

Capacidades​

O uso do acesso a dados externos expõe os mesmos dados disponíveis no Databricks para views materializadas e tabelas de transmissão gerenciadas por pipeline e autônomas, sem criar uma duplicata dos dados. Isso resulta nas seguintes características de desempenho e funcionalidade:

  • Nenhuma cópia de dados necessária: O acesso externo é ativado sem duplicar o dataset completo.
  • Acesso externo via APIs: Leia views materializadas e tabelas de transmissão usando APIs do Delta Lake ou do Iceberg.
  • Consistência de leitura após gravação: Leitores externos podem acessar dados atualizados após uma atualização no dataset, garantindo que não haja obsolescência. As atualizações estão disponíveis imediatamente após o refresh.
  • Objeto de tabela única: datasets aparecem externamente como tabelas gerenciadas com o mesmo nome do dataset de origem nas APIs do Unity Catalog.
  • Baixo custo: Como o dataset completo não é copiado, a sobrecarga para fornecer acesso externo é baixa.

Requisitos​

Os requisitos para seus datasets são:

  • Unity Catalog: As suas tabelas de transmissão e views materializadas devem estar usando o Unity Catalog.
  • Versão do Databricks Runtime: Você deve usar o Databricks Runtime 17.3 e acima.
  • Modo de publicação default: a legibilidade externa só é suportada no modo de publicação default. Para usar a legibilidade externa, migre para o modo de publicação default. Os recursos que dependem de metadados externos, como o CDF de view materializada, funcionarão no modo de publicação legado.

Os requisitos para os seus clientes são:

  • Versão da API do Delta: O cliente deve oferecer suporte às APIs do Delta Lake 4.0.0 ou acima, incluindo vetores de exclusão, e deve usar as APIs de catálogo do Unity Catalog para acesso.
  • Versão da API do Iceberg: Como alternativa, o cliente pode acessar usando APIs de catálogo do Iceberg que ofereçam suporte à especificação Iceberg v3.
  • Privilégios do Unity Catalog: O principal que lê os datasets externamente deve ter o privilégio EXTERNAL USE SCHEMA no esquema e o privilégio SELECT na tabela.
nota

Caso o cliente não ofereça suporte a esses requisitos, também é possível usar o modo de compatibilidade, que oferece suporte a todos os clientes Delta e Iceberg, mas exige a criação de uma cópia completa do dataset.

Como habilitar o acesso a um dataset​

Existem dois passos para habilitar o acesso externo a um dataset.

  1. Habilite metadados externos usando a configuração do pipeline ou uma propriedade de tabela. A configuração em nível de tabela tem precedência sobre a configuração do pipeline quando ambas estão definidas e é suportada tanto para tabelas de transmissão e views materializadas gerenciadas por pipeline quanto independentes.

    • Configuração do pipeline: defina pipelines.externalMetadata.enabled como true para habilitar metadados externos para todos os datasets no pipeline. Views materializadas e tabelas de transmissão independentes criadas com o Databricks SQL não possuem uma configuração de pipeline; use uma propriedade de tabela em vez disso.

In the pipeline settings, complete the following steps:

  1. Open your pipeline and click Settings.
  2. Under Configuration, add a key-value pair: Key pipelines.externalMetadata.enabled, Value true.
  3. Click Save.

  • Propriedade da tabela: adicione a seguinte propriedade à definição da tabela de transmissão ou view materializada. Para Lakeflow Connect Pipelines, consulte Definir propriedades da tabela Delta.

    SQL
    CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
    TBLPROPERTIES('pipelines.externalMetadata.enabled' = 'true')

Após salvar a configuração, execute ou reinicie o pipeline para aplicar as alterações:

  • Pipelines Acionados : execute o pipeline uma vez.
  • Pipelines contínuos : parar e reiniciar o pipeline.

Para objetos Databricks SQL autônomos, use CREATE OR REPLACE MATERIALIZED VIEW ou CREATE OR REFRESH STREAMING TABLE com a propriedade de tabela. O comando CREATE ou REFRESH aplica a propriedade.

  1. Se você planeja ler o dataset com um cliente Iceberg moderno, adicione as seguintes propriedades UniForm Iceberg V3 além da propriedade de metadados externos. Para pipelines do Lakeflow Connect, consulte Definir propriedades da tabela Delta.

Propriedade

Uso

'pipelines.externalMetadata.enabled' = 'true'

Habilite o acesso externo para a tabela. Essa configuração em nível de tabela tem precedência sobre a configuração de pipeline quando ambas estão definidas.

'delta.columnMapping.mode' = 'name'

Mapeamento de coluna é necessário para Iceberg.

'delta.enableRowTracking' = 'true'

Ative o acompanhamento de linhas para leituras de Iceberg.

'delta.universalFormat.enabledFormats' = 'iceberg'

Habilitar leituras de Iceberg.

'delta.enableIcebergCompatV3' = 'true'

Use o Iceberg V3 para leituras de Iceberg.

Propriedade

Uso

'pipelines.externalMetadata.enabled' = 'true'

Habilite o acesso externo para a tabela. Essa configuração em nível de tabela tem precedência sobre a configuração de pipeline quando ambas estão definidas.

'delta.columnMapping.mode' = 'name'

Mapeamento de coluna é necessário para Iceberg.

'delta.enableRowTracking' = 'true'

Ative o acompanhamento de linhas para leituras de Iceberg.

'delta.universalFormat.enabledFormats' = 'iceberg'

Habilitar leituras de Iceberg.

'delta.enableIcebergCompatV3' = 'true'

Use o Iceberg V3 para leituras de Iceberg.

SQL
CREATE OR REFRESH [MATERIALIZED VIEW | STREAMING TABLE] tbl_name
TBLPROPERTIES(
  'delta.columnMapping.mode' = 'name',
  'delta.enableRowTracking' = 'true',
  'delta.enableIcebergCompatV3' = 'true',
  'delta.universalFormat.enabledFormats' = 'iceberg',
  'pipelines.externalMetadata.enabled' = 'true')

Para views materializadas, você pode usar a sintaxe USING ICEBERG equivalente.

SQL
CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

Para datasets gerenciados por pipeline, use as instruções de atualização de pipeline acima para aplicar as propriedades do Iceberg. Para objetos autônomos do Databricks SQL, execute novamente a definição do objeto com as propriedades atualizadas. Use CREATE OR REPLACE MATERIALIZED VIEW para uma view materializada ou CREATE OR REFRESH STREAMING TABLE para uma tabela de transmissão. Para ver as propriedades do seu dataset, use as instruções SQL DESCRIBE DETAIL ou DESCRIBE EXTENDED.

Solução de problemas de acesso a dados externos​

Se você acredita que os metadados externos estão obsoletos, um principal com o privilégio MODIFY na tabela pode trigger manualmente a atualização de metadados no compute de cluster compartilhado usando o Databricks Runtime 17.3 ou acima:

SQL
REPAIR TABLE <catalog>.<schema>.<table-name> SYNC METADATA;

Você pode verificar a presença dos metadados Iceberg na interface do usuário do Catalog Explorer na página de detalhes da tabela. Alternativamente, execute os seguintes comandos no editor SQL ou em um notebook Databricks:

SQL
DESCRIBE DETAIL <catalog>.<schema>.<table-name>;
DESCRIBE EXTENDED <catalog>.<schema>.<table-name>;

Para uma tabela de transmissão, compare a versão dos metadados Iceberg com a versão mais recente da tabela de transmissão. A comparação de versões para visualizações materializadas ainda não está disponível.

Ler dados de clientes externos​

As seções a seguir fornecem exemplos de como ler seu dataset a partir de diferentes clientes e ambientes.

Para detalhes de configuração, consulte acesso de cliente Delta e acesso de cliente Iceberg.

Use a API REST do Unity com o Spark Delta Reader​

Utilize a versão 4.0 ou posterior do Apache Spark™. Você pode fazer download de https://spark.apache.org/downloads.html.

  1. Com base no seu provedor de cloud, execute o seguinte comando para iniciar um shell do Spark SQL com Delta 4.0 e Unity Catalog.
Shell
bin/spark-sql \
    --packages org.apache.spark:spark-hadoop-cloud_2.13:4.0.0,io.unitycatalog:unitycatalog-spark_2.13:0.3.1 \
    --conf spark.sql.extensions=io.delta.sql.DeltaSparkSessionExtension \
    --conf spark.sql.catalog.spark_catalog=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.hadoop.fs.s3.impl=org.apache.hadoop.fs.s3a.S3AFileSystem \
    --conf spark.sql.catalog.<uc-catalog-name>=io.unitycatalog.spark.UCSingleCatalog \
    --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url> \
    --conf spark.sql.catalog.<uc-catalog-name>.token=<PAT> \
    --conf spark.sql.defaultCatalog=<uc-catalog-name>

  1. Do shell SQL, agora se pode acessar seu dataset com o Spark SQL. Por exemplo:

    Shell
    spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

Use o leitor Snowflake Iceberg​

Dentro do Snowflake, é possível usar o leitor Iceberg. Isso requer suporte ao Iceberg v3 no Snowflake.

  1. Configurar o catálogo REST do Iceberg no Snowflake.

    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-table-name>';

  2. Acesse seu dataset a partir do Snowflake SQL.

    SQL
    ALTER ICEBERG TABLE my_table REFRESH;
    SELECT * FROM my_table;

Use o catálogo REST Iceberg com o leitor Iceberg Spark​

Utilize a versão 4.0 ou posterior do Apache Spark™. Você pode fazer download de https://spark.apache.org/downloads.html.

  1. Na AWS, execute o seguinte comando para iniciar um shell do Spark SQL com Iceberg v3.

    Shell
    bin/spark-sql \
      --packages org.apache.iceberg:iceberg-spark-runtime-4.0_2.13:1.10.0,org.apache.iceberg:iceberg-aws-bundle:1.10.0 \
      --conf spark.sql.extensions=org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions \
      --conf spark.sql.catalog.<uc-catalog-name>=org.apache.iceberg.spark.SparkCatalog \
      --conf spark.sql.catalog.<uc-catalog-name>.io-impl=org.apache.iceberg.aws.s3.S3FileIO \
      --conf spark.sql.catalog.<uc-catalog-name>.type=rest \
      --conf spark.sql.catalog.<uc-catalog-name>.uri=<workspace_url>/api/2.1/unity-catalog/iceberg-rest \
      --conf spark.sql.catalog.<uc-catalog-name>.token='<PAT>' \
      --conf spark.sql.catalog.<uc-catalog-name>.warehouse=<uc-catalog-name> \
      --conf spark.sql.iceberg.vectorization.enabled=false

  2. Acesse seu dataset a partir do Spark SQL.

    Shell
    spark-sql ()> SELECT * FROM <uc-catalog>.<uc-schema>.<uc-table-name>;

Migrar do modo de compatibilidade​

Se você está atualmente compartilhando um dataset usando o modo de compatibilidade, você pode migrar para usar o acesso a dados externos.

  1. Ative este recurso seguindo os passos em Como Habilitar o Acesso para um Dataset.
  2. Desative o modo de compatibilidade. Consulte Desativar Compatibility Mode

Limitações​

As seguintes são as limitações conhecidas do acesso a dados externos para tabelas de transmissão e views materializadas.

  • Gravações Externas: Gravações externas em datasets de pipeline não são suportadas.
  • Acesso baseado em caminho: Leitores externos que exigem acesso baseado em caminho (leitura diretamente por um local de armazenamento em vez da interface da API do UC) não são suportados. Para oferecer suporte ao acesso baseado em caminho, pode-se utilizar o modo de compatibilidade, que oferece suporte ao acesso baseado em caminho, mas exige uma cópia completa do dataset.
  • Recursos de segurança: Não há suporte para segurança em nível de linha ou mascaramento em nível de coluna a partir de leituras externas.
  • Viagem do tempo: a viagem do tempo por meio deste recurso não é compatível.
  • Catalog commits (beta): Catalog commits não são compatíveis com o acesso a dados externos. Para usar o acesso a dados externos em uma tabela de transmissão ou view materializada, você deve primeiro desabilitar os catalog commits.
  • Fabric: A leitura no Microsoft Fabric não tem suporte.
Nesta página