Pular para o conteúdo principal

Conectando o Databricks e o Azure Synapse com o PolyBase (legado)

important

Essa documentação foi descontinuada e pode não estar atualizada. O produto, serviço ou tecnologia mencionados neste conteúdo não são mais suportados. Consulte Consultar dados no Azure Synapse Analytics.

Databricks O senhor recomenda usar a funcionalidade default COPY com Azure Data Lake Storage Gen2 para conexões com Azure Synapse. Este artigo inclui a documentação herdada sobre o PolyBase e o armazenamento de blob.

Azure Synapse Analytics (anteriormente SQL data warehouse) é uma empresa baseada na nuvem data warehouse que aproveita o processamento massivamente paralelo (MPP) para executar rapidamente consultas complexas em petabytes de dados. Use o site Azure como um componente key de uma solução big data. Importe big data para Azure com consultas T-SQL simples do PolyBase ou instrução COPY e, em seguida, use o poder do MPP para executar análises de alto desempenho. À medida que o senhor integra e analisa, o site data warehouse se tornará a única versão da verdade com a qual sua empresa pode contar para obter percepções.

O senhor pode acessar Azure Synapse a partir de Databricks usando o conector Azure Synapse, uma implementação de fonte de dados para Apache Spark que usa o armazenamentoAzure Blob e o PolyBase ou a instrução COPY em Azure Synapse para transferir grandes volumes de dados com eficiência entre um clustering Databricks e uma instância Azure Synapse.

Tanto o clustering Databricks quanto a instância Azure Synapse acessam um contêiner de armazenamento Blob comum para trocar dados entre esses dois sistemas. Em Databricks, o trabalho Apache Spark é acionado pelo conector Azure Synapse para ler e gravar dados no contêiner de armazenamento Blob. No lado do Azure Synapse, as operações de carregamento e descarregamento de dados realizadas pelo PolyBase são acionadas pelo conector do Azure Synapse por meio de JDBC. Em Databricks Runtime 7.0 e acima, COPY é usado por default para carregar dados em Azure Synapse pelo conector Azure Synapse por meio de JDBC.

nota

COPY está disponível apenas nas instâncias do Azure Synapse Gen2, que oferecem melhor desempenho. Se seu banco de dados ainda usa instâncias Gen1, recomendamos que você migre o banco de dados para Gen2.

O conector do Azure Synapse é mais adequado para ETL do que para consultas interativas, porque cada execução de consulta pode extrair grandes quantidades de dados para o armazenamento Blob. Se o senhor planeja realizar várias consultas na mesma tabela Azure Synapse, recomendamos que salve a extração de dados em um formato como Parquet.

Requisitos​

Um Azure Synapse mestre de banco de dados key.

Autenticação​

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

  • Driver Spark para o Azure Synapse
  • Spark driver e executor para Azure storage account
  • Azure Synapse para Azure storage account
                                 ┌─────────┐
      ┌─────────────────────────>│ STORAGE │<────────────────────────┐
      │   Storage acc key /      │ ACCOUNT │  Storage acc key /      │
      │   Managed Service ID /   └─────────┘  OAuth 2.0 /            │
      │                               │                              │
      │                               │                              │
      │                               │ Storage acc key /            │
      │                               │ OAuth 2.0 /                  │
      │                               │                              │
      v                               v                       ┌──────v────┐
┌──────────┐                      ┌──────────┐                │┌──────────┴┐
│ Synapse  │                      │  Spark   │                ││ Spark     │
│ Analytics│<────────────────────>│  Driver  │<───────────────>│ Executors │
└──────────┘  JDBC with           └──────────┘    Configured   └───────────┘
              username & password /                in Spark

As seções a seguir descrevem as opções de configuração de autenticação de cada conexão.

Driver Spark para o Azure Synapse​

O driver Spark pode se conectar ao Azure Synapse usando JDBC com um nome de usuário e senha ou OAuth 2.0 com uma entidade de serviço para autenticação.

Nome de usuário e senha​

