Azure Synapse Analytics のクエリデータ

[アーティクル]
03/01/2024

Azure Synapse コネクタを使用して Azure Databricks から Azure Synapse にアクセスできます。これは、Azure Synapse Analytics で COPY ステートメントを使用し、一時ステージングに Azure Data Lake Storage Gen2 ストレージアカウントを使用して、Azure Databricks クラスターと Azure Synapse インスタンスの間で、大量のデータを効率的に転送できます。

注意

Azure Synapseまたは Azure Data Warehouse データに対するクエリを管理する場合は、Lakehouse Federation が適している可能性があります。「Lakehouse フェデレーションとは」を参照してください。

Azure Synapse Analytics は、超並列処理 (MPP) を利用して、ペタバイト単位のデータに対して複雑なクエリを短時間で実行するクラウドベースのエンタープライズデータウェアハウスです。

重要

このコネクタは Synapse 専用プールインスタンスでのみ使用され、他の Synapse コンポーネントとは互換性がありません。

Note

COPY は、Azure Data Lake Storage Gen2 インスタンスでのみ使用できます。 Polybase の操作の詳細については、「PolyBase を使用した Azure Databricks と Azure Synapse の接続 (レガシ)」を参照してください。

Synapse の構文の例

Scala、Python、SQL、R で Synapse のクエリを実行できます。次のコード例では、ストレージアカウントキーを使用し、ストレージ資格情報を Azure Databricks から Synapse に転送しています。

注意

Azure portal で提供される接続文字列を使用します。これにより、JDBC 接続を通じて Spark ドライバーと Azure Synapse インスタンスの間で送信されるすべてのデータに対して Secure Sockets Layer (SSL) 暗号化を有効にします。 SSL 暗号化が有効になっていることを確認するには、接続文字列で encrypt=true を検索します。

重要

Unity Catalog で定義されている外部の場所は、tempDir の場所としてサポートされていません。

Scala


// Set up the storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 11.3 LTS and above.
val df: DataFrame = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") /* Optional - will use default port 1433 if not specified. */
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") /* If schemaName not provided, default to "dbo". */
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

// Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .load()

// Load data from an Azure Synapse query.
val df: DataFrame = spark.read
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("query", "select x, count(*) as cnt from table group by x")
  .load()

// Apply some transformations to the data, then use the
// Data Source API to write the data back to another table in Azure Synapse.

df.write
  .format("com.databricks.spark.sqldw")
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .option("dbTable", "<your-table-name>")
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .save()

Python


# Set up the storage account access key in the notebook session conf.
spark.conf.set(
  "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net",
  "<your-storage-account-access-key>")

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 11.3 LTS and above.
df = spark.read
  .format("sqldw")
  .option("host", "hostname")
  .option("port", "port") # Optional - will use default port 1433 if not specified.
  .option("user", "username")
  .option("password", "password")
  .option("database", "database-name")
  .option("dbtable", "schema-name.table-name") # If schemaName not provided, default to "dbo".
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")
  .option("forwardSparkAzureStorageCredentials", "true")
  .load()

# Get some data from an Azure Synapse table. The following example applies to Databricks Runtime 10.4 LTS and below.
df = spark.read \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("dbTable", "<your-table-name>") \
  .load()

# Load data from an Azure Synapse query.
df = spark.read \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("query", "select x, count(*) as cnt from table group by x") \
  .load()

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

df.write \
  .format("com.databricks.spark.sqldw") \
  .option("url", "jdbc:sqlserver://<the-rest-of-the-connection-string>") \
  .option("forwardSparkAzureStorageCredentials", "true") \
  .option("dbTable", "<your-table-name>") \
  .option("tempDir", "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>") \
  .save()

SQL


-- Set up the storage account access key in the notebook session conf.
SET fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net=<your-storage-account-access-key>;

