Python용 Databricks SQL 커넥트or

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

참고 항목

Python용 Databricks SQL 커넥트or에는 Azure Databricks에 대한 SQLAlchemy 언어도 포함되어 있습니다. Azure Databricks에서 SQLAlchemy 사용을 참조 하세요.

요구 사항

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

시작하기

• 실행 pip install databricks-sql-connector 하거나 python -m pip install databricks-sql-connector실행하여 개발 머신에 Python 라이브러리용 Databricks SQL 커넥트or를 설치합니다.

• 사용하려는 클러스터 또는 SQL 웨어하우스에 대해 다음 정보를 수집합니다.

  클러스터

  • 클러스터의 서버 호스트 이름. 클러스터의 고급 옵션 > JDBC/ODBC 탭의 서버 호스트 이름 값으로 확인할 수 있습니다.
  • 클러스터의 HTTP 경로. 클러스터의 고급 옵션 > JDBC/ODBC 탭의 HTTP 경로 값으로 확인할 수 있습니다.

  SQL 웨어하우스

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

인증

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

• Databricks 개인용 액세스 토큰 인증
• Microsoft Entra ID(이전의 Azure Active Directory) 토큰 인증
• OAuth M2M(machine-to-machine) 인증
• OAuth U2M(사용자-컴퓨터) 인증

Python용 Databricks SQL 커넥트or는 아직 다음 Azure Databricks 인증 유형을 지원하지 않습니다.

• Azure 관리 ID 인증
• Microsoft Entra ID 보안 주체 인증
• Azure CLI 인증

Databricks 개인용 액세스 토큰 인증

Azure Databricks 개인용 액세스 토큰 인증과 함께 Python용 Databricks SQL 커넥트or를 사용하려면 먼저 다음과 같이 Azure Databricks 개인용 액세스 토큰을 만들어야 합니다.

1. Azure Databricks 작업 영역의 위쪽 표시줄에서 Azure Databricks 사용자 이름을 클릭한 다음 드롭다운에서 사용자 설정을 선택합니다.
2. 개발자를 클릭합니다.
3. 액세스 토큰 옆에 있는 관리를 클릭합니다.
4. 새 토큰 생성을 클릭합니다.
5. (선택 사항) 나중에 이 토큰을 식별할 수 있도록 하는 설명을 입력하고 토큰의 기본 수명을 90일로 변경합니다. 수명이 없는 토큰을 만들려면(권장하지 않음) 수명(일) 상자를 비워 둡니다(공백).
6. 생성을 클릭합니다.
7. 표시된 토큰을 안전한 위치에 복사한 다음 완료를 클릭합니다.

참고 항목

복사한 토큰을 안전한 위치에 저장합니다. 복사한 토큰을 다른 사용자와 공유하지 마세요. 복사한 토큰을 분실하면 정확히 동일한 토큰을 다시 생성할 수 없습니다. 대신 이 프로시저를 반복하여 새 토큰을 만들어야 합니다. 복사한 토큰이 손실되었거나 토큰이 손상되었다고 생각되는 경우 Databricks는 액세스 토큰 페이지의 토큰 옆에 있는 휴지통(해지) 아이콘을 클릭하여 작업 영역에서 해당 토큰 을 즉시 삭제하는 것이 좋습니다.

작업 영역에서 토큰을 만들거나 사용할 수 없는 경우 작업 영역 관리자가 토큰을 사용하지 않도록 설정했거나 토큰을 만들거나 사용할 수 있는 권한을 부여하지 않았기 때문일 수 있습니다. 작업 영역 관리자 또는 다음을 참조하세요.

• 작업 영역에 대한 개인용 액세스 토큰 인증 사용 또는 사용 안 함
• 개인 액세스 토큰 권한

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

• 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 커넥트or는 OAuth M2M(컴퓨터 대 컴퓨터) 인증을 지원합니다. Python 0.18.0 이상용 Databricks SDK도 설치해야 합니다(예: 실행 pip install databricks-sdk 또는 python -m pip install databricks-sdk).

