Modos de transacción

Importante

Las transacciones que escriben en tablas delta administradas por el catálogo de Unity se encuentran en versión preliminar pública.

Las transacciones que escriben en las tablas Iceberg gestionadas por Unity Catalog se encuentran en versión preliminar privada. Para unirse a esta versión preliminar, envíe el formulario de inscripción de las tablas Iceberg administradas.

Las transacciones admiten dos modos: no interactivos e interactivos. En esta página se explica cuándo usar cada modo e incluye ejemplos de implementación.

Para obtener información general sobre los requisitos y las transacciones, consulte Transacciones. Para la práctica práctica con ambos modos, consulte Tutorial: Coordinar transacciones entre tablas.

Nota:

Todas las tablas escritas en en una transacción de varias instrucciones y varias tablas deben:

Las tablas gestionadas por Unity Catalog (Delta o Iceberg)
Tener habilitadas las confirmaciones administradas por catálogo

Transacciones no interactivas

Las transacciones no interactivas usan SQL scripting con ATOMIC palabra clave. El bloque de instrucciones compuestas ATOMIC ejecuta todas las instrucciones como una sola unidad atómica. Todos tienen éxito juntos o todos fracasan juntos.

Proceso admitido: cualquier almacenamiento de SQL, proceso sin servidor o clúster que ejecute Databricks Runtime 18.0 y versiones posteriores.

Sintaxis admitida: admite bloques SQL, bloques de Scala spark.sql y bloques PySpark spark.sql .

Nota:

Puede usar transacciones no interactivas en Structured Streaming forEachBatch llamando a spark.sql("BEGIN ATOMIC ... END;"). Sin embargo, los puntos de control de Structured Streaming no avanzan transaccionalmente.

Sintaxis

BEGIN ATOMIC
  statement1;
  statement2;
  statement3;
END;

Azure Databricks confirma automáticamente todos los cambios si todas las instrucciones se realizan correctamente. Si se produce un error en alguna instrucción, Azure Databricks revierte automáticamente todos los cambios.

Uso en el editor de SQL

Ejecute transacciones no interactivas directamente en el Editor de SQL. Seleccione todo el bloque de sentencia compuesta ATOMIC y ejecútelo de manera unificada como una sola instrucción.

BEGIN ATOMIC
  DELETE FROM staging_sales WHERE load_date < current_date() - INTERVAL 7 DAYS;

  INSERT INTO staging_sales
  SELECT * FROM raw_sales WHERE load_date = current_date();

  MERGE INTO sales AS target
  USING staging_sales AS source
  ON target.sale_id = source.sale_id
  WHEN MATCHED THEN UPDATE SET *
  WHEN NOT MATCHED THEN INSERT *;
END;

Uso en cuadernos

Ejecute transacciones no interactivas en cuadernos mediante celdas SQL o API de programación.

SQL

BEGIN ATOMIC
  UPDATE inventory SET quantity = quantity - 10 WHERE product_id = 2001;
  UPDATE inventory SET quantity = quantity + 10 WHERE product_id = 2002;
  INSERT INTO inventory_moves (from_product, to_product, quantity, move_date)
  VALUES (2001, 2002, 10, current_date());
END;

Python

spark.sql("""
BEGIN ATOMIC
  UPDATE inventory SET quantity = quantity - 10 WHERE product_id = 2001;
  UPDATE inventory SET quantity = quantity + 10 WHERE product_id = 2002;
  INSERT INTO inventory_moves (from_product, to_product, quantity, move_date)
  VALUES (2001, 2002, 10, current_date());
END;
""")

Scala

spark.sql("""
BEGIN ATOMIC
  UPDATE inventory SET quantity = quantity - 10 WHERE product_id = 2001;
  UPDATE inventory SET quantity = quantity + 10 WHERE product_id = 2002;
  INSERT INTO inventory_moves (from_product, to_product, quantity, move_date)
  VALUES (2001, 2002, 10, current_date());
END;
""")

