Permitir o acesso externo de dados a tabelas de streaming e visualizações materializadas

Se tiver ativado o acesso a dados externos no Unity Catalog, pode adicionar acesso a dados externos a vistas materializadas e tabelas de streaming autónomas e geridas por pipelines. Isto permite que clientes externos Delta e Iceberg acedam aos seus conjuntos de dados através das APIs REST do Unity Catalog e Iceberg Catalog, sem necessidade de uma cópia completa dos dados.

O acesso a dados externos funciona para conjuntos de dados geridos por pipelines Lakeflow e para visualizações materializadas autónomas e tabelas de streaming.

Capabilities

A utilização do acesso externo a dados disponibiliza os mesmos dados disponíveis no Azure Databricks para vistas materializadas e tabelas de streaming, quer geridas por pipeline quer autónomas, sem criar uma duplicação dos dados. Isto confere as seguintes características de desempenho e funcionalidade:

  • Não é necessária cópia dos dados: O acesso externo é ativado sem duplicar o conjunto de dados completo.
  • Acesso externo via APIs: Leia visualizações materializadas e tabelas de streaming usando APIs Delta Lake ou Iceberg.
  • Consistência de leitura após a escrita: Os leitores externos podem aceder a dados atualizados na sequência de uma atualização do conjunto de dados, garantindo que não há desatualização. 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 geridas com o mesmo nome do conjunto de dados de origem dentro das APIs do Catálogo Unity.
  • Baixo custo: Como o conjunto de dados completo não é copiado, a sobrecarga para fornecer acesso externo é baixa.

Requirements

Os requisitos para os seus conjuntos de dados são:

  • Catálogo Unity: As suas tabelas de streaming e visualizações materializadas devem estar a usar o Unity Catalog.
  • Versão do Databricks Runtime: Deve estar a usar o Databricks Runtime 17.3 ou superior.
  • Modo de publicação padrão: A legibilidade externa só é suportada no modo de publicação por defeito. Para usar legibilidade externa, migre para o modo de publicação predefinido. Funcionalidades que dependem de metadados externos, como o CDF da vista materializada, continuarão a funcionar no modo de publicação herdado.

Os requisitos para os seus clientes são:

  • Versão da API Delta: O cliente deve suportar as APIs Delta Lake 4.0.0 ou superiores, incluindo vetores de eliminação, e deve utilizar as APIs do catálogo Unity para aceder ao Catálogo.
  • Versão da API Iceberg: Alternativamente, o cliente pode aceder usando APIs do catálogo Iceberg que suportam a especificação Iceberg v3.
  • Privilégios do Unity Catalog: A entidade que acede aos conjuntos de dados externamente tem de ter o privilégio EXTERNAL USE SCHEMA no esquema e o privilégio SELECT na tabela.

Note

Se o seu cliente não suportar estes requisitos, pode também usar o modo de compatibilidade, que suporta todos os clientes Delta e Iceberg, mas requer criar uma cópia completa do conjunto de dados.

Como permitir o acesso a um conjunto de dados

Existem dois passos para permitir 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 ao nível da tabela tem precedência sobre a configuração do pipeline quando ambas estão definidas e é suportada tanto para tabelas de streaming e vistas materializadas geridas pelo pipeline como autónomas.

    • Configuração do pipeline: Definir pipelines.externalMetadata.enabled para true permitir metadados externos para todos os conjuntos de dados no pipeline. Vistas materializadas autónomas e tabelas de streaming criadas com Databricks SQL não têm configuração de pipeline; Usa uma propriedade de tabela em vez disso.

      Interface das definições do pipeline

      Nas definições da canalização, conclua os passos seguintes:

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

      Configuração JSON do pipeline

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

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

    • Propriedade da tabela: Adicione a seguinte propriedade à definição da tabela de streaming ou da vista materializada. Para os pipelines do Lakeflow Connect, veja Definir propriedades da tabela Delta.

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

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

    • Pipelines acionados: Execute o pipeline uma vez.
    • Pipelines contínuas: Parar e reiniciar a pipeline.

    Para objetos autónomos do Databricks SQL, use CREATE OR REPLACE MATERIALIZED VIEW ou CREATE OR REFRESH STREAMING TABLE na propriedade da tabela. A instrução criar ou atualizar aplica a propriedade.

  2. Se planeia 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 os pipelines do Lakeflow Connect, veja Definir propriedades da tabela Delta.

    Property Use
    'pipelines.externalMetadata.enabled' = 'true' Ativar o acesso externo para a tabela. Esta configuração ao nível da tabela tem prioridade sobre a configuração do pipeline quando ambos estão definidos.
    'delta.columnMapping.mode' = 'name' O mapeamento de colunas é obrigatório para o Iceberg.
    'delta.enableRowTracking' = 'true' Ativar o rastreamento de linhas para leituras Iceberg.
    'delta.universalFormat.enabledFormats' = 'iceberg' Ativar a leitura de Iceberg.
    'delta.enableIcebergCompatV3' = 'true' Utilize o Iceberg V3 para operações de leitura 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 vistas materializadas, pode usar a sintaxe equivalente USING ICEBERG em vez disso.

    CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

    Para conjuntos de dados geridos pelo pipeline, utilize as instruções de atualização do pipeline acima para aplicar as propriedades do Iceberg. Para objetos SQL Databricks autónomos, 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, utilize as instruções SQL DESCRIBE DETAIL ou DESCRIBE EXTENDED.