OAuth M2M 인증에서 Python용 Databricks SQL 커넥트or를 사용하려면 다음을 수행해야 합니다.

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

   서비스 주체 및 해당 OAuth 비밀을 만들려면 OAuth M2M(컴퓨터 대 컴퓨터) 인증을 참조하세요. 서비스 주체의 UUID 또는 애플리케이션 ID 값과 서비스 주체의 OAuth 비밀에 대한 비밀 값을 기록해 둡니다.

2. 해당 서비스 주체에게 클러스터 또는 웨어하우스에 대한 액세스 권한을 부여합니다.

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

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

• 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(이전의 Azure Active Directory) 토큰 인증

Microsoft Entra ID(이전의 Azure Active Directory) 토큰 인증과 함께 Python용 Databricks SQL 커넥트or를 사용하려면 Microsoft Entra ID 토큰과 함께 Python용 Databricks SQL 커넥트or를 제공해야 합니다. Microsoft Entra ID 액세스 토큰을 만들려면 다음을 수행합니다.

• Azure Databricks 사용자의 경우 Azure CLI를 사용할 수 있습니다. Azure CLI를 사용하여 사용자에 대한 Microsoft Entra ID(이전의 Azure Active Directory) 토큰 가져오기를 참조하세요.
• Microsoft Entra ID 서비스 주체는 Azure CLI를 사용하여 Microsoft Entra ID 액세스 토큰 가져오기를 참조하세요. Microsoft Entra ID 관리 서비스 주체를 만들려면 서비스 주체 관리를 참조 하세요.

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

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

• 클러스터 또는 SQL 웨어하우스의 서버 호스트 이름 값으로 설정합니다DATABRICKS_SERVER_HOSTNAME.
• 클러스터 또는 SQL 웨어하우스에 대한 HTTP 경로 값으로 설정합니다DATABRICKS_HTTP_PATH.
• Microsoft Entra ID 토큰으로 설정합니다 DATABRICKS_TOKEN .

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

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 커넥트or는 OAuth U2M(사용자-컴퓨터) 인증을 지원합니다. Python 0.19.0 이상용 Databricks SDK도 설치해야 합니다(예: 실행 pip install databricks-sdk 또는 python -m pip install databricks-sdk).

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

• 클러스터 또는 SQL 웨어하우스의 서버 호스트 이름 값으로 설정합니다DATABRICKS_SERVER_HOSTNAME.
• 클러스터 또는 SQL 웨어하우스에 대한 HTTP 경로 값으로 설정합니다DATABRICKS_HTTP_PATH.

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

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:
# ...

예제

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

참고 항목

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

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

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

다른 방법을 사용하여 이러한 연결 변수 값을 검색할 수 있습니다. 환경 변수를 사용하는 것은 여러 방법 중 하나에 불과합니다.

• 쿼리 데이터
• 데이터 삽입
• 쿼리 메타데이터
• 커서 및 연결 관리
• 로깅 구성

쿼리 데이터

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

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)

데이터 삽입

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

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)]
    values = ",".join([f"({x}, {y})" for (x, y) in squares])

    cursor.execute(f"INSERT INTO squares VALUES {values}")

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

로깅 구성

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

API 참조

• Package(패키지)
• 모듈
  • 메서드
    • connect 메서드
• 클래스
  • Connection 클래스
    • 메서드
      • close 메서드
      • cursor 메서드
  • Cursor 클래스
    • 특성
      • arraysize 특성
      • description 특성
    • 메서드
      • cancel 메서드
      • close 메서드
      • execute 메서드
      • executemany 메서드
      • catalogs 메서드
      • schemas 메서드
      • tables 메서드
      • columns 메서드
      • fetchall 메서드
      • fetchmany 메서드
      • fetchone 메서드
      • fetchall_arrow 메서드
      • fetchmany_arrow 메서드
  • Row 클래스
    • 메서드
      • asDict 메서드
