Eseguire query sui dati in Azure Synapse Analytics

Articolo
12/18/2024

È possibile accedere ad Azure Synapse da Azure Databricks usando il connettore Azure Synapse, che usa l'istruzione COPY in Azure Synapse per trasferire in modo efficiente grandi volumi di dati tra un cluster di Azure Databricks e un'istanza di Azure Synapse tramite un account di archiviazione Azure Data Lake Storage Gen2 per la gestione temporanea.

Importante

Le configurazioni descritte in questo articolo sono sperimentali. Le caratteristiche sperimentali vengono fornite come sono e non sono supportate da Databricks tramite il supporto tecnico del cliente. Per ottenere il supporto completo della federazione delle query, è consigliabile usare invece Lakehouse Federation, che consente agli utenti di Azure Databricks di sfruttare la sintassi di Unity Catalog e gli strumenti di governance dei dati.

Azure Synapse Analytics è un data warehouse aziendale basato sul cloud che utilizza l'elaborazione MPP (Massively Parallel Processing) per eseguire rapidamente query complesse su petabyte di dati.

Importante

Questo connettore è destinato al solo uso con le istanze del pool dedicato di Synapse e non è compatibile con altri componenti di Synapse.

Nota

COPY è disponibile solo nelle istanze Azure Data Lake Storage Gen2. Per informazioni dettagliate sull'uso di Polybase, vedere Connessione di Azure Databricks e Azure Synapse con PolyBase (legacy).

Sintassi di esempio per Synapse

È possibile eseguire query su Synapse in Scala, Python, SQL e R. I seguenti esempi di codice usano le chiavi dell'account di archiviazione e inoltrano le credenziali di archiviazione da Azure Databricks a Synapse.

Nota

Usare la stringa di connessione indicata nel portale di Azure, che abilita la crittografia Secure Sockets Layer (SSL) per tutti i dati inviati tra il driver di Spark e l'istanza di Azure Synapse tramite la connessione JDBC. Per verificare che la crittografia SSL sia abilitata, cercare encrypt=true nella stringa di connessione.

Importante

Le posizioni esterne definite nel catalogo Unity non sono supportate come posizioni tempDir.

Databricks consiglia di usare il flusso di autenticazione più sicuro disponibile. Il flusso di autenticazione descritto in questo esempio comporta rischi che non sono presenti in altri flussi. È consigliabile usare questo flusso solo quando altri flussi più sicuri, ad esempio le identità gestite, non sono validi.

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

Come funziona l'autenticazione tra Azure Databricks e Synapse?

Il connettore di Azure Synapse usa tre tipi di connessioni di rete:

Driver di Spark per Azure Synapse
Cluster di Spark per l'account di archiviazione di Azure
Azure Synapse per l'account di archiviazione di Azure

Configurazione dell'accesso ad Archiviazione di Azure

Sia Azure Databricks che Synapse necessitano dell'accesso con privilegi a un account di archiviazione di Azure da usare per l'archiviazione temporanea dei dati.

Azure Synapse non supporta l'uso della firma di accesso condiviso per l'accesso all'account di archiviazione. È possibile configurare l'accesso per entrambi i servizi eseguendo una delle operazioni seguenti:

Usare la chiave dell'account e il segreto per l'account di archiviazione e impostare forwardSparkAzureStorageCredentials su true. Vedere Impostare le proprietà Spark per configurare le credenziali di Azure per accedere ad Archiviazione di Azure.
Usare Azure Data Lake Storage Gen2 con l'autenticazione OAuth 2.0 e impostare enableServicePrincipalAuth su true. Vedere Configurare la connessione da Azure Databricks a Synapse con OAuth 2.0 con un'entità servizio.
Configurare l'istanza di Azure Synapse in modo che abbia un'identità del servizio gestita e impostare useAzureMSI su true.

Autorizzazioni necessarie di Azure Synapse

Poiché usa COPY in background, il connettore Azure Synapse richiede che l'utente della connessione JDBC disponga dell'autorizzazione per eseguire i comandi seguenti nell'istanza di Azure Synapse connessa:

COPY INTO

