Python용 Databricks SQL 커넥터

Python용 Databricks SQL Connector는 Python 코드를 사용하여 Azure Databricks 다목적 컴퓨팅 및 Databricks SQL 웨어하우스에서 SQL 명령을 실행할 수 있는 Python 라이브러리입니다. Python용 Databricks SQL 커넥터는 pyodbc와 같은 다른 비슷한 Python 라이브러리보다 쉽게 설정하고 사용할 수 있습니다. 이 라이브러리는 PEP 249 – Python 데이터베이스 API 사양 v2.0을 따릅니다.

중요합니다

Python 버전 3.0.0 이상용 Databricks SQL Connector는 네이티브 매개 변수가 있는 쿼리 실행을 지원하므로 SQL 삽입을 방지하고 쿼리 성능을 향상시킬 수 있습니다. 이전 버전은 SQL 삽입에서 안전하지 않고 다른 단점이 있는 인라인 매개 변수가 있는 실행을 사용했습니다. 자세한 내용은 네이티브 매개 변수 사용을 참조하세요.

Python용 Databricks SQL Connector는 Azure Databricks에 대한 SQLAlchemy 언어도 지원하지만 이러한 기능을 사용하려면 설치해야 합니다. Azure Databricks와 함께 SQLAlchemy 사용을 참조하세요.

요구 사항

Python 3.8 이상을 실행하는 개발 머신입니다.
Databricks는 Python에 포함된 venv에서 제공하는 환경과 같은 Python 가상 환경을 사용하는 것이 좋습니다. 가상 환경은 올바른 버전의 Python과 Python용 Databricks SQL 커넥터를 함께 사용하는 데 도움이 됩니다. 가상 환경 설정 및 사용은 이 문서의 범위를 벗어납니다. 자세한 내용은 가상 환경 만들기를 참조하세요.
기존 다목적 컴퓨팅 또는 SQL 웨어하우스입니다.

시작하기

Python용 Databricks SQL 커넥터를 설치합니다. PyArrow 는 Python용 Databricks SQL Connector의 선택적 종속성이며 커넥터 버전 4.0.0 이상에서는 기본적으로 설치되지 않습니다. PyArrow가 설치되지 않은 경우 CloudFetch 및 기타 Apache Arrow 기능과 같은 기능을 사용할 수 없으므로 대용량 데이터의 성능에 영향을 미칠 수 있습니다.
- lean 커넥터를 설치하려면 다음을 사용합니다.
```
pip install databricks-sql-connector
```
- PyArrow를 포함하여 전체 커넥터를 설치하려면 다음을 사용합니다.
```
pip install databricks-sql-connector[pyarrow]
```
사용하려는 다목적 컴퓨팅 또는 SQL 웨어하우스에 대해 다음 정보를 수집합니다.

모든 용도 컴퓨팅
- 다목적 컴퓨팅의 서버 호스트 이름입니다. 다목적 컴퓨팅에 대한 탭의 > 값에서 이 값을 가져올 수 있습니다.
- 다목적 컴퓨팅의 HTTP 경로입니다. 다목적 컴퓨팅에 대한 탭의 > 값에서 이 값을 가져올 수 있습니다.
참고

SQL 커넥터는 작업 컴퓨팅에 대한 연결을 지원하지 않습니다.

SQL 웨어하우스
- SQL 웨어하우스의 서버 호스트 이름. SQL 웨어하우스의 연결 세부 정보 탭의 서버 호스트 이름 값으로 확인할 수 있습니다.
- SQL 웨어하우스의 HTTP 경로. SQL 웨어하우스의 연결 세부 정보 탭의 HTTP 경로 값으로 확인할 수 있습니다.

인증

Python용 Databricks SQL 커넥터는 다음의 Azure Databricks 인증 유형을 지원합니다.

Databricks 개인용 액세스 토큰 인증
Microsoft Entra ID 토큰 인증
OAuth M2M(기계 간) 인증
OAuth 사용자 대 컴퓨터(U2M) 인증

Python용 Databricks SQL 커넥터는 다음의 Azure Databricks 인증 유형은 아직 지원하지 않습니다.

Databricks 개인용 액세스 토큰 인증

Azure Databricks 개인용 액세스 토큰 인증과 함께 Python용 Databricks SQL Connector를 사용하려면 먼저 Azure Databricks 개인용 액세스 토큰을 만들어야 합니다. 이렇게 하려면 작업 영역 사용자를 위한 개인용 액세스 토큰 만들기의 단계를 수행합니다.

Python용 Databricks SQL 커넥터를 인증하려면 다음 코드 조각을 사용합니다. 이 코드 조각에서는 다음 환경 변수를 설정한다고 가정합니다.

DATABRICKS_SERVER_HOSTNAME다목적 컴퓨팅 또는 SQL 웨어하우스에 대한 서버 호스트 이름 값으로 설정합니다.
DATABRICKS_HTTP_PATH- 다목적 컴퓨팅 또는 SQL 웨어하우스에 대한 HTTP 경로 값으로 설정합니다.
DATABRICKS_TOKEN, Azure Databricks 개인용 액세스 토큰으로 설정.

환경 변수를 설정하려면 운영 체제 설명서를 참조하세요.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

OAuth 기계 대 기계(M2M) 인증