Recomendamos que o senhor use a conexão strings fornecida pelo portal Azure para ambos os tipos de autenticação, o que permite a criptografia Secure Sockets Layer (SSL) para todos os dados enviados entre o driver Spark e a instância Azure Synapse por meio da conexão JDBC. Para verificar se a criptografia SSL está ativada, o senhor pode procurar por encrypt=true nas cadeias de conexão.

Para permitir que o driver Spark acesse Azure Synapse, recomendamos que o senhor defina Allow Azure serviço and recurso to access this workspace como ON no painel Networking (Rede) em Security (Segurança) do Azure Synapse workspace por meio do portal Azure. Essa configuração permite comunicações de todos os endereços IP do Azure e de todas as sub-redes do Azure, o que permite que os drivers do Spark alcancem a instância do Azure Synapse.

OAuth 2.0 com uma entidade de serviço​

O senhor pode se autenticar em Azure Synapse Analytics usando uma entidade de serviço com acesso ao armazenamento subjacente account. Para obter mais informações sobre como usar credenciais de entidade de serviço para acessar um armazenamento Azure account, consulte Conectar-se a Azure Data Lake Storage Gen2 e Blob Storage. O senhor deve definir a opção enableServicePrincipalAuth como true nos parâmetros de configuração da conexão para permitir que o conector se autentique com uma entidade de serviço.

Opcionalmente, o senhor pode usar uma entidade de serviço diferente para a conexão do Azure Synapse Analytics. Um exemplo que configura credenciais de entidade de serviço para o storage account e credenciais opcionais de entidade de serviço 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>

Spark driver e executor para storage Azure account​

O contêiner de armazenamento do Azure atua como um intermediário para armazenar dados em massa ao ler ou gravar no Azure Synapse. O Spark se conecta ao ADLS Gen2 ou ao Blob Storage usando o driver.abfss

As seguintes opções de autenticação estão disponíveis:

Os exemplos abaixo ilustram essas duas formas usando a abordagem de armazenamento account access key. O mesmo se aplica à configuração do OAuth 2.0.

Notebook configuração da sessão (preferencial)​

Usando essa abordagem, o acesso account key é definido na configuração da sessão associada ao Notebook que executa o comando. Essa configuração não afeta outros notebooks anexados ao mesmo cluster. spark é o objeto SparkSession fornecido no Notebook.

Python
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

Configuração global do Hadoop​

Essa abordagem atualiza a configuração global do Hadoop associada ao objeto SparkContext compartilhado por todos os Notebooks.

Scala
sc.hadoopConfiguration.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

Azure Synapse para storage Azure account​

Azure Synapse também se conecta a um armazenamento account durante o carregamento e o descarregamento de dados temporários.

Caso tenha configurado um account key e um segredo para o account armazenamento, o senhor pode forwardSparkAzureStorageCredentials definir true como; nesse caso, o Azure Synapse conector descobre automaticamente o account acesso key definido na configuração de sessão do Notebook ou na configuração global Hadoop e encaminha o account acesso key ao armazenamento para a Azure Synapse instância conectada, criando uma credencial temporária com Azure escopo de banco de dados.

Como alternativa, se o senhor usar o ADLS Gen2 com autenticação OAuth 2.0 ou se a instância do Azure Synapse estiver configurada para ter uma identidade de serviço gerenciado (normalmente em conjunto com uma configuração de endpoint VNet + serviço), será necessário definir useAzureMSI como true. Nesse caso, o conector especificará IDENTITY = 'Managed Service Identity' para a credencial com escopo baseado no banco de dados e não SECRET.

suporte à transmissão​

O conector Azure Synapse oferece suporte eficiente e dimensionável à gravação de transmissão estruturada para Azure Synapse, o que proporciona uma experiência consistente ao usuário com lotes de gravações, e usa PolyBase ou COPY para grandes transferências de dados entre um clustering Databricks e uma instância Azure Synapse. Semelhante às gravações de lotes, a transmissão é projetada em grande parte para ETL, fornecendo assim uma latência mais alta que pode não ser adequada para o processamento de dados tempo-real em alguns casos.

