Modos de transação

info

Visualização

Transações que gravam no Unity Catalog gerenciam tabelas Delta e estão em Pré-visualização Pública.

Transações que gravam em tabelas Iceberg gerenciadas Unity Catalog estão em Pré-visualização Privada. Para join desta pré-visualização, envie o formulário de inscrição para a pré-visualização das mesas Iceberg.

As transações no Databricks suportam dois modos:

Não interativo (BEGIN ATOMIC): Faz commit ou reverte automaticamente. Ideal para Jobs agendados e sequências de declarações fixas.
Interativo (BEGIN TRANSACTION): Oferece controle manual sobre commit e rollback. Melhor para validação, depuração e clientes JDBC.

Para requisitos e uma visão geral das transações, consulte Transações. Para praticar com ambos os modos, consulte o tutorial: Coordenar transações entre tabelas.

nota

Todas as tabelas que são gravadas em uma transação com várias instruções e várias tabelas devem:

Unity Catalog gerenciar tabelas (Delta ou Iceberg)
Ativar a confirmação do catálogo

Transações não interativas

Transações não interativas usam scripts SQL com a palavra-chave ATOMIC . O bloco de instruções composto ATOMIC executa todas as instruções como uma única unidade atômica. Ou todos vencem juntos, ou todos fracassam juntos.

computesuportada : Qualquer SQL warehouse, computeserverless ou cluster executando Databricks Runtime 18.0 ou superior.

Sintaxe suportada : Suporta SQL, blocos Scala spark.sql e blocos PySpark spark.sql .

nota

É possível usar transações não interativas dentro do forEachBatch da transmissão estructurada, ao chamar spark.sql("BEGIN ATOMIC ... END;"). No entanto, os pontos de verificação da transmissão estructurada não avançam transacionalmente.

Sintaxe

SQL
BEGIN ATOMIC
  statement1;
  statement2;
  statement3;
END;

Databricks confirma automaticamente todas as alterações se todas as instruções forem bem-sucedidas. Se alguma instrução falhar, o Databricks reverte automaticamente todas as alterações.

Utilize no editor SQL

Execução de transações não interativas diretamente no EditorSQL. Selecione todo o bloco de instruções compostas ATOMIC e execute-o como uma única instrução:

SQL
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;

Usar no Notebook

Execução de transações não interativas no Notebook usando células SQL ou APIs programáticas.

