Consultar dados no Azure Synapse Analytics

2025-05-10

Você pode acessar o Azure Synapse a partir do Azure Databricks usando o conector do próprio Azure Synapse, que utiliza a instrução COPY para transferir grandes volumes de dados eficientemente entre um cluster do Azure Databricks e uma instância do Azure Synapse, utilizando uma conta de armazenamento do Azure Data Lake Storage para estágio temporário.

Importante

A documentação da federação de consulta herdada foi desativada e pode não ser atualizada. As configurações mencionadas neste conteúdo não são oficialmente endossadas ou testadas pelo Databricks. Se Federação Lakehouse der suporte ao seu banco de dados de origem, Databricks recomenda usá-lo.

O Azure Synapse Analytics é um data warehouse corporativo baseado em nuvem que aproveita o MPP (processamento paralelo maciço) para executar rapidamente consultas complexas em petabytes de dados.

Importante

Esse conector é para uso somente com instâncias do Pool Dedicado do Synapse e não é compatível com outros componentes do Synapse.

Observação

COPY está disponível somente em instâncias do Azure Data Lake Storage. Se você estiver procurando detalhes sobre como trabalhar com o Polybase, consulte Conectar o Azure Databricks e o Azure Synapse com o PolyBase (herdado).

Sintaxe de exemplo para o Synapse

Você pode consultar o Synapse no Scala, Python, SQL e R. Os exemplos de código a seguir usam chaves de conta de armazenamento e encaminham as credenciais de armazenamento do Azure Databricks para o Synapse.

Observação

Use a cadeia de conexão fornecida pelo portal do Azure, que habilita a criptografia SSL (Secure Sockets Layer) para todos os dados enviados entre o driver Spark e a instância do Azure Synapse por meio da conexão JDBC. Para verificar se a criptografia SSL está habilitada, procure encrypt=true na cadeia de conexão.

Importante

Locais externos definidos no Unity Catalog não são compatíveis como tempDir locais.

O Databricks recomenda usar o fluxo de autenticação mais seguro disponível. O fluxo de autenticação descrito neste exemplo traz riscos que não estão presentes em outros fluxos. Só deve utilizar este fluxo quando outros fluxos mais seguros, como identidades geridas, não forem viáveis.

Scala (linguagem de programação)


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

Pitão


# 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>")

Como funciona a autenticação entre o Azure Databricks e o Synapse?

O conector do Azure Synapse usa três tipos de conexões de rede:

Driver do Spark para o Azure Synapse
Cluster Spark para Conta de Armazenamento do Azure
Azure Synapse para a conta de armazenamento do Azure

Configurando o acesso ao armazenamento do Azure

O Azure Databricks e o Synapse precisam de acesso privilegiado a uma conta de armazenamento do Azure para serem usados para o armazenamento de dados temporário.

O Azure Synapse não dá suporte ao uso de SAS para acesso à conta de armazenamento. Você pode configurar o acesso para ambos os serviços fazendo um dos seguintes procedimentos:

Use a chave e o segredo da conta de armazenamento e defina forwardSparkAzureStorageCredentials como true. Consulte Definir propriedades do Spark para configurar as credenciais do Azure para acessar o armazenamento do Azure.
Use o Azure Data Lake Storage com autenticação OAuth 2.0 e defina enableServicePrincipalAuth como true. Consulte Configuração da conexão do Azure Databricks com o Synapse usando OAuth 2.0 com um principal de serviço.
Configure sua instância do Azure Synapse para ter uma Identidade de Serviço Gerenciada e definida useAzureMSI como true.

Permissões necessárias do Azure Synapse

Como ele usa COPY em segundo plano, o conector do Azure Synapse exige que o usuário de conexão JDBC tenha permissão para executar os seguintes comandos na instância conectada do Azure Synapse:

COPY INTO

Se a tabela de destino não existir no Azure Synapse, a permissão para executar o seguinte comando será necessária, além do comando acima:

CREATE TABLE

