Compartir vía


Sincronización de datos de tablas de Catálogo de Unity a una instancia de base de datos

Importante

Esta característica se encuentra en versión preliminar pública en las siguientes regiones: westus, westus2, eastuseastus2, centralussouthcentralusnortheuropewesteuropeaustraliaeastbrazilsouthcanadacentralcentralindia, , . southeastasiauksouth

En esta página se describe cómo crear y administrar una tabla sincronizada. Una tabla sincronizada es una tabla postgres de solo lectura del catálogo de Unity que sincroniza automáticamente los datos de una tabla de catálogo de Unity con la instancia de base de datos de Lakebase. La sincronización de una tabla de catálogo de Unity en Postgres permite consultas de lectura de baja latencia y admite combinaciones en tiempo de consulta con otras tablas de Postgres.

La sincronización se controla mediante Lakeflow Spark Declarative Pipelines. Una canalización administrada actualiza continuamente la tabla Postgres con cambios de la tabla de origen. Después de la creación, las tablas sincronizadas se pueden consultar directamente mediante herramientas de Postgres.

Las características clave de las tablas sincronizadas son las siguientes:

  • Solo lectura en Postgres para mantener la integridad de los datos con el origen
  • Sincronizado automáticamente mediante canalizaciones declarativas de Spark de Managed Lakeflow
  • Consultable a través de interfaces de PostgreSQL estándar
  • Administrado a través del catálogo de Unity para la administración del ciclo de vida y la gobernanza

Antes de empezar

  • Tiene una tabla de Catálogo de Unity en cualquier catálogo.
  • Tiene permisos de CAN USE sobre la instancia de base de datos.

Creación de una tabla sincronizada

Interfaz de usuario

Para sincronizar una tabla de catálogo de Unity en Postgres, haga lo siguiente:

  1. Haga clic en Catálogo en la barra lateral del área de trabajo.

  2. Busque y seleccione la tabla catálogo de Unity en la que desea crear una tabla sincronizada.

  3. Haga clic en Crear>tabla sincronizada.

  4. Seleccione el catálogo, el esquema y escriba un nombre de tabla para la nueva tabla sincronizada.

    • También se pueden crear tablas sincronizadas en catálogos estándar, con alguna configuración adicional. Seleccione el catálogo Estándar, un esquema y escriba un nombre de tabla para la tabla sincronizada recién creada.
  5. Seleccione una instancia de base de datos y escriba el nombre de la base de datos de Postgres en la que se va a crear la tabla sincronizada. El campo de base de datos postgres tiene como valor predeterminado el catálogo de destino seleccionado actualmente. Si no existe una base de datos de Postgres con este nombre, Azure Databricks crea uno nuevo.

  6. Seleccione una clave principal. Se requiere una clave principal, ya que permite el acceso eficaz a las filas para lecturas, actualizaciones y eliminaciones.

    Importante

    Las columnas de la clave principal no admiten valores NULL en la tabla sincronizada. Por lo tanto, las filas con valores NULL en las columnas de clave principal se excluyen de la sincronización.

  7. Si dos filas tienen la misma clave principal en la tabla de origen, seleccione una clave timeseries para configurar la desduplicación. Cuando se especifica una clave timeseries , las tablas sincronizadas solo contienen las filas con el valor de clave timeseries más reciente para cada clave principal.

  8. Seleccione el modo de sincronización en Instantánea, Desencadenada o Continua. Para obtener más información sobre cada modo de sincronización, consulte Modos de sincronización explicados.

  9. Elija si desea crear esta tabla sincronizada a partir de una canalización nueva o existente.

    • Si crea una canalización y usa un catálogo administrado, elija la ubicación de almacenamiento de la tabla de almacenamiento provisional. Si utiliza un catálogo estándar, la tabla de preparación se almacena automáticamente en el catálogo.
    • Si usa una canalización existente, compruebe que el nuevo modo de sincronización coincide con el modo de canalización.
  10. (Opcional) Seleccione una directiva de presupuesto sin servidor. Para crear una directiva de presupuesto sin servidor, consulte Uso de atributos con directivas de presupuesto sin servidor. Esto le permite atribuir el uso de facturación a directivas de uso específicas.

    • En el caso de las tablas sincronizadas, la entidad facturable es la canalización declarativa subyacente de Lakeflow Spark. Para modificar la directiva de presupuesto, modifique el objeto de canalización subyacente. Consulte Configuración de una canalización sin servidor.
  11. Después de que el estado de la tabla sincronizada sea En línea, inicie sesión en la instancia de base de datos y consulte la tabla recién creada. Consulte la tabla mediante el editor de SQL, las herramientas externas o los cuadernos.

