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 웨어하우스에 대한 다음 정보를 수집합니다.
클러스터
- 클러스터의 서버 호스트 이름입니다. 클러스터에 대한 고급 옵션 > JDBC/ODBC 탭의 서버 호스트 이름 값에서 이 값을 가져올 수 있습니다.
- 클러스터의 HTTP 경로입니다. 클러스터에 대한 고급 옵션 > JDBC/ODBC 탭의 HTTP 경로 값에서 가져올 수 있습니다.
- 유효한 액세스 토큰입니다. 작업 영역에 Azure Databricks 개인용 액세스 토큰 을 사용할 수 있습니다. Azure Active Directory 액세스 토큰을 사용할 수도 있습니다.
참고
보안 모범 사례로 이 정보를 코드에 하드 코딩해서는 안 됩니다. 대신 보안 위치에서 이 정보를 검색해야 합니다. 예를 들어 이 문서의 뒷부분에 있는 코드 예제에서는 환경 변수를 사용합니다.
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_hostname
http_path
및 access_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
으로 반환합니다.
Error
execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 아직 호출이 이루어지지 않은 execute
경우 을 throw합니다.
fetchmany
메서드
쿼리의 다음 행을 가져옵니다.
다음 쿼리 행의 최대 size
(또는 를 지정하지 않은 경우 size
arraysize 특성)를 개체의 Row
Python list
으로 반환합니다.
가져올 행보다 size
적은 수의 행이 있으면 나머지 모든 행이 반환됩니다.
Error
execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 아직 호출이 이루어지지 않은 execute
경우 을 throw합니다.
매개 변수 |
---|
크기 형식: int 가져올 다음 행의 수입니다. 이 매개 변수는 선택 사항입니다. 지정하지 않으면 특성 값이 arraysize 사용됩니다.예제: cursor.fetchmany(10) |
fetchone
메서드
데이터 세트의 다음 행을 가져옵니다.
매개 변수가 없습니다.
데이터 세트의 다음 행을 단일 시퀀스로 Python tuple
개체로 반환하거나 사용 가능한 데이터가 더 이상 없으면 를 반환 None
합니다.
Error
execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 아직 호출이 이루어지지 않은 execute
경우 을 throw합니다.
fetchall_arrow
메서드
쿼리의 모든 행(또는 나머지 모든 행)을 PyArrow Table
개체로 가져옵니다.
대용량 데이터를 반환하는 쿼리는 메모리 소비를 줄이기 위해 대신 를 사용해야 fetchmany_arrow
합니다.
매개 변수가 없습니다.
쿼리의 모든(또는 나머지 모든) 행을 PyArrow 테이블로 반환합니다.
Error
execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 아직 호출이 이루어지지 않은 execute
경우 을 throw합니다.
버전 2.0 이후
fetchmany_arrow
메서드
쿼리의 다음 행을 PyArrow Table
개체로 가져옵니다.
쿼리의 size
다음 행에 대한 인수(또는 지정되지 않은 경우 size
arraysize 특성)를 Python PyArrow Table
개체로 반환합니다.
Error
execute 메서드에 대한 이전 호출이 데이터를 반환하지 않았거나 아직 호출이 이루어지지 않은 execute
경우 을 throw합니다.
버전 2.0 이후
매개 변수 |
---|
크기 형식: 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
값이 올바른지 확인하고 다시 시도합니다.
서버 호스트 이름을 찾는 방법에 대한 자세한 내용은 연결 세부 정보 검색을 참조하세요.
IpAclError
메시지
문제: 코드를 실행하면 Azure Databricks Notebook에서 커넥터를 사용하려고 할 때 메시지가 Error during request to server: IpAclValidation
표시됩니다.
가능한 원인: Azure Databricks 작업 영역에 대해 IP 허용 목록을 사용하도록 설정했을 수 있습니다. IP 허용 목록을 사용하면 Spark 클러스터에서 컨트롤 플레인으로의 연결이 기본적으로 허용되지 않습니다.
권장 수정 사항: 관리자에게 IP 허용 목록에 데이터 평면 서브넷을 추가하도록 요청합니다.
추가 리소스
자세한 내용은 다음을 참조하세요.