Habilitar o acesso externo a dados em tabelas de streaming e views materializadas

Se você tiver habilitado o acesso a dados externos para o Catálogo do Unity, poderá adicionar acesso a dados externos a visualizações materializadas e tabelas de streaming gerenciadas por pipeline e independentes. Isso permite que clientes externos de Delta e Iceberg acessem seus conjuntos de dados por meio 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 conjuntos de dados gerenciados por pipelines do Lakeflow e para visualizações materializadas e tabelas de streaming independentes.

Capabilities

Usar o acesso a dados externos expõe os mesmos dados disponíveis no Azure Databricks para visualizações materializadas e tabelas de streaming gerenciadas por pipeline e independentes, sem criar uma duplicata dos dados. Isso fornece as seguintes características para desempenho e funcionalidade:

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

Requirements

Os requisitos para seus conjuntos de dados são:

  • Catálogo do Unity: Suas tabelas de streaming e exibições materializadas devem estar usando o Catálogo do Unity.
  • Versão do Databricks Runtime: Você deve estar usando o Databricks Runtime 17.3 e superior.
  • Modo padrão de publicação: A legibilidade externa só é suportada no modo padrão de publicação. Para usar legibilidade externa, migre para o modo padrão de publicação. Recursos que dependem de metadados externos, como o CDF da visualização materializada, funcionarão no modo de publicação legado.

Os requisitos para seus clientes são:

  • Versão da API Delta: O cliente deve ser compatível com as APIs do Delta Lake 4.0.0 ou posteriores, incluindo vetores de exclusão, e deve usar as APIs de catálogo do Unity Catalog para o acesso.
  • Versão da API do Iceberg: Como alternativa, o cliente pode acessar usando APIs de catálogo do Iceberg que dão suporte à especificação Iceberg v3.
  • Privilégios do Unity Catalog: a entidade que lê os conjuntos de dados externamente deve ter o privilégio EXTERNAL USE SCHEMA no esquema e o privilégio SELECT na tabela.

Note

Se o cliente não der suporte a esses requisitos, você também poderá usar o modo de compatibilidade, que dá suporte a todos os clientes Delta e Iceberg, mas requer a criação de uma cópia completa do conjunto de dados.

Como habilitar o acesso a um conjunto de dados

Existem dois passos para habilitar o acesso externo a um conjunto de dados.

  1. Ative 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 é compatível com tabelas de streaming e visualizações materializadas gerenciadas por pipeline e independentes.

    • Configuração do pipeline: Defina pipelines.externalMetadata.enabled para true permitir metadados externos para todos os conjuntos de dados do pipeline. As visualizações materializadas independentes e as tabelas de streaming criadas com o Databricks SQL não possuem configuração de pipeline; use uma propriedade da tabela.

      Interface de configurações do pipeline

      Nas configurações do pipeline, complete os seguintes passos:

      1. Abra o pipeline e clique em Configurações.
      2. Em Configuração, adicione um par chave-valor: Chavepipelines.externalMetadata.enabled, Valortrue.
      3. Clique em Salvar.

      Configuração de pipeline em JSON

      Na seção configuration do JSON do seu pipeline, adicione:

      {
  "configuration": {
    "pipelines.externalMetadata.enabled": "true"
  }
}

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

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

    Depois de salvar a configuração, execute ou reinicie o pipeline para aplicar as alterações:

    • Pipelines acionados: execute o pipeline uma vez.
    • Pipelines contínuos: interrompa e reinicie o pipeline.

    Para objetos autônomos do Databricks SQL, use CREATE OR REPLACE MATERIALIZED VIEW ou CREATE OR REFRESH STREAMING TABLE com a propriedade `table`. A instrução create ou refresh aplica a propriedade.

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

    Propriedade Utilização
    'pipelines.externalMetadata.enabled' = 'true' Ative o acesso externo para a tabela. Essa configuração em nível de tabela tem precedência sobre a configuração do pipeline quando ambas são definidas.
    'delta.columnMapping.mode' = 'name' O mapeamento de colunas é obrigatório para o Iceberg.
    'delta.enableRowTracking' = 'true' Habilite o rastreamento de linhas para leituras do Iceberg.
    'delta.universalFormat.enabledFormats' = 'iceberg' Habilite as leituras do Iceberg.
    'delta.enableIcebergCompatV3' = 'true' Use o Iceberg V3 para leituras do Iceberg. 
    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 visualizações materializadas, você pode usar a sintaxe equivalente USING ICEBERG .

    CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

    Para conjuntos de dados gerenciados por pipeline, use as instruções de atualização de pipeline acima para aplicar as propriedades do Iceberg. Para objetos SQL Databricks independentes, execute novamente a definição do objeto com as propriedades atualizadas. Use CREATE OR REPLACE MATERIALIZED VIEW para uma visualização materializada ou CREATE OR REFRESH STREAMING TABLE para uma tabela de streaming. Para ver as propriedades do seu conjunto de dados, use as instruções SQL DESCRIBE DETAIL ou DESCRIBE EXTENDED.