SDK de Python

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.database import SyncedDatabaseTable, SyncedTableSpec, NewPipelineSpec, SyncedTableSchedulingPolicy

# Initialize the Workspace client
w = WorkspaceClient()

# Create a synced table in a database catalog
synced_table = w.database.create_synced_database_table(
    SyncedDatabaseTable(
        name="database_catalog.schema.synced_table",  # Full three-part name
        spec=SyncedTableSpec(
            source_table_full_name="source_catalog.source_schema.source_table",
            primary_key_columns=["id"],  # Primary key columns
            scheduling_policy=SyncedTableSchedulingPolicy.TRIGGERED,  # SNAPSHOT, TRIGGERED, or CONTINUOUS
            # Optional: timeseries_key="timestamp"  # For deduplication
            new_pipeline_spec=NewPipelineSpec(
                storage_catalog="storage_catalog",
                storage_schema="storage_schema"
            )
        ),
    )
)
print(f"Created synced table: {synced_table.name}")

# Create a synced table in a standard UC catalog
synced_table = w.database.create_synced_database_table(
    SyncedDatabaseTable(
        name="standard_catalog.schema.synced_table",  # Full three-part name
        database_instance_name="my-database-instance",  # Required for standard catalogs
        logical_database_name="postgres_database",  # Required for standard catalogs
        spec=SyncedTableSpec(
            source_table_full_name="source_catalog.source_schema.source_table",
            primary_key_columns=["id"],
            scheduling_policy=SyncedTableSchedulingPolicy.CONTINUOUS,
            create_database_objects_if_missing=True,  # Create database/schema if needed
            new_pipeline_spec=NewPipelineSpec(
                storage_catalog="storage_catalog",
                storage_schema="storage_schema"
            )
        ),
    )
)
print(f"Created synced table: {synced_table.name}")

# Check the status of a synced table
synced_table_name = "database_catalog.schema.synced_table"
status = w.database.get_synced_database_table(name=synced_table_name)
print(f"Synced table status: {status.data_synchronization_status.detailed_state}")
print(f"Status message: {status.data_synchronization_status.message}")

Interfaz de línea de comandos (CLI)

# Create a synced table in a database catalog
databricks database create-synced-database-table  \
  --json '{
    "spec": {
      "name": "database_catalog.schema.synced_table",
      "source_table_full_name": "source_catalog.source_schema.source_table",
      "primary_key_columns": ["id"],
      "scheduling_policy": "TRIGGERED"
    },
    "new_pipeline_spec": {
      "storage_catalog": "storage_catalog",
      "storage_schema": "storage_schema"
    }
  }'

# Create a synced table in a standard UC catalog
# new_pipeline_spec, storage_catalog, and storage_schema are optional
databricks database create-synced-database-table \
  --database-instance-name "my-database-instance" \
  --logical-database-name "databricks_postgres" \
  --json '{
    "name": "standard_catalog.schema.synced_table",
    "spec": {
      "source_table_full_name": "source_catalog.source_schema.source_table",
      "primary_key_columns": ["id"],
      "scheduling_policy": "CONTINUOUS",
      "create_database_objects_if_missing": true
    }
  }'

# Check the status of a synced table
databricks database get-synced-database-table "database_catalog.schema.synced_table"

curl

Cree una tabla sincronizada en un catálogo de bases de datos.

export CATALOG_NAME=<Database catalog>
export SRC_TBL="source_catalog.source_schema.source_table"
export DEST_TBL="$CATALOG_NAME.some_schema.synced_table"
export PKS='["id"]'
export ST_CATALOG = "storage_catalog"
export ST_SCHEMA = "storage_schema"