A tabela a seguir resume as permissões necessárias para operações de gravação com COPY:

Permissões (inserir em uma tabela existente)	Permissões (inserir em uma nova tabela)
ADMINISTRAR OPERAÇÕES EM LOTE DO BANCO DE DADOS INSERT	ADMINISTRAR OPERAÇÕES EM LOTE DO BANCO DE DADOS INSERT CREATE TABLE ALTERAR EM SCHEMA :: dbo

Configurações de rede

Se você configurar um firewall no Azure Synapse, deverá definir as configurações de rede para permitir que o Azure Databricks chegue ao Azure Synapse. Primeiro, verifique se seu workspace do Azure Databricks está implantado em sua própria rede virtual após implantar o Azure Databricks em sua rede virtual do Azure (injeção de VNet). Em seguida, você pode configurar regras de firewall de IP no Azure Synpase para permitir conexões de suas sub-redes para sua conta do Synapse. Consulte as regras de firewall de IP do Azure Synapse Analytics.

Configurar a conexão do Azure Databricks com o Synapse com o OAuth 2.0 com uma entidade de serviço

Você pode se autenticar no Azure Synapse Analytics usando uma entidade de serviço com acesso à conta de armazenamento subjacente. Para obter mais informações sobre como usar credenciais de entidade de serviço para acessar uma conta de armazenamento do Azure, consulte Connect to Azure Data Lake Storage and Blob Storage. Você deve definir a opção enableServicePrincipalAuth como true na configuração de conexão da referência de opções do conector do Azure Databricks Synapse para habilitar o conector a autenticar-se com um principal de serviço.

Opcionalmente, você pode usar uma entidade de serviço diferente para a conexão do Azure Synapse Analytics. O exemplo a seguir configura as credenciais de principal de serviço para a conta de armazenamento e credenciais de principal de serviço opcionais para o 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 (linguagem de programação)

// 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>")

Pitão

# 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 salvamento compatíveis com gravações em lote

O conector do Azure Synapse dá suporte aos modos de salvamento ErrorIfExists, Ignore, Append e Overwrite, sendo ErrorIfExists o modo padrão. Para obter mais informações sobre os modos de salvamento compatíveis com o Apache Spark, confira a documentação do Spark SQL sobre modos de salvamento.

Referência de opções do conector do Azure Databricks Synapse

Os OPTIONS fornecidos no Spark SQL dão suporte às seguintes configurações:

Parâmetro	Obrigatório	Padrão	Anotações
`dbTable`	Sim, a menos que `query` seja especificado	Nenhum padrão	A tabela necessária para criação ou leitura no Azure Synapse. Esse parâmetro é necessário quando os dados são salvos novamente no Azure Synapse. Use também `{SCHEMA NAME}.{TABLE NAME}` para acessar uma tabela em determinado esquema. Se o nome do esquema não for fornecido, o esquema padrão associado ao usuário do JDBC será usado. A variante `dbtable` anteriormente compatível foi preterida e será ignorada em versões futuras. Em vez disso, use o nome em minúsculas concatenadas.
`query`	Sim, a menos que `dbTable` seja especificado	Nenhum padrão	A consulta a ser lida no Azure Synapse. Para as tabelas referenciadas na consulta, use também `{SCHEMA NAME}.{TABLE NAME}` para acessar uma tabela em determinado esquema. Se o nome do esquema não for fornecido, o esquema padrão associado ao usuário do JDBC será usado.
`user`	Não	Nenhum padrão	O nome de usuário do Azure Synapse. Precisa ser usado em conjunto com a opção `password`. Só poderá ser usado se o usuário e a senha não forem transmitidos na URL. A transmissão dos dois resultará em um erro.
`password`	Não	Nenhum padrão	A senha do Azure Synapse. Precisa ser usado em conjunto com a opção `user`. Só poderá ser usado se o usuário e a senha não forem transmitidos na URL. A transmissão dos dois resultará em um erro.
`url`	Sim	Nenhum padrão	Uma URL do JDBC com `sqlserver` definido como o subprotocolo. Recomendamos usar a cadeia de conexão fornecida pelo portal do Azure. A configuração `encrypt=true` é altamente recomendada, pois habilita a criptografia SSL da conexão JDBC. Se `user` e `password` forem definidos separadamente, você não precisará incluí-los na URL.
`jdbcDriver`	Não	Determinado pelo subprotocol da URL JDBC	O nome de classe do driver JDBC a ser usado. Essa classe precisa estar no caminho de classe. Na maioria dos casos, não deve ser necessário especificar essa opção, pois o nome de classe de driver apropriado deve ser determinado automaticamente pelo subprotocol da URL JDBC. A variante `jdbc_driver` anteriormente compatível foi preterida e será ignorada em versões futuras. Em vez disso, use o nome em minúsculas concatenadas.
`tempDir`	Sim	Nenhum padrão	Um URI `abfss`. Recomendamos que você use um contêiner dedicado do armazenamento de blobs para o Azure Synapse. A variante `tempdir` anteriormente compatível foi preterida e será ignorada em versões futuras. Em vez disso, use o nome em minúsculas concatenadas. Você não pode usar uma localidade externa definida no Catálogo do Unity como uma `tempDir` localidade.
`tempCompression`	Não	`SNAPPY`	O algoritmo de compactação a ser usado para codificar/decodificar arquivos temporários pelo Spark e pelo Azure Synapse. Os valores atualmente compatíveis são: `UNCOMPRESSED`, `SNAPPY` e `GZIP`.
`forwardSparkAzureStorageCredentials`	Não	falso	Se `true`, a biblioteca descobre automaticamente as credenciais de chave de acesso da conta de armazenamento que o Spark está usando para conectar-se ao contêiner de armazenamento de blobs e encaminha essas credenciais para o Azure Synapse por JDBC. Essas credenciais são enviadas como parte da consulta do JDBC. Portanto, é altamente recomendável que você habilite a criptografia SSL da conexão JDBC ao usar essa opção. Ao configurar a autenticação de armazenamento, você deve definir exatamente um de `useAzureMSI` e `forwardSparkAzureStorageCredentials` para `true`. Como alternativa, você pode definir `enableServicePrincipalAuth` para `true` e usar a entidade de serviço para a autenticação tanto de JDBC quanto de armazenamento. A `forwardSparkAzureStorageCredentials` opção não oferece suporte à autenticação no armazenamento usando uma identidade de serviço gerenciada ou um principal de serviço. Há suporte apenas para a chave de acesso da conta de armazenamento. A variante `forward_spark_azure_storage_credentials` anteriormente compatível foi preterida e será ignorada em versões futuras. Em vez disso, use o nome em minúsculas concatenadas.
`useAzureMSI`	Não	falso	Se ele for `true`, a biblioteca especificará `IDENTITY = 'Managed Service Identity'` e nenhum `SECRET` para as credenciais no escopo do banco de dados criadas por ela. Ao configurar a autenticação de armazenamento, você deve definir exatamente um de `useAzureMSI` e `forwardSparkAzureStorageCredentials` para `true`. Como alternativa, você pode definir `enableServicePrincipalAuth` para `true` e usar a entidade de serviço para a autenticação tanto de JDBC quanto de armazenamento.
`enableServicePrincipalAuth`	Não	falso	Se ele for `true`, a biblioteca usará as credenciais da entidade de serviço fornecidas para se conectar à conta de armazenamento do Azure e ao Azure Synapse Analytics por meio do JDBC. Se `forward_spark_azure_storage_credentials` ou `useAzureMSI` estiver configurado como `true`, essa opção terá precedência sobre a autenticação da entidade de serviço no armazenamento.
`tableOptions`	Não	`CLUSTERED COLUMNSTORE INDEX`, `DISTRIBUTION = ROUND_ROBIN`	Uma cadeia de caracteres usada para especificar opções de tabela ao criar a tabela do Azure Synapse definida por meio de `dbTable`. Essa cadeia de caracteres é transmitida literalmente à cláusula `WITH` da instrução SQL `CREATE TABLE` que é emitida no Azure Synapse. A variante `table_options` anteriormente compatível foi preterida e será ignorada em versões futuras. Em vez disso, use o nome em minúsculas concatenadas.
`preActions`	Não	Sem padrão (cadeia de caracteres vazia)	Uma lista separada por `;` de comandos SQL a serem executados no Azure Synapse antes da gravação de dados na instância do Azure Synapse. Esses comandos SQL precisam ser comandos válidos aceitos pelo Azure Synapse. Se um desses comandos falhar, ele será tratado como um erro e a operação de gravação não será executada.
`postActions`	Não	Sem padrão (cadeia de caracteres vazia)	Uma lista separada por `;` de comandos SQL a serem executados no Azure Synapse depois que o conector gravar os dados com êxito na instância do Azure Synapse. Esses comandos SQL precisam ser comandos válidos aceitos pelo Azure Synapse. Se algum desses comandos falhar, ele será tratado como um erro e você obterá uma exceção depois que os dados forem gravados com êxito na instância do Azure Synapse.
`maxStrLength`	Não	256	`StringType` no Spark é mapeado para o tipo `NVARCHAR(maxStrLength)` no Azure Synapse. Você pode usar `maxStrLength` para definir o comprimento da cadeia de caracteres para todas as `NVARCHAR(maxStrLength)` colunas de tipo que estão na tabela com o nome `dbTable` no Azure Synapse. A variante `maxstrlength` anteriormente compatível foi preterida e será ignorada em versões futuras. Em vez disso, use o nome em minúsculas concatenadas.
`applicationName`	Não	`Databricks-User-Query`	A marca da conexão para cada consulta. Se um valor não for especificado ou o valor for uma cadeia de caracteres vazia, o valor padrão da marca será adicionado à URL do JDBC. O valor padrão impede que a ferramenta de monitoramento de banco de dados do Azure gere alertas de injeção de SQL falsos em consultas.
`maxbinlength`	Não	Nenhum padrão	Controle o comprimento das colunas `BinaryType`. Esse parâmetro é convertido como `VARBINARY(maxbinlength)`.
`identityInsert`	Não	falso	A configuração como `true` habilita o modo `IDENTITY_INSERT`, que insere um valor fornecido pelo DataFrame na coluna de identidade da tabela do Azure Synapse. Confira Como inserir explicitamente os valores em uma coluna IDENTITY.
`externalDataSource`	Não	Nenhum padrão	Uma fonte de dados externa previamente provisionada para ler dados do Azure Synapse. Uma fonte de dados externa só pode ser usada com o PolyBase e remove o requisito de permissão CONTROL porque o conector não precisa criar uma credencial com escopo e uma fonte de dados externa para carregar dados. Para ver exemplos de uso e a lista de permissões necessárias ao usar uma fonte de dados externa, confira Permissões do Azure Synapse necessárias para o PolyBase com a opção de fonte de dados externa.
`maxErrors`	Não	0	O número máximo de linhas que podem ser rejeitadas durante leituras e gravações antes que a operação de carregamento seja cancelada. As linhas rejeitadas serão ignoradas. Por exemplo, quando dois registros entre dez estão com erros, apenas oito deles são processados. Consulte a documentação de REJECT_VALUE na CREATE EXTERNAL TABLE e a de MAXERRORS na COPY.
`inferTimestampNTZType`	Não	falso	Se `true`, os valores do tipo Azure Synapse `TIMESTAMP` são interpretados como `TimestampNTZType` (timestamp sem fuso horário) nas leituras. Caso contrário, todos os carimbos de data/hora são interpretados como `TimestampType` independentemente do tipo na tabela subjacente do Azure Synapse.