Solução de problemas no acesso a dados externos

Se você acha que os metadados externos estão desatualizados, uma entidade com o privilégio MODIFY na tabela pode acionar manualmente a atualização de metadados no cluster de computação compartilhado usando o Databricks Runtime 17.3 ou superior:

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

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

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

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

Lendo dados de clientes externos

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

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

Usar a API REST do Unity com o Leitor Delta do Spark

Use o Apache Spark™ versão 4.0 ou posterior. Você pode baixar de https://spark.apache.org/downloads.html.

  1. Com base em seu provedor de nuvem, execute o comando a seguir para iniciar um shell do Spark SQL com o Delta 4.0 e o Catálogo do Unity.

    AWS

    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>

    Azure

    bin/spark-sql \
    --packages org.apache.hadoop:hadoop-azure:3.3.6,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.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>

    GCP

    bin/spark-sql \
    --packages 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.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFileSystem \
    --conf spark.hadoop.fs.AbstractFileSystem.gs.impl=com.google.cloud.hadoop.fs.gcs.GoogleHadoopFS \
    --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>

  2. No shell do SQL, agora você pode acessar seu conjunto de dados com o Spark SQL. Por exemplo:

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

Usar o Leitor Snowflake Iceberg

No Snowflake, você pode usar o Leitor de Iceberg. Isso requer suporte ao Iceberg v3 no Snowflake.

  1. Configure o catálogo REST do Iceberg em 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-table-name>';

  2. Acesse seu conjunto de dados pelo Snowflake SQL.

    ALTER ICEBERG TABLE my_table REFRESH;
SELECT * FROM my_table;

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

Use o Apache Spark™ versão 4.0 ou posterior. Você pode baixar de https://spark.apache.org/downloads.html.

  1. No AWS, execute o comando a seguir para iniciar um shell do Spark SQL com o Iceberg v3.

    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 conjunto de dados no Spark SQL.

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

Migrar do modo de compatibilidade

Se você estiver compartilhando um conjunto de dados no momento usando o modo de compatibilidade, poderá migrar para o uso de acesso a dados externos.

  1. Habilite esse recurso seguindo as etapas em Como habilitar o acesso a um conjunto de dados.
  2. Desabilite o modo de compatibilidade. Consulte Desativar o Modo de Compatibilidade

Limitações

A seguir, estão as limitações conhecidas do acesso a dados externos para tabelas de streaming e visualizações materializadas.

  • Gravações externas: Não há suporte para gravações externas em conjuntos de dados de pipeline.
  • Acesso baseado em caminho: Não há suporte para leitores externos que exigem acesso baseado em caminho (lendo diretamente de um local de armazenamento em vez da interface da API UC). Para dar suporte ao acesso baseado em caminho, você pode usar o modo de compatibilidade, que dá suporte ao acesso baseado em caminho, mas requer uma cópia completa do conjunto de dados.
  • Recursos de segurança: Não há suporte a segurança em nível de linha nem a mascaramento em nível de coluna em leituras externas.
  • Viagem no tempo:Viagem no tempo por meio deste recurso não é suportada.
  • Confirmações de catálogo (beta):as confirmações de catálogo não são compatíveis com o acesso a dados externos. Para usar o acesso a dados externos em uma tabela de streaming ou visualização materializada, você deve primeiro desabilitar os commits de catálogo.
  • Fabric: Não há suporte para leitura a partir do Microsoft Fabric.
  • Last updated on