curl -X POST https://$WORKSPACE/api/2.0/database/synced_tables \
-H "Content-Type: text/json" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--data-binary @- << EOF
{
  "name": "$DEST_TBL",
  "spec": {
    "source_table_full_name": "$SRC_TBL",
    "primary_key_columns": $PKS,
    "scheduling_policy": "TRIGGERED",
  },
  "new_pipeline_spec": {
    "storage_catalog": "$ST_CATALOG",
    "storage_schema": "$ST_SCHEMA",
  }
}
EOF

Cree una tabla sincronizada en un catálogo estándar de Unity.

export CATALOG_NAME=<Standard catalog>
export DATABASE_INSTANCE=<database instance>
export POSTGRES_DATABASE=$CATALOG_NAME
export SRC_TBL="source_catalog.source_schema.source_table"
export DEST_TBL="$CATALOG_NAME.some_schema.sync_table"
export PKS='["id"]'
export ST_CATALOG = "storage_catalog"
export ST_SCHEMA = "storage_schema"

curl -X POST https://$WORKSPACE/api/2.0/database/synced_tables \
-H "Content-Type: text/json" \
-H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
--data-binary @- << EOF
{
  "name": "$DEST_TBL",
  "database_instance_name": "$DATABASE_INSTANCE",
  "logical_database_name": "$POSTGRES_DATABASE",
  "spec": {
    "source_table_full_name": "$SRC_TBL",
    "primary_key_columns": $PKS,
    "scheduling_policy": "TRIGGERED",
  },
  "new_pipeline_spec": {
    "storage_catalog": "$ST_CATALOG",
    "storage_schema": "$ST_SCHEMA",
  }
}
EOF

Compruebe el estado de una tabla sincronizada.

export SYNCEDTABLE='pg_db.silver.sbtest1_online'

curl --request GET \
  "https://e2-dogfood.staging.cloud.databricks.com/api/2.0/database/synced_tables/$SYNCEDTABLE" \
  --header "Authorization: Bearer dapi..."

Modos de sincronización explicados

Se puede crear una tabla sincronizada con uno de los siguientes modos de sincronización, que determinan cómo se sincronizan los datos desde el origen a la tabla sincronizada en Postgres:

Modo de sincronización Description Performance
Instantánea La canalización se ejecuta una vez para tomar una instantánea de la tabla de origen y copiarla en la tabla sincronizada. Las subsiguientes ejecuciones del canalización copian todos los datos de origen al destino y los reemplazan en su lugar de forma atómica. La canalización se puede desencadenar manualmente a través de una API o según una programación. Este modo es 10 veces más eficaz que los modos desencadenados o de sincronización continua porque vuelve a crear datos desde cero. Si va a modificar más de 10% de la tabla de origen, considere la posibilidad de usar este modo.
Desencadenado La canalización se ejecuta una vez para tomar una instantánea de la tabla de origen y copiarla en la tabla sincronizada. A diferencia del modo de sincronización de instantáneas, cuando se actualiza la tabla sincronizada, solo se recuperan los cambios desde la última ejecución de la canalización y se aplican a la tabla sincronizada. La actualización incremental se puede desencadenar manualmente, a través de una API o según una programación. Este modo es un buen compromiso entre retraso y costo, ya que se ejecuta a petición y solo aplica cambios desde la última ejecución. Para minimizar el retraso, ejecute esta canalización inmediatamente después de actualizar la tabla de origen. Si ejecuta esto con más frecuencia que cada 5 minutos, puede ser más caro que el modo continuo debido al costo de iniciar y detener la canalización cada vez.
Continuo La canalización se ejecuta una vez para tomar una instantánea de la tabla de origen y copiarla en la tabla sincronizada y, a continuación, la canalización se ejecuta continuamente. Los cambios posteriores en la tabla de origen se aplican incrementalmente a la tabla sincronizada en tiempo real. No es necesario actualizar manualmente. Este modo tiene el retraso más bajo pero un costo mayor, ya que se está ejecutando continuamente.

Nota:

Para admitir desencadenado o modo de sincronización continua, la tabla de origen debe tener fuente de distribución de datos modificado habilitado. Algunos orígenes (como Vistas) no admiten la alimentación de datos de cambios, por lo que solo pueden sincronizarse en modo de instantánea.