Python 버전 2.7.0 이상용 Databricks SQL 커넥터는 OAuth M2M(컴퓨터 대 컴퓨터) 인증을 지원합니다. Python 0.18.0 이상 버전용 Databricks SDK도 설치해야 합니다(예: pip install databricks-sdk 또는 python -m pip install databricks-sdk 실행).

OAuth M2M 인증과 함께 Python용 Databricks SQL 커넥터를 사용하려면 다음을 수행해야 합니다.

Azure Databricks 작업 영역에서 Azure Databricks 서비스 주체를 만들고 해당 서비스 주체에 대한 OAuth 비밀을 만듭니다.

서비스 주체 및 해당 OAuth 비밀을 만들려면 OAuth를 사용하여 Azure Databricks에 대한 서비스 주체 액세스 권한 부여를 참조하세요. 서비스 주체의 UUID 또는 애플리케이션 ID 값과 서비스 주체의 OAuth 비밀에 대한 비밀 값을 기록해 둡니다.
해당 서비스 주체에게 다목적 컴퓨팅 또는 웨어하우스에 대한 액세스 권한을 부여합니다.

서비스 주체에게 다목적 컴퓨팅 또는 웨어하우스에 대한 액세스 권한을 부여하려면 컴퓨팅 사용 권한 또는 SQL 웨어하우스 관리를 참조하세요.

Python용 Databricks SQL 커넥터를 인증하려면 다음 코드 조각을 사용합니다. 이 코드 조각에서는 다음 환경 변수를 설정한다고 가정합니다.

DATABRICKS_SERVER_HOSTNAME 다목적 컴퓨팅 또는 SQL 웨어하우스에 대한 서버 호스트 이름 값으로 설정합니다.
DATABRICKS_HTTP_PATH- 다목적 컴퓨팅 또는 SQL 웨어하우스에 대한 HTTP 경로 값으로 설정합니다.
DATABRICKS_CLIENT_ID- 서비스 주체의 UUID 또는 애플리케이션 ID 값으로 설정합니다.
DATABRICKS_CLIENT_SECRET- 서비스 주체의 OAuth 비밀 에 대한 비밀 값으로 설정합니다.

환경 변수를 설정하려면 운영 체제 설명서를 참조하세요.

from databricks.sdk.core import Config, oauth_service_principal
from databricks import sql
import os

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

with sql.connect(server_hostname      = server_hostname,
                 http_path            = os.getenv("DATABRICKS_HTTP_PATH"),
                 credentials_provider = credential_provider) as connection:
# ...

Microsoft Entra ID 토큰 인증

Microsoft Entra ID 토큰 인증과 함께 Python용 Databricks SQL 커넥터를 사용하려면 Python용 Databricks SQL 커넥터에 Microsoft Entra ID 토큰을 제공해야 합니다. Microsoft Entra ID 액세스 토큰을 만들려면 다음을 수행합니다:

Azure Databricks 사용자의 경우 Azure CLI를 사용할 수 있습니다. 수동으로 Microsoft Entra ID 토큰 가져오기를 참조하세요.
Microsoft Entra ID 서비스 주체에 대한 내용은 서비스 주체용 토큰 가져오기 참고를 참조하세요. Microsoft Entra ID 관리 서비스 주체를 만들려면 서비스 주체를 참조하세요.

Microsoft Entra ID 토큰의 기본 수명은 약 1시간입니다. 새 Microsoft Entra ID 토큰을 만들려면 이 프로세스를 반복합니다.

Python용 Databricks SQL 커넥터를 인증하려면 다음 코드 조각을 사용합니다. 이 코드 조각에서는 다음 환경 변수를 설정한다고 가정합니다.

다목적 컴퓨팅 또는 SQL 웨어하우스를 위한 DATABRICKS_SERVER_HOSTNAME 값으로 설정합니다.
DATABRICKS_HTTP_PATH을(를) 다목적 컴퓨팅 또는 SQL 웨어하우스의 HTTP 경로 값으로 설정합니다.
DATABRICKS_TOKEN을 Microsoft Entra ID 토큰으로 설정합니다.

환경 변수를 설정하려면 운영 체제 설명서를 참조하세요.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:
# ...

OAuth 사용자 대 컴퓨터(U2M) 인증

Python 2.7.0 이상 버전용 Databricks SQL 커넥터는 OAuth U2M(사용자 대 컴퓨터) 인증을 지원합니다. Python 0.19.0 이상 버전용 Databricks SDK도 설치해야 합니다(예: pip install databricks-sdk 또는 python -m pip install databricks-sdk 실행).

OAuth U2M 인증으로 Python용 Databricks SQL 커넥터를 인증하려면 다음 코드 조각을 사용합니다. OAuth U2M 인증은 실시간 사용자 로그인 및 대상 Azure Databricks 사용자 계정 인증을 위한 동의를 사용합니다. 이 코드 조각에서는 다음 환경 변수를 설정한다고 가정합니다.

다목적 컴퓨팅 또는 SQL 웨어하우스를 위한 DATABRICKS_SERVER_HOSTNAME 값으로 설정합니다.
DATABRICKS_HTTP_PATH을(를) 다목적 컴퓨팅 또는 SQL 웨어하우스의 HTTP 경로 값으로 설정합니다.

환경 변수를 설정하려면 운영 체제 설명서를 참조하세요.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 auth_type       = "databricks-oauth") as connection:
# ...

예제

