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 suportam dois modos: não interativo e interativo. Esta página explica quando usar cada modo e inclui exemplos de implementação.

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)
• Ative a opção de confirmação Catalog-gerenciar

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

Você pode usar transações não interativas dentro de forEachBatch da transmissão estruturada chamando spark.sql("BEGIN ATOMIC ... END;"). Entretanto, os postos de controle de transmissão estruturada 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

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

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

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

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:

1. Analise a mensagem de erro para identificar qual instrução falhou.
2. Teste as instruções individualmente fora do bloco de transação.
3. Adicione verificações de validação usando SIGNAL para falhar com mensagens de erro personalizadas.
4. 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

SQL

BEGIN TRANSACTION;

statement1;
statement2;

COMMIT;
-- or: 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.

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

execução de todas as operações de metadados 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

As alterações não confirmadas em uma transação interativa são visíveis apenas para a sua sessão. Outras sessões visualizam o estado da tabela como estava antes do início da sua transação.

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

1. 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');

1. 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);

2. 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.

3. Retorne à sua primeira sessão e commit:

   SQL

   COMMIT;

4. 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

Próximos passos

• Tutorial: Coordenar transações entre tabelas
• Transações
• Commit de gerenciamento de catálogo
• Níveis de isolamento e conflitos de escrita

Referência SQL relacionada

• 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.