Observação

tableOptions, preActions, postActions e maxStrLength só são relevantes na gravação de dados do Azure Databricks para uma nova tabela do Azure Synapse.
Embora todos os nomes de opções de fonte de dados não diferenciem maiúsculas de minúsculas, recomendamos especificá-los em “minúsculas concatenadas” para maior clareza.

Pushdown de consulta no Azure Synapse

O conector do Azure Synapse implementa um conjunto de regras de otimização para efetuar pushdown dos seguintes operadores para o Azure Synapse:

Filter
Project
Limit

Os operadores Project e Filter dão suporte às seguintes expressões:

A maioria dos operadores lógicos boolianos
Comparações
Operadores aritméticos básicos
Conversões numéricas e de cadeia de caracteres

Para o operador Limit, só há suporte para o pushdown quando não há nenhuma ordenação especificada. Por exemplo:

SELECT TOP(10) * FROM table, mas não SELECT TOP(10) * FROM table ORDER BY col.

Observação

O conector do Azure Synapse não efetua pushdown de expressões que operam em cadeias de caracteres, datas ou carimbos de data/hora.

O pushdown de consulta criado com o conector do Azure Synapse está habilitado por padrão. Você pode desabilitá-lo definindo spark.databricks.sqldw.pushdown como false.

Gerenciamento de dados temporários

