Wykonywanie zapytań dotyczących danych w usłudze Azure Synapse Analytics

Dostęp do usługi Azure Synapse z usługi Azure Databricks można uzyskać za pomocą łącznika Azure Synapse, który wykorzystuje instrukcję COPY w Azure Synapse do efektywnego transferu dużych ilości danych między klastrem Azure Databricks a instancją Azure Synapse, przy użyciu konta magazynowego Azure Data Lake Storage do tymczasowego przechowywania danych.

Ważne

Konfiguracje opisane w tym artykule są eksperymentalne. Funkcje eksperymentalne są udostępniane w stanie, w jakim są, i nie są obsługiwane przez Databricks za pośrednictwem pomocy technicznej dla klienta. Aby uzyskać pełną obsługę federacji zapytań, należy zamiast tego użyć Lakehouse Federation, która umożliwia użytkownikom usługi Azure Databricks korzystanie ze składni Unity Catalog i narzędzi do zarządzania danymi.

Usługa Azure Synapse Analytics to oparty na chmurze magazyn danych przedsiębiorstwa, który wykorzystuje masowe przetwarzanie równoległe (MPP) do szybkiego uruchamiania złożonych zapytań w petabajtach danych.

Ważne

Ten łącznik jest przeznaczony do użytku tylko z instancjami Puli Dedykowanej w usłudze Synapse i nie jest kompatybilny z innymi składnikami tej usługi.

Uwaga