Se la tabella di destinazione non esiste in Azure Synapse, è necessaria l'autorizzazione per eseguire il comando seguente, oltre al comando sopraindicato:

CREATE TABLE

Nella tabella seguente sono riepilogate le autorizzazioni necessarie per le operazioni di scrittura con COPY:

Autorizzazioni (inserimento in una tabella esistente)	Autorizzazioni (inserimento in una nuova tabella)
ADMINISTER DATABASE BULK OPERATIONS INSERT	ADMINISTER DATABASE BULK OPERATIONS INSERT CREA TABELLA ALTER ON SCHEMA:: dbo

Configurazioni di rete

Se si configura un firewall in Azure Synapse, è necessario configurare le impostazioni di rete per consentire ad Azure Databricks di raggiungere Azure Synapse. Assicurarsi prima di tutto che l'area di lavoro di Azure Databricks sia distribuita nella propria rete virtuale seguendo Distribuire Azure Databricks nella rete virtuale di Azure (VNet injection). È quindi possibile configurare le regole del firewall IP in Azure Synpase per consentire le connessioni dalle subnet all'account Synapse. Vedere Regole del firewall IP di Azure Synapse Analytics.

Configurare la connessione da Azure Databricks a Synapse con OAuth 2.0 con un'entità servizio

È possibile eseguire l'autenticazione in Azure Synapse Analytics usando un'entità servizio con accesso all'account di archiviazione sottostante. Per ulteriori informazioni sull’uso delle credenziali dell’entità servizio per accedere a un account di archiviazione Azure, vedere Connessione a Azure Data Lake Storage Gen2 e archiviazione BLOB. È necessario impostare l'opzione enableServicePrincipalAuth su true nella configurazione della connessione Riferimento alle opzioni del connettore Synapse di Azure Databricks per consentire al connettore di eseguire l'autenticazione con un'entità servizio.

Facoltativamente, è possibile usare un'entità servizio diversa per la connessione ad Azure Synapse Analytics. Nell’esempio seguente vengono configurate le credenziali dell'entità servizio per l'account di archiviazione e le credenziali facoltative dell'entità servizio per 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>")

Modalità di salvataggio supportate per le operazioni di scrittura in batch

Il connettore Azure Synapse supporta le modalità di salvataggio ErrorIfExists, Ignore, Append e Overwrite con la modalità predefinita ErrorIfExists. Per altre informazioni sulle modalità di salvataggio supportate in Apache Spark, vedere la documentazione di Spark SQL sulle modalità di salvataggio.

Informazioni di riferimento sulle opzioni del connettore Synapse di Azure Databricks

Le OPTIONS fornite in Spark SQL supportano le impostazioni seguenti:

Parametro	Richiesto	Valore predefinito	Note
`dbTable`	Sì, a meno che non venga specificato `query`	Nessun valore predefinito	Tabella da cui creare o leggere in Azure Synapse. Questo parametro è obbligatorio quando si salvano i dati in Azure Synapse. È anche possibile usare `{SCHEMA NAME}.{TABLE NAME}` per accedere a una tabella in uno schema specifico. Se non viene specificato il nome dello schema, viene usato lo schema predefinito associato all'utente JDBC. La variante `dbtable` supportata in precedenza è deprecata e verrà ignorata nelle versioni future. Usare invece il nome nella notazione a cammello (camelCase).
`query`	Sì, a meno che non venga specificato `dbTable`	Nessun valore predefinito	Query da cui leggere in Azure Synapse. Per le tabelle a cui fa riferimento la query, è anche possibile usare `{SCHEMA NAME}.{TABLE NAME}` per accedere a una tabella in uno schema specifico. Se non viene specificato il nome dello schema, viene usato lo schema predefinito associato all'utente JDBC.
`user`	No	Nessun valore predefinito	Nome utente di Azure Synapse. Deve essere utilizzato in combinazione con l'opzione `password`. Può essere usato solo se l'utente e la password non vengono passati nell'URL. Il passaggio di entrambi genererà un errore.
`password`	No	Nessun valore predefinito	Password di Azure Synapse. Deve essere utilizzato in combinazione con l'opzione `user`. Può essere usato solo se l'utente e la password non vengono passati nell'URL. Il passaggio di entrambi genererà un errore.
`url`	Sì	Nessun valore predefinito	URL JDBC con `sqlserver` impostato come sottoprotocolo. È consigliabile usare la stringa di connessione fornita dal portale di Azure. È consigliabile impostare `encrypt=true` perché abilita la crittografia SSL della connessione JDBC. Se `user` e `password` vengono impostati separatamente, non è necessario includerli nell'URL.
`jdbcDriver`	No	Determinato dal sottoprotocolo dell'URL JDBC	Nome della classe del driver JDBC da usare. Questa classe deve trovarsi nel classpath. Nella maggior parte dei casi, non dovrebbe essere necessario specificare questa opzione, perché il nome della classe del driver appropriato dovrebbe essere determinato automaticamente dal sottoprotocolo dell'URL JDBC. La variante `jdbc_driver` supportata in precedenza è deprecata e verrà ignorata nelle versioni future. Usare invece il nome nella notazione a cammello (camelCase).
`tempDir`	Sì	Nessun valore predefinito	URI `abfss`. È consigliabile usare un contenitore di archiviazione BLOB dedicato per Azure Synapse. La variante `tempdir` supportata in precedenza è deprecata e verrà ignorata nelle versioni future. Usare invece il nome nella notazione a cammello (camelCase). Non è possibile usare un percorso esterno definito nel catalogo Unity come posizione `tempDir`.
`tempCompression`	No	`SNAPPY`	Algoritmo di compressione da usare per codificare/decodificare in modo temporaneo sia Spark che Azure Synapse. I valori attualmente supportati sono: `UNCOMPRESSED`, `SNAPPY` e `GZIP`.
`forwardSparkAzureStorageCredentials`	No	false	Se `true`, la libreria individua automaticamente le credenziali della chiave di accesso dell'account di archiviazione usate da Spark per connettersi al contenitore di archiviazione BLOB e inoltra tali credenziali ad Azure Synapse tramite JDBC. Queste credenziali vengono inviate come parte della query JDBC. È pertanto consigliabile abilitare la crittografia SSL della connessione JDBC quando si usa questa opzione. Quando si configura l'autenticazione di archiviazione, è necessario impostare esattamente uno di `useAzureMSI` e `forwardSparkAzureStorageCredentials` su `true`. In alternativa, è possibile impostare `enableServicePrincipalAuth` su `true` e usare l'entità servizio sia per l'autenticazione di archiviazione che di JDBC. L'opzione `forwardSparkAzureStorageCredentials` non supporta l'autenticazione per l'archiviazione tramite un'identità del servizio gestita o un'entità servizio. È supportata solo la chiave di accesso dell'account di archiviazione. La variante `forward_spark_azure_storage_credentials` supportata in precedenza è deprecata e verrà ignorata nelle versioni future. Usare invece il nome nella notazione a cammello (camelCase).
`useAzureMSI`	No	false	Se `true`, la libreria specificherà `IDENTITY = 'Managed Service Identity'` e nessun `SECRET` per le credenziali con ambito database create. Quando si configura l'autenticazione di archiviazione, è necessario impostare esattamente uno di `useAzureMSI` e `forwardSparkAzureStorageCredentials` su `true`. In alternativa, è possibile impostare `enableServicePrincipalAuth` su `true` e usare l'entità servizio sia per l'autenticazione di archiviazione che di JDBC.
`enableServicePrincipalAuth`	No	false	Se `true`, la libreria userà le credenziali dell'entità servizio fornite per connettersi all'account di archiviazione di Azure e ad Azure Synapse Analytics tramite JDBC. Se `forward_spark_azure_storage_credentials` o `useAzureMSI` è impostato su `true`, tale opzione ha la precedenza sull'entità servizio nell'autenticazione dell'archiviazione.
`tableOptions`	No	`CLUSTERED COLUMNSTORE INDEX`, `DISTRIBUTION = ROUND_ROBIN`	Stringa usata per specificare le opzioni di tabella durante la creazione della tabella di Azure Synapse impostata tramite `dbTable`. Questa stringa viene passata letteralmente alla clausola `WITH` dell'istruzione SQL `CREATE TABLE` rilasciata in Azure Synapse. La variante `table_options` supportata in precedenza è deprecata e verrà ignorata nelle versioni future. Usare invece il nome nella notazione a cammello (camelCase).
`preActions`	No	Nessuna impostazione predefinita (stringa vuota)	Elenco `;` separato di comandi SQL da eseguire in Azure Synapse prima di scrivere dati nell'istanza di Azure Synapse. Questi comandi SQL devono essere comandi validi accettati da Azure Synapse. Se uno di questi comandi ha esito negativo, viene considerato come un errore e l'operazione di scrittura non viene eseguita.
`postActions`	No	Nessuna impostazione predefinita (stringa vuota)	Elenco `;` separato di comandi SQL da eseguire in Azure Synapse dopo che il connettore scrive correttamente i dati nell'istanza di Azure Synapse. Questi comandi SQL devono essere comandi validi accettati da Azure Synapse. Se uno di questi comandi ha esito negativo, viene considerato come un errore e si riceverà un'eccezione dopo che i dati vengono scritti correttamente nell'istanza di Azure Synapse.
`maxStrLength`	No	256	`StringType` in Spark viene mappato al tipo `NVARCHAR(maxStrLength)` in Azure Synapse. È possibile usare `maxStrLength` per impostare la lunghezza della stringa per tutte le colonne di tipo `NVARCHAR(maxStrLength)` presenti nella tabella con nome `dbTable` in Azure Synapse. La variante `maxstrlength` supportata in precedenza è deprecata e verrà ignorata nelle versioni future. Usare invece il nome nella notazione a cammello (camelCase).
`applicationName`	No	`Databricks-User-Query`	Tag della connessione per ogni query. Se non specificato, o se il valore è una stringa vuota, il valore predefinito del tag viene aggiunto all'URL JDBC. Il valore predefinito impedisce allo strumento di monitoraggio del database di Azure di generare falsi avvisi SQL injection sulle query.
`maxbinlength`	No	Nessun valore predefinito	Controllare la lunghezza delle colonne `BinaryType`. Questo parametro viene convertito come `VARBINARY(maxbinlength)`.
`identityInsert`	No	false	L'impostazione su `true` abilita la modalità `IDENTITY_INSERT`, che inserisce un valore fornito dal DataFrame nella colonna Identity della tabella di Azure Synapse. Vedere Inserimento in modo esplicito di valori in una colonna IDENTITY.
`externalDataSource`	No	Nessun valore predefinito	Un'origine dati esterna con provisioning preliminare per leggere i dati da Azure Synapse. Un'origine dati esterna può essere usata solo con PolyBase e rimuove il requisito di autorizzazione CONTROL perché il connettore non deve creare credenziali con ambito né un'origine dati esterna per caricare i dati. Per esempi di utilizzo e per l'elenco delle autorizzazioni necessarie quando si usa un'origine dati esterna, vedere Autorizzazioni necessarie di Azure Synapse per PolyBase con l'opzione origine dati esterna.
`maxErrors`	No	0	Numero massimo di righe che possono essere rifiutate durante le operazioni di lettura e scrittura prima dell'annullamento dell'operazione di caricamento. Le righe rifiutate verranno ignorate. Ad esempio, se due record su dieci presentano errori, verranno elaborati solo otto record. Vedere la documentazione su REJECT_VALUE in CREATE EXTERNAL TABLE e la documentazione su MAXERRORS in COPY.
`inferTimestampNTZType`	No	false	Se `true`, i valori di tipo Azure Synapse `TIMESTAMP` vengono interpretati come `TimestampNTZType` (timestamp senza fuso orario) durante le letture. In caso contrario, tutti i timestamp vengono interpretati come `TimestampType` indipendentemente dal tipo nella tabella di Azure Synapse sottostante.

