Compartilhar via

Conector do Spark para bancos de dados SQL (versão prévia)

Importante

Esse recurso está na versão prévia.

O conector do Spark para bancos de dados SQL é uma biblioteca de alto desempenho que permite ler e gravar no SQL Server, bancos de dados SQL do Azure e bancos de dados SQL do Fabric. O conector oferece os seguintes recursos:

  • Use o Spark para executar grandes operações de gravação e leitura no Banco de Dados SQL do Azure, na Instância Gerenciada de SQL do Azure, no SQL Server na VM do Azure e nos bancos de dados SQL do Fabric.
  • Quando você usa uma tabela ou uma exibição, o conector dá suporte a modelos de segurança definidos no nível do mecanismo SQL. Esses modelos incluem segurança em nível de objeto (OLS), segurança em nível de linha (RLS) e segurança em nível de coluna (CLS).

O conector é pré-instalado no runtime do Fabric, portanto, você não precisa instalá-lo separadamente.

Authentication

A autenticação do Microsoft Entra é integrada ao Microsoft Fabric.

  • Quando você entra no workspace do Fabric, suas credenciais são passadas automaticamente para o mecanismo SQL para autenticação e autorização.
  • Exige que a ID do Microsoft Entra seja habilitada e configurada em seu mecanismo de banco de dados SQL.
  • Nenhuma configuração extra será necessária no código do Spark se a ID do Microsoft Entra estiver configurada. As credenciais são mapeadas automaticamente.

Você também pode usar o método de autenticação SQL (especificando um nome de usuário e senha do SQL) ou um principal de serviço (fornecendo um token de acesso do Azure para autenticação baseada em aplicativo).

Permissions

Para usar o conector do Spark, sua identidade, seja um usuário ou um aplicativo, deve ter as permissões de banco de dados necessárias para o mecanismo SQL de destino. Essas permissões são necessárias para ler ou gravar em tabelas e exibições.

Para o Banco de Dados SQL do Azure, a Instância Gerenciada de SQL do Azure e o SQL Server na VM do Azure:

  • A identidade que executa a operação normalmente precisa db_datawriter e db_datareader permissões e, opcionalmente db_owner , para controle total.

Para bancos de dados SQL do Fabric:

  • A identidade normalmente precisa das permissões db_datawriter e db_datareader, e, opcionalmente, db_owner.
  • A identidade também precisa de pelo menos permissão de leitura no banco de dados SQL do Fabric no nível do item.

Observação

Se você usar uma entidade de serviço (service principal), ela poderá funcionar como um aplicativo (sem contexto de usuário) ou como usuário, se a representação do usuário estiver habilitada. O principal de serviço deve ter as permissões de banco de dados necessárias para as operações que você deseja executar.

Exemplos de uso e código

Nesta seção, fornecemos exemplos de código para demonstrar como usar o conector Spark para bancos de dados SQL com eficiência. Esses exemplos abrangem vários cenários, incluindo ler e gravar em tabelas SQL e configurar as opções do conector.

Opções com suporte

A opção mínima necessária é url como "jdbc:sqlserver://<server>:<port>;database=<database>;" ou definir spark.mssql.connector.default.url.

  • Quando o url for fornecido:

    • Sempre use url como primeira preferência.
    • Se spark.mssql.connector.default.url não estiver definido, o conector o definirá e o reutilizará para uso futuro.

  • Quando o url não for fornecido:

    • Se spark.mssql.connector.default.url estiver definido, o conector usará o valor da configuração do spark.
    • Se spark.mssql.connector.default.url não estiver definido, um erro será gerado porque os detalhes necessários não estão disponíveis.

Esse conector dá suporte às opções definidas aqui: Opções JDBC do SQL DataSource

O conector também dá suporte às seguintes opções:

Opção Valor padrão Description
reliabilityLevel "MELHOR_ESFORÇO" Controla a confiabilidade das operações de inserção. Valores possíveis: BEST_EFFORT (padrão, mais rápido, pode resultar em linhas duplicadas se um executor for reiniciado), NO_DUPLICATES (mais lento, garante que nenhuma linha duplicada seja inserida mesmo se um executor for reiniciado). Escolha com base em sua tolerância para duplicatas e necessidades de desempenho.
isolationLevel "READ_COMMITTED" Define o nível de isolamento da transação para operações SQL. Valores possíveis: READ_COMMITTED (padrão, impede a leitura de dados não confirmados), READ_UNCOMMITTED, , REPEATABLE_READ, SNAPSHOT. SERIALIZABLE Níveis de isolamento mais altos podem reduzir a simultaneidade, mas melhorar a consistência dos dados.
tableLock falso Controla se a dica de bloqueio no nível da tabela TABLOCK do SQL Server é usada durante as operações de inserção. Valores possíveis: true (habilita TABLOCK, que pode melhorar o desempenho de gravação em massa), false (padrão, não usa TABLOCK). Definir para true pode aumentar a taxa de transferência para inserções grandes, mas pode reduzir a concorrência para outras operações na tabela.
schemaCheckEnabled "verdadeiro" Controla se a validação estrita de esquema é imposta entre o Spark DataFrame e a tabela SQL. Valores possíveis: true (padrão, impõe correspondência estrita de esquema) false (permite mais flexibilidade e pode ignorar algumas verificações de esquema). Definir para false pode ajudar nas incompatibilidades de esquema, mas pode levar a resultados inesperados caso as estruturas sejam significativamente diferentes.