Semântica de tolerância a falhas​

Por meio do site default, a transmissão Azure Synapse oferece garantia exatamente única de ponta a ponta para a gravação de dados em uma tabela Azure Synapse, acompanhando de forma confiável o andamento da consulta usando uma combinação de local de ponto de verificação em DBFS, tabela de ponto de verificação em Azure Synapse e mecanismo de bloqueio para garantir que a transmissão possa lidar com qualquer tipo de falha, nova tentativa e reinício de consulta. Opcionalmente, o senhor pode selecionar uma semântica at-least-once menos restritiva para a transmissão Azure Synapse, definindo a opção spark.databricks.sqldw.streaming.exactlyOnce.enabled como false, caso em que poderá ocorrer duplicação de dados em caso de falhas intermitentes de conexão com Azure Synapse ou de encerramento inesperado da consulta.

Uso (lotes)​

O senhor pode usar esse conector por meio da fonte de dados API em Scala, Python, SQL e R Notebook.

Scala

// Otherwise, set up the Blob 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.
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()

Uso (transmissão)​

O senhor pode escrever uso de transmissão de dados estruturada em Scala e Python Notebook.

Scala
// Set up the Blob 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>")

// Prepare streaming source; this could be Kafka or a simple rate stream.
val df: DataFrame = spark.readStream
  .format("rate")
  .option("rowsPerSecond", "100000")
  .option("numPartitions", "16")
  .load()

// Apply some transformations to the data then use
// Structured Streaming API to continuously write the data to a table in Azure Synapse.
df.writeStream
  .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>")
  .option("checkpointLocation", "/tmp_checkpoint_location")
  .start()

Configuração​

Esta seção descreve como configurar a semântica de gravação para o conector, as permissões necessárias e diversos parâmetros de configuração.

Nesta secção:

Modos de salvamento suportados para gravações de lotes​

O conector Azure Synapse suporta os modos de salvamento ErrorIfExists, Ignore, Append e Overwrite, sendo que o modo default é ErrorIfExists. Para obter mais informações sobre os modos de salvamento suportados em Apache Spark, consulte a documentaçãoSpark SQL em Save Modes.

Modos de saída suportados para gravações de transmissão​

O conector do Azure Synapse oferece suporte aos modos de saída Append e Complete para acréscimos e agregações de registros. Para obter mais detalhes sobre os modos de saída e a matriz de compatibilidade, consulte o guia transmissão estructurada.

Escreva semântica​

nota

COPY está disponível em Databricks Runtime 7.0 e acima.

Além do PolyBase, o conector do Azure Synapse é compatível com a declaração COPY. A instrução COPY oferece uma maneira mais conveniente de carregar dados no Azure Synapse sem a necessidade de criar uma tabela externa, requer menos permissões para carregar dados e melhora o desempenho da ingestão de dados no Azure Synapse.

Por meio do default, o conector descobre automaticamente a melhor semântica de gravação (COPY quando direcionado a uma instância do Azure Synapse Gen2, caso contrário, PolyBase). Você também pode especificar a semântica de gravação com o seguinte configuração:

Scala
// Configure the write semantics for Azure Synapse connector in the notebook session conf.
spark.conf.set("spark.databricks.sqldw.writeSemantics", "<write-semantics>")

onde <write-semantics> é polybase para usar PolyBase ou copy para usar a instrução COPY.

Permissões necessárias do Azure Synapse para o PolyBase​

Quando o senhor usa o PolyBase, o conector Azure Synapse exige que o usuário da conexão JDBC tenha permissão para executar o seguinte comando na instância Azure Synapse conectada:

Como pré-requisito para o primeiro comando, o conector espera que já exista um mestre de banco de dados key para a instância Azure Synapse especificada. Caso contrário, o senhor pode criar um key usando o comando CREATE MASTER key.