다음 코드 예제에서는 Databricks SQL Connector for Python을 사용하여 데이터를 쿼리 및 삽입하고, 메타데이터를 쿼리하고, 커서 및 연결을 관리하고, Unity 카탈로그에서 파일을 관리하고, 로깅을 구성하는 방법을 보여 줍니다.

참고

다음 코드 예제에서는 인증에 Azure Databricks 개인용 액세스 토큰을 사용하는 방법을 보여 줍니다. 다른 인증 유형을 사용하려면 인증을 참조 하세요.

이러한 코드 예제는 다음 환경 변수에서 해당 server_hostname, http_path 및 access_token 연결 변수 값을 검색합니다.

DATABRICKS_SERVER_HOSTNAME - 요구 사항의 서버 호스트 이름 값을 나타냅니다.
DATABRICKS_HTTP_PATH - 요구 사항의 HTTP 경로를 나타냅니다.
DATABRICKS_TOKEN - 요구 사항의 액세스 토큰을 나타냅니다.

User-Agent 설정

다음 코드 예제에서는 사용 현황 추적을 위해 User-Agent 애플리케이션 product_name 설정하는 방법을 보여 줍니다.

from databricks import sql
import os

with sql.connect(server_hostname   = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path         = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token      = os.getenv("DATABRICKS_TOKEN"),
                 user_agent_entry = "product_name") as connection:
  with connection.cursor() as cursor:
    cursor.execute("SELECT 1 + 1")
    result = cursor.fetchall()

    for row in result:
      print(row)

쿼리 데이터

다음 코드 예제에서는 Python용 Databricks SQL Connector를 호출하여 다목적 컴퓨팅 또는 SQL 웨어하우스에서 기본 SQL 명령을 실행하는 방법을 보여 줍니다. 이 명령은 trips 카탈로그의 samples 스키마에서 nyctaxi 테이블의 처음 두 행을 반환합니다.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
    result = cursor.fetchall()

    for row in result:
      print(row)

쿼리 태그

중요합니다

이 기능은 비공개 프리뷰. 액세스를 요청하려면 계정 팀에 문의하세요.

다음 예제에서는 추적 및 분석을 위해 SQL 쿼리에 키-값 태그를 연결하는 방법을 보여 줍니다. 쿼리 태그가 테이블에 표시됩니다 system.query.history .

from databricks import sql
import os

with sql.connect(
    server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
    http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
    access_token    = os.getenv("DATABRICKS_TOKEN"),
    session_configuration = {
        'query_tags': 'team:engineering,dashboard:abc123,env:prod'
    }
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [2])
        result = cursor.fetchall()
        # Query is now tagged and trackable in system.query.history
        for row in result:
            print(row)

데이터 삽입

다음 예제에서는 적은 양의 데이터(수천 개의 행)를 삽입하는 방법을 보여 줍니다.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.execute("CREATE TABLE IF NOT EXISTS squares (x int, x_squared int)")

    squares = [(i, i * i) for i in range(100)]

    cursor.executemany("INSERT INTO squares VALUES (?, ?)", squares)

    cursor.execute("SELECT * FROM squares LIMIT ?", [10])

    result = cursor.fetchall()

    for row in result:
      print(row)

대용량 데이터의 경우 먼저 클라우드 스토리지에 데이터를 업로드한 다음 COPY INTO 명령을 실행해야 합니다.

메타데이터 쿼리

메타데이터를 찾아오기 위한 전용 메서드가 있습니다. 다음 예제에서는 샘플 테이블에서 열에 대한 메타데이터를 찾아옵니다.

from databricks import sql
import os

with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token    = os.getenv("DATABRICKS_TOKEN")) as connection:

  with connection.cursor() as cursor:
    cursor.columns(schema_name="default", table_name="squares")
    print(cursor.fetchall())

커서 및 연결 관리

더 이상 사용되지 않는 연결 및 커서를 닫는 것이 가장 좋습니다. 이렇게 하면 Azure Databricks 다목적 컴퓨팅 및 Databricks SQL 웨어하우스의 리소스가 해제됩니다.

컨텍스트 관리자(이전 예제에서 사용된 with 구문)를 사용하여 리소스를 관리하거나, 명시적으로 close를 호출할 수 있습니다.

from databricks import sql
import os

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")
print(cursor.fetchall())

cursor.close()
connection.close()

Unity 카탈로그 볼륨의 파일 관리

Databricks SQL 커넥터를 사용하면 다음 예제와 같이 Unity 카탈로그 볼륨에 로컬 파일을 작성하고, 볼륨에서 파일을 다운로드하고, 볼륨에서 파일을 삭제할 수 있습니다.

from databricks import sql
import os

# For writing local files to volumes and downloading files from volumes,
# you must set the staging_allowed_local_path argument to the path to the
# local folder that contains the files to be written or downloaded.
# For deleting files in volumes, you must also specify the
# staging_allowed_local_path argument, but its value is ignored,
# so in that case its value can be set for example to an empty string.
with sql.connect(server_hostname            = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                 http_path                  = os.getenv("DATABRICKS_HTTP_PATH"),
                 access_token               = os.getenv("DATABRICKS_TOKEN"),
                 staging_allowed_local_path = "/tmp/") as connection:

  with connection.cursor() as cursor:

    # Write a local file to the specified path in a volume.
    # Specify OVERWRITE to overwrite any existing file in that path.
    cursor.execute(
      "PUT '/tmp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE"
    )

    # Download a file from the specified path in a volume.
    cursor.execute(
      "GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'"
    )

    # Delete a file from the specified path in a volume.
    cursor.execute(
      "REMOVE '/Volumes/main/default/my-volume/my-data.csv'"
    )

