Habilitar el acceso externo a datos de tablas de transmisión y vistas materializadas

Si tiene habilitado el acceso a datos externos en Unity Catalog, puede añadir acceso a datos externos a las vistas materializadas y tablas de streaming administradas por pipelines y a las independientes. Esto permite que los clientes externos de Delta e Iceberg accedan a sus conjuntos de datos a través de las API REST del catálogo de Unity y del catálogo de Iceberg, sin necesidad de realizar una copia completa de los datos.

El acceso a datos externos funciona para conjuntos de datos administrados por pipelines de Lakeflow y para vistas materializadas y tablas de streaming independientes.

Capabilities

El uso del acceso a datos externos expone los mismos datos disponibles en Azure Databricks para las vistas materializadas y las tablas de streaming administradas por el pipeline y las independientes, sin crear un duplicado de los datos. Esto proporciona las siguientes características para el rendimiento y la funcionalidad:

  • No se requiere ninguna copia de datos: El acceso externo está habilitado sin duplicar el conjunto de datos completo.
  • Acceso externo a través de las API: Leer vistas materializadas y tablas de transmisión mediante las API de Delta Lake o Iceberg.
  • Consistencia de lectura tras escritura: Los lectores externos pueden acceder a datos actualizados después de una actualización del conjunto de datos, lo que garantiza que no haya datos obsoletos. Las actualizaciones están disponibles inmediatamente después de la actualización.
  • Objeto de tabla única: Los conjuntos de datos aparecen externamente como tablas administradas con el mismo nombre que el conjunto de datos de origen en las API de catálogo de Unity.
  • Bajo costo: Dado que el conjunto de datos completo no se copia, la sobrecarga para proporcionar acceso externo es baja.

Requirements

Los requisitos de los conjuntos de datos son:

  • Catálogo de Unity: Las tablas de streaming y las vistas materializadas deben usar el catálogo de Unity.
  • Versión de Databricks Runtime: Debe usar Databricks Runtime 17.3 y versiones posteriores.
  • Modo de publicación por defecto: La legibilidad externa solo se soporta en el modo de publicación por defecto. Para usar la legibilidad externa, migra al modo de publicación por defecto. Las características que dependen de metadatos externos, como el CDF de vistas materializadas, funcionarán en modo de publicación heredado.

Los requisitos para sus clientes son:

  • Versión de la API delta: El cliente debe admitir las API de Delta Lake 4.0.0 o posteriores, incluidos los vectores de eliminación, y debe usar las API de catálogo del catálogo de Unity para el acceso.
  • Versión de la API de Iceberg: Como alternativa, el cliente puede tener acceso mediante las API de catálogo de Cosmos que admiten la especificación de Cosmos v3.
  • Privilegios de Unity Catalog: la entidad de seguridad que lee los conjuntos de datos externamente debe tener el privilegio EXTERNAL USE SCHEMA sobre el esquema y el privilegio SELECT sobre la tabla.

Nota:

Si su cliente no admite estos requisitos, también puede usar el modo de compatibilidad, que admite todos los clientes de Delta e Iceberg, pero requiere crear una copia completa del conjunto de datos.

Habilitación del acceso para un conjunto de datos

Hay dos pasos para habilitar el acceso externo a un conjunto de datos.

  1. Habilita los metadatos externos mediante la configuración de la canalización o una propiedad de la tabla. La configuración en el nivel de tabla tiene prioridad sobre la configuración del pipeline cuando ambas están establecidas, y es compatible tanto con las vistas materializadas y las tablas de streaming administradas por el pipeline como con las independientes.

    • Configuración de la canalización: Configura pipelines.externalMetadata.enabled como true para habilitar metadatos externos para todos los conjuntos de datos de la canalización. Las vistas materializadas independientes y las tablas de streaming creadas con Databricks SQL no tienen una configuración de pipeline; Utiliza una propiedad de tabla en su lugar.

      Interfaz de usuario de la configuración de canalizaciones

      En la configuración de la canalización, completa los siguientes pasos:

      1. Abra la canalización y haga clic en Configuración.
      2. En Configuración, agregue un par clave-valor: Clavepipelines.externalMetadata.enabled, Valortrue.
      3. Haz clic en Guardar.

      JSON de configuración de canalizaciones

      En la sección configuration del JSON de la canalización, agregue:

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

    • Propiedad de la tabla: Añade la siguiente propiedad a la tabla de streaming o a la definición de vista materializada. Para las tuberías Lakeflow Connect, consulte las propiedades de la tabla Set Delta.

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

    Después de guardar la configuración, ejecute o reinicie la canalización para aplicar los cambios:

    • Canalizaciones desencadenadas: ejecute la canalización una vez.
    • Canalizaciones continuas: detenga y reinicie la canalización.

    Para objetos SQL Databricks independientes, usa CREATE OR REPLACE MATERIALIZED VIEW o CREATE OR REFRESH STREAMING TABLE con la propiedad de tabla. La instrucción CREATE o REFRESH aplica la propiedad.

  2. Si planeas leer el conjunto de datos con un cliente Iceberg moderno, añade las siguientes propiedades UniForm Iceberg V3 además de la propiedad de metadatos externos. Para las tuberías Lakeflow Connect, consulte las propiedades de la tabla Set Delta.

    Propiedad Uso
    'pipelines.externalMetadata.enabled' = 'true' Habilita el acceso externo a la tabla. Esta configuración a nivel de tabla tiene prioridad sobre la configuración de la tubería cuando ambas están establecidas.
    'delta.columnMapping.mode' = 'name' La asignación de columnas es obligatoria para Iceberg.
    'delta.enableRowTracking' = 'true' Habilitar el seguimiento de filas para las lecturas de Iceberg.
    'delta.universalFormat.enabledFormats' = 'iceberg' Habilitar las lecturas de Iceberg.
    'delta.enableIcebergCompatV3' = 'true' Utilizar Iceberg V3 para las lecturas de 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, puedes usar la sintaxis equivalente USING ICEBERG en su lugar.

    CREATE OR REFRESH MATERIALIZED VIEW tbl_name USING ICEBERG

    Para conjuntos de datos gestionados por canalización, utiliza las instrucciones de actualización de tubería anteriores para aplicar las propiedades de Iceberg. Para objetos SQL independientes de Databricks, reejecuta la definición del objeto con las propiedades actualizadas. Use CREATE OR REPLACE MATERIALIZED VIEW para una vista materializada o CREATE OR REFRESH STREAMING TABLE para una tabla de streaming. Para ver las propiedades de tu conjunto de datos, utiliza las sentencias SQL DESCRIBE DETAIL o DESCRIBE EXTENDED.