Resolução de problemas no acesso a dados externos

Se achar que os metadados externos estão obsoletos, um principal com o MODIFY privilégio na tabela pode ativar manualmente a atualização dos metadados no cluster partilhado usando Databricks Runtime 17.3 ou superior:

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

Pode verificar a presença dos metadados do Iceberg na interface do Explorador de Catálogos na página de detalhes da tabela. Em alternativa, execute os seguintes comandos no editor SQL ou num notebook 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 vistas materializadas ainda não está disponível.

Leitura de dados de clientes externos

As secções seguintes fornecem exemplos de como ler o seu conjunto de dados de diferentes clientes e ambientes.

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

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

Use o Apache Spark™ versão 4.0 ou posterior. Pode descarregar de https://spark.apache.org/downloads.html.

  1. Com base no seu fornecedor de cloud, execute o seguinte comando para iniciar um shell SQL Spark com Delta 4.0 e Unity Catalog.

    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. A partir do SQL shell, agora pode aceder ao seu conjunto de dados com o Spark SQL. Por exemplo:

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

Utilize o Snowflake Iceberg Reader

Dentro do Snowflake, podes usar o Leitor de Iceberg. Isto requer suporte ao Iceberg v3 no Snowflake.

  1. Configura o catálogo Iceberg REST 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. Acede ao teu conjunto de dados a partir do Snowflake SQL.

    ALTER ICEBERG TABLE my_table REFRESH;
SELECT * FROM my_table;

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

Use o Apache Spark™ versão 4.0 ou posterior. Pode descarregar de https://spark.apache.org/downloads.html.

  1. Na AWS, execute o seguinte comando para iniciar um shell SQL Spark 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. Acede ao teu conjunto de dados a partir do Spark SQL.

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

Migrar do modo de compatibilidade

Se estiver atualmente a partilhar um conjunto de dados usando o modo de compatibilidade, pode migrar para o acesso externo a dados.

  1. Ative esta funcionalidade seguindo os passos em Como permitir o acesso a um conjunto de dados.
  2. Desativar o modo de compatibilidade. Ver Desativar Modo de Compatibilidade

Limitações

Seguem-se as limitações conhecidas do acesso a dados externos para tabelas de streaming e vistas materializadas.

  • Escritas externas: Escritas externas para conjuntos de dados de pipeline não são suportadas.
  • Acesso baseado em caminhos: Os leitores externos que necessitam de acesso baseado em caminhos (leitura direta a partir de uma localização de armazenamento, em vez de através da interface da API UC) não são suportados. Para suportar acesso baseado em caminhos, pode usar o modo de compatibilidade, que suporta acesso baseado em caminhos, mas requer uma cópia completa do conjunto de dados.
  • Características de Segurança: Não é suportado o suporte de segurança ao nível de linha ou mascaramento ao nível de coluna a partir de leituras externas.
  • Viagem no tempo:A viagem no tempo através desta funcionalidade 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 acesso externo a dados numa tabela de streaming ou numa vista materializada, deve primeiro desativar os commits do catálogo.
  • Fabric: A leitura do Microsoft Fabric não é suportada.
  • Last updated on