-- Read data using SQL. The following example applies to Databricks Runtime 11.3 LTS and above.
CREATE TABLE example_table_in_spark_read
USING sqldw
OPTIONS (
  host '<hostname>',
  port '<port>' /* Optional - will use default port 1433 if not specified. */
  user '<username>',
  password '<password>',
  database '<database-name>'
  dbtable '<schema-name>.<table-name>', /* If schemaName not provided, default to "dbo". */
  forwardSparkAzureStorageCredentials 'true',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Read data using SQL. The following example applies to Databricks Runtime 10.4 LTS and below.
CREATE TABLE example_table_in_spark_read
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbtable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
);

-- Write data using SQL.
-- Create a new table, throwing an error if a table with the same name already exists:

CREATE TABLE example_table_in_spark_write
USING com.databricks.spark.sqldw
OPTIONS (
  url 'jdbc:sqlserver://<the-rest-of-the-connection-string>',
  forwardSparkAzureStorageCredentials 'true',
  dbTable '<your-table-name>',
  tempDir 'abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>'
)
AS SELECT * FROM table_to_save_in_spark;

R

# Load SparkR
library(SparkR)

# Set up the storage account access key in the notebook session conf.
conf <- sparkR.callJMethod(sparkR.session(), "conf")
sparkR.callJMethod(conf, "set", "fs.azure.account.key.<your-storage-account-name>.dfs.core.windows.net", "<your-storage-account-access-key>")

# Get some data from an Azure Synapse table.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   dbTable = "<your-table-name>",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