로깅 구성

Databricks SQL 커넥터는 Python의 표준 로깅 모듈을 사용합니다. 다음 예제에서는 로깅 수준을 구성하고 디버그 로그를 생성합니다.

from databricks import sql
import os, logging

logging.getLogger("databricks.sql").setLevel(logging.DEBUG)
logging.basicConfig(filename = "results.log",
                    level    = logging.DEBUG)

connection = sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
                         http_path       = os.getenv("DATABRICKS_HTTP_PATH"),
                         access_token    = os.getenv("DATABRICKS_TOKEN"))

cursor = connection.cursor()

cursor.execute("SELECT * from range(10)")

result = cursor.fetchall()

for row in result:
   logging.debug(row)

cursor.close()
connection.close()

테스트

코드를 테스트하려면 pytest와 같은 Python 테스트 프레임워크를 사용합니다. Azure Databricks REST API 엔드포인트를 호출하지 않거나 Azure Databricks 계정 또는 작업 영역의 상태를 변경하지 않고 시뮬레이션된 조건에서 코드를 테스트하려면 unittest.mock와 같은 Python 모의 라이브러리를 사용할 수 있습니다.

예를 들어 Azure Databricks 개인용 액세스 토큰을 사용하여 Azure Databricks 작업 영역에 대한 연결을 반환하는 helpers.py 함수와 get_connection_personal_access_token 이 연결을 사용하여 카탈로그 스키마의 select_nyctaxi_trips 테이블에서 trips 지정된 수의 데이터 행 samples 을 가져오는 함수가 포함된 다음 nyctaxi 파일을 지정합니다.

# helpers.py

from databricks import sql
from databricks.sql.client import Connection, List, Row, Cursor

def get_connection_personal_access_token(
  server_hostname: str,
  http_path: str,
  access_token: str
) -> Connection:
  return sql.connect(
    server_hostname = server_hostname,
    http_path = http_path,
    access_token = access_token
  )

def select_nyctaxi_trips(
  connection: Connection,
  num_rows: int
) -> List[Row]:
  cursor: Cursor = connection.cursor()
  cursor.execute("SELECT * FROM samples.nyctaxi.trips LIMIT ?", [num_rows])
  result: List[Row] = cursor.fetchall()
  return result

그리고 main.py 및 get_connection_personal_access_token 함수를 호출하는 select_nyctaxi_trips라는 이름의 다음 파일을 가정합니다.

# main.py

from databricks.sql.client import Connection, List, Row
import os
from helpers import get_connection_personal_access_token, select_nyctaxi_trips

connection: Connection = get_connection_personal_access_token(
  server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
  http_path = os.getenv("DATABRICKS_HTTP_PATH"),
  access_token = os.getenv("DATABRICKS_TOKEN")
)

rows: List[Row] = select_nyctaxi_trips(
  connection = connection,
  num_rows = 2
)

for row in rows:
  print(row)

test_helpers.py(으)로 명명된 다음 파일은 select_nyctaxi_trips 함수가 예상 응답을 반환하는지 여부를 테스트합니다. 이 테스트는 대상 작업 영역에 대한 실제 연결을 만드는 대신 Connection 개체를 모의합니다. 또한 이 테스트는 실제 데이터에 있는 스키마 및 값을 준수하는 일부 데이터를 모의합니다. 이 테스트는 모의 연결을 통해 모의 데이터를 반환한 다음 모의 데이터 행 값 중 하나가 예상 값과 일치하는지 확인합니다.

# test_helpers.py

import pytest
from databricks.sql.client import Connection, List, Row
from datetime import datetime
from helpers import select_nyctaxi_trips
from unittest.mock import create_autospec

@pytest.fixture
def mock_data() -> List[Row]:
  return [
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 14, 16, 52, 13),
      tpep_dropoff_datetime = datetime(2016, 2, 14, 17, 16, 4),
      trip_distance = 4.94,
      fare_amount = 19.0,
      pickup_zip = 10282,
      dropoff_zip = 10171
    ),
    Row(
      tpep_pickup_datetime = datetime(2016, 2, 4, 18, 44, 19),
      tpep_dropoff_datetime = datetime(2016, 2, 4, 18, 46),
      trip_distance = 0.28,
      fare_amount = 3.5,
      pickup_zip = 10110,
      dropoff_zip = 10110
    )
  ]

def test_select_nyctaxi_trips(mock_data: List[Row]):
  # Create a mock Connection.
  mock_connection = create_autospec(Connection)

  # Set the mock Connection's cursor().fetchall() to the mock data.
  mock_connection.cursor().fetchall.return_value = mock_data

  # Call the real function with the mock Connection.
  response: List[Row] = select_nyctaxi_trips(
    connection = mock_connection,
    num_rows = 2)

  # Check the value of one of the mocked data row's columns.
  assert response[1].fare_amount == 3.5