Além disso, para ler o conjunto de tabelas do Azure Synapse por meio de dbTable ou tabelas referenciadas em query, o usuário JDBC deve ter permissão para acessar as tabelas necessárias do Azure Synapse. Para gravar dados de volta em uma tabela do Azure Synapse definida por meio de dbTable, o usuário JDBC deve ter permissão para gravar nessa tabela do Azure Synapse.

A tabela a seguir resume as permissões necessárias para todas as operações com o PolyBase:

Operação

Permissões

Permissões ao usar uma fonte de dados externa

lotes write

CONTROLE

Ver lotes escrever

transmissão write

CONTROLE

Ver transmissão write

Ler

CONTROLE

Veja Ler

Permissões necessárias no site Azure Synapse para o PolyBase com a opção de fonte externa de dados​

O senhor pode usar o PolyBase com uma fonte de dados externa de pré-provisionamento. Consulte o parâmetro externalDataSource em Parâmetros para obter mais informações.

Para usar o PolyBase com uma fonte de dados externa de pré-provisionamento, o conector Azure Synapse exige que o usuário da conexão JDBC tenha permissão para executar o seguinte comando na instância Azure Synapse conectada:

Para criar uma fonte de dados externa, o senhor deve primeiro criar uma credencial com escopo de banco de dados. Os links a seguir descrevem como criar uma credencial com escopo para entidade de serviço e uma fonte externa de dados para um local ABFS:

nota

O local da fonte de dados externa deve apontar para um contêiner. O conector não funcionará se o local for um diretório em um contêiner.

A tabela a seguir resume as permissões para operações de gravação do PolyBase com a opção de fonte externa de dados:

Operação

Permissões (inserir em uma tabela existente)

Permissões (inserir em uma nova tabela)

lotes write

ADMINISTER DATABASE BULK operações

INSERT

CREATE TABLE

ALTERAR QUALQUER ESQUEMA

ALTERAR QUALQUER fonte de dados EXTERNA

ALTERAR QUALQUER FORMATO DE ARQUIVO EXTERNO

ADMINISTER DATABASE BULK operações

INSERT

CREATE TABLE

ALTERAR QUALQUER ESQUEMA

ALTERAR QUALQUER fonte de dados EXTERNA

ALTERAR QUALQUER FORMATO DE ARQUIVO EXTERNO

transmissão write

ADMINISTER DATABASE BULK operações

INSERT

CREATE TABLE

ALTERAR QUALQUER ESQUEMA

ALTERAR QUALQUER fonte de dados EXTERNA

ALTERAR QUALQUER FORMATO DE ARQUIVO EXTERNO

ADMINISTER DATABASE BULK operações

INSERT

CREATE TABLE

ALTERAR QUALQUER ESQUEMA

ALTERAR QUALQUER fonte de dados EXTERNA

ALTERAR QUALQUER FORMATO DE ARQUIVO EXTERNO

A tabela a seguir resume as permissões para operações de leitura do PolyBase com a opção de fonte externa de dados:

Operação

Permissões

Ler

CREATE TABLE

ALTERAR QUALQUER ESQUEMA

ALTERAR QUALQUER fonte de dados EXTERNA

ALTERAR QUALQUER FORMATO DE ARQUIVO EXTERNO

O senhor pode usar esse conector para ler por meio da fonte de dados API em Scala, Python, SQL e R Notebook.

Scala
// Get some data from an Azure Synapse table.
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("externalDataSource", "<your-pre-provisioned-data-source>")
  .option("dbTable", "<your-table-name>")
  .load()

Permissões necessárias do Azure Synapse para a declaração COPY​

nota

Disponível em Databricks Runtime 7.0 e acima.

Quando o senhor usa a instrução COPY, o conector Azure Synapse exige que o usuário da conexão JDBC tenha permissão para executar o seguinte comando na instância Azure Synapse conectada:

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

A tabela a seguir resume as permissões para lotes e gravações de transmissão com COPY:

Operação

Permissões (inserir em uma tabela existente)

Permissões (inserir em uma nova tabela)

lotes write

ADMINISTER DATABASE BULK operações

INSERT

ADMINISTER DATABASE BULK operações

