Python용 Databricks SQL Connector

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

요구 사항

시작하기

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

    클러스터

    참고

    보안 모범 사례로 이 정보를 코드에 하드 코딩해서는 안 됩니다. 대신 보안 위치에서 이 정보를 검색해야 합니다. 예를 들어 이 문서의 뒷부분에 있는 코드 예제에서는 환경 변수를 사용합니다.

    Sql 웨어하우스

    • SQL 웨어하우스의 서버 호스트 이름입니다. SQL 웨어하우스에 대한 연결 세부 정보 탭의 서버 호스트 이름 값에서 이 값을 가져올 수 있습니다.
    • SQL 웨어하우스의 HTTP 경로입니다. SQL 웨어하우스에 대한 연결 세부 정보 탭의 HTTP 경로 값에서 가져올 수 있습니다.
    • 유효한 액세스 토큰입니다. 작업 영역에 Azure Databricks 개인용 액세스 토큰 을 사용할 수 있습니다. Azure Active Directory 액세스 토큰을 사용할 수도 있습니다.

    참고

    보안 모범 사례로 이 정보를 코드에 하드 코딩해서는 안 됩니다. 대신 보안 위치에서 이 정보를 검색해야 합니다. 예를 들어 이 문서의 뒷부분에 있는 코드 예제에서는 환경 변수를 사용합니다.

  • 를 실행 pip install databricks-sql-connector하여 개발 컴퓨터에 Databricks SQL Connector for Python 라이브러리를 설치합니다.

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

다음 코드 예제에서는 이러한 환경 변수에서 , server_hostnamehttp_pathaccess_token 연결 변수 값을 검색합니다.

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

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

쿼리 데이터

다음 코드 예제에서는 Databricks SQL Connector for Python을 호출하여 클러스터 또는 SQL 웨어하우스에서 기본 SQL 명령을 실행하는 방법을 보여 줍니다. 이 명령은 테이블에서 처음 두 행을 반환합니다 diamonds .

참고

테이블은 diamonds샘플 데이터 세트에 포함되어 있습니다.

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 default.diamonds 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 Connector는 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 참조

패키지

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/1.0/warehouses/a1b234c567d8e9fa SQL 웨어하우스의 경우
access_token

형식: str

클러스터 또는 SQL 웨어하우스의 작업 영역에 대한 Azure Databricks 개인용 액세스 토큰 또는 Azure Active Directory 토큰입니다. 토큰을 만들려면 이 문서의 앞부분에 있는 지침을 참조하세요.

이 매개 변수는 필수입니다.

예제: dapi...<the-remaining-portion-of-your-token>
session_configuration

형식: dict[str, Any]

Spark 세션 구성 매개 변수의 사전입니다. 구성 설정은 SQL 명령을 사용하는 SET key=val 것과 같습니다. SQL 명령을 SET -v 실행하여 사용 가능한 구성의 전체 목록을 가져옵니다.

기본값은 입니다 None.

이 매개 변수는 선택 사항입니다.

예제: {"spark.sql.variable.substitute": True}
http_headers

형식: List[Tuple[str, str]]]

클라이언트가 요청하는 모든 RPC 요청에서 HTTP 헤더에 설정할 추가(키, 값) 쌍입니다. 일반적인 사용은 추가 HTTP 헤더를 설정하지 않습니다. 기본값은 입니다 None.

이 매개 변수는 선택 사항입니다.

버전 2.0 이후
카탈로그

형식: str