select_nyctaxi_trips 함수는 SELECT 문을 포함하기 때문에 trips 테이블의 상태를 변경하지 않으므로 이 예제에서는 모의 작업이 반드시 필요하지는 않습니다. 그러나 모의 작업을 사용하면 작업 영역과의 실제 연결을 기다리지 않고 테스트를 신속하게 실행할 수 있습니다. 또한 모의 작업을 사용하면 다음과 같이 INSERT INTOUPDATEDELETE FROM테이블의 상태를 변경할 수 있는 함수에 대해 시뮬레이션된 테스트를 여러 번 실행할 수 있습니다.

API 참조

이 섹션에는 패키지에 대한 API 참조가 포함되어 있습니다 databricks-sql-connector . PyPI(Python 패키지 인덱스)에서 databricks-sql-connector 를 참조하세요.

모듈

패키지의 databricks.sql 모듈에는 databricks-sql-connector SQL 웨어하우스에 대한 연결을 초기화하는 메서드가 포함되어 있습니다.

connect 메서드

SQL 웨어하우스에 대한 연결을 초기화합니다. Connection 개체를 반환합니다.

매개 변수	유형	Description
`server_hostname`	`str`	필수 사항입니다. 다목적 컴퓨팅 또는 SQL 웨어하우스의 서버 호스트 이름입니다. 예를 들면 다음과 같습니다 `adb-1234567890123456.7.azuredatabricks.net`. 서버 호스트 이름을 얻으려면 시작의 지침을 참조 하세요.
`http_path`	`str`	필수 사항입니다. 다목적 컴퓨팅 또는 SQL 웨어하우스와 같은 `sql/protocolv1/o/1234567890123456/1234-567890-test123` 다목적 컴퓨팅 또는 `/sql/1.0/warehouses/a1b234c567d8e9fa` SQL 웨어하우스의 HTTP 경로입니다. HTTP 경로를 얻으려면 시작의 지침을 참조 하세요.
`access_token`, `auth_type`, `credentials_provider`, `passwordusername`	`str`	Azure Databricks 인증 설정에 대한 정보. 세부 정보는 인증을 참조하세요.
`session_configuration`	`dict[str, Any]`	Spark 세션 구성 매개 변수 사전입니다. 구성을 설정하는 것은 `SET key=val` SQL 명령을 사용하는 것과 동일합니다. SQL 명령 `SET -v`를 실행하여 사용 가능한 구성의 전체 목록을 가져옵니다. 기본값은 `None`입니다. 예: `{"spark.sql.variable.substitute": True}`
`http_headers`	`List[Tuple[str, str]]]`	Optional. 클라이언트가 수행하는 모든 RPC 요청에 대해 HTTP 헤더에 설정할 추가적인 (키, 값) 쌍입니다. 일반적인 사용법은 추가 HTTP 헤더를 설정하지 않습니다. 기본값은 `None`입니다.
`catalog`	`str`	Optional. 연결에 사용할 초기 카탈로그입니다. 기본값은 `None`이며, 이 경우 기본 카탈로그, 일반적으로 `hive_metastore`를 사용함이 적용됩니다.
`schema`	`str`	Optional. 연결에 사용할 초기 스키마입니다. 기본값은 `None`(이 경우 기본 스키마 `default`가 사용됨)입니다. 버전 2.0 이후
`use_cloud_fetch`	`bool`	Optional. 데이터 청크를 다운로드하기 위해 페치 요청을 클라우드 개체 저장소에 직접 보낼지 여부입니다. 기본값은 `True`입니다. `False`로 설정하여 페치 요청을 Azure Databricks에 직접 보냅니다. `use_cloud_fetch`가 `True`로 설정되었지만 네트워크 액세스가 차단된 경우 페치 요청은 실패합니다. 버전 2.8 이후
`user_agent_entry`	`str`	Optional. 사용 추적을 위해 HTTP 요청 헤더에 포함할 User-Agent 항목입니다. 기본값은 `PyDatabricksSqlConnector`입니다.

`Connection` 클래스

컴퓨팅 또는 SQL 웨어하우스에 대한 연결을 나타냅니다.

메서드

클래스는 Connection 다음 메서드를 제공합니다.

메서드	Description
`close`	데이터베이스에 대한 연결을 닫고 서버에서 연결된 모든 리소스를 해제합니다. 이 연결에 대한 추가 호출은 `Error`를 발생시킵니다. 매개 변수는 없습니다. 반환 값이 없습니다.
`cursor`	데이터베이스의 레코드를 트래버스할 수 있는 새 Cursor 개체 를 반환합니다. 매개 변수는 없습니다.

`Cursor` 클래스

데이터 레코드를 순회하는 메커니즘을 나타냅니다.

개체를 Cursor 만들려면 cursor의 메서드를 호출 합니다.

특성

선택한 Cursor 특성에는 다음이 포함됩니다.

특성 Description

arraysize fetchmany 메서드와 함께 사용되며 내부 버퍼 크기를 지정합니다. 이 크기는 한 번에 서버에서 실제로 페치되는 행 수이기도 합니다. 기본값은 10000입니다. 좁은 범위의 결과(각 행이 많은 데이터를 포함되지 않는 결과)를 얻으려면 성능 향상을 위해 이 값을 늘려야 합니다. 읽기 및 쓰기 권한입니다.