INSERT

CREATE TABLE

ALTERAR NO ESQUEMA:: dbo

transmissão write

ADMINISTER DATABASE BULK operações

INSERT

ADMINISTER DATABASE BULK operações

INSERT

CREATE TABLE

ALTERAR NO ESQUEMA:: dbo

Parâmetros​

O mapa de parâmetros ou OPTIONS fornecido no Spark SQL suporta as seguintes configurações:

Parâmetro

Obrigatório

Padrão

Notas

dbTable

Sim, a menos que query seja especificado

Não default

A tabela para criar ou ler no Azure Synapse. Esse parâmetro é necessário ao salvar dados de volta no Azure Synapse.

Você também pode usar {SCHEMA NAME}.{TABLE NAME} para acessar uma tabela em um determinado esquema. Se o nome do esquema não for fornecido, será usado o esquema default associado ao usuário JDBC.

A variante dbtable suportada anteriormente está obsoleta e será ignorada em versões futuras. Em vez disso, use o nome “estojo de camelo”.

query

Sim, a menos que dbTable seja especificado

Não default

A consulta para leitura no Azure Synapse.

Para tabelas referenciadas na consulta, você também pode usar {SCHEMA NAME}.{TABLE NAME} para acessar uma tabela em um determinado esquema. Se o nome do esquema não for fornecido, será usado o esquema default associado ao usuário JDBC.

user

Não

Não default

O nome de usuário do Azure Synapse. Deve ser usado em conjunto com a opção password. Só pode ser usado se o usuário e a senha não forem passados na URL. Passar os dois resultará em um erro.

password

Não

Não default

A senha do Azure Synapse. Deve ser usado em conjunto com a opção user. Só pode ser usado se o usuário e a senha não forem passados na URL. Passar os dois resultará em um erro.

url

Sim

Não default

Um URL JDBC com sqlserver definido como o subprotocolo. Recomenda-se usar as cadeias de conexão fornecidas pelo portal Azure. A configuração de encrypt=true é altamente recomendada, pois permite a criptografia SSL da conexão JDBC. Se user e password estiverem definidos separadamente, você não precisará incluí-los na URL.

jdbcDriver

Não

Determinado pelo subprotocolo do URL do JDBC

O nome da classe do driver JDBC a ser usado. Essa classe deve estar no classpath. Na maioria dos casos, não deve ser necessário especificar essa opção, pois o nome de classe do driver apropriado deve ser determinado automaticamente pelo subprotocolo do URL do JDBC.

A variante jdbc_driver suportada anteriormente está obsoleta e será ignorada em versões futuras. Em vez disso, use o nome “estojo de camelo”.

tempDir

Sim

Não default

UM URI abfss. Recomendamos que o senhor use um contêiner de armazenamento Blob dedicado para o Azure Synapse.

A variante tempdir suportada anteriormente está obsoleta e será ignorada em versões futuras. Em vez disso, use o nome “estojo de camelo”.

tempFormat

Não

PARQUET

O formato no qual salvar arquivos temporários no armazenamento de blob ao gravar no Azure Synapse. padrão para PARQUET; nenhum outro valor é permitido no momento.

tempCompression

Não

SNAPPY

O algoritmo de compactação a ser usado para codificar/decodificar temporariamente pelo Spark e pelo Azure Synapse. Os valores atualmente suportados são: UNCOMPRESSED, SNAPPY e GZIP.

forwardSparkAzureStorageCredentials

Não

falso

Se true, a biblioteca descobre automaticamente as credenciais que o Spark está usando para se conectar ao contêiner de armazenamento Blob e encaminha essas credenciais para o Azure Synapse por JDBC. Essas credenciais são enviadas como parte da consulta JDBC. Portanto, é altamente recomendável que o senhor ative a criptografia SSL da conexão JDBC ao usar essa opção.

A versão atual do conector do Azure Synapse requer (exatamente) que um dos sites forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI seja explicitamente definido como true.