# Load data from an Azure Synapse query.
df <- read.df(
   source = "com.databricks.spark.sqldw",
   url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
   forward_spark_azure_storage_credentials = "true",
   query = "select x, count(*) as cnt from table group by x",
   tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

# Apply some transformations to the data, then use the
# Data Source API to write the data back to another table in Azure Synapse.

write.df(
  df,
  source = "com.databricks.spark.sqldw",
  url = "jdbc:sqlserver://<the-rest-of-the-connection-string>",
  forward_spark_azure_storage_credentials = "true",
  dbTable = "<your-table-name>",
  tempDir = "abfss://<your-container-name>@<your-storage-account-name>.dfs.core.windows.net/<your-directory-name>")

Azure Databricks と Synapse の間の認証のしくみ

Azure Synapse コネクタでは、3 種類のネットワーク接続が使用されます:

Spark ドライバーから Azure Synapse
Spark クラスターから Azure ストレージアカウント
Azure Synapse から Azure ストレージアカウント

Azure Storage へのアクセスの構成

Azure Databricks と Synapse の両方で、一時データストレージに使用される Azure ストレージアカウントへの特権アクセスが必要です。

Azure Synapse では、ストレージアカウントのアクセスに SAS の使用はサポートされていません。両方のサービスのアクセスを構成するには、次のいずれかの操作を行います。

ストレージアカウントのアカウントキーとシークレットを使用し、forwardSparkAzureStorageCredentials を true に設定します。「Spark プロパティを設定して Azure ストレージにアクセスする Azure 資格情報を構成する」を参照してください。
OAuth 2.0 認証で Azure Data Lake Storage Gen2 を使用し、enableServicePrincipalAuth を true に設定します。「サービスプリンシパルで OAuth 2.0 を使用して Azure Databricks から Synapse への接続を構成する」をご覧ください。
管理サービス ID を使うように Azure Synapse インスタンスを構成し、useAzureMSI を true に設定します。

必要な Azure Synapse のアクセス許可

バックグラウンドで COPY が使用されるため、Azure Synapse コネクタでは、JDBC 接続ユーザーが、接続されている Azure Synapse インスタンスで次のコマンドを実行するためのアクセス許可を持つ必要があります。

COPY INTO

コピー先のテーブルが Azure Synapse に存在しない場合は、上記のコマンドに加えて、次のコマンドを実行するアクセス許可が必要です。

CREATE TABLE

次の表に、COPY による書き込みに必要なアクセス許可をまとめています。

アクセス許可 (既存のテーブルへの挿入)	アクセス許可 (新しいテーブルへの挿入)
ADMINISTER DATABASE BULK OPERATIONS INSERT	ADMINISTER DATABASE BULK OPERATIONS INSERT CREATE TABLE ALTER ON SCHEMA :: dbo

ネットワークの構成

Azure Synapse でファイアウォールを構成する場合は、Azure Databricks で Azure Synapse に到達できるようにネットワーク設定を構成する必要があります。まず、「Azure Virtual Network で Azure Databricks をデプロイする (VNet インジェクション)」に従って、Azure Databricks ワークスペースが自分の仮想ネットワークにデプロイされていることを確認します。次に、Azure Synapse で IP ファイアウォール規則を構成して、お使いのサブネットから Synapse アカウントへの接続を許可することができます。「Azure Synapse Analytics の IP ファイアウォール規則」を参照してください。

サービスプリンシパルで OAuth 2.0 を使用して Azure Databricks から Synapse への接続を構成する

基になるストレージアカウントへのアクセス許可を持つサービスプリンシパルを使用して、Azure Synapse Analytics に対する認証を行うことができます。サービスプリンシパルの資格情報を使用して Azure ストレージアカウントにアクセスする方法の詳細については、「Azure Data Lake Storage Gen2 と Blob Storage に接続する」を参照してください。コネクタがサービスプリンシパルによって認証できるようにするには、接続構成 Azure Databricks Synapse コネクタオプションリファレンスで enableServicePrincipalAuth オプションを true に設定する必要があります。

必要に応じて、Azure Synapse Analytics 接続に別のサービスプリンシパルを使用することもできます。次の例では、ストレージアカウントのサービスプリンシパル資格情報と、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>")

バッチ書き込みでサポートされる保存モード

Azure Synapse では、ErrorIfExists、Ignore、Append、Overwrite の保存モードがサポートされています。既定のモードは ErrorIfExists です。 Apache Spark でサポートされている保存モードの詳細については、「保存モードの Spark SQL ドキュメント」を参照してください。

Azure Databricks Synapse コネクタのオプションリファレンス

Spark SQL に用意されている OPTIONS では、次の設定がサポートされています。

パラメーター	必須	Default	メモ
`dbTable`	はい (`query` を指定した場合を除く)	既定値なし	Azure Synapse で作成または読み取りを行うテーブル。このパラメーターは、データを Azure Synapse に保存するときに必要です。また、`{SCHEMA NAME}.{TABLE NAME}` を使用して、特定のスキーマのテーブルにアクセスすることもできます。スキーマ名が指定されていない場合は、JDBC ユーザーに関連付けられている既定のスキーマが使用されます。以前にサポート対象であった `dbtable` バリアントは非推奨とされ、今後のリリースでは無視されます。代わりに "キャメルケース" の名前を使用してください。
`query`	はい (`dbTable` を指定した場合を除く)	既定値なし	Azure Synapse で読み取るクエリ。クエリで参照されているテーブルでは、`{SCHEMA NAME}.{TABLE NAME}` を使用して、特定のスキーマのテーブルにアクセスすることもできます。スキーマ名が指定されていない場合は、JDBC ユーザーに関連付けられている既定のスキーマが使用されます。
`user`	いいえ	既定値なし	Azure Synapse ユーザー名。 `password` オプションと共に使用する必要があります。ユーザーとパスワードが URL に渡されない場合にのみ使用できます。両方を渡すと、エラーになります。
`password`	いいえ	既定値なし	Azure Synapse パスワード。 `user` オプションと共に使用する必要があります。ユーザーとパスワードが URL に渡されない場合にのみ使用できます。両方を渡すと、エラーになります。
`url`	はい	既定値なし	`sqlserver` がサブプロトコルとして設定された JDBC URL。 Azure portal が提供する接続文字列を使用することをお勧めします。 Setting JDBC 接続の SSL 暗号化を有効にするため、`encrypt=true` を強くお勧めします。 `user` と `password` が個別に設定されている場合は、それらを URL に含める必要はありません。
`jdbcDriver`	いいえ	JDBC URL のサブプロトコルによって決定されます	使用する JDBC ドライバーのクラス名。このクラスは、クラスパス上にある必要があります。ほとんどの場合、適切なドライバークラス名が JDBC URL のサブプロトコルによって自動的に決定されるため、このオプションを指定する必要はありません。以前にサポート対象であった `jdbc_driver` バリアントは非推奨とされ、今後のリリースでは無視されます。代わりに "キャメルケース" の名前を使用してください。
`tempDir`	はい	既定値なし	`abfss` URI。 Azure Synapse には専用の Blob ストレージコンテナーを使用することをお勧めします。以前にサポート対象であった `tempdir` バリアントは非推奨とされ、今後のリリースでは無視されます。代わりに "キャメルケース" の名前を使用してください。 Unity Catalog で定義されている外部の場所を `tempDir` の場所として使用することはできません。
`tempCompression`	いいえ	`SNAPPY`	Spark と Azure Synapse の両方で一時的なエンコード/デコードに使用される圧縮アルゴリズム。現在サポートされている値は、`UNCOMPRESSED`、`SNAPPY` および `GZIP` です。
`forwardSparkAzureStorageCredentials`	いいえ	false	`true` の場合、ライブラリは、Spark が Blob Storage コンテナーへの接続に使っているストレージアカウントのアクセスキーの資格情報を自動的に検出し、それらの資格情報を JDBC 経由で Azure Synapse に転送します。これらの資格情報は、JDBC クエリの一部として送信されます。このため、このオプションを使用する場合は、JDBC 接続の SSL 暗号化を有効にすることを強くお勧めします。ストレージ認証を構成する場合は、`useAzureMSI` と `forwardSparkAzureStorageCredentials` の正確に 1 つだけを `true` に設定する必要があります。または、`enableServicePrincipalAuth` を `true` に設定し、JDBC およびストレージ認証の両方にサービスプリンシパルを使用することもできます。 `forwardSparkAzureStorageCredentials` オプションでは、管理サービス ID またはサービスプリンシパルを使ったストレージに対する認証はサポートされていません。サポートされているのはストレージアカウントのアクセスキーのみです。以前にサポート対象であった `forward_spark_azure_storage_credentials` バリアントは非推奨とされ、今後のリリースでは無視されます。代わりに "キャメルケース" の名前を使用してください。
`useAzureMSI`	いいえ	false	`true` の場合、ライブラリは、作成するデータベーススコープ資格情報に対して `IDENTITY = 'Managed Service Identity'` を指定し、`SECRET` は指定しません。ストレージ認証を構成する場合は、`useAzureMSI` と `forwardSparkAzureStorageCredentials` の正確に 1 つだけを `true` に設定する必要があります。または、`enableServicePrincipalAuth` を `true` に設定し、JDBC およびストレージ認証の両方にサービスプリンシパルを使用することもできます。
`enableServicePrincipalAuth`	いいえ	false	`true` の場合、ライブラリは提供されたサービスプリンシパルの資格情報を使用して、Azure ストレージアカウントと Azure Synapse Analytics OVER JDBC に接続します。 `forward_spark_azure_storage_credentials` または `useAzureMSI` のいずれかが `true` に設定されている場合、そのオプションがストレージ認証でサービスプリンシパルよりも優先されます。
`tableOptions`	いいえ	`CLUSTERED COLUMNSTORE INDEX`, `DISTRIBUTION = ROUND_ROBIN`	`dbTable` で設定された Azure Synapse テーブルを作成するときにテーブルオプションを指定するために使用する文字列。この文字列は、Azure Synapse に対して発行される `WITH` SQL ステートメントの `CREATE TABLE` 句に文字どおり渡されます。以前にサポート対象であった `table_options` バリアントは非推奨とされ、今後のリリースでは無視されます。代わりに "キャメルケース" の名前を使用してください。
`preActions`	いいえ	既定値なし ( 空の文字列)	Azure Synapse インスタンスにデータを書き込む前に、Azure Synapse で実行される SQL コマンドの `;` 区切りリスト。これらの SQL コマンドは、Azure Synapse で使用できる有効なコマンドである必要があります。これらのコマンドが失敗した場合、エラーとして扱われるので、書き込み操作は実行されません。
`postActions`	いいえ	既定値なし ( 空の文字列)	コネクタが正常に Azure Synapse インスタンスにデータを書き込んだ後、Azure Synapse で実行される SQL コマンドの `;` 区切りリスト。これらの SQL コマンドは、Azure Synapse で使用できる有効なコマンドである必要があります。これらのコマンドが失敗した場合は、エラーとして扱われるので、データが Azure Synapse インスタンスに正常に書き込まれた後に例外が発生します。
`maxStrLength`	いいえ	256	Spark の `StringType` は、Azure Synapse の `NVARCHAR(maxStrLength)` 型にマッピングされます。 `maxStrLength` を使用して、名前を持つテーブル内にある、すべての `NVARCHAR(maxStrLength)` 型の列に対して文字列の長さを設定できます Azure Synapse の `dbTable`。以前にサポート対象であった `maxstrlength` バリアントは非推奨とされ、今後のリリースでは無視されます。代わりに "キャメルケース" の名前を使用してください。
`applicationName`	いいえ	`Databricks-User-Query`	各クエリの接続のタグ。指定されていない場合、または値が空の文字列の場合は、タグの既定値に JDBC URL が追加されます。既定値を指定すると、Azure DB 監視ツールでクエリに対して誤った SQL インジェクションアラートが発生するのを防ぎます。
`maxbinlength`	いいえ	既定値なし	`BinaryType` 列の長さを制御します。このパラメーターは、`VARBINARY(maxbinlength)` として変換されます。
`identityInsert`	いいえ	false	`true` を `IDENTITY_INSERT` に設定すると、Azure Synapse テーブルの ID 列に DataFrame 指定の値が挿入されます。「IDENTITY 列に値を明示的に挿入する」を参照してください。
`externalDataSource`	いいえ	既定値なし	Azure Synapse からデータを読み取る事前にプロビジョニングされた外部データソース。外部データソースは PolyBase でのみ使用できます。コネクタは、データを読み込むためにスコープ資格情報と外部データソースを作成する必要がないので、CONTROL アクセス許可の要件は削除されます。既存の外部データソースを使用する場合に必要な使用状況とアクセス許可の一覧については、「外部オプションを使用して PolyBase に必要な Azure Synapse アクセス許可を取得する」を参照してください。
`maxErrors`	いいえ	0	読み込み操作がキャンセルされるまでの、読み取り中または書き込み中に拒否できる行の最大数。拒否された行は無視されます。たとえば、10 レコード中 2 レコードにエラーがある場合、処理されるのは 8 レコードのみです。 REJECT_VALUE ドキュメントの CREATE EXTERNAL TABLE と MAXERRORS ドキュメントの COPY を参照してください。
`inferTimestampNTZType`	いいえ	false	`true` の場合、Azure Synapse `TIMESTAMP` の値は、読み取り中に `TimestampNTZType` (タイムゾーンのないタイムスタンプ) として解釈されます。それ以外の場合、基になる Azure Synapse テーブルでの型に関係なく、すべてのタイムスタンプが `TimestampType` として解釈されます。

注意

tableOptions、preActions、postActions、maxStrLength は、Azure Databricks のデータを、Azure Synapse の新しいテーブルに書き込む場合にのみ使用します。
すべてのデータソースオプション名では大文字と小文字が区別されませんが、わかりやすくするために"キャメルケース" で指定することをお勧めします。

Azure Synapse へのクエリプッシュダウン

この Azure Synapse コネクタでは、次の演算子を一連の最適化規則を実装して、次の演算子を Azure Synapse にプッシュします。

Filter
Project
Limit

演算子 Project と演算子 Filter は、次の式をサポートします。

ほとんどのブール型ロジック演算子
比較
基本的な算術演算
数値と文字列のキャスト

Limit 演算子の場合、順序が指定されていない場合にのみ、プッシュダウンがサポートされます。次に例を示します。

SELECT TOP(10) * FROM table、ただし SELECT TOP(10) * FROM table ORDER BY col は使用できません。

注意

Azure Synapse コネクタは、文字列、日付、またはタイムスタンプで動作する式をプッシュダウンしません。

Azure Synapse コネクタを使用して構築されたクエリプッシュは、既定では有効になっています。 spark.databricks.sqldw.pushdown を false に設定して、サイズ変更を無効にすることもできます。

一時的なデータ管理

Azure Synapse コネクタでは、Azure ストレージコンテナーに作成される一時ファイルが削除されません。 Databricks では、ユーザーが指定した tempDir の場所にある一時ファイルを定期的に削除することが推奨されます。

データを容易にクリーンアップできるよう、Azure Synapse コネクタは、データファイルを tempDir の下に直接格納するのではなく、<tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/ という形式のサブディレクトリを作成します。 (Azure Databricks ジョブ機能を使用するか、それ以外の方法で) 定期的なジョブを設定して、特定のしきい値より使用していないサブディレクトリ (たとえば、2 日) を再帰的に削除できます。そのしきい値を超える Spark ジョブを実行することはできません。

より簡単な方法は、コンテナー全体を定期的に削除し、同じ名前の新しいコンテナーを作成する方法です。これには、Azure Synapse コネクタによって生成された一時データに、専用のコンテナーを使用する必要があります。また、コネクタに関連するクエリが実行されないことを保証できる時間枠を見つける必要があります。

一時的なオブジェクト管理

Azure Synapse コネクタは、Azure Databricks クラスターと Azure Synapse インスタンスの間のデータ転送を自動化します。 Azure Synapse テーブルからデータを読み取り、クエリを実行する場合や、Azure Synapse テーブルにデータを書き込む場合、Azure Synapse コネクタは、DATABASE SCOPED CREDENTIAL、EXTERNAL DATA SOURCE、EXTERNAL FILE FORMAT、EXTERNAL TABLE などの一時オブジェクトを背後で作成します。これらのオブジェクトは、対応する Spark ジョブの期間中のみ有効であり、自動的に削除されます。

クラスターが Azure Synapse コネクタを使用してクエリを実行している場合、Spark ドライバープロセスがクラッシュまたは強制的に再起動された場合、またはクラスターが強制的に終了または再起動された場合、一時オブジェクトが削除されない可能性があります。これらのオブジェクトを容易に識別および手動で削除できるよう、Azure Synapse コネクタは、Azure Synapse インスタンスで作成された中間一時オブジェクトの名前の先頭に、tmp_databricks_<yyyy_MM_dd_HH_mm_ss_SSS>_<randomUUID>_<internalObject> という形式のタグを付けます。

次のようなクエリを使用して、リークしたオブジェクトを定期的に検索することをお勧めします。

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

Azure Synapse Analytics のクエリ データ

Synapse の構文の例

Scala

Python

SQL

R

Azure Databricks と Synapse の間の認証のしくみ

Azure Storage へのアクセスの構成

必要な Azure Synapse のアクセス許可

ネットワークの構成

サービス プリンシパルで OAuth 2.0 を使用して Azure Databricks から Synapse への接続を構成する

ini

Scala

Python

R

バッチ書き込みでサポートされる保存モード

Azure Databricks Synapse コネクタのオプション リファレンス

Azure Synapse へのクエリ プッシュダウン

一時的なデータ管理

一時的なオブジェクト管理

その他のリソース

Azure Synapse Analytics のクエリデータ

サービスプリンシパルで OAuth 2.0 を使用して Azure Databricks から Synapse への接続を構成する

Azure Databricks Synapse コネクタのオプションリファレンス

Azure Synapse へのクエリプッシュダウン