Nota

tableOptions, preActions, postActions e maxStrLength sono rilevanti solo quando si scrivono dati da Azure Databricks in una nuova tabella in Azure Synapse.
Anche se nessun nome delle opzioni dell'origine dati fa distinzione tra maiuscole e minuscole, è consigliabile specificarli nella notazione "camel case" per maggiore chiarezza.

Eseguire il pushdown delle query in Azure Synapse

Il connettore Azure Synapse implementa un set di regole di ottimizzazione per eseguire il pushdown degli operatori seguenti in Azure Synapse:

Filter
Project
Limit

Le operazioni Project e Filter supportano le seguenti espressioni:

La maggior parte degli operatori logici booleani
Confronti
Operazioni aritmetiche di base
Cast numerici e stringa

Per l'operatore Limit, il pushdown è supportato solo quando non è specificato alcun ordinamento. Ad esempio:

SELECT TOP(10) * FROM table, ma non SELECT TOP(10) * FROM table ORDER BY col.

Nota

Il connettore Azure Synapse non esegue il push delle espressioni che operano su stringhe, date o timestamp.

Il pushdown delle query compilato con il connettore Azure Synapse è abilitato per impostazione predefinita. Puoi disabilitarlo impostando spark.databricks.sqldw.pushdown su false.

Gestione temporanea dei dati

