Compartir a través de

Conector de Spark para bases de datos SQL (versión preliminar)

Importante

Esta característica se encuentra en versión preliminar.

El conector de Spark para bases de datos SQL es una biblioteca de alto rendimiento que le permite leer y escribir en SQL Server, bases de datos de Azure SQL y bases de datos SQL de Fabric. El conector ofrece las siguientes capacidades:

  • Use Spark para ejecutar operaciones de escritura y lectura grandes en Azure SQL Database, Azure SQL Managed Instance, SQL Server en máquinas virtuales de Azure y bases de datos SQL fabric.
  • Cuando se usa una tabla o una vista, el conector admite modelos de seguridad establecidos en el nivel del motor de SQL. Estos modelos incluyen seguridad de nivel de objeto (OLS), seguridad de nivel de fila (RLS) y seguridad de nivel de columna (CLS).

El conector está preinstalado en el entorno de ejecución de Fabric, por lo que no es necesario instalarlo por separado.

Autenticación

La autenticación de Microsoft Entra se integra con Microsoft Fabric.

  • Al iniciar sesión en el área de trabajo de Fabric, las credenciales se pasan automáticamente al motor de SQL para la autenticación y autorización.
  • Requiere que Microsoft Entra ID esté habilitado y configurado en el motor de base de datos SQL.
  • No se necesita ninguna configuración adicional en el código de Spark si está configurado el identificador de Entra de Microsoft. Las credenciales se asignan automáticamente.

También puede usar el método de autenticación de SQL (especificando un nombre de usuario y una contraseña de SQL) o un principal de servicio (proporcionando un token de acceso de Azure para la autenticación de aplicaciones).

Permissions

Para usar el conector de Spark, la identidad (ya sea un usuario o una aplicación) debe tener los permisos de base de datos necesarios para el motor SQL de destino. Estos permisos son necesarios para leer o escribir en tablas y vistas.

Para Azure SQL Database, Azure SQL Managed Instance y SQL Server en una máquina virtual de Azure:

  • La identidad que ejecuta la operación normalmente necesita permisos de db_datawriter y de db_datareader, y opcionalmente db_owner para el control total.

Para las bases de datos SQL de Fabric:

  • La identidad normalmente necesita db_datawriter y db_datareader permisos y, opcionalmente, db_owner.
  • La identidad también necesita al menos permiso de lectura en la base de datos de Fabric SQL a nivel de elemento.

Nota:

Si utiliza una entidad de servicio, esta puede ejecutarse como una aplicación (sin contexto de usuario) o como un usuario si está habilitada la suplantación de usuario. La entidad de servicio debe tener los permisos de base de datos necesarios para las operaciones que desea realizar.

Ejemplos de uso y código

En esta sección, se proporcionan ejemplos de código para demostrar cómo usar el conector de Spark para bases de datos SQL de forma eficaz. En estos ejemplos se tratan varios escenarios, incluida la lectura y escritura en tablas SQL, y la configuración de las opciones del conector.

Opciones admitidas

La opción mínima requerida es url como "jdbc:sqlserver://<server>:<port>;database=<database>;" o configurar spark.mssql.connector.default.url.

  • Cuando se proporciona url:

    • url Use siempre como primera preferencia.
    • Si spark.mssql.connector.default.url no se establece, el conector lo establecerá y lo reutilizará para su uso futuro.

  • Cuando no se proporciona url:

    • Si spark.mssql.connector.default.url se establece, el conector usa el valor de la configuración de Spark.
    • Si spark.mssql.connector.default.url no se establece, se produce un error porque los detalles necesarios no están disponibles.

Este conector admite las opciones definidas aquí: Opciones JDBC de SQL DataSource

El conector también admite las siguientes opciones:

Opción Valor predeterminado Description
reliabilityLevel "MEJOR_ESFUERZO" Controla la confiabilidad de las operaciones de inserción. Valores posibles: BEST_EFFORT (predeterminado, más rápido, podría dar lugar a filas duplicadas si se reinicia un ejecutor), NO_DUPLICATES (más lento, garantiza que no se inserten filas duplicadas incluso si se reinicia un ejecutor). Elija en función de la tolerancia a los duplicados y las necesidades de rendimiento.
isolationLevel "READ_COMMITTED" Establece el nivel de aislamiento de transacción para las operaciones SQL. Valores posibles: READ_COMMITTED (valor predeterminado, impide leer datos no confirmados), READ_UNCOMMITTED, REPEATABLE_READ, SNAPSHOT, SERIALIZABLE. Los niveles de aislamiento más altos pueden reducir la simultaneidad, pero mejorar la coherencia de los datos.
tableLock falso Controla si se usa la sugerencia de bloqueo de nivel de tabla TABLOCK de SQL Server durante las operaciones de inserción. Valores posibles: true (habilita TABLOCK, que puede mejorar el rendimiento de escritura masiva), false (valor predeterminado, no usa TABLOCK). Al configurar a true, se podría aumentar el rendimiento de las inserciones grandes, pero podría reducir la concurrencia de otras operaciones en la tabla.
schemaCheckEnabled "true" Controla si se aplica una validación de esquema estricta entre spark DataFrame y la tabla SQL. Valores posibles: true (valor predeterminado, aplica la coincidencia estricta de esquemas), false (permite más flexibilidad y podría omitir algunas comprobaciones de esquema). Establecer en false puede ayudar con desajustes de esquema, pero podría dar lugar a resultados inesperados si las estructuras difieren significativamente.

Otras opciones de API en masa se pueden establecer como opciones en DataFrame y se pasan a APIs de copia en masa al escribir.

Ejemplo de escritura y lectura

En el código siguiente se muestra cómo escribir y leer datos mediante el método mssql("<schema>.<table>") con la autenticación automática de Microsoft Entra ID.

Sugerencia

Los datos se crean en línea con fines de demostración. En un escenario de producción, normalmente leería datos de un origen existente o crearía un elemento más complejo 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

También puede seleccionar columnas, aplicar filtros y usar otras opciones al leer datos del motor de base de datos SQL.

Ejemplos de autenticación

En los ejemplos siguientes se muestra cómo usar métodos de autenticación distintos de Microsoft Entra ID, como la entidad de servicio (token de acceso) y la autenticación de SQL.

Nota:

Como se mencionó anteriormente, la autenticación de Microsoft Entra ID se gestiona automáticamente al iniciar sesión en el área de trabajo de Fabric, por lo que solo debe usar estos métodos si su escenario lo requiere.

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 guardado de DataFrame compatibles

Al escribir datos de Spark en bases de datos SQL, puede elegir entre varios modos de guardado. Los modos de guardado controlan cómo se escriben los datos cuando la tabla de destino ya existe y pueden afectar al esquema, los datos y la indexación. Comprender estos modos le ayuda a evitar cambios o pérdida de datos inesperados.

Este conector admite las opciones definidas aquí: Funciones de guardado de Spark

  • ErrorIfExists (modo de guardado predeterminado): si existe la tabla de destino, se anula la escritura y se devuelve una excepción. De lo contrario, se crea una nueva tabla con datos.

  • Omitir: si existe la tabla de destino, la escritura omite la solicitud y no devuelve un error. De lo contrario, se crea una nueva tabla con datos.

  • Sobrescribir: Si la tabla de destino existe, se elimina, se recrea y se anexan nuevos datos.

    Nota:

    Cuando se usa overwrite, el esquema de la tabla original (especialmente los tipos de datos exclusivos de MSSQL) y los índices de la tabla se pierden y son reemplazados por el esquema inferido del DataFrame de Spark. Para evitar perder el esquema y los índices, use .option("truncate", true) en lugar de overwrite.

  • Anexar: si la tabla de destino existe, se anexan nuevos datos a ella. De lo contrario, se crea una nueva tabla con datos.

Troubleshoot

Cuando finaliza el proceso, la salida de la operación de lectura de Spark aparece en el área de salida de la celda. Los errores de com.microsoft.sqlserver.jdbc.SQLServerException proceden directamente de SQL Server. Puede encontrar información detallada sobre los errores en los registros de la aplicación Spark.

Contenido relacionado

  • Last updated on