Outras opções de API em massa podem ser configuradas e DataFrame são passadas para as APIs de cópia em massa durante a gravação.

Exemplo de gravação e leitura

O código a seguir mostra como gravar e ler dados usando o mssql("<schema>.<table>") método com autenticação automática da ID do Microsoft Entra.

Dica

Os dados são criados in-line para fins de demonstração. Em um cenário de produção, você normalmente leria dados de uma fonte existente ou criaria algo mais complexo DataFrame.

import com.microsoft.sqlserver.jdbc.spark
url = "jdbc:sqlserver://<server>:<port>;database=<database>;"
row_data = [("Alice", 1),("Bob", 2),("Charlie", 3)]
column_header = ["Name", "Age"]
df = spark.createDataFrame(row_data, column_header)
df.write.mode("overwrite").option("url", url).mssql("dbo.publicExample")
spark.read.option("url", url).mssql("dbo.publicExample").show()

url = "jdbc:sqlserver://<server>:<port>;database=<database2>;" # different database
df.write.mode("overwrite").option("url", url).mssql("dbo.tableInDatabase2") # default url is updated
spark.read.mssql("dbo.tableInDatabase2").show() # no url option specified and will use database2

Você também pode selecionar colunas, aplicar filtros e usar outras opções ao ler dados do mecanismo de banco de dados SQL.

Exemplos de autenticação

Os exemplos a seguir mostram como usar métodos de autenticação além do Microsoft Entra ID, como service principal (token de acesso) e a autenticação SQL.

Observação

Conforme mencionado anteriormente, a autenticação de ID do Microsoft Entra é tratada automaticamente quando você faz login na área de trabalho do Fabric. Portanto, você só precisa usar esses métodos se o cenário exigir.

import com.microsoft.sqlserver.jdbc.spark
url = "jdbc:sqlserver://<server>:<port>;database=<database>;"
row_data = [("Alice", 1),("Bob", 2),("Charlie", 3)]
column_header = ["Name", "Age"]
df = spark.createDataFrame(row_data, column_header)

from azure.identity import ClientSecretCredential
credential = ClientSecretCredential(tenant_id="", client_id="", client_secret="") # service principal app
scope = "https://database.windows.net/.default"
token = credential.get_token(scope).token

df.write.mode("overwrite").option("url", url).option("accesstoken", token).mssql("dbo.publicExample")
spark.read.option("accesstoken", token).mssql("dbo.publicExample").show()

Modos de salvamento de DataFrame com suporte

Ao gravar dados do Spark em bancos de dados SQL, você pode escolher entre vários modos de salvamento. Os modos de salvamento controlam como os dados são gravados quando a tabela de destino já existe e podem afetar o esquema, os dados e a indexação. Entender esses modos ajuda você a evitar perdas ou alterações inesperadas de dados.

Esse conector dá suporte às opções definidas aqui: Funções de salvamento do Spark

  • ErrorIfExists (modo de salvamento padrão): se a tabela de destino existir, a gravação será anulada e uma exceção será retornada. Caso contrário, uma nova tabela será criada com dados.

  • Ignorar: se a tabela de destino existir, a gravação ignorará a solicitação e não retornará um erro. Caso contrário, uma nova tabela será criada com dados.

  • Substituir: Caso a tabela de destino já exista, ela será descartada, recriada e novos dados serão adicionados.

    Observação

    Quando você usa overwrite, o esquema de tabela original (especialmente tipos de dados exclusivos do MSSQL) e os índices de tabela são perdidos e substituídos pelo esquema inferido do DataFrame do Spark. Para evitar a perda de esquema e índices, use .option("truncate", true) em vez de overwrite.

  • Acrescentar: se a tabela de destino existir, novos dados serão acrescentados a ela. Caso contrário, uma nova tabela será criada com dados.

Troubleshoot

Quando o processo é concluído, a saída da operação de leitura do Spark é exibida na área de saída da célula. Erros de com.microsoft.sqlserver.jdbc.SQLServerException vêm diretamente do SQL Server. Você pode encontrar informações detalhadas de erro nos logs de aplicativos do Spark.

Conteúdo relacionado

  • Last updated on