Azure Synapse Analytics のクエリデータ

2025-04-17

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

重要

従来のクエリフェデレーションドキュメントは廃止され、更新されない可能性があります。このコンテンツに記載されている構成は、Databricks によって公式に承認またはテストされていません。 Lakehouse Federation がソースデータベースをサポートしている場合、Databricks では代わりにこれを使用することをお勧めします。

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

重要

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

注

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

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 の場所としてサポートされていません。

Databricks では、使用可能な最も安全な認証フローを使用することをお勧めします。この例で説明する認証フローには、他のフローに存在しないリスクがあります。このフローは、マネージド ID など、より安全なフローが実行可能ではない場合にのみ使用してください。

スカラ (プログラミング言語)


// 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 に設定します。 Azure Storage にアクセスするための Azure 資格情報を構成するための Spark プロパティの設定に関するページを参照してください。
OAuth 2.0 認証で Azure Data Lake Storage を使用し、 enableServicePrincipalAuth を true に設定します。「サービスプリンシパルを使用して OAuth 2.0 を使用して Azure Databricks から Synapse への接続を構成する」を参照してください。
マネージドサービス ID を持つ Azure Synapse インスタンスを構成し、 useAzureMSI を true に設定します。

必要な Azure Synapse アクセス許可

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

COPY INTO

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

CREATE TABLE

次の表は、 COPYを使用した書き込みに必要なアクセス許可をまとめたものです。

アクセス許可 (既存のテーブルへの挿入)	アクセス許可 (新しいテーブルへの挿入)
データベースの一括操作の管理 INSERT	データベースの一括操作の管理 INSERT CREATE TABLE ALTER ON SCHEMA :: dbo

ネットワーク構成

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

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

基になるストレージアカウントへのアクセス許可を持つサービスプリンシパルを使用して、Azure Synapse Analytics に対する認証を行うことができます。サービスプリンシパルの資格情報を使用して Azure ストレージアカウントにアクセスする方法の詳細については、「 Azure Data Lake Storage と Blob Storage への接続」を参照してください。コネクタがサービスプリンシパルによって認証できるようにするには、接続構成 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>

スカラ (プログラミング言語)

// 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 では、次の設定がサポートされています。

パラメーター	必須	既定値	注記
`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 が提供する接続文字列を使用することをお勧めします。 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`	いいえ	偽り	`true`場合、ライブラリは Spark が Blob Storage コンテナーへの接続に使用しているストレージアカウントアクセスキーの資格情報を自動的に検出し、それらの資格情報を JDBC 経由で Azure Synapse に転送します。これらの資格情報は、JDBC クエリの一部として送信されます。このため、このオプションを使用する場合は、JDBC 接続の SSL 暗号化を有効にすることを強くお勧めします。ストレージ認証を構成するときは、 `useAzureMSI` と `forwardSparkAzureStorageCredentials` のいずれかを `true`に設定する必要があります。または、 `enableServicePrincipalAuth` を `true` に設定し、JDBC 認証とストレージ認証の両方にサービスプリンシパルを使用することもできます。 `forwardSparkAzureStorageCredentials` オプションでは、マネージドサービス ID またはサービスプリンシパルを使用したストレージへの認証はサポートされていません。ストレージアカウントのアクセスキーのみがサポートされています。以前にサポート対象であった `forward_spark_azure_storage_credentials` バリアントは非推奨とされ、今後のリリースでは無視されます。代わりに "キャメルケース" の名前を使用してください。
`useAzureMSI`	いいえ	偽り	`true` の場合、ライブラリは、作成するデータベーススコープ資格情報に対して `IDENTITY = 'Managed Service Identity'` を指定し、`SECRET` は指定しません。ストレージ認証を構成するときは、 `useAzureMSI` と `forwardSparkAzureStorageCredentials` のいずれかを `true`に設定する必要があります。または、 `enableServicePrincipalAuth` を `true` に設定し、JDBC 認証とストレージ認証の両方にサービスプリンシパルを使用することもできます。
`enableServicePrincipalAuth`	いいえ	偽り	`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` を使って、Azure Synapse の `NVARCHAR(maxStrLength)` という名前のテーブル内にあるすべての `dbTable` 型の列に対して、文字列の長さを設定できます以前にサポート対象であった `maxstrlength` バリアントは非推奨とされ、今後のリリースでは無視されます。代わりに "キャメルケース" の名前を使用してください。
`applicationName`	いいえ	`Databricks-User-Query`	各クエリの接続のタグ。指定されていない場合、または値が空の文字列の場合は、タグの既定値に JDBC URL が追加されます。既定値を指定すると、Azure DB 監視ツールでクエリに対して誤った SQL インジェクションアラートが発生するのを防ぎます。
`maxbinlength`	いいえ	既定値なし	`BinaryType` 列の長さを制御します。このパラメーターは、`VARBINARY(maxbinlength)` として変換されます。
`identityInsert`	いいえ	偽り	`true` を `IDENTITY_INSERT` に設定すると、Azure Synapse テーブルの ID 列に DataFrame 指定の値が挿入されます。「IDENTITY 列に値を明示的に挿入する」を参照してください。
`externalDataSource`	いいえ	既定値なし	Azure Synapse からデータを読み取る事前にプロビジョニングされた外部データソース。外部データソースは PolyBase でのみ使用でき、データを読み込むためのスコープ付き資格情報と外部データソースをコネクタで作成する必要がないため、CONTROL アクセス許可の要件は削除されます。既存の外部データソースを使用する場合に必要な使用状況とアクセス許可の一覧については、「外部オプションを使用して PolyBase に必要な Azure Synapse アクセス許可を取得する」を参照してください。
`maxErrors`	いいえ	0	読み込み操作が取り消されるまでの読み取りと書き込みの間に拒否できる行の最大数。拒否された行は無視されます。たとえば、10 レコード中 2 レコードにエラーがある場合、処理されるのは 8 レコードのみです。 CREATE EXTERNAL TABLE の REJECT_VALUE に関するドキュメントと COPY の MAXERRORS に関するドキュメントをご覧ください。
`inferTimestampNTZType`	いいえ	偽り	`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>/ という形式のサブディレクトリを作成します。 (Lakeflow ジョブ機能を使用して) 定期的なジョブを設定し、特定のしきい値 (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 の構文例

スカラ (プログラミング言語)

Python（プログラミング言語）

SQL

R

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

Azure Storage へのアクセスの構成

必要な Azure Synapse アクセス許可

ネットワーク構成

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

ini

スカラ (プログラミング言語)

Python（プログラミング言語）

R

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

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

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

一時的なデータ管理

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

フィードバック

その他のリソース

Azure Synapse Analytics のクエリデータ

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

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

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