Consulta de datos en Azure Synapse Analytics

Puede acceder a Azure Synapse desde Azure Databricks con el conector de Azure Synapse, que utiliza la instrucción COPY en Azure Synapse para transferir eficazmente grandes volúmenes de datos entre un clúster de Azure Databricks y una instancia de Azure Synapse con una cuenta de almacenamiento de Azure Data Lake Storage Gen2 para el almacenamiento provisional temporal.

Importante

Las configuraciones descritas en este artículo son experimentales. Las características experimentales se proporcionan tal cual y no cuentan con soporte técnico de Databricks a través del soporte técnico al cliente. Para obtener compatibilidad completa con la federación de consultas, debe usar la federación de Lakehouse, que permite a los usuarios de Azure Databricks aprovechar la sintaxis de Unity Catalog y las herramientas de gobernanza de datos.

Azure Synapse Analytics es un almacenamiento de datos empresarial basado en la nube que aprovecha el procesamiento paralelo masivo (MPP) para ejecutar rápidamente consultas complejas en petabytes de datos.

Importante

Este conector se usa solo con instancias de grupo dedicado de Synapse y no es compatible con otros componentes de Synapse.

Nota:

COPY solo está disponible en las instancias de Azure Data Lake Storage Gen2. Si busca detalles sobre cómo trabajar con Polybase, consulte Conexión de Azure Databricks y Azure Synapse con PolyBase (heredado).

Sintaxis de ejemplo para Synapse

Puede consultar Synapse en Scala, Python, SQL y R. En los ejemplos de código siguientes, se usan claves de cuenta de almacenamiento y se reenvían las credenciales de almacenamiento de Azure Databricks a Synapse.

Nota:

Use las cadenas de conexión que proporciona Azure Portal, lo que habilita el cifrado Capa de sockets seguros (SSL) para todos los datos que se envían entre el controlador de Spark y la instancia de Azure Synapse a través de la conexión JDBC. Si quiere comprobar que el cifrado SSL está habilitado, busque encrypt=true en la cadena de conexión.

Importante

Las ubicaciones externas definidas en Unity Catalog no se admiten como ubicaciones tempDir.

Databricks recomienda usar el flujo de autenticación más seguro disponible. El flujo de autenticación descrito en este ejemplo conlleva riesgos que no están presentes en otros flujos. Solo debe usar este flujo cuando otros flujos más seguros, como las identidades administradas, no sean viables.

Scala

// Set up the storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 11.3 LTS and above.
val df: DataFrame = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") /* Optional - will use default port 1433 if not specified. */
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") /* If schemaName not provided, default to "dbo". */
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .load()

// Load data from an Azure Synapse query.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("query", "select x, count(*) as cnt from table group by x")
  .load()

// Apply some transformations to the data, then use the
// Data Source API to write the data back to another table in Azure Synapse.

df.write
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .save()

Python

# Set up the storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 11.3 LTS and above.
df = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") # Optional - will use default port 1433 if not specified.
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") # If schemaName not provided, default to "dbo".
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
df = spark.read \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("dbTable", "<your-table-name>") \
  .load()

# Load data from an Azure Synapse query.
df = spark.read \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("query", "select x, count(*) as cnt from table group by x") \
  .load()

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

