Databricks SQL Connector for Python
Databricks SQL Connector for Python は、Python コードを使用して Databricks クラスターおよび Databricks SQLウェアハウスで SQL コマンドを実行できるようにする Python ライブラリです。Databricks SQL Connector for Python は、 pyodbc などの同様の Python ライブラリよりもセットアップと使用が簡単です。 このライブラリは PEP 249 – Python データベース API 仕様 v2.0 に準拠しています。
注
Databricks SQL Connector for Python には、Databricks 用の SQLAlchemy ダイアレクトも含まれています。 「 Databricks で SQLAlchemy を使用する」を参照してください。
要件
Python >=3.8 および <=3.11 を実行している開発マシン。
Databricks では、Python に含まれる venv によって提供されるものなど、Python 仮想環境を使用することをお勧めします。 仮想環境は、正しいバージョンの Python と Databricks SQL Connector for Python を一緒に使用するのに役立ちます。 仮想環境の設定と使用は、この記事の範囲外です。 詳細については、「 仮想環境の作成」を参照してください。
既存のクラスターまたはSQL ウェアハウス。
はじめに
pip install databricks-sql-connector
またはpython -m pip install databricks-sql-connector
を実行して、開発用コンピューターに Databricks SQL Connector for Python ライブラリをインストールします。使用するクラスターまたは SQLウェアハウスに関する次の情報を収集します。
クラスターのサーバー・ホスト名。 これは、クラスターの [ Advanced Options] > [JDBC/ODBC ] タブの [Server ホスト名 ] の値から取得できます。
クラスターの HTTP パス。 これは、クラスターの [ Advanced Options] > [JDBC/ODBC ] タブの [HTTP Path] ( HTTP パス ) 値から取得できます。
認証
Databricks SQL Connector for Python では、次の Databricks 認証の種類がサポートされています。
Databricks個人用アクセストークン認証
Databricks 個人用アクセストークン認証で Databricks SQL Connector for Python を使用するには、まず次のように Databricks 個人 用アクセストークンを作成する必要があります。
Databricks ワークスペースで、上部のバーにある Databricks ユーザー名をクリックし、ドロップダウンから[設定]を選択します。
[ 開発者] をクリックします。
[アクセストークン] の横にある [管理] をクリックします。
[ 新しいトークンの生成] をクリックします。
(任意)今後このトークンを識別するのに役立つコメントを入力し、トークンのデフォルトの有効期間である90日を変更します。有効期間のないトークンを作成するには(非推奨)、[有効期間 (日) ] ボックスを空白のままにしてください。
[生成] をクリックします。
表示されたトークンを安全な場所にコピーし、[完了] をクリックします。
注
コピーしたトークンは、必ず安全な場所に保存してください。 コピーしたトークンを他のユーザーと共有しないでください。 コピーしたトークンを紛失した場合、まったく同じトークンを再生成することはできません。 代わりに、この手順を繰り返して新しいトークンを作成する必要があります。 コピーしたトークンを紛失した場合、またはトークンが侵害されたと思われる場合は、アクセストークン ページでトークンの横にあるごみ箱 (取り消し) アイコンをクリックして、ワークスペースからそのトークンをすぐに削除することを強くお勧めします。
ワークスペースでトークンを作成または使用できない場合は、ワークスペース管理者がトークンを無効にしたか、トークンを作成または使用する権限を与えていないことが原因である可能性があります。ワークスペース管理者に問い合わせるか、以下をご覧ください。
Databricks SQL Connector for Python を認証するには、次のコード スニペットを使用します。 このスニペットは、次の環境変数が設定されていることを前提としています。
DATABRICKS_SERVER_HOSTNAME
をクラスターまたは SQLウェアハウスの [Server Hostname ] の値に設定します。DATABRICKS_HTTP_PATH
で、クラスターまたは SQLウェアハウスの HTTP パス 値に設定します。DATABRICKS_TOKEN
を Databricks personal アクセストークンに設定します。
環境変数を設定するには、ご利用になっているオペレーティングシステムのドキュメントを参照してください。
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:
# ...
ユーザー名とパスワードによる認証
ユーザー名とパスワードによる認証 ( 基本認証とも呼ばれます) を使用して Databricks SQL Connector for Python を認証するには、次のコード スニペットを使用します。 このスニペットは、次の環境変数が設定されていることを前提としています。
DATABRICKS_SERVER_HOSTNAME
をクラスターまたは SQLウェアハウスの [Server Hostname ] の値に設定します。DATABRICKS_HTTP_PATH
で、クラスターまたは SQLウェアハウスの HTTP パス 値に設定します。DATABRICKS_USERNAME
、Databricks ユーザー アカウントのユーザー名に設定します。DATABRICKS_PASSWORD
で、Databricks ユーザー アカウントのパスワードに設定します。
環境変数を設定するには、ご利用になっているオペレーティングシステムのドキュメントを参照してください。
ユーザー名とパスワードによる認証は、シングルサインオン が無効になっている場合にのみ可能です。
from databricks import sql
import os
with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
http_path = os.getenv("DATABRICKS_HTTP_PATH"),
username = os.getenv("DATABRICKS_USERNAME"),
password = os.getenv("DATABRICKS_PASSWORD")) as connection:
# ...
OAuthマシン間(M2M)認証
Databricks SQL Connector for Python バージョン 2.5.0 以降では、OAuth マシン間 (M2M) 認証がサポートされています。 Databricks SDK for Pythonもインストールする必要があります (たとえばpip install databricks-sdk
またはpython -m pip install databricks-sdk
を実行します)。
OAuth M2M 認証で Databricks SQL Connector for Python を使用するには、次の操作を行う必要があります。
Databricks ワークスペースに Databricks サービスプリンシパルを作成し、そのサービスプリンシパルの OAuth シークレットを作成します。
サービスプリンシパルとその OAuth シークレットを作成するには、 「OAuth マシン間 (M2M) 認証」を参照してください。 サービスプリンシパルのUUIDまたはアプリケーション ID の値と、サービスプリンシパルの OAuth シークレットのシークレット値をメモします。
そのサービスプリンシパルにクラスターまたはウェアハウスへのアクセス権を付与します。
サービスプリンシパルにクラスターまたはウェアハウスへのアクセスを許可するには、 「コンピュート権限」または「SQL ウェアハウスの管理」を参照してください。
Databricks SQL Connector for Python を認証するには、次のコード スニペットを使用します。 このスニペットは、次の環境変数が設定されていることを前提としています。
DATABRICKS_SERVER_HOSTNAME
をクラスターまたは SQLウェアハウスの [Server Hostname ] の値に設定します。DATABRICKS_HTTP_PATH
で、クラスターまたは SQLウェアハウスの HTTP パス 値に設定します。DATABRICKS_CLIENT_ID
は、サービスプリンシパルの UUID または アプリケーション ID の値に設定されます。DATABRICKS_CLIENT_SECRET
で、サービスプリンシパルの OAuth シークレットの Secret 値に設定します。
環境変数を設定するには、ご利用になっているオペレーティングシステムのドキュメントを参照してください。
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:
# ...
OAuthユーザー対マシン(U2M)認証
Databricks SQL Connector for Python バージョン 2.1.0 以上は 、OAuth user-to-machine (U2M) 認証をサポートしています。
OAuth U2M 認証を使用して Databricks SQL Connector for Python を認証するには、次のコード スニペットを使用します。 OAuth U2M 認証では、リアルタイムの人間のサインインと同意を使用して、ターゲット Databricks ユーザー アカウントを認証します。 このスニペットは、次の環境変数が設定されていることを前提としています。
DATABRICKS_SERVER_HOSTNAME
をクラスターまたは SQL ウェアハウスのサーバー ホスト名の値に設定します。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 コネクタ for Python を使用して、データのクエリと挿入、メタデータのクエリー、カーソルと接続の管理、およびログの構成を行う方法を示しています。
注
次のコード例は、認証に Databricks 個人用アクセストークンを使用する方法を示しています。 代わりに、他の使用可能な Databricks 認証の種類を使用するには、「 認証」を参照してください。
これらのコード例では、これらの環境変数から server_hostname
、 http_path
、および access_token
接続変数の値を取得します。
DATABRICKS_SERVER_HOSTNAME
これは、要件の サーバ ホスト名 の値を表します。DATABRICKS_HTTP_PATH
これは、要件からの HTTP パス 値を表します。DATABRICKS_TOKEN
これは、要件からのアクセストークンを表します。
これらの接続変数の値を取得するには、他の方法を使用できます。 環境変数の使用は、多くのアプローチの 1 つにすぎません。
データのクエリー
次のコード例は、Databricks SQL Connector for Python を呼び出して、クラスターまたは SQLウェアハウスで基本的な SQL コマンドを実行する方法を示しています。 このコマンドは、samples
カタログのnyctaxi
スキーマのtrips
テーブルから最初の 2 行を返します。
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())
カーソルと接続の管理
使用しなくなった接続とカーソルを閉じるのがベスト・プラクティスです。 これにより、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 リファレンス
パッケージ
databricks-sql-connector
使い: pip install databricks-sql-connector
Python パッケージインデックス (PyPI) の databricks-sql-connector も参照してください。
モジュール
databricks.sql
使い: from databricks import sql
メソッド
connect
方法
データベースへの接続を作成します。
接続 オブジェクトを返します。
パラメーター |
---|
server_hostname 種類: クラスターまたは SQLウェアハウスのサーバーのホスト名。 サーバーのホスト名を取得するには、この記事で前述した手順を参照してください。 このパラメーターは必須です。 例: |
http_path 種類: クラスターまたは SQLウェアハウスの HTTP パス。 HTTP パスを取得するには、この記事で前述した手順を参照してください。 このパラメーターは必須です。 例: クラスターの |
access_token、 auth_type、 credentials_provider、 パスワード、 ユーザー名 種類: Databricks の認証設定に関する情報。 詳細については、「 認証」を参照してください。 |
session_configuration 種類: Spark セッション構成パラメーターのディクショナリ。 構成の設定は、 デフォルトは このパラメーターはオプションです。 例: |
http_headers 種類: クライアントが行うすべての RPC 要求の HTTP ヘッダーに設定する追加の (キーと値のペア。 一般的な使用法では、追加の HTTP ヘッダーは設定されません。 デフォルトは このパラメーターはオプションです。 バージョン 2.0 以降 |
カタログ 種類: 接続に使用する初期カタログ。 デフォルトから このパラメーターはオプションです。 バージョン 2.0 以降 |
スキーマ 種類: 接続に使用する初期スキーマ。 デフォルトから このパラメーターはオプションです。 バージョン 2.0 以降 |
use_cloud_fetch 種類:
バージョン 2.8 以降 |
クラス
Connection
クラス
データベースへの接続を表します。
Cursor
クラス
属性
arraysize
属性
fetchmany メソッドと共に使用すると、内部バッファ サイズを指定します。このサイズは、サーバーから一度に実際にフェッチされる行数でもあります。デフォルト値は 10000
です。 狭い結果 (各行に大量のデータが含まれていない結果) の場合は、パフォーマンスを向上させるためにこの値を増やす必要があります。
読み取り/書き込みアクセス。
description
属性
tuple
オブジェクトの Python list
が含まれています。これらの tuple
オブジェクトにはそれぞれ 7 つの値が含まれ、各 tuple
オブジェクトの最初の 2 つの項目には、次のように 1 つの結果列を説明する情報が含まれています。
name
: 列の名前。type_code
: 列の型を表す文字列。 たとえば、整数列の型コードはint
になります。
各 7 項目 tuple
オブジェクトの残りの 5 項目は実装されておらず、その値は定義されていません。 通常、これらは 4 つの None
値とそれに続く 1 つの True
値として返されます。
読み取り専用アクセス。
メソッド
cancel
方法
カーソルが開始したデータベースクエリーまたはコマンドの実行を中断します。 サーバー上の関連リソースを解放するには、 cancel
メソッドを呼び出した後に close メソッドを呼び出します。
パラメーターはありません。
戻り値はありません。
execute
方法
データベースを準備し、クエリーまたはコマンドを実行します。
戻り値はありません。
パラメーター |
---|
操作 種類: 準備して実行するクエリーまたはコマンド。 このパラメーターは必須です。
cursor.execute(
'SELECT * FROM samples.nyctaxi.trips WHERE pickup_zip="10019" LIMIT 2'
)
cursor.execute(
'SELECT * FROM samples.nyctaxi.trips WHERE zip=%(pickup_zip)s LIMIT 2',
{ 'pickup_zip': '10019' }
)
|
パラメーター 原稿種別: 辞書
このパラメーターはオプションです。 デフォルトは |
executemany
方法
データベースを準備し、 seq_of_parameters
引数のすべてのパラメーター シーケンスを使用してクエリまたはコマンドを実行します。 最終的な結果セットのみが保持されます。
戻り値はありません。
パラメーター |
---|
操作 種類: 準備して実行するクエリーまたはコマンド。 このパラメーターは必須です。 |
seq_of_parameters タイプ:
このパラメーターは必須です。 |
catalogs
方法
カタログに関するメタデータクエリを実行します。 実際の結果は、 fetchmany
または fetchall
を使用してフェッチする必要があります。 結果セットの重要なフィールドは次のとおりです。
フィールド名:
TABLE_CAT
。 タイプ:str
. カタログの名前。
パラメーターはありません。
戻り値はありません。
バージョン 1.0 以降
schemas
方法
スキーマに関するメタデータクエリを実行します。 実際の結果は、 fetchmany
または fetchall
を使用してフェッチする必要があります。 結果セットの重要なフィールドは次のとおりです。
フィールド名:
TABLE_SCHEM
。 タイプ:str
. スキーマの名前。フィールド名:
TABLE_CATALOG
。 タイプ:str
. スキーマが属するカタログ。
戻り値はありません。
バージョン 1.0 以降
パラメーター |
---|
catalog_name 種類: 情報を取得するカタログ名。 このパラメーターはオプションです。 |
schema_name 種類: 情報を取得するスキーマ名。 このパラメーターはオプションです。 |
tables
方法
テーブルとビューに関するメタデータ クエリを実行します。 実際の結果は、 fetchmany
または fetchall
を使用してフェッチする必要があります。 結果セットの重要なフィールドは次のとおりです。
フィールド名:
TABLE_CAT
。 タイプ:str
. 表が属するカタログ。フィールド名:
TABLE_SCHEM
。 タイプ:str
. テーブルが属するスキーマ。フィールド名:
TABLE_NAME
。 タイプ:str
. テーブルの名前。フィールド名:
TABLE_TYPE
. 「str
. 関係の種類。たとえば、VIEW
またはTABLE
(Databricks Runtime 10.4 LTS 以上と Databricks SQL に適用されます。それより前のバージョンの Databricks Runtime は空の文字列を返します)。
戻り値はありません。
バージョン 1.0 以降
パラメーター |
---|
catalog_name 種類: 情報を取得するカタログ名。 このパラメーターはオプションです。 |
schema_name 種類: 情報を取得するスキーマ名。 このパラメーターはオプションです。 |
table_name 種類: 情報を取得するテーブル名。 このパラメーターはオプションです。 |
table_types 種類: 照合するテーブルタイプのリスト ( このパラメーターはオプションです。 |
columns
方法
列に関するメタデータクエリを実行します。 実際の結果は、 fetchmany
または fetchall
を使用してフェッチする必要があります。 結果セットの重要なフィールドは次のとおりです。
フィールド名:
TABLE_CAT
。 タイプ:str
. 列が属するカタログ。フィールド名:
TABLE_SCHEM
。 タイプ:str
. 列が属するスキーマ。フィールド名:
TABLE_NAME
。 タイプ:str
. 列が属するテーブルの名前。フィールド名:
COLUMN_NAME
。 タイプ:str
. 列の名前。
戻り値はありません。
バージョン 1.0 以降
パラメーター |
---|
catalog_name 種類: 情報を取得するカタログ名。 このパラメーターはオプションです。 |
schema_name 種類: 情報を取得するスキーマ名。 このパラメーターはオプションです。 |
table_name 種類: 情報を取得するテーブル名。 このパラメーターはオプションです。 |
column_name 種類: 情報を取得する列名。 このパラメーターはオプションです。 |
fetchall
方法
クエリーのすべて (または残りのすべて) 行を取得します。
パラメーターはありません。
クエリーのすべての (または残りのすべての) 行を、 Row
オブジェクトの Python list
として返します。
execute メソッドの前の呼び出しでデータが返されなかったか execute
呼び出しがまだ行われていない場合に、 Error
をスローします。
fetchmany
方法
クエリーの次の行を取得します。
クエリーの次の行の最大 size
(size
が指定されていない場合は arraysize 属性) を、 Row
オブジェクトの Python list
として返します。フェッチする行が size
行未満の場合は、残りの行がすべて返されます。
execute メソッドの前の呼び出しでデータが返されなかったか execute
呼び出しがまだ行われていない場合に、 Error
をスローします。
パラメーター |
---|
大きさ 種類: 取得する次の行の数。 このパラメーターはオプションです。 指定しない場合は、 例: |
fetchone
方法
データセットの次の行を取得します。
パラメーターはありません。
データセットの次の行を Python tuple
オブジェクトとして 1 つのシーケンスとして返し、使用可能なデータがなくなった場合は None
を返します。
execute メソッドの前の呼び出しでデータが返されなかったか execute
呼び出しがまだ行われていない場合に、 Error
をスローします。
fetchall_arrow
方法
クエリーのすべて (または残りのすべて) 行を PyArrow Table
オブジェクトとして取得します。 非常に大量のデータを返すクエリーは、メモリ消費を減らすために代わりに fetchmany_arrow
を使用する必要があります。
パラメーターはありません。
クエリーのすべて (または残りのすべて) 行を PyArrow テーブルとして返します。
execute メソッドの前の呼び出しでデータが返されなかったか execute
呼び出しがまだ行われていない場合に、 Error
をスローします。
バージョン 2.0 以降
fetchmany_arrow
方法
クエリーの次の行を PyArrow Table
オブジェクトとして取得します。
クエリーの次の行の size
引数 (size
が指定されていない場合は arraysize 属性) までを Python PyArrow Table
オブジェクトとして返します。
execute メソッドの前の呼び出しでデータが返されなかったか execute
呼び出しがまだ行われていない場合に、 Error
をスローします。
バージョン 2.0 以降
パラメーター |
---|
大きさ 種類: 取得する次の行の数。 このパラメーターはオプションです。 指定しない場合は、 例: |
Row
クラス
行クラスは、個々の結果行を表すタプルのようなデータ構造です。 行に "my_column"
という名前の列が含まれている場合は、 row.my_column
を介して row
の "my_column"
フィールドにアクセスできます。数値インデックスを使用して、 row[0]
などのフィールドにアクセスすることもできます。 列名が属性メソッド名として許可されていない場合 (たとえば、数字で始まる場合)、フィールドには row["1_my_column"]
としてアクセスできます。
バージョン 1.0 以降
型変換
次の表は、Apache Spark SQL データ型を同等の Python データ型にマップします。
Apache Spark SQL データ型 |
Python データ型 |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
トラブルシューティング
tokenAuthWrapperInvalidAccessToken: Invalid access token
メッセージ
問題: コードを実行すると、 Error during request to server: tokenAuthWrapperInvalidAccessToken: Invalid access token
のようなメッセージが表示されます。
考えられる原因: access_token
に渡された値が有効な 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
に渡された値が正しいことを確認し、再試行してください。
サーバーのホスト名の検索の詳細については、「 Databricks コンピュート リソースの接続の詳細を取得する」を参照してください。