COPY jest dostępna tylko w wystąpieniach usługi Azure Data Lake Storage. Jeśli szukasz szczegółowych informacji na temat pracy z programem Polybase, zobacz Connecting Azure Databricks and Azure Synapse with PolyBase (legacy) (Łączenie usług Azure Databricks i Azure Synapse z technologią PolyBase (starsza wersja).

Przykładowa składnia usługi Synapse

Zapytania dotyczące usługi Synapse można wykonywać w języku Scala, Python, SQL i R. W poniższych przykładach kodu są używane klucze konta magazynu i przekazywanie poświadczeń magazynu z usługi Azure Databricks do usługi Synapse.

Uwaga

Użyj ciągu połączenia dostarczonego przez portal Azure, który umożliwia szyfrowanie Secure Sockets Layer (SSL) dla wszystkich danych wysyłanych między sterownikiem Spark a wystąpieniem usługi Azure Synapse za pośrednictwem połączenia JDBC. Aby sprawdzić, czy szyfrowanie SSL jest włączone, możesz wyszukać encrypt=true w parametry połączenia.

Ważne

Lokalizacje zewnętrzne zdefiniowane w katalogu Unity nie są obsługiwane jako tempDir lokalizacje.

Usługa Databricks zaleca korzystanie z najbezpieczniejszego dostępnego przepływu uwierzytelniania. Przepływ uwierzytelniania opisany w tym przykładzie niesie ze sobą ryzyko, które nie są obecne w innych przepływach. Tego przepływu należy używać tylko wtedy, gdy inne bezpieczniejsze przepływy, takie jak tożsamości zarządzane, nie są opłacalne.

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

Jak działa uwierzytelnianie między usługą Azure Databricks i usługą Synapse?

Łącznik usługi Azure Synapse używa trzech typów połączeń sieciowych:

• Sterownik Spark dla Azure Synapse
• Klaster Spark do konta usługi Azure Storage
• Usługa Azure Synapse do konta usługi Azure Storage

Konfigurowanie dostępu do usługi Azure Storage

Zarówno usługi Azure Databricks, jak i Synapse wymagają uprzywilejowanego dostępu do konta usługi Azure Storage, które ma być używane na potrzeby tymczasowego magazynu danych.

Usługa Azure Synapse nie obsługuje używania sygnatury dostępu współdzielonego na potrzeby dostępu do konta magazynu. Dostęp dla obu usług można skonfigurować, wykonując jedną z następujących czynności:

• Użyj klucza konta i tajnego klucza dla konta magazynu i ustaw forwardSparkAzureStorageCredentials na true. Zobacz Ustawianie właściwości platformy Spark w celu skonfigurowania poświadczeń platformy Azure w celu uzyskania dostępu do usługi Azure Storage.
• Użyj usługi Azure Data Lake Storage z uwierzytelnianiem OAuth 2.0 i ustaw enableServicePrincipalAuth na true. Zobacz Konfigurowanie połączenia z usługi Azure Databricks do usługi Synapse przy użyciu protokołu OAuth 2.0 z jednostką usługi.
• Skonfiguruj wystąpienie usługi Azure Synapse tak, aby miało tożsamość usługi zarządzanej i ustaw useAzureMSI na true.

Wymagane uprawnienia usługi Azure Synapse

Ponieważ używa COPY w tle, łącznik Azure Synapse wymaga, aby użytkownik połączenia JDBC miał uprawnienia do uruchamiania następujących poleceń w podłączonym wystąpieniu Azure Synapse:

• COPY INTO

Jeśli tabela docelowa nie istnieje w usłudze Azure Synapse, oprócz powyższego polecenia wymagane jest uprawnienie do uruchomienia następującego polecenia:

• CREATE TABLE

Poniższa tabela przedstawia wymagane uprawnienia do wykonywania zapisów z użyciem COPY.

Uprawnienia (na wstawianie do istniejącej tabeli)	Uprawnienia (wstaw do nowej tabeli)
ADMINISTROWANIE ZBIORCZYMI OPERACJAMI BAZY DANYCH INSERT	ADMINISTROWANIE OPERACJAMI HURTOWYMI BAZY DANYCH INSERT CREATE TABLE ALTER ON SCHEMA :: dbo

Konfiguracje sieci

Jeśli skonfigurujesz zaporę w usłudze Azure Synapse, musisz skonfigurować ustawienia sieci, aby umożliwić usłudze Azure Databricks dotarcie do usługi Azure Synapse. Najpierw upewnij się, że obszar roboczy usługi Azure Databricks jest wdrożony we własnej sieci wirtualnej zgodnie z instrukcjami podanymi w Wdrażanie usługi Azure Databricks w sieci wirtualnej platformy Azure (iniekcja VNet). Następnie można skonfigurować reguły zapory ip w usłudze Azure Synpase, aby zezwolić na połączenia z podsieci do konta usługi Synapse. Zobacz reguły zapory ogniowej IP dla usługi Azure Synapse Analytics.

Konfigurowanie połączenia z Azure Databricks do Synapse przy użyciu protokołu OAuth 2.0 z jednostką usługi

Możesz uwierzytelnić się w usłudze Azure Synapse Analytics przy użyciu jednostki usługi z dostępem do bazowego konta magazynu. Aby uzyskać więcej informacji na temat używania poświadczeń jednostki usługi w celu uzyskania dostępu do konta usługi Azure Storage, zobacz Connect to Azure Data Lake Storage and Blob Storage. Należy ustawić opcję enableServicePrincipalAuth na true w konfiguracji Azure Databricks Synapse connector options reference, aby umożliwić łącznikowi uwierzytelnianie za pomocą jednostki usługi.

Opcjonalnie możesz użyć innych zasad uwierzytelniania dla połączenia z usługą Azure Synapse Analytics. Poniższy przykład umożliwia skonfigurowanie poświadczeń jednostki usługi dla konta magazynu i opcjonalnych poświadczeń jednostki usługi dla usługi 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>")

Obsługiwane tryby zapisywania dla zapisów wsadowych

Łącznik usługi Azure Synapse obsługuje tryby zapisywania: ErrorIfExists, Ignore, Append i Overwrite, przy domyślnym trybie ErrorIfExists. Aby uzyskać więcej informacji na temat obsługiwanych trybów zapisywania na platformie Apache Spark, zobacz dokumentację spark SQL dotyczącą trybów zapisywania.

Opcje łącznika Azure Databricks Synapse - dokumentacja

Dostępne OPTIONS w usłudze Spark SQL obsługują następujące ustawienia:

Parametr	Wymagane	Wartość domyślna	Uwagi
dbTable	Tak, jeśli query nie został określony	Brak wartości domyślnej	Tabela do utworzenia lub odczytania w usłudze Azure Synapse. Ten parametr jest wymagany podczas zapisywania danych z powrotem do usługi Azure Synapse. Możesz również użyć {SCHEMA NAME}.{TABLE NAME} polecenia , aby uzyskać dostęp do tabeli w danym schemacie. Jeśli nie podano nazwy schematu, zostanie użyty domyślny schemat skojarzony z użytkownikiem JDBC. Wcześniej obsługiwany dbtable wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy "camel case".
query	Tak, chyba że dbTable określono	Brak wartości domyślnej	Zapytanie do odczytu w usłudze Azure Synapse. W przypadku tabel określonych w zapytaniu można również użyć {SCHEMA NAME}.{TABLE NAME} do uzyskania dostępu do tabeli w danym schemacie. Jeśli nie podano nazwy schematu, zostanie użyty domyślny schemat skojarzony z użytkownikiem JDBC.
user	Nie.	Brak wartości domyślnej	Nazwa użytkownika usługi Azure Synapse. Należy używać razem z opcją password . Można go używać tylko wtedy, gdy użytkownik i hasło nie zostaną przekazane w adresie URL. Przekazanie obu spowoduje wystąpienie błędu.
password	Nie.	Brak wartości domyślnej	Hasło usługi Azure Synapse. Należy używać razem z opcją user . Można go używać tylko wtedy, gdy użytkownik i hasło nie zostaną przekazane w adresie URL. Przekazanie obu spowoduje wystąpienie błędu.
url	Tak	Brak wartości domyślnej	Adres URL JDBC z sqlserver ustawionym jako podprotocol. Zaleca się używanie parametry połączenia udostępnianych przez witrynę Azure Portal. Ustawienie encrypt=true jest zdecydowanie zalecane, ponieważ umożliwia szyfrowanie SSL połączenia JDBC. Jeśli user i password są ustawione oddzielnie, nie musisz ich uwzględniać w adresie URL.
jdbcDriver	Nie.	Określony przez podprotocol adresu URL JDBC	Nazwa klasy sterownika JDBC do użycia. Ta klasa musi znajdować się na classpath. W większości przypadków nie należy określać tej opcji, ponieważ odpowiednia nazwa klasy sterownika powinna być automatycznie określana przez podprotocol adresu URL JDBC. Wcześniej obsługiwany jdbc_driver wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy w formacie "camelCase".
tempDir	Tak	Brak ustawienia domyślnego	Jeden abfss URI. Zalecamy użycie dedykowanego kontenera usługi Blob Storage dla usługi Azure Synapse. Wcześniej obsługiwany tempdir wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy "camel case". Nie można użyć zewnętrznej lokalizacji zdefiniowanej w katalogu Unity jako lokalizacji.
tempCompression	Nie.	SNAPPY	Algorytm kompresji, który ma być używany do kodowania/dekodowania tymczasowego zarówno przez platformę Spark, jak i usługę Azure Synapse. Obecnie obsługiwane wartości to: UNCOMPRESSED, SNAPPY i GZIP.
forwardSparkAzureStorageCredentials	Nie.	fałsz	Jeśli true, biblioteka automatycznie rozpoznaje poświadczenia klucza dostępu do konta magazynu, które platforma Spark wykorzystuje do połączenia z kontenerem w usłudze Blob Storage, i przekazuje te poświadczenia do usługi Azure Synapse za pośrednictwem protokołu JDBC. Te poświadczenia są wysyłane w ramach zapytania JDBC. Dlatego zdecydowanie zaleca się włączenie szyfrowania SSL połączenia JDBC podczas korzystania z tej opcji. Podczas konfigurowania uwierzytelniania magazynu należy ustawić dokładnie jedną z wartości useAzureMSI i forwardSparkAzureStorageCredentials na true. Alternatywnie, można ustawić enableServicePrincipalAuth na true i użyć jednostki serwisowej do uwierzytelniania zarówno JDBC, jak i magazynu. Opcja forwardSparkAzureStorageCredentials nie obsługuje uwierzytelniania do magazynu przy użyciu ani tożsamości usługi zarządzanej, ani jednostki usługi. Obsługiwany jest tylko klucz dostępu do konta przechowywania. Wcześniej obsługiwany forward_spark_azure_storage_credentials wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy w formacie „CamelCase”.
useAzureMSI	Nie.	fałsz	Jeśli true, biblioteka określi IDENTITY = 'Managed Service Identity' i nie określi SECRET dla poświadczeń o określonym zakresie bazy danych, które tworzy. Podczas konfigurowania uwierzytelniania magazynu należy ustawić dokładnie jedną z opcji useAzureMSI lub forwardSparkAzureStorageCredentials na true. Alternatywnie, można ustawić enableServicePrincipalAuth na true i użyć jednostki usługi zarówno do uwierzytelniania JDBC, jak i magazynu.
enableServicePrincipalAuth	Nie.	fałsz	Jeśli true, biblioteka użyje podanych poświadczeń jednostki usługi, aby nawiązać połączenie z kontem Azure Storage i usługą Azure Synapse Analytics za pośrednictwem protokołu JDBC. Jeśli którąkolwiek z forward_spark_azure_storage_credentials lub useAzureMSI jest ustawiona na wartość true, ta opcja będzie miała pierwszeństwo przed jednostkę główną podczas uwierzytelniania magazynu.
tableOptions	Nie.	CLUSTERED COLUMNSTORE INDEX, DISTRIBUTION = ROUND_ROBIN	Ciąg służący do określania opcji tabeli podczas tworzenia tabeli usługi Azure Synapse ustawionej za pomocą polecenia dbTable. Ten ciąg jest przekazywany dosłownie do klauzuli WITH instrukcji SQL wykonywanej wobec usługi Azure Synapse CREATE TABLE. Wcześniej obsługiwany table_options wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy w stylu "camel case".
preActions	Nie.	Brak wartości domyślnej (pusty ciąg)	Oddzielona ; lista poleceń SQL do wykonania w usłudze Azure Synapse przed zapisaniem danych w wystąpieniu usługi Azure Synapse. Te polecenia SQL muszą być prawidłowymi poleceniami akceptowanymi przez usługę Azure Synapse. Jeśli którykolwiek z tych poleceń zakończy się niepowodzeniem, jest traktowany jako błąd, a operacja zapisu nie jest wykonywana.
postActions	Nie.	Brak wartości domyślnej (pusty ciąg)	; Oddzielona lista poleceń SQL do wykonania w usłudze Azure Synapse po tym, jak łącznik pomyślnie zapisze dane w instancji Azure Synapse. Te polecenia SQL muszą być prawidłowymi poleceniami akceptowanymi przez usługę Azure Synapse. Jeśli którykolwiek z tych poleceń zakończy się niepowodzeniem, zostanie on potraktowany jako błąd i otrzymasz wyjątek po pomyślnym zapisaniu danych w wystąpieniu usługi Azure Synapse.
maxStrLength	Nie.	256	StringType na platformie Spark jest mapowany na typ NVARCHAR(maxStrLength) w Azure Synapse. Za pomocą maxStrLength można ustawić długość ciągu dla wszystkich kolumn typu NVARCHAR(maxStrLength), które znajdują się w tabeli o nazwie dbTable w usłudze Azure Synapse. Wcześniej obsługiwany maxstrlength wariant jest przestarzały i zostanie zignorowany w przyszłych wersjach. Zamiast tego użyj nazwy „camel case”.
applicationName	Nie.	Databricks-User-Query	Tag połączenia dla każdego zapytania. Jeśli nie zostanie określona lub wartość jest pustym ciągiem, domyślna wartość tagu jest dodawana do adresu URL JDBC. Wartość domyślna uniemożliwia narzędziu do monitorowania usługi Azure DB zgłaszanie fałszywych alertów iniekcji SQL względem zapytań.
maxbinlength	Nie.	Brak wartości domyślnej	Steruj długością BinaryType kolumn. Ten parametr jest tłumaczony jako VARBINARY(maxbinlength).
identityInsert	Nie.	fałsz	Ustawienie opcji true włącza tryb IDENTITY_INSERT, który wstawia podaną wartość ramki danych do kolumny tożsamości tabeli usługi Azure Synapse. Zobacz Jawne wstawianie wartości do kolumny IDENTITY.
externalDataSource	Nie.	Brak wartości domyślnej	Wstępnie skonfigurowane zewnętrzne źródło danych do odczytu danych z usługi Azure Synapse. Zewnętrzne źródło danych może być używane tylko z technologią PolyBase i usuwa wymaganie uprawnień CONTROL, ponieważ łącznik nie musi tworzyć poświadczeń o określonym zakresie i zewnętrznego źródła danych w celu załadowania danych. Na przykład użycie i lista uprawnień wymaganych podczas korzystania z zewnętrznego źródła danych można znaleźć w temacie Required Azure Synapse permissions for PolyBase with the external data source option (Wymagane uprawnienia usługi Azure Synapse dla programu PolyBase z opcją zewnętrznego źródła danych).
maxErrors	Nie.	0	Maksymalna liczba wierszy, które można odrzucić podczas operacji odczytu i zapisu przed anulowaniem operacji ładowania. Odrzucone wiersze zostaną zignorowane. Jeśli na przykład dwa z dziesięciu rekordów zawierają błędy, zostaną przetworzone tylko osiem rekordów. Zapoznaj się z dokumentacją REJECT_VALUE w CREATE EXTERNAL TABLE oraz dokumentacją MAXERRORS w COPY.
inferTimestampNTZType	Nie.	fałsz	Jeśli true wartości typu Azure Synapse TIMESTAMP są interpretowane jako TimestampNTZType (sygnatura czasowa bez strefy czasowej) podczas odczytu. W przeciwnym razie wszystkie znaczniki czasu są interpretowane jako TimestampType niezależnie od typu w bazowej tabeli usługi Azure Synapse.

Uwaga

• tableOptions, , preActionspostActionsi maxStrLength są istotne tylko podczas zapisywania danych z usługi Azure Databricks do nowej tabeli w usłudze Azure Synapse.
• Mimo że wszystkie nazwy opcji źródła danych są niezależne od wielkości liter, zalecamy określenie ich w formacie "camel case" w celu uzyskania jasności.

Wypychanie zapytań do usługi Azure Synapse

Łącznik Azure Synapse implementuje zestaw reguł optymalizacji, aby przenieść następujące operatory do usługi Azure Synapse.

• Filter
• Project
• Limit

Operatory Project i Filter obsługują następujące wyrażenia:

• Większość operatorów logicznych boolowskich
• Porównania
• Podstawowe operacje arytmetyczne
• Rzutowanie liczbowe i ciągowe

Limit W przypadku operatora przesunięcie w dół jest obsługiwane tylko wtedy, gdy nie określono kolejności. Na przykład:

SELECT TOP(10) * FROM table, ale nie SELECT TOP(10) * FROM table ORDER BY col.

Uwaga

Łącznik usługi Azure Synapse nie wypycha wyrażeń działających na ciągach, datach lub znacznikach czasu.

Wypychanie zapytań utworzone za pomocą łącznika usługi Azure Synapse jest domyślnie włączone. Można ją wyłączyć, ustawiając wartość spark.databricks.sqldw.pushdownfalse.

Tymczasowe zarządzanie danymi

Łącznik usługi Azure Synapse nie usuwa plików tymczasowych tworzonych w kontenerze usługi Azure Storage. Usługa Databricks zaleca okresowe usuwanie plików tymczasowych z lokalizacji wskazanej przez użytkownika tempDir.

Aby ułatwić oczyszczanie danych, łącznik usługi Azure Synapse nie przechowuje plików danych bezpośrednio w obszarze tempDir, ale zamiast tego tworzy podkatalog formularza: <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/. Można skonfigurować zadania okresowe (przy użyciu funkcji zadań usługi Azure Databricks lub w inny sposób), aby rekursywnie usuwać wszystkie podkatalogi starsze niż określony próg (na przykład 2 dni), przy założeniu, że nie będzie zadań platformy Spark uruchomionych dłużej niż ten próg.

Prostszą alternatywą jest okresowe usunięcie całego kontenera i utworzenie nowego o tej samej nazwie. Wymaga to użycia dedykowanego kontenera dla danych tymczasowych utworzonych przez łącznik usługi Azure Synapse i że można znaleźć przedział czasu, w którym można zagwarantować, że żadne zapytania z udziałem łącznika nie są uruchomione.

Tymczasowe zarządzanie obiektami

Łącznik usługi Azure Synapse automatyzuje transfer danych między klastrem usługi Azure Databricks i wystąpieniem usługi Azure Synapse. W celu odczytywania danych z tabeli usługi Azure Synapse lub wykonywania zapytań lub zapisywania danych w tabeli usługi Azure Synapse łącznik usługi Azure Synapse tworzy obiekty tymczasowe, w tym DATABASE SCOPED CREDENTIAL, EXTERNAL DATA SOURCE, EXTERNAL FILE FORMATi EXTERNAL TABLE w tle. Te obiekty są aktywne tylko przez cały czas trwania odpowiedniego zadania platformy Spark i są automatycznie porzucane.

Jeśli klaster uruchamia zapytanie przy użyciu łącznika usługi Azure Synapse, jeśli proces sterownika Spark ulegnie awarii lub zostanie wymuszony do ponownego uruchomienia, lub jeśli klaster zostanie wymuszony do zakończenia lub ponownego uruchomienia, obiekty tymczasowe mogą nie zostać usunięte. Aby ułatwić identyfikację i ręczne usuwanie tych obiektów, łącznik Azure Synapse dodaje prefiks do nazw wszystkich pośrednich obiektów tymczasowych utworzonych w instancji Azure Synapse w postaci tagu: tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject>.

Zalecamy okresowe wyszukiwanie ujawnionych obiektów przy użyciu zapytań, takich jak:

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