A variante forward_spark_azure_storage_credentials suportada anteriormente está obsoleta e será ignorada em versões futuras. Em vez disso, use o nome “estojo de camelo”.

useAzureMSI

Não

falso

Se for true, a biblioteca especificará IDENTITY = 'Managed Service Identity' e não SECRET para as credenciais com escopo de banco de dados que criar.

A versão atual do conector do Azure Synapse requer (exatamente) que um dos sites forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI seja explicitamente definido como true.

enableServicePrincipalAuth

Não

falso

Se true, a biblioteca usará as credenciais de entidade de serviço fornecidas para se conectar ao armazenamento Azure account e Azure Synapse Analytics em JDBC.

A versão atual do conector do Azure Synapse requer (exatamente) que um dos sites forwardSparkAzureStorageCredentials, enableServicePrincipalAuth ou useAzureMSI seja explicitamente definido como true.

tableOptions

Não

CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN

Uma cadeia de caracteres usada para especificar opções de tabela ao criar o conjunto de tabelas Azure Synapse por meio de dbTable. Essa cadeia de caracteres é passada literalmente para a cláusula WITH da instrução CREATE TABLE SQL que é emitida contra Azure Synapse.

A variante table_options suportada anteriormente está obsoleta e será ignorada em versões futuras. Em vez disso, use o nome “estojo de camelo”.

preActions

Não

No default (cadeias de caracteres vazias)

Uma lista separada por ; de SQL comando a ser executado em Azure Synapse antes de gravar dados na instância Azure Synapse. Esses comandos do SQL devem ser válidos e aceitos pelo Azure Synapse.

Se algum desses comandos falhar, ele será tratado como um erro e as operações de gravação não serão executadas.

postActions

Não

No default (cadeias de caracteres vazias)

Uma lista separada por ; de SQL comando a ser executado em Azure Synapse depois que o conector gravar com êxito os dados na instância Azure Synapse. Esses comandos do SQL devem ser válidos e aceitos pelo Azure Synapse.

Se algum desses comandos falhar, ele será tratado como um erro e o senhor receberá uma exceção depois que os dados forem gravados com êxito na instância Azure Synapse.

maxStrLength

Não

256

StringType no Spark é mapeado para o tipo NVARCHAR(maxStrLength) no Azure Synapse. O senhor pode usar maxStrLength para definir o comprimento das cadeias de caracteres para todas as colunas do tipo NVARCHAR(maxStrLength) que estão na tabela com o nome dbTable em Azure Synapse.

A variante maxstrlength suportada anteriormente está obsoleta e será ignorada em versões futuras. Em vez disso, use o nome “estojo de camelo”.

checkpointLocation

Sim

Não default

Local em DBFS que será usado pela transmissão estruturada para gravar metadados e informações de ponto de verificação. Consulte Recuperação de falhas com checkpointing no guia de programação do Transmissão Estruturada.

numStreamingTempDirsToKeep

Não

0

Indica quantos diretórios temporários (mais recentes) devem ser mantidos para limpeza periódica de micro lotes na transmissão. Quando definido como 0, a exclusão do diretório é acionada imediatamente depois que os microlotes são confirmados; caso contrário, o número fornecido dos microlotes mais recentes é mantido e o restante dos diretórios é removido. Use -1 para desativar a limpeza periódica.

applicationName

Não

Databricks-User-Query

A tag da conexão para cada consulta. Se não for especificado ou se o valor for uma cadeia de caracteres vazia, o valor default da tag será adicionado ao URL JDBC. O valor default impede que a ferramenta de monitoramento Azure DB levante alertas de injeção SQL espúrios contra consultas.

maxbinlength

Não

Não default

Controle o comprimento das colunas BinaryType. Esse parâmetro é traduzido como VARBINARY(maxbinlength).

identityInsert

Não

falso

Definir como true ativa o modo IDENTITY_INSERT, que insere um valor fornecido pelo DataFrame na coluna de identidade da tabela do Azure Synapse.

Consulte Inserção explícita de valores em uma coluna IDENTITY.

externalDataSource

Não