• 형식 변환

Package(패키지)

databricks-sql-connector

사용법: pip install databricks-sql-connector

PyPI(Python 패키지 인덱스)의 databricks-sql-connector도 참조하세요.

모듈

databricks.sql

사용법: from databricks import sql

메서드

connect 메서드

데이터베이스에 대한 연결을 만듭니다.

Connection 개체를 반환합니다.

매개 변수
server_hostname 유형: str 클러스터 또는 SQL 웨어하우스의 서버 호스트 이름입니다. 서버 호스트 이름을 가져오려면 이 문서의 앞부분에 나와 있는 지침을 참조하세요. 이 매개 변수는 필수입니다. 예: adb-1234567890123456.7.azuredatabricks.net
http_path 유형: str 클러스터 또는 SQL 웨어하우스의 HTTP 경로입니다. HTTP 경로를 가져오려면 이 문서의 앞부분에 나와 있는 지침을 참조하세요. 이 매개 변수는 필수입니다. 예시: sql/protocolv1/o/1234567890123456/1234-567890-test123(클러스터). SQL 웨어하우스의 경우 /sql/1.0/warehouses/a1b234c567d8e9fa입니다.
access_token, auth_type 유형: 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]]] 클라이언트가 만드는 모든 RPC 요청에 대해 HTTP 헤더에 설정할 추가(키, 값) 쌍입니다. 일반적인 사용법은 추가 HTTP 헤더를 설정하지 않습니다. 기본값은 None입니다. 이 매개 변수는 선택 사항입니다. 버전 2.0 이후
catalog 유형: str 연결에 사용할 초기 카탈로그입니다. 기본값은 None(이 경우 일반적으로 기본 카탈로그인 hive_metastore가 사용됨)입니다. 이 매개 변수는 선택 사항입니다. 버전 2.0 이후
schema(스키마) 유형: str 연결에 사용할 초기 스키마입니다. 기본값은 None(이 경우 기본 스키마 default가 사용됨)입니다. 이 매개 변수는 선택 사항입니다. 버전 2.0 이후
use_cloud_fetch 유형: bool True 데이터 청크를 다운로드하기 위해 페치 요청을 클라우드 개체 저장소로 직접 보냅니다. False (기본값) Azure Databricks에 직접 페치 요청을 보냅니다. 설정 True 되었지만 네트워크 액세스가 차단된 경우 use_cloud_fetch 페치 요청이 실패합니다. 버전 2.8 이후

클래스

Connection 클래스

데이터베이스에 대한 연결을 나타냅니다.

메서드

close 메서드

데이터베이스에 대한 연결을 닫고 서버에서 연결된 모든 리소스를 해제합니다. 이 연결에 대한 추가 호출은 Error를 throw합니다.

매개 변수는 없습니다.

반환 값이 없습니다.

cursor 메서드

데이터베이스의 레코드를 트래버스할 수 있도록 해 주는 메커니즘을 반환합니다.

매개 변수는 없습니다.

Cursor 개체를 반환합니다.

Cursor 클래스

특성

arraysize 특성

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

읽기/쓰기 액세스입니다.

description 특성

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

• name: 열의 이름입니다.
• type_code: 열의 형식을 나타내는 문자열입니다. 예를 들어, 정수 열은 int라는 형식 코드를 갖습니다.

7개 항목으로 구성된 tuple 개체의 나머지 5개 항목은 구현되지 않았으며, 값이 정의되지 않았습니다. 일반적으로 4개의 None 값과 하나의 True 값으로 반환됩니다.

읽기 전용 액세스입니다.

메서드

cancel 메서드

커서가 시작된 데이터베이스 쿼리 또는 명령의 실행을 중단합니다. 서버에서 연결된 리소스를 해제하려면 cancel 메서드를 호출한 후에 close 메서드를 호출합니다.