특성	Description
`arraysize`	`fetchmany` 메서드와 함께 사용되며 내부 버퍼 크기를 지정합니다. 이 크기는 한 번에 서버에서 실제로 페치되는 행 수이기도 합니다. 기본값은 `10000`입니다. 좁은 범위의 결과(각 행이 많은 데이터를 포함되지 않는 결과)를 얻으려면 성능 향상을 위해 이 값을 늘려야 합니다. 읽기 및 쓰기 권한입니다.
`description`	Python `list`로 구성된 `tuple` 개체를 포함합니다. 각 `tuple` 개체는 7개의 값을 포함하며, 각 `tuple` 개체의 처음 2개 항목은 다음과 같이 단일 결과 열을 설명하는 정보를 포함합니다. `name`: 열의 이름입니다. `type_code`: 열의 형식을 나타내는 문자열입니다. 예를 들어, 정수 열은 `int`라는 형식 코드를 갖습니다. 7개 항목으로 구성된 `tuple` 개체의 나머지 5개 항목은 구현되지 않았으며, 값이 정의되지 않았습니다. 일반적으로 4 `None` 개 값과 단일 `True` 값으로 반환됩니다. 읽기 전용 액세스입니다.

description

Python list로 구성된 tuple 개체를 포함합니다. 각 tuple 개체는 7개의 값을 포함하며, 각 tuple 개체의 처음 2개 항목은 다음과 같이 단일 결과 열을 설명하는 정보를 포함합니다.

name: 열의 이름입니다.
type_code: 열의 형식을 나타내는 문자열입니다. 예를 들어, 정수 열은 int라는 형식 코드를 갖습니다. 7개 항목으로 구성된 tuple 개체의 나머지 5개 항목은 구현되지 않았으며, 값이 정의되지 않았습니다. 일반적으로 4 None 개 값과 단일 True 값으로 반환됩니다. 읽기 전용 액세스입니다.

메서드

선택한 Cursor 메서드에는 다음 내용이 포함됩니다.