df.write \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("dbTable", "<your-table-name>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .save()

SQL

-- Set up the storage account access key in the notebook session conf.
SET fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net=<your-storage-account-access-key>;

-- Read data using SQL. The following example applies to Databricks Runtime 11.3 LTS and above.
CREATE TABLE example_table_in_spark_read
USING sqldw
OPTIONS (
  host '<hostname>',
  port '<port>' /* Optional - will use default port 1433 if not specified. */
  user '<username>',
  password '<password>',
  database '<database-name>'
  dbtable '<schema-name>.<table-name>', /* If schemaName not provided, default to "dbo". */
  forwardSparkAzureStorageCredentials 'true',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Read data using SQL. The following example applies to Databricks Runtime 10.4 LTS and below.
CREATE TABLE example_table_in_spark_read
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbtable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Write data using SQL.
-- Create a new table, throwing an error if a table with the same name already exists:

CREATE TABLE example_table_in_spark_write
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbTable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
)
AS SELECT * FROM table_to_save_in_spark;

R

# Load SparkR
library(SparkR)

# Set up the storage account access key in the notebook session conf.
conf <- sparkR.callJMethod(sparkR.session(), "conf")
sparkR.callJMethod(conf, "set", "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net", "<your-storage-account-access-key>")

# Get some data from an Azure Synapse table.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   dbTable = "<your-table-name>",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

# Load data from an Azure Synapse query.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   query = "select x, count(*) as cnt from table group by x",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

write.df(
  df,
  source = "com.databricks.spark.sqldw",
  url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
  forward_spark_azure_storage_credentials = "true",
  dbTable = "<your-table-name>",
  tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

¿Cómo funciona la autenticación entre Azure Databricks y Synapse?

El conector de Azure Synapse usa tres tipos de conexiones de red:

• Controlador de Spark a Azure Synapse
• Clúster de Spark a la cuenta de almacenamiento de Azure
• Azure Synapse a la cuenta de Azure Storage

Configuración del acceso a Azure Storage

Tanto Azure Databricks como Synapse necesitan acceso con privilegios a una cuenta de almacenamiento de Azure que se usará para el almacenamiento de datos temporal.

Azure Synapse no admite el uso de SAS para el acceso a la cuenta de almacenamiento. Puede configurar el acceso para ambos servicios mediante una de las acciones siguientes:

• Use la clave de cuenta y el secreto de la cuenta de almacenamiento y establezca en forwardSparkAzureStorageCredentials en true. Consulte Establecimiento de las propiedades de Spark para configurar las credenciales de Azure para acceder a Azure Storage.
• Use Azure Data Lake Storage Gen2 con la autenticación de OAuth 2.0 y establezca enableServicePrincipalAuth en true. Consulte Configuración de la conexión de Azure Databricks a Synapse con OAuth 2.0 con una entidad de servicio.
• Configure la instancia de Azure Synapse para que tenga una identidad de servicio administrada y establezca useAzureMSI en true.

Permisos requeridos de Azure Synapse

Dado que usa COPY en segundo plano, el conector de Azure Synapse requiere que el usuario de la conexión JDBC tenga permiso para ejecutar los comandos siguientes en la instancia de Azure Synapse conectada:

• COPY INTO

Si la tabla de destino no existe en Azure Synapse, se requiere permiso para ejecutar el comando siguiente además del comando anterior:

• CREATE TABLE

En la tabla siguiente, se resumen los permisos necesarios para las operaciones de escritura con COPY:

Permisos (insertar en una tabla existente)	Permisos (insertar en una tabla nueva)
ADMINISTER DATABASE BULK OPERATIONS INSERT	ADMINISTER DATABASE BULK OPERATIONS INSERT CREATE TABLE ALTER ON SCHEMA :: dbo

Configuraciones de red

Si configura un firewall en Azure Synapse, debe definir la configuración de red para permitir que Azure Databricks llegue a Azure Synapse. En primer lugar, asegúrese de que el área de trabajo de Azure Databricks se implemente en su propia red virtual según lo indicado en Implementación de Azure Databricks en una red virtual de Azure (inserción en red virtual). Después, puede configurar reglas de firewall de IP en Azure Synapse para permitir conexiones desde las subredes a la cuenta de Synapse. Consulte Reglas de firewall de IP de Azure Synapse Analytics.

Configuración de la conexión de Azure Databricks a Synapse con OAuth 2.0 con una entidad de servicio

Puede autenticarse en Azure Synapse Analytics con una entidad de servicio con acceso a la cuenta de almacenamiento subyacente. Para obtener más información sobre el uso de las credenciales de entidad de servicio para acceder a una cuenta de almacenamiento de Azure, consulte el documento sobre Conexión a Azure Data Lake Storage Gen2 y Blob Storage. Debe establecer la opción enableServicePrincipalAuth en true en la referencia de las opciones del conector de Azure Databricks Synapse de la configuración de conexión para permitir que el conector se autentique con una entidad de servicio.

También puede utilizar otra entidad de servicio para la conexión de Azure Synapse Analytics. En el ejemplo siguiente se configuran credenciales de entidad de servicio para la cuenta de almacenamiento y credenciales de entidad de servicio opcionales para Synapse:

ini

; Defining the Service Principal credentials for the Azure storage account
fs.azure.account.auth.type OAuth
fs.azure.account.oauth.provider.type org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider
fs.azure.account.oauth2.client.id <application-id>
fs.azure.account.oauth2.client.secret <service-credential>
fs.azure.account.oauth2.client.endpoint https://login.microsoftonline.com/<directory-id>/oauth2/token

; Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.databricks.sqldw.jdbc.service.principal.client.id <application-id>
spark.databricks.sqldw.jdbc.service.principal.client.secret <service-credential>

Scala

// Defining the Service Principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<application-id>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<service-credential>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

// Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Python

# Defining the service principal credentials for the Azure storage account
spark.conf.set("fs.azure.account.auth.type", "OAuth")
spark.conf.set("fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
spark.conf.set("fs.azure.account.oauth2.client.id", "<application-id>")
spark.conf.set("fs.azure.account.oauth2.client.secret", "<service-credential>")
spark.conf.set("fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

# Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
spark.conf.set("spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

R

# Load SparkR
library(SparkR)
conf <- sparkR.callJMethod(sparkR.session(), "conf")

# Defining the service principal credentials for the Azure storage account
sparkR.callJMethod(conf, "set", "fs.azure.account.auth.type", "OAuth")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth.provider.type",  "org.apache.hadoop.fs.azurebfs.oauth2.ClientCredsTokenProvider")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.id", "<application-id>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.secret", "<service-credential>")
sparkR.callJMethod(conf, "set", "fs.azure.account.oauth2.client.endpoint", "https://login.microsoftonline.com/<directory-id>/oauth2/token")

# Defining a separate set of service principal credentials for Azure Synapse Analytics (If not defined, the connector will use the Azure storage account credentials)
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.id", "<application-id>")
sparkR.callJMethod(conf, "set", "spark.databricks.sqldw.jdbc.service.principal.client.secret", "<service-credential>")

Modos de guardado admitidos para escrituras por lotes

El conector de Azure Synapse admite los modos de guardado ErrorIfExists, Ignore, Append y Overwrite, con ErrorIfExists como modo predeterminado. Para más información sobre los modos de guardado que se admiten en Apache Spark, consulte la documentación de Spark SQL sobre los modos de guardado.

Referencia de las opciones del conector de Synapse de Azure Databricks

Los objetos OPTIONS que se proporcionan en Spark SQL admiten la configuración siguiente:

Parámetro	Obligatorio	Valor predeterminado	Notas
dbTable	Sí, a menos que se especifique query	Sin valor predeterminado	Tabla a partir de la que se creará o leerá en Azure Synapse. Se requiere este parámetro al guardar los datos de vuelta en Azure Synapse. También puede usar {SCHEMA NAME}.{TABLE NAME} para acceder a una tabla en un esquema determinado. Si no se proporciona el nombre del esquema, se usa el esquema predeterminado asociado al usuario de JDBC. La variante dbtable admitida previamente está en desuso y se omitirá en las versiones futuras. En su lugar, use el nombre en una mezcla de mayúsculas y minúsculas.
query	Sí, a menos que se especifique dbTable	Sin valor predeterminado	Consulta a partir de la que se leerá en Azure Synapse. En el caso de las tablas a las que se hace referencia en la consulta, también puede usar {SCHEMA NAME}.{TABLE NAME} para acceder a una tabla en un esquema determinado. Si no se proporciona el nombre del esquema, se usa el esquema predeterminado asociado al usuario de JDBC.
user	No	Sin valor predeterminado	Nombre de usuario de Azure Synapse. Se debe usar en conjunto con la opción password. Solo se puede usar si el usuario y la contraseña no se pasan en la dirección URL. Si se pasan ambos, se producirá un error.
password	No	Sin valor predeterminado	Contraseña de Azure Synapse. Se debe usar en conjunto con la opción user. Solo se puede usar si el usuario y la contraseña no se pasan en la dirección URL. Si se pasan ambos, se producirá un error.
url	Sí	Sin valor predeterminado	Dirección URL de JDBC con sqlserver establecido como subprotocolo. Se recomienda usar la cadena de conexión proporcionada por Azure Portal. Configuración Se recomienda encrypt=true, porque habilita el cifrado SSL de la conexión JDBC. Si user y password se establecen por separado, no es necesario que los incluya en la dirección URL.
jdbcDriver	No	Determinado por el subprotocolo de la dirección URL de JDBC	Nombre de clase del controlador JDBC que se usará. Esta clase debe estar en la ruta de clases. En la mayoría de los casos, no debería ser necesario especificar esta opción, ya que el subprotocolo de la dirección URL de JDBC debe determinar automáticamente el nombre de clase del controlador adecuado. La variante jdbc_driver admitida previamente está en desuso y se omitirá en las versiones futuras. En su lugar, use el nombre en una mezcla de mayúsculas y minúsculas.
tempDir	Sí	Sin valor predeterminado	Identificador URI abfss. Se recomienda usar un contenedor de Blob Storage dedicado para la instancia de Azure Synapse. La variante tempdir admitida previamente está en desuso y se omitirá en las versiones futuras. En su lugar, use el nombre en una mezcla de mayúsculas y minúsculas. No puede usar una ubicación externa definida en Unity Catalog como ubicación tempDir.
tempCompression	No	SNAPPY	Algoritmo de compresión que se va a usar para codificar o descodificar temporalmente tanto mediante Spark como Azure Synapse. Actualmente, los valores admitidos son UNCOMPRESSED, SNAPPY y GZIP.
forwardSparkAzureStorageCredentials	No	false	Si es true, la biblioteca detecta automáticamente las credenciales de clave de acceso de la cuenta de almacenamiento que Spark utiliza para conectarse al contenedor de Blob Storage y reenvía esas credenciales a Azure Synapse a través de JDBC. Estas credenciales se envían como parte de la consulta de JDBC. Por lo tanto, se recomienda encarecidamente habilitar el cifrado SSL de la conexión JDBC cuando use esta opción. Al configurar la autenticación de almacenamiento, debe establecer exactamente una de las opciones useAzureMSI y forwardSparkAzureStorageCredentials en true. Como alternativa, puede establecer enableServicePrincipalAuth en true y usar la entidad de servicio tanto para la autenticación de almacenamiento como JDBC. La opción forwardSparkAzureStorageCredentials no admite la autenticación en el almacenamiento mediante una identidad de servicio administrada o una entidad de servicio. Solo se admite la clave de acceso de la cuenta de almacenamiento. La variante forward_spark_azure_storage_credentials admitida previamente está en desuso y se omitirá en las versiones futuras. En su lugar, use el nombre en una mezcla de mayúsculas y minúsculas.
useAzureMSI	No	false	Si es true, la biblioteca especificará IDENTITY = 'Managed Service Identity' y ningún SECRET para las credenciales con ámbito de base de datos que crea. Al configurar la autenticación de almacenamiento, debe establecer exactamente una de las opciones useAzureMSI y forwardSparkAzureStorageCredentials en true. Como alternativa, puede establecer enableServicePrincipalAuth en true y usar la entidad de servicio tanto para la autenticación de almacenamiento como JDBC.
enableServicePrincipalAuth	No	false	Si es true, la biblioteca usará las credenciales de entidad de servicio proporcionadas para conectarse a la cuenta de Azure Storage y a Azure Synapse Analytics a través de JDBC. Si forward_spark_azure_storage_credentials o useAzureMSI se establece en true, esa opción tendría prioridad sobre la entidad de servicio en la autenticación del almacenamiento.
tableOptions	No	CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN	Cadena que se usa para especificar las opciones de tabla al crear la tabla de Azure Synapse establecida a través de dbTable. Esta cadena se pasa literalmente a la cláusula WITH de la instrucción SQL CREATE TABLE que se emite en Azure Synapse. La variante table_options admitida previamente está en desuso y se omitirá en las versiones futuras. En su lugar, use el nombre en una mezcla de mayúsculas y minúsculas.
preActions	No	Sin valor predeterminado (cadena vacía)	Lista separada por ; de los comandos SQL que se ejecutarán en Azure Synapse antes de escribir datos en la instancia de Azure Synapse. Estos comandos SQL deben ser comandos válidos aceptados por Azure Synapse. Si se produce un error con cualquiera de estos comandos, se tratará como un error y no se ejecutará la operación de escritura.
postActions	No	Sin valor predeterminado (cadena vacía)	Lista separada por ; de los comandos SQL que se ejecutarán en Azure Synapse después de que el conector escribe correctamente datos en la instancia de Azure Synapse. Estos comandos SQL deben ser comandos válidos aceptados por Azure Synapse. Si se produce un error con cualquiera de estos comandos, se tratará como un error y recibirá una excepción después de que los datos se escriban correctamente en la instancia de Azure Synapse.
maxStrLength	No	256	StringType en Spark se asigna al tipo NVARCHAR(maxStrLength) en Azure Synapse. Puede usar maxStrLength para establecer la longitud de cadena de todas las columnas de tipo NVARCHAR(maxStrLength) que se encuentran en la tabla con el nombre dbTable en Azure Synapse. La variante maxstrlength admitida previamente está en desuso y se omitirá en las versiones futuras. En su lugar, use el nombre en una mezcla de mayúsculas y minúsculas.
applicationName	No	Databricks-User-Query	Etiqueta de la conexión para cada consulta. Si el valor no se especifica o es una cadena vacía, se agrega el valor predeterminado de la etiqueta a la dirección URL de JDBC. El valor predeterminado impide que la herramienta de supervisión de bases de datos de Azure genere alertas falsas de inyección de código SQL con relación a consultas.
maxbinlength	No	Sin valor predeterminado	Controla la longitud de las columnas BinaryType. Este parámetro se traduce como VARBINARY(maxbinlength).
identityInsert	No	false	Establecer este valor en true habilita el modo IDENTITY_INSERT, que inserta un valor proporcionado por DataFrame en la columna de identidad de la tabla de Azure Synapse. Consulte Inserción explícita de valores en una columna IDENTITY.
externalDataSource	No	Sin valor predeterminado	Origen de datos externo aprovisionado previamente para leer datos de Azure Synapse. Un origen de datos externo solo se puede usar con PolyBase y quita el requisito del permiso CONTROL, ya que el conector no necesita crear una credencial con ámbito y un origen de datos externo para cargar datos. Para ver un ejemplo de uso y la lista de permisos necesarios al usar un origen de datos externo, consulte Permisos de Azure Synapse requeridos para PolyBase con la opción de origen de datos externo.
maxErrors	No	0	Número máximo de filas que se pueden rechazar durante las lecturas y escrituras antes de que se cancele la operación de carga. Se omitirán las filas rechazadas. Por ejemplo, si dos de cada diez registros tienen errores, solo se procesarán ocho registros. Consulte REJECT_VALUE documentación de CREATE EXTERNAL TABLE y MAXERRORS en COPY.
inferTimestampNTZType	No	false	Si es true, los valores de tipo TIMESTAMP de Azure Synapse se interpretan como TimestampNTZType (marca de tiempo sin zona horaria) durante las lecturas. De lo contrario, todas las marcas de tiempo se interpretan como TimestampType, independientemente del tipo de la tabla de Azure Synapse subyacente.

Nota:

• tableOptions, preActions, postActions y maxStrLength solo son pertinentes al escribir datos de Azure Databricks en una tabla nueva de Azure Synapse.
• Si bien los nombres de las opciones del origen de datos no distinguen mayúsculas de minúsculas, se recomienda que los especifique en una mezcla de mayúsculas y minúsculas.

Inserción de consultas en Azure Synapse

El conector de Azure Synapse implementa un conjunto de reglas de optimización para insertar los operaciones siguientes en Azure Synapse:

• Filter
• Project
• Limit

Los operadores Project y Filter admiten las expresiones siguientes:

• La mayoría de operadores lógicos booleanos
• Comparaciones
• Operaciones aritméticas básicas
• Conversiones numéricas y de cadena

En el caso del operador Limit, la inserción solo se admite cuando no hay ninguna ordenación especificada. Por ejemplo:

SELECT TOP(10) * FROM table, pero no SELECT TOP(10) * FROM table ORDER BY col.

Nota:

El conector de Azure Synapse no insertar expresiones que operan en cadenas, fechas o marcas de tiempo.

La inserción de consultas integrada con el conector de Azure Synapse está habilidad de manera predeterminada. Si desea deshabilitarla, establezca spark.databricks.sqldw.pushdown en false.

Administración de datos temporales

El conector de Azure Synapse no elimina los archivos temporales que crea en el contenedor de almacenamiento de Azure. Databricks recomienda eliminar periódicamente estos archivos temporales que se encuentran en la ubicación tempDir suministrada por el usuario.

Para facilitar la limpieza de los datos, el conector de Azure Synapse no almacena los archivos de datos directamente en tempDir, sino que crea un subdirectorio con el formato <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Puede configurar trabajos periódicos (con la característica trabajos de Azure Databricks o de otro modo) a fin de eliminar recursivamente los subdirectorios anteriores a un umbral determinado (por ejemplo, 2 días), con el supuesto de que no puede haber trabajos de Spark en ejecución por más tiempo que lo indicado en dicho umbral.

Una alternativa más sencilla es quitar periódicamente todo el contenedor y crear uno con el mismo nombre. Esto requiere que utilice un contenedor dedicado para los datos temporales que genera el conector de Azure Synapse, además de que pueda encontrar una ventana de tiempo en la que pueda garantizar que no hay ninguna consulta en ejecución que implique al conector.

Administración de objetos temporales

El conector de Azure Synapse automatiza la transferencia de datos entre un clúster de Azure Databricks y una instancia de Azure Synapse. Para leer datos de una consulta o una tabla de Azure Synapse o para escribir datos en una tabla de Azure Synapse, el conector de Azure Synapse crea objetos temporales, incluidos DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMAT y EXTERNAL TABLE en segundo plano. Estos objetos solo existen durante el trabajo de Spark correspondiente y se quitan automáticamente.

Cuando un clúster ejecuta una consulta con el conector de Azure Synapse, si el proceso del controlador de Spark se bloquea o se reinicia por la fuerza o si el clúster se termina o reinicia de manera forzosa, es posible que no se quiten los objetos temporales. A fin de facilitar la identificación y eliminación manual de estos objetos, el conector de Azure Synapse antepone un prefijo a los nombres de todos los objetos temporales intermedios creados en la instancia de Azure Synapse con una etiqueta con el formato tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

Se recomienda buscar periódicamente objetos filtrados mediante consultas como las siguientes:

• SELECT * FROM sys.database_scoped_credentials WHERE name LIKE 'tmp_databricks_%'
• SELECT * FROM sys.external_data_sources WHERE name LIKE 'tmp_databricks_%'
• SELECT * FROM sys.external_file_formats WHERE name LIKE 'tmp_databricks_%'
• SELECT * FROM sys.external_tables WHERE name LIKE 'tmp_databricks_%'