Spark connector para bases de dados SQL (Pré-visualização)

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

• Use o Spark para executar grandes operações de escrita e leitura em bases de dados Azure SQL, Azure SQL Managed Instance, SQL Server em Azure VM e bases de dados Fabric SQL.
• Quando usa uma tabela ou uma vista, o conector suporta modelos de segurança definidos ao nível do motor 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 está pré-instalado no runtime do Fabric, por isso não precisas de o instalar separadamente.

Authentication

A autenticação Microsoft Entra está integrada com o Microsoft Fabric.

• Quando inicia sessão no espaço de trabalho do Fabric, as suas credenciais são automaticamente passadas para o motor SQL para autenticação e autorização.
• Requer que o Microsoft Entra ID esteja ativado e configurado no seu motor de base de dados SQL.
• Não é necessária nenhuma configuração extra no seu código Spark se o Microsoft Entra ID estiver configurado. As credenciais são automaticamente mapeadas.

Também pode usar o método de autenticação SQL (especificando um nome de utilizador e palavra-passe SQL) ou um principal de serviço (fornecendo um token de acesso Azure para autenticação baseada em aplicações).

Permissions

Para usar o conector Spark, a sua identidade — seja um utilizador ou uma aplicação — deve ter as permissões necessárias para a base de dados do motor SQL alvo. Estas permissões são necessárias para ler ou escrever em tabelas e vistas.

Para Azure SQL Database, Azure SQL Managed Instance e SQL Server no Azure VM:

• A identidade que executa a operação normalmente necessita das permissões db_datawriter e db_datareader, e opcionalmente de db_owner para controlo total.

Para bases de dados SQL Fabric:

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

Utilização e exemplos de código

Nesta secção, fornecemos exemplos de código para demonstrar como usar eficazmente o conector Spark para bases de dados SQL. Estes exemplos abrangem vários cenários, incluindo ler e escrever em tabelas SQL, e configurar as opções do conector.

Opções suportadas

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 é fornecido:

  • Usa url sempre como primeira preferência.
  • Se spark.mssql.connector.default.url não estiver definido, o conector irá configurá-lo e reutilizá-lo para usos futuros.

• Quando não é url fornecido:

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

Este conector suporta as opções definidas aqui: SQL DataSource JDBC Options

O conector também suporta as seguintes opções:

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

Exemplo de escrita e leitura

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

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

import com.microsoft.sqlserver.jdbc.spark.SparkSqlImplicits._
import org.apache.spark.sql.Row
import org.apache.spark.sql.types._
val url = "jdbc:sqlserver://<server>:<port>;database=<database>;"
val row_data = Seq(
  Row("Alice", 2),
  Row("Bob", 2),
  Row("Charlie", 3)
)
val schema = List(
  StructField("Name", StringType, nullable = true),
  StructField("Age", IntegerType, nullable = true)
)
val df = spark.createDataFrame(spark.sparkContext.parallelize(row_data), StructType(schema))
df.write.mode("overwrite").option("url", url).mssql("dbo.publicExample")
spark.read.option("url", url).mssql("dbo.publicExample").show

val 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

Também pode selecionar colunas, aplicar filtros e usar outras opções quando lê dados do motor de base de dados SQL.

Exemplos de autenticação

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

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

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).option("user", "").option("password", "").mssql("dbo.publicExample")
spark.read.option("user", "").option("password", "").mssql("dbo.publicExample").show()

Modos de salvamento DataFrame suportados

Quando escreves dados do Spark para bases de dados SQL, podes escolher entre vários modos de gravação. Os modos de gravação controlam como os dados são escritos quando a tabela de destino já existe, e podem afetar o esquema, os dados e a indexação. Compreender estes modos ajuda-o a evitar perdas ou alterações inesperadas de dados.

Este conector suporta as opções aqui definidas: Funções de Spark Save

• ErrorIfExists (modo de gravação predefinido): Se a tabela de destino existir, a escrita é abortada e uma exceção é retornada. Caso contrário, é criada uma nova tabela com dados.

• Ignorar: Se a tabela de destino existir, a escrita ignora o pedido e não devolve o erro. Caso contrário, é criada uma nova tabela com dados.

• Sobrescrever: Se a tabela de destino existir, a tabela é eliminada, recriada e novos dados são adicionados.

  Observação

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

• Anexar: Se a tabela de destino existir, novos dados são adicionados a ela. Caso contrário, é criada uma nova tabela com dados.

Troubleshoot

Quando o processo é concluído, a saída da sua operação de leitura do Spark aparece na área de saída da célula. Os erros de com.microsoft.sqlserver.jdbc.SQLServerException vêm diretamente do SQL Server. Pode encontrar informações detalhadas sobre erros nos registos de aplicação do Spark.

Conteúdo relacionado

• Banco de Dados SQL do Azure
• Bases de dados SQL de Fabric
• Azure SQL Database - Autenticação e autorização