Compartir vía

Acceso a tablas de Databricks desde clientes Delta

En esta página se describe cómo usar la API REST de Unity para crear, leer y escribir en el catálogo de Unity tablas administradas y externas desde clientes delta externos. Para obtener una lista completa de las integraciones admitidas, consulte Integraciones del catálogo de Unity.

Consejo (if the meaning of "Tip" is advice or suggestion)

Para obtener información sobre cómo leer datos de Azure Databricks mediante Microsoft Fabric, consulte Usar Microsoft Fabric para leer datos que están registrados en el Catálogo de Unity.

Creación, lectura y escritura mediante la API REST de Unity

Importante

La capacidad de crear y escribir en tablas gestionadas de Unity Catalog desde clientes Delta está en Beta. La compatibilidad con clientes externos es limitada.

La API rest de Unity proporciona a los clientes externos acceso de creación, lectura y escritura a tablas registradas en el catálogo de Unity. Configure el acceso utilizando la URL del espacio de trabajo como endpoint. Se puede acceder a los siguientes tipos de tabla:

Tipo de tabla Lectura Escribir Crear
Delta administrado Sí Sí* Sí*
Delta externo Sí Sí Sí

* Compatible con tablas Delta administradas con confirmaciones de catálogo.

Requisitos

Azure Databricks admite el acceso de la API REST de Unity a tablas como parte del catálogo de Unity. Debe tener habilitado el Catálogo de Unity en el área de trabajo para usar estos puntos de conexión.

También debe completar los pasos de configuración siguientes para configurar el acceso a tablas de clientes Delta mediante la API REST de Unity:

Limitaciones

  • Actualmente no se admite el acceso externo a tablas UniForm con IcebergCompatV3. Después de escribir externamente en una tabla UniForm, debe ejecutar MSCK REPAIR TABLE en Databricks para generar metadatos de Iceberg.
  • Los cambios de esquema (por ejemplo, ALTER TABLE), las actualizaciones de propiedades de tabla y los cambios de características de tabla no se admiten actualmente en tablas administradas de clientes externos.
  • Los clientes externos no pueden realizar operaciones de mantenimiento de tablas, como OPTIMIZE, VACUUMy ANALYZE, en tablas Delta administradas.
  • Los clientes externos no pueden crear clones poco profundos.
  • Los clientes externos no pueden crear tablas con columnas generadas, columnas predeterminadas o columnas de restricción.
  • Al crear tablas externas, Azure Databricks recomienda usar Apache Spark para asegurarse de que las definiciones de columna están en un formato compatible con Apache Spark. La API no valida la exactitud de la especificación de columna. Si la especificación no es compatible con Apache Spark, es posible que Databricks Runtime no pueda leer las tablas.

Acceso a tablas delta con Apache Spark mediante la autenticación PAT

La siguiente configuración es necesaria para leer o escribir en tablas delta administradas y externas del catálogo de Unity con Apache Spark mediante la autenticación PAT:

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.token": "<token>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Sustituya las siguientes variables:

  • <uc-catalog-name>: El nombre del catálogo en Unity Catalog que contiene tus tablas.
  • <token>: token de acceso personal (PAT) para el usuario principal que configura la integración.
  • <workspace-url>: la dirección URL de Azure Databricks workspace, incluido el identificador del área de trabajo. Por ejemplo: adb-1234567890123456.12.azuredatabricks.net.

Nota:

Las versiones del paquete mostradas anteriormente son actuales a partir de la última actualización de esta página. Es posible que haya versiones más recientes disponibles. Compruebe que las versiones del paquete son compatibles con la versión de Spark.

Para más información sobre cómo configurar Apache Spark para el almacenamiento de objetos en la nube, consulte la documentación del sistema operativo del catálogo de Unity.

Importante

Databricks Runtime 16.4 y versiones posteriores son necesarios para leer, escribir en o crear tablas con confirmaciones de catálogo habilitadas. Databricks Runtime 18.0 y versiones posteriores son necesarios para habilitar o deshabilitar confirmaciones de catálogo en tablas existentes.

Para crear tablas delta administradas con confirmaciones de catálogo, use el siguiente código SQL:

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported') USING delta;

Para crear tablas delta externas, use el siguiente código SQL:

CREATE TABLE <uc-catalog-name>.<schema-name>.<table-name> (id INT, desc STRING)
USING delta
LOCATION <path>;

Acceso a tablas delta con Apache Spark mediante la autenticación de OAuth