Uso en trabajos programados

Las transacciones no interactivas funcionan bien en trabajos programados porque controlan automáticamente la confirmación y reversión:

BEGIN ATOMIC
  -- Clear previous staging data
  DELETE FROM staging_daily_sales WHERE load_date = current_date();

  -- Load new data
  INSERT INTO staging_daily_sales
  SELECT sale_id, customer_id, amount, sale_date, current_date() as load_date
  FROM raw_sales
  WHERE sale_date = current_date() - INTERVAL 1 DAY;

  -- Validate row count (fails transaction if no data)
  IF (SELECT COUNT(*) FROM staging_daily_sales WHERE load_date = current_date()) = 0 THEN
    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'No sales data loaded for yesterday';
  END IF;

  -- Merge into production
  MERGE INTO daily_sales AS target
  USING staging_daily_sales AS source
  ON target.sale_id = source.sale_id
  WHEN MATCHED THEN UPDATE SET *
  WHEN NOT MATCHED THEN INSERT *;
END;

Si se produce un error en alguna instrucción, incluida la aserción, toda la transacción se revierte automáticamente.

Uso con JDBC

Los clientes externos pueden ejecutar transacciones no interactivas.

JDBC

String sql = """
    BEGIN ATOMIC
      INSERT INTO orders (order_id, total) VALUES (1001, 500.00);
      UPDATE customers SET last_order = CURRENT_DATE() WHERE customer_id = 5001;
    END;
    """;

Statement stmt = conn.createStatement();
stmt.execute(sql);

Uso con la API para la ejecución de sentencias

Ejecute transacciones no interactivas mediante la API de ejecución de instrucciones:

import requests

sql = """
BEGIN ATOMIC
  INSERT INTO sales (sale_id, amount) VALUES (3001, 750.00);
  UPDATE daily_totals SET total = total + 750.00 WHERE sale_date = CURRENT_DATE();
END;
"""

response = requests.post(
    f"{workspace_url}/api/2.0/sql/statements",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "warehouse_id": warehouse_id,
        "statement": sql,
        "wait_timeout": "30s"
    }
)

Patrones ETL

Los patrones siguientes muestran flujos de trabajo ETL comunes mediante transacciones no interactivas.

Patrón de almacenamiento provisional y validación

Este patrón carga datos en un área de almacenamiento provisional, valida la calidad de los datos y combina registros validados en tablas de producción:

BEGIN ATOMIC
  -- Load into staging
  INSERT INTO staging_customers
  SELECT * FROM external_source
  WHERE ingest_date = current_date();

  -- Validate data quality
  IF (SELECT COUNT(*) FROM staging_customers WHERE email NOT LIKE '%@%') > 0 THEN
    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Invalid email addresses found';
  END IF;

  -- Merge validated data
  MERGE INTO customers AS target
  USING staging_customers AS source
  ON target.customer_id = source.customer_id
  WHEN MATCHED THEN UPDATE SET *
  WHEN NOT MATCHED THEN INSERT *;

  -- Update metadata
  UPDATE etl_metadata
  SET last_load_date = current_date(),
      rows_processed = (SELECT COUNT(*) FROM staging_customers)
  WHERE table_name = 'customers';
END;

Patrón de tabla de dimensiones y hechos

Este patrón actualiza las tablas de dimensiones antes de cargar tablas de hechos para mantener la integridad referencial:

BEGIN ATOMIC
  -- Update dimension tables first
  MERGE INTO dim_products AS target
  USING staging_products AS source
  ON target.product_id = source.product_id
  WHEN MATCHED THEN UPDATE SET *
  WHEN NOT MATCHED THEN INSERT *;

  MERGE INTO dim_customers AS target
  USING staging_customers AS source
  ON target.customer_id = source.customer_id
  WHEN MATCHED THEN UPDATE SET *
  WHEN NOT MATCHED THEN INSERT *;

  -- Then load fact table with foreign key references
  INSERT INTO fact_sales
  SELECT s.sale_id, p.product_key, c.customer_key, s.sale_amount, s.sale_date
  FROM staging_sales s
  JOIN dim_products p ON s.product_id = p.product_id
  JOIN dim_customers c ON s.customer_id = c.customer_id;