Não default

Um pré-provisionamento externo de fonte de dados para ler dados de Azure Synapse. Uma fonte de dados externa só pode ser usada com o PolyBase e elimina o requisito de permissão CONTROL, pois o conector não precisa criar uma credencial com escopo e uma fonte de dados externa para carregar dados.

Para obter um exemplo de uso e a lista de permissões necessárias ao usar uma fonte de dados externa, consulte as permissões necessárias em Azure Synapse 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 as leituras e gravações antes que as operações de carregamento (PolyBase ou COPY) sejam canceladas. As linhas rejeitadas serão ignoradas. Por exemplo, se dois em cada dez registros tiverem erros, somente oito registros serão processados.

Consulte a documentação REJECT_VALUE em CREATE EXTERNAL TABLE e a documentação MAXERRORS em COPY.

nota
  • tableOptions, preActions, postActions, e maxStrLength são relevantes apenas ao gravar dados do Databricks em uma nova tabela no Azure Synapse.
  • externalDataSource é relevante somente ao ler dados do Azure Synapse e gravar dados do Databricks em uma nova tabela no Azure Synapse com a semântica PolyBase. Você não deve especificar outros tipos de autenticação de armazenamento ao usar externalDataSource, como forwardSparkAzureStorageCredentials ou useAzureMSI.
  • checkpointLocation e numStreamingTempDirsToKeep são relevantes apenas para gravações de transmissão de Databricks para uma nova tabela em Azure Synapse.
  • Embora todos os nomes de opções de fonte de dados não diferenciem maiúsculas de minúsculas, recomendamos que o senhor os especifique em "camel case" para maior clareza.

Envio de consulta para o Azure Synapse​

O conector do Azure Synapse implementa um conjunto de regras de otimização para enviar os seguintes operadores para o Azure Synapse:

  • Filter
  • Project
  • Limit

Os operadores Project e Filter suportam as seguintes expressões:

  • A maioria dos operadores de lógica booleana
  • Comparações
  • Operações aritméticas básicas
  • Conversão de números e strings

Para o operador Limit, o pushdown é suportado somente quando não há nenhum pedido especificado. Por exemplo:

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

nota

O conector Azure Synapse não pressiona expressões que operam em strings, datas ou registros de data e hora.

O pushdown de consulta criado com o conector Azure Synapse é ativado por default. Você pode desativá-lo configurando spark.databricks.sqldw.pushdown para false.

Gerenciamento temporário de dados​

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

Para facilitar a limpeza dos dados, o conector do Azure Synapse não armazena os arquivos de dados diretamente em tempDir, , mas cria um subdiretório no formato: <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. O senhor pode configurar um trabalho periódico (usando o recurso Databricks Job ou de outra forma) para excluir recursivamente todos os subdiretórios mais antigos do que um determinado limite (por exemplo, 2 dias), com a suposição de que não pode haver um trabalho Spark em execução por mais tempo do que esse limite.

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

Gerenciamento temporário de objetos​

O conector Azure Synapse automatiza a transferência de dados entre um clustering Databricks e uma instância Azure Synapse. Para ler dados de uma tabela ou consulta do Azure Synapse 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 permanecem ativos somente durante a duração do trabalho correspondente no site Spark e devem ser descartados automaticamente depois disso.

Quando um clustering estiver executando uma consulta usando o conector Azure Synapse, se o processo do driver Spark falhar ou for reiniciado à força, ou se o clustering for encerrado ou reiniciado à força, os objetos temporários poderão não ser descartados. 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 tag do tipo: 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_%'

gerenciamento da tabela de pontos de controle de transmissão​

O conector Azure Synapse não exclui a tabela de pontos de controle de transmissão que é criada quando uma nova consulta de transmissão é iniciada. Esse comportamento é consistente com o site checkpointLocation no DBFS. Portanto, recomendamos que o senhor exclua periodicamente as tabelas de ponto de verificação ao mesmo tempo em que remove os locais de ponto de verificação em DBFS para consultas que não serão executadas no futuro ou que já tenham o local de ponto de verificação removido.