O conector do Azure Synapse não exclui os arquivos temporários que ele cria no contêiner de armazenamento do Azure. O Databricks recomenda que você exclua periodicamente arquivos temporários no local fornecido pelo tempDir usuário.

Para facilitar a limpeza dos dados, o conector do Azure Synapse não armazena arquivos de dados diretamente em tempDir, mas cria um subdiretório do formato <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Você pode configurar trabalhos periódicos (usando o recurso Jobs do Lakeflow ou de outra forma) para excluir recursivamente quaisquer subdiretórios que sejam mais antigos que um determinado limite (por exemplo, 2 dias), com a suposição de que não pode haver trabalhos do Spark em execução mais longos que esse limite.

Uma alternativa mais simples é remover periodicamente todo o contêiner e criar outro com o mesmo nome. Isso exige que você use um contêiner dedicado para os dados temporários produzidos pelo conector do Azure Synapse e que você possa encontrar uma janela de tempo na qual possa garantir que nenhuma consulta que envolva o conector esteja em execução.

Gerenciamento de objetos temporários

O conector do Azure Synapse automatiza a transferência de dados entre um cluster do Azure Databricks e uma instância do Azure Synapse. Para ler dados de uma tabela do Azure Synapse ou consultar ou gravar dados em uma tabela do Azure Synapse, o conector do Azure Synapse cria objetos temporários, incluindo DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMAT e EXTERNAL TABLE nos bastidores. Esses objetos vivem apenas durante toda a duração do trabalho do Spark correspondente e são descartados automaticamente.

Quando um cluster está executando uma consulta por meio do conector do Azure Synapse, se o processo do driver do Spark falha ou é forçado a ser reiniciado ou se o cluster é encerrado ou é forçado a ser reiniciado, os objetos temporários podem não ser removidos. Para facilitar a identificação e a exclusão manual desses objetos, o conector do Azure Synapse prefixa os nomes de todos os objetos temporários intermediários criados na instância do Azure Synapse com uma marca do formato tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

Recomendamos que você procure periodicamente objetos vazados usando consultas como as seguintes:

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_%'

Compartilhar via

Consultar dados no Azure Synapse Analytics

Sintaxe de exemplo para o Synapse

Scala (linguagem de programação)

Pitão

SQL

R

Como funciona a autenticação entre o Azure Databricks e o Synapse?

Configurando o acesso ao armazenamento do Azure

Permissões necessárias do Azure Synapse

Configurações de rede

Configurar a conexão do Azure Databricks com o Synapse com o OAuth 2.0 com uma entidade de serviço

ini

Scala (linguagem de programação)

Pitão

R

Modos de salvamento compatíveis com gravações em lote

Referência de opções do conector do Azure Databricks Synapse

Pushdown de consulta no Azure Synapse

Gerenciamento de dados temporários

Gerenciamento de objetos temporários

Comentários

Recursos adicionais