END;

Control de errores

Cuando se produce un error en una instrucción dentro de un BEGIN ATOMIC ... END; bloque, Azure Databricks revierte todos los cambios y devuelve un mensaje de error.

Sugerencias de depuración:

Revise el mensaje de error para identificar qué instrucción produjo un error.
Pruebe instrucciones individualmente fuera del bloque de transacciones.
Agregue validaciones mediante SIGNAL para fallar con mensajes de error personalizados.
Consultar el historial de transacciones para obtener contexto adicional.

Transacciones interactivas

Las transacciones interactivas proporcionan un control explícito sobre los límites de transacción. Inicie manualmente una transacción, ejecute instrucciones y confirme o revierte explícitamente.

Computación admitida: solo almacenes SQL.

Sintaxis admitida: solo SQL.

Sintaxis

BEGIN TRANSACTION;

statement1;
statement2;

COMMIT;
-- or: ROLLBACK;

Validar antes de confirmar

Use transacciones interactivas para validar los resultados antes de confirmar:

BEGIN TRANSACTION;

-- Load staging data
INSERT INTO staging_customers
SELECT * FROM external_customers
WHERE load_date = current_date();

-- Validate and commit or rollback
BEGIN
  DECLARE duplicate_count INT;
  SET duplicate_count = (
    SELECT COUNT(*) FROM (
      SELECT customer_id, COUNT(*) as cnt
      FROM staging_customers
      WHERE load_date = current_date()
      GROUP BY customer_id
      HAVING COUNT(*) > 1
    )
  );

  IF duplicate_count > 0 THEN
    ROLLBACK;
    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Duplicate customers found in staging data';
  ELSE
    MERGE INTO customers AS target
    USING staging_customers AS source
    ON target.customer_id = source.customer_id
    WHEN MATCHED THEN UPDATE SET *
    WHEN NOT MATCHED THEN INSERT *;
    COMMIT;
  END IF;
END;

Reversión explícita

Revertir una transacción cuando se produce un error en la validación o la lógica de negocios requiere descartar los cambios:

BEGIN TRANSACTION;

UPDATE inventory
SET quantity = quantity - 50
WHERE product_id = 2001;

-- Check if quantity would go negative
BEGIN
  DECLARE new_quantity INT;
  SET new_quantity = (SELECT quantity FROM inventory WHERE product_id = 2001);

  IF new_quantity < 0 THEN
    ROLLBACK;
    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = 'Insufficient inventory for product 2001';
  ELSE
    COMMIT;
  END IF;
END;

Uso con JDBC

El controlador JDBC admite la ejecución de instrucciones DML mediante executeUpdate() dentro de transacciones. Para obtener una lista de instrucciones DML admitidas, consulte Operaciones admitidas.

Los clientes JDBC usan transacciones interactivas deshabilitando el modo de confirmación automática:

Connection conn = DriverManager.getConnection(jdbcUrl, properties);

try {
    conn.setAutoCommit(false);  // Start transaction mode
    Statement stmt = conn.createStatement();

    stmt.executeUpdate("INSERT INTO accounts (account_id, balance) VALUES (1001, 5000)");
    stmt.executeUpdate("UPDATE accounts SET balance = balance - 100 WHERE account_id = 1001");

    conn.commit();  // Commit the transaction

} catch (SQLException e) {
    conn.rollback();  // Roll back on error
    throw e;
} finally {
    conn.close();
}

Operaciones JDBC no admitidas

