Azure Synapse Analytics에서 데이터 쿼리

아티클
11/07/2024

Azure Synapse에서 임시 스테이징에 Azure Data Lake Storage Gen2 스토리지 계정을 사용하여 Azure Databricks 클러스터와 Azure Synapse 인스턴스 간에 대량의 데이터를 효율적으로 전송하는 Azure Synapse 커넥터(Azure Synapse에서 COPY 문 사용)를 사용하여 Azure Databricks의 Azure Synapse에 액세스할 수 있습니다.

Important

이 문서에서 설명한 구성은 실험적입니다. 실험적 기능은 있는 그대로 제공되며 Databricks에서 고객 기술 지원을 통해 지원하지 않습니다. 전체 쿼리 페더레이션 지원을 받으려면 Azure Databricks 사용자가 Unity 카탈로그 구문 및 데이터 거버넌스 도구를 활용하는 데 도움이 되는 Lakehouse Federation을 대신 사용해야 합니다.

Azure Synapse Analytics는 MPP(대규모 병렬 처리)를 활용하는 클라우드 기반 엔터프라이즈 데이터 웨어하우스이며 페타바이트 데이터에서 복잡한 쿼리를 신속하게 실행합니다.

Important

이 커넥터는 Synapse 전용 풀 인스턴스에서만 사용되며 다른 Synapse 구성 요소와 호환되지 않습니다.

참고 항목

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 인스턴스 간에 전송되는 모든 데이터에 대해 SSL(Secure Sockets Layer) 암호화를 사용하도록 설정합니다. SSL 암호화를 사용하도록 설정되어 있는지 확인하려면 연결 문자열에서 encrypt=true를 검색할 수 있습니다.

Important

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 커넥터는 다음 세 가지 유형의 네트워크 연결을 사용합니다.

Azure Synapse에 대한 Spark 드라이버
Spark 클러스터에서 Azure Storage 계정으로
Azure 스토리지 계정에 대한 Azure Synapse

Azure Storage에 대한 액세스 구성

Azure Databricks와 Synapse는 모두 임시 데이터 스토리지에 사용할 Azure Storage 계정에 대한 권한 있는 액세스가 필요합니다.

Azure Synapse는 스토리지 계정 액세스에 SAS 사용을 지원하지 않습니다. 다음 중 하나를 수행하여 두 서비스에 대한 액세스를 구성할 수 있습니다.

스토리지 계정의 계정 키와 비밀을 사용하고 forwardSparkAzureStorageCredentials를 true로 설정합니다. Azure Storage에 액세스 가능한 Azure 자격 증명을 구성하도록 Spark 속성 설정을 참조하세요.
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 작업 영역이 자체 가상 네트워크에 배포되었는지 확인합니다. 그런 다음, 서브넷에서 Synapse 계정으로의 연결을 허용하도록 Azure Synapse에서 IP 방화벽 규칙을 구성할 수 있습니다. 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인 ErrorIfExists, Ignore, Append 및 Overwrite 저장 모드를 지원합니다. Apache Spark에서 지원되는 저장 모드에 대한 자세한 내용은 Spark SQL 설명서의 저장 모드를 참조하세요.

Azure Databricks Synapse 커넥터 옵션 참조

Spark SQL에 제공된 OPTIONS는 다음 설정을 지원합니다.