Il connettore Azure Synapse non elimina i file temporanei che crea nel contenitore di archiviazione di Azure. Databricks consiglia di eliminare periodicamente i file temporanei nel percorso tempDir fornito dall'utente.

Per facilitare la pulizia dei dati, il connettore Azure Synapse non archivia i file di dati direttamente in tempDir, ma crea invece una sottodirectory del modulo: <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. È possibile configurare processi periodici (usando la funzionalità processi di Azure Databricks o in altro modo) per eliminare in modo ricorsivo tutte le sottodirectory precedenti a una determinata soglia (ad esempio, 2 giorni), presupponendo che i processi Spark non possano essere eseguiti più a lungo di tale soglia.

Un'alternativa più semplice consiste nell'eliminare periodicamente l'intero contenitore e crearne uno nuovo con lo stesso nome. Ciò richiede l'uso di un contenitore apposito per i dati temporanei prodotti dal connettore Azure Synapse e che sia possibile trovare un intervallo di tempo in cui è possibile garantire che non siano in esecuzione query che coinvolgono il connettore.

Gestione temporanea degli oggetti

Il connettore Azure Synapse automatizza il trasferimento dei dati tra un cluster di Azure Databricks e un'istanza di Azure Synapse. Per leggere i dati di una tabella di Azure Synapse, eseguire query o scrivere dati in una tabella di Azure Synapse, il connettore Azure Synapse dietro le quinte crea oggetti temporanei, tra cui DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMAT e EXTERNAL TABLE. Questi oggetti esistono solo per tutta la durata del processo Spark corrispondente e vengono eliminati automaticamente.

Quando un cluster esegue una query usando il connettore Azure Synapse, se il processo del driver Spark si arresta in modo anomalo o viene riavviato forzatamente, o se il cluster viene terminato o riavviato forzatamente, gli oggetti temporanei potrebbero non essere eliminati. Per facilitare l'identificazione e l'eliminazione manuale di questi oggetti, il connettore Azure Synapse antepone ai nomi di tutti gli oggetti temporanei intermedi creati nell'istanza di Azure Synapse un tag del modulo: tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

È consigliabile cercare periodicamente oggetti persi usando query come le seguenti:

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

Condividi tramite

Eseguire query sui dati in Azure Synapse Analytics

Sintassi di esempio per Synapse

Scala

Python

SQL

R

Come funziona l'autenticazione tra Azure Databricks e Synapse?

Configurazione dell'accesso ad Archiviazione di Azure

Autorizzazioni necessarie di Azure Synapse

Configurazioni di rete

Configurare la connessione da Azure Databricks a Synapse con OAuth 2.0 con un'entità servizio

ini

Scala

Python

R

Modalità di salvataggio supportate per le operazioni di scrittura in batch

Informazioni di riferimento sulle opzioni del connettore Synapse di Azure Databricks

Eseguire il pushdown delle query in Azure Synapse

Gestione temporanea dei dati

Gestione temporanea degli oggetti

Commenti e suggerimenti

Risorse aggiuntive