메서드	Description
`cancel`	커서가 시작된 데이터베이스 쿼리 또는 명령의 실행을 중단합니다. 관련된 리소스를 서버에서 해제하려면 `close` 메서드를 호출한 후 `cancel` 메서드를 호출하세요. 매개 변수는 없습니다. 반환 값이 없습니다.
`close`	커서를 닫고 서버에서 연결된 리소스를 해제합니다. 이미 닫힌 커서를 닫으면 오류가 발생할 수 있습니다. 매개 변수는 없습니다. 반환 값이 없습니다.
`execute`	데이터베이스 쿼리 또는 명령을 준비하고 실행합니다. 매개 변수: `operation`:필수. 준비하고 실행할 쿼리 또는 명령입니다. 형식: `str` 매개 변수가 `parameters` 없는 예제: `cursor.execute('SELECT * FROM samples.nyctaxi.trips LIMIT 2')` 매개 변수를 사용하는 예제(네이티브 위치 매개 변수를 사용): `parameters` `parameters`: 선택 사항입니다. `operation` 매개 변수와 함께 사용할 매개 변수 시퀀스입니다. 기본값은 `None`입니다. 유형: `dictionary` 반환 값이 없습니다.
`executemany`	`seq_of_parameters` 인수의 모든 매개 변수 시퀀스를 사용하여 데이터베이스 쿼리 또는 명령을 준비하고 실행합니다. 최종 결과 집합만 유지됩니다. 매개 변수: `operation`:필수. 준비하고 실행할 쿼리 또는 명령입니다. 유형: `str` `seq_of_parameters`:필수. 여러 매개 변수 값 집합의 시퀀스이며, 이는 매개 변수 `operation`와 함께 사용됩니다. 형식: `list`의 `dict` 반환 값이 없습니다.
`catalogs`	카탈로그에 대한 메타데이터 쿼리를 실행합니다. 실제 결과는 `fetchmany` 또는 `fetchall`을 사용하여 가져와야 합니다. 결과 집합의 중요한 필드는 다음과 같습니다. 필드 이름: `TABLE_CAT`. 카탈로그의 이름. 유형: `str` 매개 변수는 없습니다. 반환 값이 없습니다. 버전 1.0 이후
`schemas`	스키마에 대한 메타데이터 쿼리를 실행합니다. 실제 결과는 `fetchmany` 또는 `fetchall`을 사용하여 가져와야 합니다. 결과 집합의 중요한 필드는 다음과 같습니다. 필드 이름: `TABLE_SCHEM`. 스키마의 이름입니다. 유형: `str` 필드 이름: `TABLE_CATALOG`. 스키마가 속한 카탈로그입니다. 유형: `str` 매개 변수: `catalog_name`: 선택 사항입니다. 정보를 검색할 카탈로그 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` `schema_name`: 선택 사항입니다. 정보를 검색할 스키마 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` 반환 값이 없습니다. 버전 1.0 이후
`tables`	테이블 및 뷰에 대한 메타데이터 쿼리를 실행합니다. 실제 결과는 `fetchmany` 또는 `fetchall`을 사용하여 가져와야 합니다. 결과 집합의 중요한 필드는 다음과 같습니다. 필드 이름: `TABLE_CAT`. 테이블이 속한 카탈로그입니다. 유형: `str` 필드 이름: `TABLE_SCHEM`. 테이블이 속한 스키마입니다. 유형: `str` 필드 이름: `TABLE_NAME`. 테이블의 이름입니다. 유형: `str` 필드 이름: `TABLE_TYPE`. 관계 종류(예 `VIEW` 또는 `TABLE`, Databricks Runtime 10.4 LTS 이상 및 Databricks SQL 적용됨, 이전 버전의 Databricks Runtime은 빈 문자열 반환) 유형: `str` 매개 변수: `catalog_name`: 선택 사항입니다. 정보를 검색할 카탈로그 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` `schema_name`: 선택 사항입니다. 정보를 검색할 스키마 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` `table_name`: 선택 사항입니다. 정보를 검색할 테이블 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` `table_types`: 선택 사항입니다. 매칭할 테이블 형식의 목록입니다(예: `TABLE` 또는 `VIEW`). 유형: `List[str]` 반환 값이 없습니다. 버전 1.0 이후
`columns`	열에 대한 메타데이터 쿼리를 실행합니다. 실제 결과는 `fetchmany` 또는 `fetchall`을 사용하여 가져와야 합니다. 결과 집합의 중요한 필드는 다음과 같습니다. 필드 이름: `TABLE_CAT`. 열이 속한 카탈로그입니다. 유형: `str` 필드 이름: `TABLE_SCHEM`. 열이 속해 있는 스키마입니다. 유형: `str` 필드 이름: `TABLE_NAME`. 해당 열이 속한 테이블의 이름입니다. 유형: `str` 필드 이름: `COLUMN_NAME`. 열 이름입니다. 유형: `str` 매개 변수: `catalog_name`: 선택 사항입니다. 정보를 검색할 카탈로그 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` `schema_name`: 선택 사항입니다. 정보를 검색할 스키마 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` `table_name`: 선택 사항입니다. 정보를 검색할 테이블 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` `column_name`: 선택 사항입니다. 정보를 검색할 열의 이름입니다. `%` 문자는 와일드카드로 해석됩니다. 유형: `str` 반환 값이 없습니다. 버전 1.0 이후
`fetchall`	쿼리의 모든 행(또는 남아 있는 모든 행)을 가져옵니다. 매개 변수는 없습니다. 쿼리의 모든(또는 나머지 모든) 행을 개체의 `list` Python `Row` 으로 반환합니다. `Error` 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 `execute` 호출이 아직 수행되지 않은 경우 `execute`를 반환합니다.
`fetchmany`	쿼리의 다음 행을 가져옵니다. 매개 변수: `size`: 선택 사항입니다. 가져올 다음 행의 수입니다. 지정되지 않은 경우 `arraysize` 특성의 값이 사용됩니다. 유형: `int`. 예: `cursor.fetchmany(10)` 쿼리의 다음 행의 `size`까지(또는 `arraysize`가 지정되지 않은 경우 `size` 특성)를 `list` 개체로 구성된 Python `Row`로 반환합니다. 가져올 행보다 `size` 행이 적으면 나머지 행이 모두 반환됩니다. `Error` 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 `execute` 호출이 아직 수행되지 않은 경우 `execute`를 반환합니다.
`fetchone`	데이터 세트의 다음 행을 가져옵니다. 매개 변수는 없습니다. 데이터 세트의 다음 행을 단일 시퀀스로 Python `tuple` 개체로 반환하거나 사용 가능한 데이터가 더 이상 없는 경우 반환 `None` 합니다. `Error` 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 `execute` 호출이 아직 수행되지 않은 경우 `execute`를 반환합니다.
`fetchall_arrow`	쿼리의 모든 행(또는 남아 있는 모든 행)을 PyArrow `Table` 개체로 가져옵니다. 대용량 데이터를 반환하는 쿼리는 메모리 사용량을 줄이기 위해 대신 `fetchmany_arrow`를 사용해야 합니다. 매개 변수는 없습니다. 쿼리의 모든 행(또는 남아 있는 모든 행)을 PyArrow 테이블로 반환합니다. `Error` 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 `execute` 호출이 아직 수행되지 않은 경우 `execute`를 반환합니다. 버전 2.0 이후
`fetchmany_arrow`	쿼리의 다음 행을 PyArrow `Table` 개체로 가져옵니다. 매개 변수: `size`: 선택 사항입니다. 가져올 다음 행의 수입니다. 지정되지 않은 경우 `arraysize` 특성의 값이 사용됩니다. 유형: `int`. 예: `cursor.fetchmany_arrow(10)` 쿼리의 `size` 다음 행에 대한 인수(또는 `arraysize` 지정되지 않은 경우 `size` 특성)까지 Python PyArrow `Table` 개체로 반환합니다. `Error` 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 `execute` 호출이 아직 수행되지 않은 경우 `execute`를 반환합니다. 버전 2.0 이후

`Row` 클래스

행 클래스는 SQL 쿼리 결과의 개별 결과 행을 나타내는 튜플과 유사한 데이터 구조입니다. 행에 이름이 "my_column"인 열이 포함된 경우 "my_column"을 통해 row의 row.my_column 필드에 액세스할 수 있습니다. 숫자 인덱스를 사용하여 필드에 액세스할 수도 있습니다(예: row[0]). 열 이름이 특성 메서드 이름으로 허용되지 않는 경우(예: 숫자로 시작하는 경우) 필드에 row["1_my_column"]과 같이 액세스할 수 있습니다.

버전 1.0 이후

선택한 Row 메서드에는 다음이 포함됩니다.

메서드