SQL
Python
Scala

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;
""")

Utilizar em tarefas agendadas

Transações não interativas funcionam bem em tarefas agendadas porque lidam automaticamente com commit e rollbacks:

SQL
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;

Se alguma instrução falhar, incluindo a asserção, toda a transação será revertida automaticamente.

Utilizar com JDBC

Clientes externos podem executar transações não interativas.

JDBC

Java
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);

Utilize com a API de Execução de Instruções.

Execução de transações não interativas usando a APIde Execução de Declarações:

Python
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={&quot;Authorization&quot;: f&quot;Bearer {token}&quot;},
    json={
        &quot;warehouse_id&quot;: warehouse_id,
        &quot;statement&quot;: sql,
        &quot;wait_timeout&quot;: &quot;30s&quot;
    }
)

Padrões ETL

Os padrões a seguir demonstram o fluxo de trabalho ETL comum usando transações não interativas.

Padrão de estágio e validação

Esse padrão carrega dados em uma área de preparação, valida a qualidade dos dados e mescla os registros validados em tabelas de produção:

SQL
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;

Padrão de tabela de dimensões e fatos

Este padrão atualiza as tabelas de dimensões antes de carregar as tabelas de fatos para manter a integridade referencial:

SQL
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;

Tratamento de erros

Quando uma instrução falha dentro de um bloco BEGIN ATOMIC ... END; , o Databricks reverte todas as alterações e retorna uma mensagem de erro.

Dicas de depuração:

Analise a mensagem de erro para identificar qual instrução falhou.
Teste as instruções individualmente fora do bloco de transação.
Adicione verificações de validação usando SIGNAL para falhar com mensagens de erro personalizadas.
Consulte a história da transação para obter contexto adicional.

Transações interativas

Transações interativas oferecem controle explícito sobre os limites da transação. Você inicia manualmente uma transação, executa instruções e commit ou reverte explicitamente as alterações.

computesuportada : somente SQL Warehouse .

Sintaxe suportada : somente SQL.

Sintaxe

Para fazer commit:

SQL
BEGIN TRANSACTION;
statement1;
statement2;
COMMIT;

Para reverter:

SQL
BEGIN TRANSACTION;
statement1;
statement2;
ROLLBACK;

Valide antes de confirmar.

Utilize transações interativas para validar os resultados antes de confirmá-los:

SQL
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;

Reversão explícita

Reverter uma transação quando a validação falhar ou a lógica de negócios exigir o descarte de alterações:

SQL
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;

Utilizar com JDBC

O driver JDBC suporta a execução de instruções DML usando executeUpdate() dentro de transações. Para obter uma lista das instruções DML suportadas, consulte Operações suportadas.

Os clientes JDBC utilizam transações interativas desativando o modocommit automática:

Java
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();
}

Operações JDBC não suportadas

As seguintes operações JDBC não são suportadas em transações interativas:

Categoria	Não suportado
Troca de catálogo ou esquema	`Connection.setCatalog()` e `Connection.setSchema()`
Alterações na configuração da sessão	`Connection.setClientInfo()` para propriedades de nível de sessão, como `TIMEZONE` e `ANSI_MODE`
Todos os metadados do banco de dados (todos os protocolos)	Todos os métodos `DatabaseMetaData.*`
Metadados de declaração preparada	`PreparedStatement.getMetaData()`
Procedimentos armazenados	`CALL procedure_name()`

Utilizar com ODBC

O driver ODBC suporta a execução de instruções DML usando SQLExecute() e SQLExecDirect() dentro de transações. Para obter uma lista das instruções DML suportadas, consulte Operações suportadas.

Os clientes ODBC podem usar transações interativas com o driver ODBC do Databricks usando funções padrão de gerenciamento de transações ODBC.

nota

Você deve desativar AutoCommit para usar transações. Para desativar AutoCommit em tempo de execução, defina UseNativeQuery como 1. Consulte Suporte a consultas ANSI SQL-92 em ODBC.

Operações ODBC não suportadas

As seguintes operações ODBC não são suportadas em transações interativas:

Categoria	Não suportado
Todas as funções do catálogo	`SQLTables`, `SQLColumns`, `SQLStatistics`, `SQLSpecialColumns`, `SQLPrimaryKeys`, `SQLForeignKeys`, `SQLTablePrivileges`, `SQLColumnPrivileges`, `SQLProcedures`, `SQLProcedureColumns`
Definindo atributos de conexão	Troca de catálogo, alterações de nível de isolamento e alterações de modo de acesso usando `SQLSetConnectAttr()`
Tradução SQL	`SQLNativeSql`

Utilize com o conector Databricks SQL para Python

O conector Databricks SQL para Python suporta a execução de instruções DML usando cursor.execute() dentro de transações. Para obter uma lista das instruções DML suportadas, consulte Operações suportadas.

Aplicações Python podem usar transações interativas com o ConectorDatabricks SQL para Python definindo autocommit=False:

Python
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()

Operações de conector Python não suportadas

As seguintes operações do conector Python não são suportadas em transações interativas:

Categoria	Não suportado
Todos os metadados	`cursor.catalogs()`, `cursor.schemas()`, `cursor.tables()`, `cursor.columns()`

Limitações do driver para transações interativas

As seguintes limitações aplicam-se a todos os condutores ao utilizarem transações interativas.

Operações com metadados não são suportadas em transações interativas. As seguintes operações podem falhar em uma transação, independentemente do driver ou protocolo:

Driver/Protocolo	Tipo	Métodos
JDBC	`DatabaseMetaData`	`getCatalogs()`, `getSchemas()`, `getTables()`, `getColumns()`, `getTypeInfo()`
ODBC	Funções do catálogo	`SQLTables`, `SQLColumns`, `SQLGetTypeInfo`
Conector Python	Métodos de metadados	`cursor.catalogs()`, `cursor.schemas()`, `cursor.tables()`, `cursor.columns()`
SQL	Metadados comando	`SHOW TABLES`, `SHOW DATABASES`, `DESCRIBE TABLE`, `USE CATALOG`, `USE SCHEMA`
SQL	`information_schema`	`SELECT` consultas em tabelas `information_schema`

A Databricks recomenda que todas as operações de metadados sejam executadas fora das transações.

atenção

Executar transações em várias threads em um único objeto de conexão de driver leva a um comportamento indefinido. A execução permite apenas uma transação por vez em cada objeto de conexão.

comportamento de isolamento

Alterações não confirmadas em uma transação interativa são visíveis apenas para sua sessão. As alterações são visíveis para outras sessões somente após você realizar a execução de COMMIT;.

nota

Transações interativas utilizam um sistema de detecção de conflitos mais conservador do que transações não interativas e podem entrar em conflito no nível da tabela (exceto para acréscimos incondicionais). Para detecção de conflitos em nível de linha, use transações não interativas (BEGIN ATOMIC ... END;).

Para verificar o isolamento, crie a tabela de amostra caso ela não exista:

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

Nessa mesma sessão, inicie uma transação e faça uma alteração:

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

Em uma tab separada do Editor SQL ou em uma sessão de Notebook (não em uma nova célula no mesmo Notebook), consulte a tabela:
SQL
```
-- Run this in the SECOND session
SELECT * FROM sample_accounts WHERE id = 10;
```
Isso retorna 0 linhas porque a alteração não confirmada não é visível fora da sua primeira sessão.
Retorne à sua primeira sessão e commit:
SQL
```
COMMIT;
```
Consulta da segunda sessão novamente:
SQL
```
-- Run this in the SECOND session
SELECT * FROM sample_accounts WHERE id = 10;
```
A linha está visível porque a transação foi confirmada.

Esse isolamento impede que outros usuários leiam dados que possam ser revertidos.

Escolha um modo de transação

Cenário	Modo recomendado
Tarefa ETL agendada	Não interativo — o commit ou rollback automático simplifica o tratamento de erros.
Sequências de instruções fixas	Não interativo — sintaxe mais simples, sem necessidade commit manual.
Validação de dados antes commit	Interativo — examine os resultados e decida se deseja commit
Aplicações JDBC que necessitam de controle manual	Interativo — padrões de transação de banco de dados padrão

Recursos adicionais

Tutorial: Coordenar transações entre tabelas
Transações
Confirmação do catálogo
Níveis de isolamento e conflitos de escrita
Instrução composta ATÔMICA (transações não interativas): execução de múltiplas instruções SQL como uma única transação atômica com commit e reversão automáticas.
INICIAR TRANSAÇÃO (transações interativas): Inicia uma transação interativa com controle manual commit e reversão.
commit: confirma uma transação interativa e torna todas as alterações permanentes.
ROLLBACK: Reverte uma transação interativa e descarta todas as alterações.

Transações não interativas​

Sintaxe​

Utilize no editor SQL​

Usar no Notebook​

Utilizar em tarefas agendadas​

Utilizar com JDBC​

Utilize com a API de Execução de Instruções.​

Padrões ETL​

Padrão de estágio e validação​

Padrão de tabela de dimensões e fatos​

Tratamento de erros​

Transações interativas​

Sintaxe​

Valide antes de confirmar.​

Reversão explícita​

Utilizar com JDBC​

Operações JDBC não suportadas​

Utilizar com ODBC​

Operações ODBC não suportadas​

Utilize com o conector Databricks SQL para Python​

Operações de conector Python não suportadas​

Limitações do driver para transações interativas​

comportamento de isolamento​

Escolha um modo de transação​

Recursos adicionais​

Transações não interativas

Sintaxe

Utilize no editor SQL

Usar no Notebook

Utilizar em tarefas agendadas

Utilizar com JDBC

Utilize com a API de Execução de Instruções.

Padrões ETL

Padrão de estágio e validação

Padrão de tabela de dimensões e fatos

Tratamento de erros

Transações interativas

Sintaxe

Valide antes de confirmar.

Reversão explícita

Utilizar com JDBC

Operações JDBC não suportadas

Utilizar com ODBC

Operações ODBC não suportadas

Utilize com o conector Databricks SQL para Python

Operações de conector Python não suportadas

Limitações do driver para transações interativas

comportamento de isolamento

Escolha um modo de transação

Recursos adicionais