Consultar dados no Azure Synapse Analytics

Artigo
03/01/2024

Você pode acessar o Azure Sinapse no Azure Databricks usando o conector do Azure Synapse, que usa a instrução COPY no Azure Synapse para transferir grandes volumes de dados com eficiência entre um cluster do Azure Databricks e uma instância do Azure Synapse usando uma conta de armazenamento do Azure Data Lake Storage Gen2 para preparo temporário.

Observação

Você pode preferir a Federação do Lakehouse para gerenciar consultas nos dados do Azure Synapse ou do Azure Data Warehouse. Veja O que é Lakehouse Federation.

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

COPYestá disponível somente em instâncias do Azure Data Lake Storage Gen2. Se você estiver procurando detalhes sobre como trabalhar com o Polybase, consulte Conectar o Azure Databricks e 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 do protocolo SSL para todos os dados enviados entre o driver do 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

Os locais externos definidos no Unity Catalog não são suportados como locais tempDir.

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

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 do Spark para a conta de armazenamento do Azure
Azure Synapse para a conta de armazenamento do Azure

Configurar acesso ao armazenamento do Azure

Tanto o Azure Databricks quanto o Synapse precisam de acesso privilegiado a uma conta de armazenamento do Azure para serem usados para 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 os dois serviços realizando um dos seguintes procedimentos:

Usar a chave de conta e o segredo para a conta de armazenamento e definir forwardSparkAzureStorageCredentials como true. Consulte Definir as propriedades do Spark para configurar as credenciais do Azure para acessar o armazenamento do Azure.
Usar o Azure Data Lake Storage Gen2 com a autenticação OAuth 2.0 e defina enableServicePrincipalAuth como true. Consulte Configurar a conexão do Azure Databricks ao Synapse com o OAuth 2.0 com uma entidade de serviço.
Configure sua instância do Azure Synapse para ter uma identidade de serviço gerenciado e defina useAzureMSI como true.

Permissões de acesso necessárias do Azure Synapse

Como ele usa COPY em segundo plano, o conector do Azure Synapse exige que o usuário da 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 gravações 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 ALTER ON SCHEMA :: dbo

Configurações de rede

Se você configurar um firewall no Azure Synapse, será preciso definir as configurações de rede para permitir que o Azure Databricks alcance o Azure Synapse. Primeiro, verifique se o 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 com sua conta do Synapse. Confira Regras de firewall de IP do Azure Synapse Analytics.

Configurar a conexão do Azure Databricks ao 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 as credenciais da entidade de serviço para acessar uma conta de armazenamento do Azure, confira Conectar-se ao Azure Data Lake Storage Gen2 e ao Armazenamento de Blobs. É preciso definir a opção enableServicePrincipalAuth como true na configuração da conexão Referência de opções de conector do Synapse do Azure Databricks a fim de habilitar o conector para se autenticar em uma entidade 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 da entidade de serviço para a conta de armazenamento e as credenciais da entidade de serviço opcionais para o Azure 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 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 Synapse do Azure Databricks

O OPTIONS fornecido no Spark SQL dá suporte às seguintes configurações:

Parâmetro	Obrigatório	Padrão	Observaçõ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`	No	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`	No	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. Configuração `encrypt=true` é altamente recomendável, 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`	No	Determinado pelo subprotocolo da URL do 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 apropriado do driver deve ser determinado automaticamente pelo subprotocolo da URL do 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 um local externo definido no Unity Catalog como um local `tempDir`.
`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`	No	false	Se for `true`, a biblioteca descobrirá automaticamente as credenciais da chave de acesso da conta de armazenamento que o Spark está usando para se conectar ao contêiner do armazenamento de blobs e encaminhará essas credenciais para o Azure Synapse por meio do 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` como `true`. Como alternativa, você pode definir `enableServicePrincipalAuth` para `true` e usar a entidade de serviço para autenticação de armazenamento e JDBC. A opção `forwardSparkAzureStorageCredentials` não dá suporte à autenticação no armazenamento usando uma identidade de serviço gerenciado ou uma entidade 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`	No	false	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` como `true`. Como alternativa, você pode definir `enableServicePrincipalAuth` para `true` e usar a entidade de serviço para autenticação de armazenamento e JDBC.
`enableServicePrincipalAuth`	Não	false	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 definido como `true`, essa opção terá precedência sobre a entidade de serviço na autenticação de 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`	No	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`	No	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 um desses comandos falhar, ele será tratado como um erro e você receberá uma exceção depois que os dados forem gravados com êxito na instância do Azure Synapse.
`maxStrLength`	No	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 colunas do tipo `NVARCHAR(maxStrLength)` 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`	No	`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 Monitoramento de BD do Azure gere alertas de injeção de SQL falsos em consultas.
`maxbinlength`	No	Nenhum padrão	Controle o comprimento das colunas `BinaryType`. Esse parâmetro é convertido como `VARBINARY(maxbinlength)`.
`identityInsert`	No	false	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`	No	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 específico 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`	No	0	O número máximo de linhas que podem ser rejeitadas durante leituras e gravações antes do cancelamento da operação de carregamento. As linhas rejeitadas serão ignoradas. Por exemplo, quando dois registros entre dez estão com erros, apenas oito deles são processados. Confira a documentação de REJECT_VALUE em CREATE EXTERNAL TABLE e a documentação de MAXERRORS em COPY.
`inferTimestampNTZType`	No	false	Se for `true`, os valores do tipo Azure Synapse `TIMESTAMP` serão interpretados como `TimestampNTZType` (carimbo de data/hora sem fuso horário) durante as leituras. Caso contrário, todos os carimbos de data/hora são interpretados como `TimestampType` independentemente do tipo na tabela Azure Synapse subjacente.

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 os arquivos temporários na localização tempDir fornecida pelo 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 trabalhos do Azure Databricks ou de outra forma) para excluir recursivamente os subdiretórios com mais de um limite especificado (por exemplo, dois dias), com a suposição de que não pode haver trabalhos do Spark em execução por mais tempo do 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 só existem durante a duração do trabalho do Spark correspondente e são removidos 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_%'

Consultar dados no Azure Synapse Analytics

Sintaxe de exemplo para o Synapse

Scala

Python

SQL

R

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

Configurar acesso ao armazenamento do Azure

Permissões de acesso necessárias do Azure Synapse

Configurações de rede

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

ini

Scala

Python

R

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

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

Pushdown de consulta no Azure Synapse

Gerenciamento de dados temporários

Gerenciamento de objetos temporários

Recursos adicionais