매개 변수	Required	기본값	주의
`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에서 제공하는 연결 문자열을 사용하는 것이 좋습니다. 설정 `encrypt=true`는 JDBC 연결에 SSL 암호화를 사용하도록 설정하므로 권장됩니다. `user`와 `password`가 별도로 설정된 경우 URL에 포함할 필요가 없습니다.
`jdbcDriver`	아니요	JDBC URL의 하위 프로토콜에 의해 결정됨	사용할 JDBC 드라이버의 클래스 이름입니다. 이 클래스는 클래스 경로에 있어야 합니다. 대부분의 경우 적절한 드라이버 클래스 이름이 JDBC URL의 하위 프로토콜에 의해 자동으로 결정되므로 이 옵션을 지정할 필요가 없습니다. 이전에 지원된 `jdbc_driver` 변형은 더 이상 사용되지 않으며 이후 릴리스에서 무시됩니다. 대신 "대/소문자를 구분한" 이름을 사용합니다.
`tempDir`	예	기본값 없음	`abfss` URI입니다. Azure Synapse에 전용 Blob Storage 컨테이너를 사용하는 것이 좋습니다. 이전에 지원된 `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` 중 하나를 `true`로 설정해야 합니다. 또는 `enableServicePrincipalAuth`를 `true`로 설정하고 JDBC 및 스토리지 인증 모두에 서비스 주체를 사용할 수 있습니다. `forwardSparkAzureStorageCredentials` 옵션은 관리 서비스 ID 또는 서비스 주체를 사용하여 스토리지에 대한 인증을 지원하지 않습니다. 스토리지 계정 액세스 키만 지원됩니다. 이전에 지원된 `forward_spark_azure_storage_credentials` 변형은 더 이상 사용되지 않으며 이후 릴리스에서 무시됩니다. 대신 "대/소문자를 구분한" 이름을 사용합니다.
`useAzureMSI`	아니요	false	`true`인 경우 라이브러리는 만든 데이터베이스 범위 자격 증명에 대해 `IDENTITY = 'Managed Service Identity'`를 지정하고 `SECRET`을 지정하지 않습니다. 스토리지 인증을 구성할 때는 정확히 `useAzureMSI` 및 `forwardSparkAzureStorageCredentials` 중 하나를 `true`로 설정해야 합니다. 또는 `enableServicePrincipalAuth`를 `true`로 설정하고 JDBC 및 스토리지 인증 모두에 서비스 주체를 사용할 수 있습니다.
`enableServicePrincipalAuth`	아니요	false	`true`인 경우 라이브러리는 제공된 서비스 주체 자격 증명을 사용하여 JDBC를 통해 Azure Storage 계정 및 Azure Synapse Analytics에 연결합니다. `forward_spark_azure_storage_credentials` 또는 `useAzureMSI`가 `true`로 설정된 경우 해당 옵션이 스토리지 인증의 서비스 주체보다 우선합니다.
`tableOptions`	아니요	`CLUSTERED COLUMNSTORE INDEX`: `DISTRIBUTION = ROUND_ROBIN`	`dbTable`을 통해 설정된 Azure Synapse 테이블을 만들 때 테이블 옵션을 지정하는 데 사용되는 문자열입니다. 이 문자열은 Azure Synapse에 대해 발급된 `CREATE TABLE` SQL 문의 `WITH` 절에 글자 그대로 전달됩니다. 이전에 지원된 `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개의 레코드만 처리됩니다. CREATE EXTERNAL TABLE의 REJECT_VALUE 설명서 및 COPY의 MAXERRORS 설명서를 참조하세요.
`inferTimestampNTZType`	아니요	false	`true`이면 읽기 중에 Azure Synapse `TIMESTAMP` 형식의 값이 `TimestampNTZType`(표준 시간대가 없는 타임스탬프)로 해석됩니다. 그렇지 않을 경우 모든 타임스탬프가 기본 Azure Synapse 테이블의 형식에 관계없이 `TimestampType`으로 해석됩니다.

참고 항목

tableOptions, preActions, postActions 및 maxStrLength는 Azure Databricks의 데이터를 Azure Synapse의 새 테이블에 쓸 때만 관련이 있습니다.
모든 데이터 원본 옵션 이름은 대/소문자를 구분하지 않지만 명확성을 위해 "대/소문자를 구분하여" 지정하는 것이 좋습니다.

Azure Synapse Analytics로 쿼리 푸시다운

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 Storage 컨테이너에서 만든 임시 파일을 삭제하지 않습니다. 사용자가 제공한 tempDir 위치에서 임시 파일을 주기적으로 삭제하는 것이 좋습니다.

데이터 정리를 용이하게 하기 위해 Azure Synapse 커넥터는 데이터 파일을 tempDir 바로 아래에 저장하지 않고 대신 <tempDir>/<yyyy-MM-dd>/<HH-mm-ss-SSS>/<randomUUID>/ 형식의 하위 디렉터리를 만듭니다. 제공된 임계값보다 오래 실행되는 Spark 작업은 있을 수 없다고 가정하고, 제공된 임계값보다 오래된(예: 2일) 하위 디렉터리를 재귀적으로 삭제하도록 주기적 작업(Azure Databricks 작업 기능 사용 여부와 관계 없이)을 설정할 수 있습니다.

더 간단한 대안은 전체 컨테이너를 주기적으로 삭제하고 이름이 같은 새 컨테이너를 만드는 것입니다. 이렇게 하려면 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 Analytics로 쿼리 푸시다운

임시 데이터 관리

임시 개체 관리

피드백

추가 리소스