연결에 사용할 초기 카탈로그입니다. 기본값은 입니다 None (이 경우 기본 카탈로그( 일반적으로 hive_metastore).

이 매개 변수는 선택 사항입니다.

버전 2.0 이후
스키마

형식: str

연결에 사용할 초기 스키마입니다. 기본값은 None (이 경우 기본 스키마 default 가 사용됨)입니다.

이 매개 변수는 선택 사항입니다.

버전 2.0 이후

클래스

Connection 클래스

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

방법
close 메서드

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

매개 변수가 없습니다.

반환 값이 없습니다.

cursor 메서드

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

매개 변수가 없습니다.

Cursor 개체를 반환합니다.

Cursor 클래스

특성
arraysize 특성

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

읽기-쓰기 액세스.

description 특성

개체의 tuple Python list 을 포함합니다. 이러한 tuple 각 개체에는 다음과 같이 단일 결과 열을 설명하는 정보가 포함된 각 tuple 개체의 처음 2개 항목과 함께 7개의 값이 포함됩니다.

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

각 7개 항목 tuple 개체의 나머지 5개 항목은 구현되지 않으며 해당 값은 정의되지 않습니다. 일반적으로 4 None 개 값과 단일 True 값으로 반환됩니다.

읽기 전용 액세스.

방법
cancel 메서드

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

매개 변수가 없습니다.

반환 값이 없습니다.

close 메서드

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

매개 변수가 없습니다.

반환 값이 없습니다.

execute 메서드

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

반환 값이 없습니다.

매개 변수
작업

형식: str

준비한 다음 실행할 쿼리 또는 명령입니다.

이 매개 변수는 필수입니다.

매개 변수가 parameters 없는 예제:


cursor.execute(
'SELECT * FROM default.diamonds WHERE cut="Ideal" LIMIT 2'
)

매개 변수가 있는 parameters 예제:


cursor.execute(
'SELECT * FROM default.diamonds WHERE cut=%(cut_type)s LIMIT 2',
{ 'cut_type': 'Ideal' }
)
매개 변수

형식: 사전

매개 변수와 함께 사용할 매개 변수 시퀀스입니다 operation .

이 매개 변수는 선택 사항입니다. 기본값은 None입니다.
executemany 메서드

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

반환 값이 없습니다.

매개 변수
작업

형식: str

준비한 다음 실행할 쿼리 또는 명령입니다.

이 매개 변수는 필수입니다.
seq_of_parameters

형식: list of dict

에 사용할 여러 매개 변수 값 집합의 시퀀스입니다.
operation 매개 변수.

이 매개 변수는 필수입니다.
catalogs 메서드

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

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

매개 변수가 없습니다.

반환 값이 없습니다.

버전 1.0 이후

schemas 메서드

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

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

반환 값이 없습니다.

버전 1.0 이후

매개 변수
catalog_name

형식: str

정보를 검색할 카탈로그 이름입니다. 문자는 % 와일드카드로 해석됩니다.

이 매개 변수는 선택 사항입니다.
schema_name

형식: str

정보를 검색할 스키마 이름입니다. 문자는 % 와일드카드로 해석됩니다.

이 매개 변수는 선택 사항입니다.
tables 메서드

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

  • 필드 이름: 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 메서드

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

  • 필드 이름: 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 으로 반환합니다.

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

fetchmany 메서드

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

다음 쿼리 행의 최대 size (또는 를 지정하지 않은 경우 sizearraysize 특성)를 개체의 Row Python list 으로 반환합니다. 가져올 행보다 size 적은 수의 행이 있으면 나머지 모든 행이 반환됩니다.

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

매개 변수
크기

형식: int

가져올 다음 행의 수입니다.

이 매개 변수는 선택 사항입니다. 지정하지 않으면 특성 값이 arraysize 사용됩니다.

예제: cursor.fetchmany(10)
fetchone 메서드

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

매개 변수가 없습니다.

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

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

fetchall_arrow 메서드

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

매개 변수가 없습니다.

쿼리의 모든(또는 나머지 모든) 행을 PyArrow 테이블로 반환합니다.

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

버전 2.0 이후

fetchmany_arrow 메서드

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

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

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

버전 2.0 이후

매개 변수
크기

형식: int

가져올 다음 행의 수입니다.

이 매개 변수는 선택 사항입니다. 지정하지 않으면 특성 값이 arraysize 사용됩니다.

예제: cursor.fetchmany_arrow(10)

Row 클래스

행 클래스는 개별 결과 행을 나타내는 튜플과 유사한 데이터 구조입니다. 행에 이름이 "my_column"인 열이 포함된 경우 를 통해 row.my_columnrow 필드에 액세스할 "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 값이 올바른지 확인하고 다시 시도합니다.

서버 호스트 이름을 찾는 방법에 대한 자세한 내용은 연결 세부 정보 검색을 참조하세요.

IpAclError 메시지

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

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

권장 수정 사항: 관리자에게 IP 허용 목록에 데이터 평면 서브넷을 추가하도록 요청합니다.

추가 리소스

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