Operaciones compatibles

Databricks recomienda realizar solo las siguientes operaciones en Postgres para tablas sincronizadas para evitar sobrescrituras accidentales o incoherencias de datos:

  • Consultas de solo lectura
  • Creación de índices
  • Quitar la tabla (para liberar espacio después de quitar la tabla sincronizada del catálogo de Unity)

Aunque puede modificar esta tabla de otras maneras, interfiere con la canalización de sincronización.

Eliminación de una tabla sincronizada

Para eliminar una tabla sincronizada, debe eliminarla del catálogo de Unity y, a continuación, quitar la tabla en la instancia de base de datos. Al eliminar la tabla sincronizada de Unity Catalog, se anula el registro de la tabla y se detiene cualquier actualización de datos. Sin embargo, la tabla permanece en la base de datos de Postgres subyacente. Para liberar espacio en la instancia de base de datos, conéctese a la instancia y use el DROP TABLE comando .

Interfaz de usuario

  1. Haga clic en Catálogo en la barra lateral del área de trabajo.
  2. Busque y seleccione la tabla sincronizada que desea eliminar.
  3. Haga clic en el icono de menú Kebab.>Eliminar.
  4. Conéctese a la instancia con psql, el editor de SQL o desde un cuaderno.
  5. Quite la tabla mediante PostgreSQL.
    DROP TABLE synced_table_database.synced_table_schema.synced_table
    

SDK de Python

from databricks.sdk import WorkspaceClient

# Initialize the Workspace client
w = WorkspaceClient()

# Delete a synced table from UC
synced_table_name = "catalog.schema.synced_table"
w.database.delete_synced_database_table(name=synced_table_name)
print(f"Deleted synced table from UC: {synced_table_name}")

# To free up space in your database instance, you need to connect to the
# instance and drop the table using PostgreSQL:
#
# DROP TABLE synced_table_database.synced_table_schema.synced_table;

Interfaz de línea de comandos (CLI)

# Delete a synced table from UC
databricks database delete-synced-database-table "catalog.schema.synced_table"

# To free up space in your database instance, you need to connect to the
# instance and drop the table using PostgreSQL:
#
# DROP TABLE synced_table_database.synced_table_schema.synced_table;

curl

# Delete a synced table from UC
curl -X DELETE --header "Authorization: Bearer ${DATABRICKS_TOKEN}" \
  https://$WORKSPACE/api/2.0/database/synced_tables/$SYNCED_TABLE_NAME

# To free up space in your database instance, you need to connect to the
# instance and drop the table using PostgreSQL:
#
# DROP TABLE synced_table_database.synced_table_schema.synced_table;

Propiedad y permisos

Si crea una nueva base de datos, esquema o tabla de Postgres, la propiedad de Postgres se establece de la siguiente manera:

  • La propiedad se asigna al usuario que crea la base de datos, el esquema o la tabla, si su inicio de sesión de Azure Databricks existe como un rol en Postgres. Para agregar un rol de identidad de Azure Databricks en Postgres, consulte Administración de roles de Postgres.
  • De lo contrario, la propiedad se asigna al propietario del objeto primario en Postgres (normalmente).databricks_superuser

Administración del acceso a tablas sincronizadas

Una vez creada una tabla sincronizada, el databricks_superuser puede READ una tabla sincronizada desde Postgres. databricks_superuser tiene pg_read_all_data, lo que permite a este rol leer de todas las tablas. También tiene el privilegio pg_write_all_data, que permite a este rol escribir en todas las tablas. Esto significa que un databricks_superuser objeto también puede escribir en una tabla sincronizada en Postgres. Lakebase admite esta funcionalidad de escritura en caso de que necesite realizar cambios urgentes en la tabla objetivo. Sin embargo, Databricks recomienda realizar correcciones en la tabla de origen en su lugar.

  • databricks_superuser También puede conceder estos privilegios a otros usuarios:

    GRANT USAGE ON SCHEMA synced_table_schema TO user;
    
    GRANT SELECT ON synced_table_name TO user;
    
  • databricks_superuser puede revocar estos privilegios:

    REVOKE USAGE ON SCHEMA synced_table_schema FROM user;
    
    REVOKE {SELECT | INSERT | UPDATE | DELETE} ON synced_table_name FROM user;
    