매개 변수는 없습니다.

반환 값이 없습니다.

close 메서드

커서를 닫고 서버에서 연결된 리소스를 해제합니다. 이미 닫힌 커서를 닫으면 오류가 throw될 수 있습니다.

매개 변수는 없습니다.

반환 값이 없습니다.

execute 메서드

데이터베이스 쿼리 또는 명령을 준비하고 실행합니다.

반환 값이 없습니다.

매개 변수
작업 유형: str 준비하고 실행할 쿼리 또는 명령입니다. 이 매개 변수는 필수입니다. parameters 매개 변수가 없는 예: cursor.execute( 'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2' ) parameters 매개 변수가 있는 예: cursor.execute( 'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2', { 'pickup_zip': '10019' } )
parameters 형식: 사전 operation 매개 변수와 함께 사용할 매개 변수 시퀀스입니다. 이 매개 변수는 선택 사항입니다. 기본값은 None입니다.

executemany 메서드

seq_of_parameters 인수의 모든 매개 변수 시퀀스를 사용하여 데이터베이스 쿼리 또는 명령을 준비하고 실행합니다. 최종 결과 집합만 유지됩니다.

반환 값이 없습니다.

매개 변수
작업 유형: str 준비하고 실행할 쿼리 또는 명령입니다. 이 매개 변수는 필수입니다.
seq_of_parameters 형식: dict의 list 에 사용할 여러 매개 변수 값 집합의 시퀀스입니다. operation 매개 변수와 함께 사용할 여러 매개 변수 값 세트의 시퀀스입니다. 이 매개 변수는 필수입니다.

catalogs 메서드

카탈로그에 대한 메타데이터 쿼리를 실행합니다. 실제 결과는 fetchmany 또는 fetchall을 사용하여 가져와야 합니다. 결과 집합의 중요한 필드는 다음과 같습니다.

• 필드 이름: TABLE_CAT. 입력: str 카탈로그의 이름입니다.

매개 변수는 없습니다.

반환 값이 없습니다.

버전 1.0 이후

schemas 메서드

스키마에 대한 메타데이터 쿼리를 실행합니다. 실제 결과는 fetchmany 또는 fetchall을 사용하여 가져와야 합니다. 결과 집합의 중요한 필드는 다음과 같습니다.

• 필드 이름: TABLE_SCHEM. 입력: str 스키마의 이름입니다.
• 필드 이름: TABLE_CATALOG. 입력: str 스키마가 속한 카탈로그입니다.

반환 값이 없습니다.

버전 1.0 이후

매개 변수
catalog_name 유형: str 정보를 검색할 카탈로그 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.
schema_name 유형: str 정보를 검색할 스키마 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.

tables 메서드

테이블 및 뷰에 대한 메타데이터 쿼리를 실행합니다. 실제 결과는 fetchmany 또는 fetchall을 사용하여 가져와야 합니다. 결과 집합의 중요한 필드는 다음과 같습니다.

• 필드 이름: TABLE_CAT. 입력: str 테이블이 속한 카탈로그입니다.
• 필드 이름: TABLE_SCHEM. 입력: str 테이블이 속한 스키마입니다.
• 필드 이름: TABLE_NAME. 입력: str 테이블의 이름입니다.
• 필드 이름: TABLE_TYPE. 입력: str 관계 종류(예 VIEW 또는 TABLE, Databricks Runtime 10.2 이상 및 Databricks SQL 적용됨, 이전 버전의 Databricks Runtime은 빈 문자열 반환)

반환 값이 없습니다.

버전 1.0 이후

매개 변수
catalog_name 유형: str 정보를 검색할 카탈로그 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.
schema_name 유형: str 정보를 검색할 스키마 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.
table_name 유형: str 정보를 검색할 테이블 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.
table_types 유형: List[str] 매칭할 테이블 형식의 목록입니다(예: TABLE 또는 VIEW). 이 매개 변수는 선택 사항입니다.