Las siguientes operaciones JDBC no se admiten en transacciones interactivas:

Categoría	No soportado
Cambio de catálogo o esquema	`Connection.setCatalog()` y `Connection.setSchema()`
Cambios de configuración de sesión	`Connection.setClientInfo()` para propiedades de nivel de sesión, como `TIMEZONE` y `ANSI_MODE`
Todos los metadatos de base de datos (todos los protocolos)	Todos los `DatabaseMetaData.*` métodos
Metadatos de PreparedStatement	`PreparedStatement.getMetaData()`
Procedimientos almacenados	`CALL procedure_name()`

Uso con ODBC

El controlador ODBC admite la ejecución de instrucciones DML mediante SQLExecute() y SQLExecDirect() dentro de transacciones. Para obtener una lista de instrucciones DML admitidas, consulte Operaciones admitidas.

Los clientes ODBC pueden usar transacciones interactivas con el controlador ODBC de Azure Databricks mediante funciones estándar de administración de transacciones ODBC.

Operaciones ODBC no admitidas

Las siguientes operaciones ODBC no se admiten en transacciones interactivas:

Categoría	No soportado
Todas las funciones de catálogo	`SQLTables`, `SQLColumns`, `SQLStatistics`, `SQLSpecialColumns`, `SQLPrimaryKeys`, `SQLForeignKeys`, `SQLTablePrivileges`, `SQLColumnPrivileges`, `SQLProcedures`, `SQLProcedureColumns`
Establecimiento de atributos de conexión	Cambio de catálogo, cambios en el nivel de aislamiento y cambios en el modo de acceso mediante `SQLSetConnectAttr()`
Traducción de SQL	`SQLNativeSql`

Uso del Conector SQL de Databricks para Python

Databricks SQL Connector para Python admite la ejecución de instrucciones DML mediante cursor.execute() dentro de transacciones. Para obtener una lista de instrucciones DML admitidas, consulte Operaciones admitidas.

Las aplicaciones de Python pueden usar transacciones interactivas con databricks SQL Connector para Python estableciendo autocommit=False:

from databricks import sql