Administración de operaciones de tabla sincronizadas

databricks_superuser puede administrar qué usuarios están autorizados para realizar operaciones específicas en una tabla sincronizada. Las operaciones admitidas para las tablas sincronizadas son:

  • CREATE INDEX
  • ALTER INDEX
  • DROP INDEX
  • DROP TABLE

Todas las demás operaciones DDL se deniegan para las tablas sincronizadas.

Para conceder estos privilegios a usuarios adicionales, databricks_superuser primero debe crear una extensión en databricks_auth:

CREATE EXTENSION IF NOT EXISTS databricks_auth;

databricks_superuser A continuación, puede agregar un usuario para administrar una tabla sincronizada:

SELECT databricks_synced_table_add_manager('"synced_table_schema"."synced_table"'::regclass, '[user]');

databricks_superuser puede quitar un usuario de la administración de una tabla sincronizada:

SELECT databricks_synced_table_remove_manager('[table]', '[user]');

El databricks_superuser puede ver a todos los administradores.

SELECT * FROM databricks_synced_table_managers;

Asignación de tipos de datos

Esta tabla de asignación de tipos define cómo se asigna cada tipo de datos en la tabla de catálogo de Unity de origen a la tabla de sincronización de destino en Postgres:

Tipo de columna de origen Tipo de columna Postgres
BIGINT BIGINT
BINARIO BYTEA
BOOLEANO BOOLEAN
FECHA DATE
DECIMAL(p,s) NUMÉRICO
DOBLE doble precisión
FLOTAR REAL
INT INTEGER
INTERVAL intervalQualifier INTERVALO
SMALLINT SMALLINT
CUERDA Mensaje de texto
TIMESTAMP MARCA DE TIEMPO CON ZONA HORARIA
TIMESTAMP_NTZ MARCA DE TIEMPO SIN ZONA HORARIA
TINYINT SMALLINT
GEOGRAPHY(srid) NO COMPATIBLE
GEOMETRY(srid) NO COMPATIBLE
ARRAY < elementType > JSONB
MAP < keyType,valueType > JSONB
STRUCT < [fieldName : fieldType [NOT NULL][COMMENT str][, ...]] > JSONB
VARIANTE JSONB
OBJETO NO COMPATIBLE

Nota:

  • La asignación de tipos ARRAY, MAP y STRUCT se cambió en mayo de 2025. Sincronice las tablas creadas antes de que continúen asignando esos tipos a JSON.
  • La asignación de TIMESTAMP se cambió en agosto de 2025. Sincronice las tablas creadas antes de que continúen a asignarla a TIMESTAMP WITHOUT TIME ZONE.

Controlar caracteres no válidos

Algunos caracteres, como el byte nulo (0x00), se permiten en las columnas STRING, ARRAY, MAP o STRUCT de las tablas Delta, pero no se admiten en columnas TEXT o JSONB de Postgres. Como resultado, la sincronización de estos datos de Delta a Postgres puede provocar fallos de inserción:

org.postgresql.util.PSQLException: ERROR: invalid byte sequence for encoding "UTF8": 0x00

org.postgresql.util.PSQLException: ERROR: unsupported Unicode escape sequence DETAIL: \u0000 cannot be converted to text.
  • El primer error se produce cuando un byte nulo aparece en una columna de cadena de nivel superior, que se asigna directamente a Postgres TEXT.
  • El segundo error se produce cuando un byte nulo aparece en una cadena anidada dentro de un tipo complejo (STRUCT, ARRAYo MAP), que Azure Databricks serializa como JSONB. Durante la serialización, todas las cadenas de texto se transforman en Postgres TEXT, donde \u0000 no se permite.

Cómo resolverlo:

Puede solucionar este problema de una de las maneras siguientes:

  • Sanitizar campos de cadena

    Quite o reemplace caracteres no admitidos de todos los campos de cadena, incluidos los de tipos complejos, antes de sincronizar con Postgres.

    Para quitar bytes NULL de una columna de nivel STRING superior, use la REPLACE función :

    SELECT REPLACE(column_name, CAST(CHAR(0) AS STRING), '') AS cleaned_column FROM your_table;
    
  • Conversión a binario (solo para STRING columnas)

    Si es necesario conservar el contenido de bytes sin procesar, convierta las columnas afectadas STRING en BINARY.