Resolución de problemas en el acceso externo a datos

Si crees que los metadatos externos no están actualizados, un usuario con el privilegio MODIFY sobre la tabla puede desencadenar manualmente la actualización de metadatos mediante el cómputo compartido del clúster con Databricks Runtime 17.3 o posterior:

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

Puedes comprobar la presencia de los metadatos de Iceberg en la página de detalles de la tabla de la interfaz de Catalog Explorer. Alternativamente, ejecuta los siguientes comandos en el editor SQL o en un cuaderno de Azure Databricks:

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

Para una tabla de streaming, compara la versión de metadatos de Iceberg con la última versión de la tabla de streaming. La comparación de versiones para las vistas materializadas aún no está disponible.

Lectura de datos de clientes externos

Las siguientes secciones ofrecen ejemplos de cómo leer tu conjunto de datos de diferentes clientes y entornos.

Para detalles de configuración, véase acceso al cliente Delta y acceso al cliente Iceberg.

Uso de la API REST de Unity con el Lector delta de Spark

Use Apache Spark™ versión 4.0 o posterior. Puede descargar desde https://spark.apache.org/downloads.html.

  1. En función del proveedor de nube, ejecute el siguiente comando para iniciar un shell de Spark SQL con Delta 4.0 y catálogo de 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. Ahora, desde el intérprete de comandos de SQL, puede acceder a su conjunto de datos con Spark SQL. Por ejemplo:

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

Use el lector Snowflake Iceberg

En Snowflake, puede usar Iceberg Reader. Esto requiere la compatibilidad con Iceberg v3 en Snowflake.

  1. Configure el catálogo REST de Iceberg en 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. Accede a tu conjunto de datos desde Snowflake SQL.

    ALTER ICEBERG TABLE my_table REFRESH;
SELECT * FROM my_table;

Usar el catálogo REST de Iceberg con el lector Iceberg de Spark

Use Apache Spark™ versión 4.0 o posterior. Puede descargar desde https://spark.apache.org/downloads.html.

  1. En AWS, ejecute el siguiente comando para iniciar un shell de Spark SQL con 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. Acceda al conjunto de datos desde Spark SQL.

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

Migración desde el modo de compatibilidad

Si actualmente está compartiendo un conjunto de datos mediante el modo de compatibilidad, puede migrar para usar el acceso a datos externos.

  1. Habilite esta característica siguiendo los pasos descritos en Habilitación del acceso para un conjunto de datos.
  2. Deshabilite el modo de compatibilidad. Consulte Deshabilitar el modo de compatibilidad.

Limitaciones

A continuación se muestran limitaciones conocidas con el acceso a datos externos para tablas de streaming y vistas materializadas.

  • Escrituras externas: No se admiten escrituras externas en conjuntos de datos de canalización.
  • Acceso basado en rutas: No se admiten los lectores externos que requieren acceso basado en rutas (leyendo directamente desde una ubicación de almacenamiento en lugar de a través de la API de UC). Para admitir el acceso basado en rutas de acceso, puede usar el modo de compatibilidad, que admite el acceso basado en rutas de acceso, pero requiere una copia completa del conjunto de datos.
  • Características de seguridad: No se admite la seguridad de nivel de fila ni el enmascaramiento de nivel de columna en lecturas externas.
  • Viaje en el tiempo:No se soporta el viaje en el tiempo mediante esta función.
  • Confirmaciones de catálogo (beta):las confirmaciones del catálogo no son compatibles con el acceso a datos externos. Para utilizar el acceso a datos externos en una tabla de streaming o una vista materializada, primero debes desactivar las confirmaciones del catálogo.
  • Fabric: No se admite la lectura desde Microsoft Fabric.
  • Last updated on