columns 메서드

열에 대한 메타데이터 쿼리를 실행합니다. 실제 결과는 fetchmany 또는 fetchall을 사용하여 가져와야 합니다. 결과 집합의 중요한 필드는 다음과 같습니다.

• 필드 이름: TABLE_CAT. 입력: str 열이 속한 카탈로그입니다.
• 필드 이름: TABLE_SCHEM. 입력: str 열이 속한 스키마입니다.
• 필드 이름: TABLE_NAME. 입력: str 열이 속한 테이블의 이름입니다.
• 필드 이름: COLUMN_NAME. 입력: str 열 이름입니다.

반환 값이 없습니다.

버전 1.0 이후

매개 변수
catalog_name 유형: str 정보를 검색할 카탈로그 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.
schema_name 유형: str 정보를 검색할 스키마 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.
table_name 유형: str 정보를 검색할 테이블 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.
column_name 유형: str 정보를 검색할 열 이름입니다. % 문자는 와일드카드로 해석됩니다. 이 매개 변수는 선택 사항입니다.

fetchall 메서드

쿼리의 모든 행(또는 남아 있는 모든 행)을 가져옵니다.

매개 변수는 없습니다.

쿼리의 모든 행(또는 남아 있는 모든 행)을 Row 개체로 구성된 Python list로 반환합니다.

execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 execute 호출이 아직 수행되지 않은 경우 Error를 throw합니다.

fetchmany 메서드

쿼리의 다음 행을 가져옵니다.

쿼리의 다음 행의 size까지(또는 size가 지정되지 않은 경우 arraysize 특성)를 Row 개체로 구성된 Python list로 반환합니다. 가져올 행보다 size 행이 적으면 나머지 행이 모두 반환됩니다.

execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 execute 호출이 아직 수행되지 않은 경우 Error를 throw합니다.

매개 변수
size 유형: int 가져올 다음 행의 수입니다. 이 매개 변수는 선택 사항입니다. 지정되지 않은 경우 arraysize 특성의 값이 사용됩니다. 예: cursor.fetchmany(10)

fetchone 메서드

데이터 세트의 다음 행을 가져옵니다.

매개 변수는 없습니다.

데이터 세트의 다음 행을 Python tuple 개체로 구성된 단일 시퀀스로 반환하거나, 더 이상 사용 가능한 데이터가 없으면 None을 반환합니다.

execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 execute 호출이 아직 수행되지 않은 경우 Error를 throw합니다.

fetchall_arrow 메서드

쿼리의 모든 행(또는 남아 있는 모든 행)을 PyArrow Table 개체로 가져옵니다. 대용량 데이터를 반환하는 쿼리는 메모리 사용량을 줄이기 위해 대신 fetchmany_arrow를 사용해야 합니다.

매개 변수는 없습니다.

쿼리의 모든 행(또는 남아 있는 모든 행)을 PyArrow 테이블로 반환합니다.

execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 execute 호출이 아직 수행되지 않은 경우 Error를 throw합니다.

버전 2.0 이후

fetchmany_arrow 메서드

쿼리의 다음 행을 PyArrow Table 개체로 가져옵니다.

쿼리의 다음 행의 size 인수까지(또는 size가 지정되지 않은 경우 arraysize 특성)를 Python PyArrow Table 개체로 반환합니다.

execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 execute 호출이 아직 수행되지 않은 경우 Error를 throw합니다.

버전 2.0 이후

매개 변수
size 유형: int 가져올 다음 행의 수입니다. 이 매개 변수는 선택 사항입니다. 지정되지 않은 경우 arraysize 특성의 값이 사용됩니다. 예: cursor.fetchmany_arrow(10)

Row 클래스

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

버전 1.0 이후

메서드

asDict 메서드

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

매개 변수는 없습니다.

필드로 구성된 dict를 반환합니다.

형식 변환

다음 표에서는 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

문제 해결

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)