with sql.connect(
    server_hostname="dbc-a1b2345c-d6e7.cloud.databricks.com",
    http_path="sql/1.0/warehouses/abc123def456",
    access_token="your-access-token",
    autocommit=False
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("INSERT INTO accounts (account_id, balance) VALUES (1001, 5000)")
        cursor.execute("UPDATE accounts SET balance = balance - 100 WHERE account_id = 1001")
        connection.commit()

Operaciones del conector de Python no admitidas

Las siguientes operaciones del conector de Python no se admiten en transacciones interactivas:

Categoría	No soportado
Todos los metadatos	`cursor.catalogs()`, `cursor.schemas()`, , `cursor.tables()`, `cursor.columns()`

Limitaciones del controlador para transacciones interactivas

Las siguientes limitaciones se aplican a todos los controladores de dispositivo cuando se utilizan transacciones interactivas.

Las operaciones de metadatos no se admiten dentro de transacciones interactivas. Es posible que se produzca un error en las siguientes operaciones dentro de una transacción, independientemente del controlador o protocolo:

Controlador o protocolo	Tipo	Methods
JDBC	`DatabaseMetaData`	`getCatalogs()`, `getSchemas()`, `getTables()`, , `getColumns()`, `getTypeInfo()`
ODBC	Funciones de catálogo	`SQLTables`, , `SQLColumns`, `SQLGetTypeInfo`
Conector de Python	Métodos de metadatos	`cursor.catalogs()`, `cursor.schemas()`, , `cursor.tables()`, `cursor.columns()`
SQL	Comandos de metadatos	`SHOW TABLES`, `SHOW DATABASES`, `DESCRIBE TABLE`, , `USE CATALOG`, `USE SCHEMA`
SQL	`information_schema`	`SELECT` consultas contra `information_schema` tablas

Ejecute todas las operaciones de metadatos fuera de las transacciones.

Advertencia

La ejecución de transacciones en varios subprocesos en un único objeto de conexión de controlador conduce a un comportamiento indefinido. Ejecute solo una transacción cada vez en cada objeto de conexión.

Comportamiento de aislamiento

Los cambios no confirmados en una transacción interactiva solo son visibles para la sesión. Otras sesiones ven el estado de la tabla tal como estaba antes de que se iniciara la transacción.

Nota:

Las transacciones interactivas usan una detección de conflictos más conservadora que las transacciones no interactivas y pueden entrar en conflicto en el nivel de tabla (excepto los anexos incondicionales). Para la detección de conflictos de nivel de fila, use transacciones no interactivas (BEGIN ATOMIC ... END;).

Para comprobar el aislamiento, cree la tabla de ejemplo si no existe:

CREATE TABLE IF NOT EXISTS sample_accounts (
  id INT,
  account_name STRING,
  balance DECIMAL(10,2)
) USING DELTA
TBLPROPERTIES ('delta.feature.catalogManaged' = 'supported');

En esa misma sesión, inicie una transacción y realice un cambio:

BEGIN TRANSACTION;
INSERT INTO sample_accounts VALUES (10, 'Test', 100.00);

En una sesión de cuaderno o pestaña del Editor de SQL independiente (no una nueva celda del mismo cuaderno), consulte la tabla:
```
-- Run this in the SECOND session
SELECT * FROM sample_accounts WHERE id = 10;
```
Esto devuelve 0 filas porque el cambio no confirmado no está visible fuera de tu primera sesión.
Vuelva a la primera sesión y confirme:
```
COMMIT;
```
Consulta desde la segunda sesión de nuevo:
```
-- Run this in the SECOND session
SELECT * FROM sample_accounts WHERE id = 10;
```
La fila está visible porque se ha confirmado la transacción.

Este aislamiento impide que otros usuarios lean los datos que puedan ser objeto de una reversión.

Elegir un modo de transacción

Escenario	Modo recomendado
Trabajos ETL programados	No interactivo: la confirmación o reversión automática simplifica el control de errores.
Secuencias de instrucciones fijas	Sintaxis no interactiva: sintaxis más sencilla, sin confirmación manual necesaria
Validación de datos antes de confirmar	Interactivo: inspeccione los resultados y decida si se debe confirmar.
Aplicaciones JDBC que necesitan control manual	Interactivo: patrones de transacción de base de datos estándar

Pasos siguientes

Instrucción compuesta ATOMIC (transacciones no interactivas): ejecute varias instrucciones SQL como una única transacción atómica con confirmación y reversión automáticas.
BEGIN TRANSACTION (transacciones interactivas): comience una transacción interactiva con el control manual de confirmación y reversión.
COMMIT: confirme una transacción interactiva y realice todos los cambios permanentes.
ROLLBACK: revierte una transacción interactiva y descarta todos los cambios.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-03-15

Compartir a través de

Modos de transacción

Transacciones no interactivas

Sintaxis

Uso en el editor de SQL

Uso en cuadernos

SQL

Python

Scala

Uso en trabajos programados

Uso con JDBC

JDBC

Uso con la API para la ejecución de sentencias

Patrones ETL

Patrón de almacenamiento provisional y validación

Patrón de tabla de dimensiones y hechos

Control de errores

Transacciones interactivas

Sintaxis

Validar antes de confirmar

Reversión explícita

Uso con JDBC

Operaciones JDBC no admitidas

Uso con ODBC

Operaciones ODBC no admitidas

Uso del Conector SQL de Databricks para Python

Operaciones del conector de Python no admitidas

Limitaciones del controlador para transacciones interactivas

Comportamiento de aislamiento

Elegir un modo de transacción

Pasos siguientes

Referencia de SQL relacionada

Comentarios

Recursos adicionales