Em default, todas as tabelas de checkpoint têm o nome <prefix>_<query-id>, em que <prefix> é um prefixo configurável com default valor databricks_streaming_checkpoint e query_id é um ID de consulta de transmissão com _ caracteres removidos. Para encontrar todas as tabelas de pontos de verificação para consultas de transmissão obsoletas ou excluídas, execute a consulta:

SQL
SELECT * FROM sys.tables WHERE name LIKE 'databricks_streaming_checkpoint%'

O senhor pode configurar o prefixo com a opção de configuração do Spark SQL spark.databricks.sqldw.streaming.exactlyOnce.checkpointTableNamePrefix.

Perguntas frequentes (FAQ)​

Recebi um erro ao usar o conector do Azure Synapse. Como posso saber se esse erro é do Azure Synapse ou do Databricks?

Para ajudá-lo a depurar erros, qualquer exceção lançada por código específico do conector do Azure Synapse é envolvida em uma exceção que estende a característica SqlDWException. As exceções também fazem a seguinte distinção:

  • SqlDWConnectorException representa um erro lançado pelo conector do Azure Synapse
  • SqlDWSideException representa um erro lançado pela instância do Azure Synapse conectada

O que devo fazer se minha consulta falhar com o erro "No access key found in the session conf or the global Hadoop conf"?

Esse erro significa que o conector Azure Synapse não conseguiu localizar o acesso ao armazenamento account key na configuração da sessão do Notebook ou na configuração global Hadoop para o armazenamento account especificado em tempDir. Consulte Uso (lotes) para obter exemplos de como configurar corretamente o acesso à conta do Storage. Se uma tabela Spark for criada usando o conector Azure Synapse, o senhor ainda deverá fornecer as credenciais de acesso account do armazenamento para ler ou gravar na tabela Spark.

Posso usar uma Assinatura de Acesso Compartilhado (SAS) para acessar o contêiner de armazenamento Blob especificado por tempDir?

O Azure Synapse não oferece suporte ao uso do SAS para acessar o armazenamento Blob. Portanto, o conector do Azure Synapse não oferece suporte ao SAS para acessar o contêiner de armazenamento Blob especificado por tempDir.

Criei uma tabela do Spark usando o conector do Azure Synapse com a opção dbTable, escrevi alguns dados nessa tabela do Spark e, em seguida, eliminei essa tabela do Spark. A tabela criada no lado do Azure Synapse será descartada?

Não. O site Azure Synapse é considerado uma fonte externa de dados. A tabela do Azure Synapse com o nome definido em dbTable não é descartada quando a tabela do Spark é descartada.

Ao escrever um DataFrame no Azure Synapse, por que preciso dizer .option("dbTable", tableName).save() em vez de apenas .saveAsTable(tableName)?

Isso ocorre porque queremos deixar clara a seguinte distinção: .option("dbTable", tableName) refere-se à tabela do banco de dados (ou seja, Azure Synapse), enquanto .saveAsTable(tableName) refere-se à tabela do Spark. Na verdade, o senhor poderia até combinar os dois: df.write. ... .option("dbTable", tableNameDW).saveAsTable(tableNameSpark) que cria uma tabela no Azure Synapse chamada tableNameDW e uma tabela externa no Spark chamada tableNameSpark que é apoiada pela tabela do Azure Synapse.

atenção

Cuidado com a seguinte diferença entre .save() e .saveAsTable():

  • Para df.write. ... .option("dbTable", tableNameDW).mode(writeMode).save(), writeMode atua na tabela do Azure Synapse, como esperado.
  • Para df.write. ... .option("dbTable", tableNameDW).mode(writeMode).saveAsTable(tableNameSpark), writeMode atua na tabela Spark, enquanto tableNameDW é sobrescrito silenciosamente se já existir no Azure Synapse.

Esse comportamento não é diferente de escrever em qualquer outra fonte de dados. É apenas uma ressalva da API Spark DataFrameWriter.

Última atualização em