Azure Databricks también admite la autenticación de máquina a máquina (M2M) de OAuth. OAuth controla automáticamente la renovación de tokens y credenciales para la autenticación del catálogo de Unity.

La autenticación de OAuth para clientes de Spark externos requiere:

La siguiente configuración es necesaria para crear, leer o escribir en tablas administradas del catálogo de Unity y tablas delta externas con Apache Spark mediante la autenticación de OAuth:

"spark.sql.extensions": "io.delta.sql.DeltaSparkSessionExtension",
"spark.sql.catalog.spark_catalog": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>": "io.unitycatalog.spark.UCSingleCatalog",
"spark.sql.catalog.<uc-catalog-name>.uri": "<workspace-url>",
"spark.sql.catalog.<uc-catalog-name>.auth.type": "oauth",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.uri": "<oauth-token-endpoint>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientId": "<oauth-client-id>",
"spark.sql.catalog.<uc-catalog-name>.auth.oauth.clientSecret": "<oauth-client-secret>",
"spark.sql.defaultCatalog": "<uc-catalog-name>",
"spark.jars.packages": "io.delta:delta-spark_4.1_2.13:4.2.0,io.unitycatalog:unitycatalog-spark_2.13:0.4.1,org.apache.hadoop:hadoop-azure:3.4.2"

Sustituya las siguientes variables:

  • <workspace-url>: la dirección URL de Azure Databricks workspace, incluido el identificador del área de trabajo. Por ejemplo: adb-1234567890123456.12.azuredatabricks.net.

Nota:

Las versiones del paquete mostradas anteriormente son actuales a partir de la última actualización de esta página. Es posible que haya versiones más recientes disponibles. Compruebe que las versiones del paquete son compatibles con la versión de Spark.

Creación de tablas Delta mediante la API

Para crear una tabla delta externa mediante la API REST del catálogo de Unity, siga estos pasos:

Paso 1: Realizar una solicitud POST a Create Table API

Use la siguiente solicitud de API para registrar los metadatos de tabla en el catálogo de Unity:

curl --location --request POST 'https://<workspace-url>/api/2.0/unity-catalog/tables/' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "<table-name>",
  "catalog_name": "<uc-catalog-name>",
  "schema_name": "<schema-name>",
  "table_type": "EXTERNAL",
  "data_source_format": "DELTA",
  "storage_location": "<path>",
  "columns": [
    {
      "name": "id",
      "type_name": "LONG",
      "type_text": "bigint",
      "type_json": "\"long\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 0,
      "nullable": true
    },
    {
      "name": "name",
      "type_name": "STRING",
      "type_text": "string",
      "type_json": "\"string\"",
      "type_precision": 0,
      "type_scale": 0,
      "position": 1,
      "nullable": true
    }
  ]
}'

Sustituya las siguientes variables:

  • <workspace-url>: dirección URL del área de trabajo de Azure Databricks
  • <token>: Token del principal que realiza la llamada a la API.
  • <uc-catalog-name>: nombre del catálogo en el catálogo de Unity que contendrá la tabla externa.
  • <schema-name>: nombre del esquema dentro del catálogo donde se creará la tabla.
  • <table-name>: nombre de la tabla externa
  • <path>: ruta de acceso completa a los datos de la tabla

Paso 2: Inicializar la ubicación de la tabla Delta

La llamada API anterior registra la tabla en :[UC], pero no crea los archivos Delta en la ubicación de almacenamiento. Para inicializar la ubicación de la tabla, escriba una tabla Delta vacía mediante Spark:

El esquema usado en este paso debe coincidir exactamente con las definiciones de columna proporcionadas en la solicitud de API.


from pyspark.sql.types import StructType, StructField, StringType, LongType

# Define schema matching your API call
schema = StructType([
    StructField("id", LongType(), True),
    StructField("name", StringType(), True)
])

# Create an empty DataFrame and initialize the Delta table
empty_df = spark.createDataFrame([], schema)
empty_df.write \
    .format("delta") \
    .mode("overwrite") \
    .save("<path>")

Nota:

Create Table API para clientes externos tiene las siguientes limitaciones:

  • Solo se admiten tablas delta externas ("table_type": "EXTERNAL" y "data_source_format": "DELTA").
  • Solo se permiten los siguientes campos:
    • name
    • catalog_name
    • schema_name
    • table_type
    • data_source_format
    • columns
    • storage_location
    • properties
  • No se admiten máscaras de columna.
  • Last updated on