Limitaciones y consideraciones

Tablas de origen admitidas

Según el modo de sincronización de una tabla sincronizada, se admiten distintos tipos de tablas de origen:

  • Para el modo instantánea, la tabla de origen debe admitir SELECT *. Entre los ejemplos se incluyen las tablas Delta, las tablas de Alias, las vistas, las vistas materializadas y otros tipos similares.

  • En el caso de los modos de sincronización desencadenada o continua, la tabla de origen también debe tener habilitada la fuente de distribución de datos modificados .

Limitaciones de nomenclatura e identificador

  • Caracteres permitidos: Los nombres de base de datos, esquemas y tablas de Postgres para las tablas sincronizadas solo pueden contener caracteres alfanuméricos y caracteres de subrayado ([A-Za-z0-9_]+). No se admiten guiones (-) ni otros caracteres especiales.
  • Identificadores de columna y tabla: Evite usar letras mayúsculas o caracteres especiales en nombres de columna o tabla en la tabla de catálogo de Unity de origen. Si se mantiene, debe citar estos identificadores al hacer referencia a ellos en Postgres.

Rendimiento y sincronización

  • Velocidad de sincronización: La sincronización de datos en tablas sincronizadas puede ser más lenta que escribir datos directamente en la instancia de base de datos con un cliente de PostgreSQL nativo debido al procesamiento adicional. El modo de sincronización continua actualiza los datos de la tabla administrada del catálogo de Unity a la tabla sincronizada en un intervalo mínimo de 15 segundos.
  • Uso de la conexión: Cada sincronización de tablas puede usar hasta 16 conexiones a la instancia de base de datos, que cuentan hacia el límite de conexión de la instancia.
  • Idempotencia de las API: Las API de tablas sincronizadas son idempotentes y pueden necesitar reintentarse si ocurren errores para garantizar operaciones oportunas.
  • Cambios de esquema: En el caso de las tablas sincronizadas en Triggered modo o Continuous , solo los cambios de esquema aditivos (por ejemplo, la adición de una nueva columna) de las tablas del catálogo de Unity se reflejan en la tabla sincronizada.
  • Claves duplicadas: Si dos filas tienen la misma clave principal en la tabla de origen, se produce un error en la canalización de sincronización a menos que configure la desduplicación mediante una clave timeseries. Sin embargo, el uso de una clave Timeseries incluye una penalización de rendimiento.
  • Velocidad de actualización: La canalización de sincronización admite escrituras continuas en aproximadamente 1200 filas por segundo por unidad de capacidad (CU) y escrituras masivas en hasta 15 000 filas por segundo por segundo.

Capacidad y límites

  • Límites de tabla:
    • Límite de 20 tablas sincronizadas por tabla de origen.
    • Cada sincronización de tablas puede usar hasta 16 conexiones de base de datos.
  • Límites de tamaño y actualización completa:
    • Si realiza una actualización completa de una tabla sincronizada, la versión anterior en Postgres no se elimina hasta que se sincroniza la nueva tabla. Ambas versiones cuentan temporalmente para el límite de tamaño de la base de datos lógica durante la actualización.
    • Las tablas sincronizadas individuales no tienen un límite, pero el límite total de tamaño de datos lógicos en todas las tablas de la instancia es de 2 TB. Sin embargo, si necesita actualizaciones en lugar de recreación completa de la tabla, Databricks recomienda no superar los 1 TB.
    • Si el tamaño de formato de fila sin comprimir de la tabla catálogo de Unity supera el límite de tamaño de la instancia de base de datos (2 TB), se produce un error en la sincronización. Debe eliminar la tabla sincronizada en Postgres antes de realizar más escrituras en la instancia.

Integración del catálogo

  • Duplicación de catálogos: La creación de una tabla sincronizada en un catálogo estándar destinado a una base de datos postgres que también está registrada como catálogo de bases de datos independiente hace que la tabla sincronizada aparezca en el catálogo de Unity en los catálogos estándar y de base de datos.