메서드	Description
`asDict`	필드 이름으로 인덱싱되는 행의 사전 표현을 반환합니다. 중복된 필드 이름이 있는 경우 중복된 필드 중 하나만 사전에 반환됩니다. 중복된 필드 중 어느 것이 반환되는지는 정의되지 않았습니다.

형식 변환

다음 표에서는 Apache Spark SQL 데이터 형식을 대응되는 Python 데이터 형식에 매핑합니다.

Apache Spark SQL 데이터 형식	Python 데이터 형식
`array`	`numpy.ndarray`
`bigint`	`int`
`binary`	`bytearray`
`boolean`	`bool`
`date`	`datetime.date`
`decimal`	`decimal.Decimal`
`double`	`float`
`int`	`int`
`map`	`str`
`null`	`NoneType`
`smallint`	`int`
`string`	`str`
`struct`	`str`
`timestamp`	`datetime.datetime`
`tinyint`	`int`

원격 분석 수집

Python용 Databricks SQL 커넥터는 Azure Databricks가 안정성을 개선하고 문제를 해결하는 데 도움이 되는 원격 분석 데이터를 수집합니다. 텔레메트리는 기본값으로 활성화되며 다음 작업 데이터를 수집합니다.

드라이버 버전, Python 런타임 및 운영 체제와 같은 클라이언트 환경 세부 정보
드라이버 연결 구성(개인 식별 정보 제외)
작업 대기 시간 측정
인라인 JSON 또는 Apache 화살표와 같은 실행 결과 형식
쿼리 실행, 메타데이터 쿼리 또는 볼륨 작업과 같은 작업 유형
오류 분류 데이터
재시도 횟수

중요합니다

Azure Databricks는 원격 분석을 통해 쿼리 콘텐츠, 쿼리 결과 또는 PII(개인 식별 정보)를 수집하지 않습니다.

원격 분석 수집을 사용하지 않으려면 연결을 만들 때 매개 변수를 enable_telemetry로 설정하세요0.

문제 해결

`tokenAuthWrapperInvalidAccessToken: Invalid access token` 메시지

문제: 코드를 실행하면 다음과 같은 메시지가 표시됩니다. Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token.

가능한 원인: access_token으로 전달된 값이 유효한 Azure Databricks 개인용 액세스 토큰이 아닙니다.

권장 수정 사항: access_token으로 전달된 값이 올바른지 확인하고 다시 시도하세요.

`gaierror(8, 'nodename nor servname provided, or not known')` 메시지

문제: 코드를 실행하면 다음과 같은 메시지가 표시됩니다. Error during request to server: gaierror(8, 'nodename nor servname provided, or not known').

가능한 원인: server_hostname으로 전달된 값이 올바른 호스트 이름이 아닙니다.

권장 수정 사항: server_hostname으로 전달된 값이 올바른지 확인하고 다시 시도하세요.

서버 호스트 이름을 찾는 방법에 대한 자세한 내용은 Azure Databricks 컴퓨팅 리소스에 대한 연결 세부 정보 가져오기를 참조하세요.

`IpAclError` 메시지

문제: 코드를 실행하고 Azure Databricks Notebook에서 커넥터를 사용하려고 하면 다음과 같은 메시지가 표시됩니다. Error during request to server: IpAclValidation.

가능한 원인: Azure Databricks 작업 영역에 대해 IP 허용 목록이 사용하도록 설정되어 있을 수 있습니다. IP 허용 목록이 설정된 경우에는 Spark 클러스터에서 컨트롤 플레인으로의 연결이 기본적으로 허용되지 않습니다.

권장 수정 사항: 관리자에게 IP 허용 목록에 컴퓨팅 플레인 서브넷을 추가해 달라고 요청하세요.

추가 리소스

자세한 내용은 다음을 참조하세요.

GitHub의 Python용 Databricks SQL 커넥터 리포지토리
데이터 형식
Python 웹 사이트의 기본 제공 형식(bool, bytearray, float, int, str)
Python 웹 사이트의 datetime(datetime.date, datatime.datetime)
Python 웹 사이트에서의 decimal(decimal.Decimal)
Python 웹 사이트의 기본 제공 상수(NoneType)

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-10-31

다음을 통해 공유

Python용 Databricks SQL 커넥터

요구 사항

시작하기

모든 용도 컴퓨팅

SQL 웨어하우스

인증

Databricks 개인용 액세스 토큰 인증

OAuth 기계 대 기계(M2M) 인증

Microsoft Entra ID 토큰 인증

OAuth 사용자 대 컴퓨터(U2M) 인증

예제

User-Agent 설정

쿼리 데이터

쿼리 태그

데이터 삽입

메타데이터 쿼리

커서 및 연결 관리

Unity 카탈로그 볼륨의 파일 관리

로깅 구성

테스트

API 참조

모듈

connect 메서드

Connection 클래스

메서드

Cursor 클래스

특성

메서드

Row 클래스

메서드

형식 변환

원격 분석 수집

문제 해결

tokenAuthWrapperInvalidAccessToken: Invalid access token 메시지

gaierror(8, 'nodename nor servname provided, or not known') 메시지

IpAclError 메시지

추가 리소스

피드백

추가 리소스

`Connection` 클래스

`Cursor` 클래스

`Row` 클래스

`tokenAuthWrapperInvalidAccessToken: Invalid access token` 메시지

`gaierror(8, 'nodename nor servname provided, or not known')` 메시지

`IpAclError` 메시지