Python と pyodbc を Databricks に接続する
ローカル Python API コードから ODBC を介して、 Databricks クラスターまたは SQLウェアハウス内のデータに接続できます。 これを行うには、オープンソース Python コード モジュール pyodbc
を使用できます。
次の手順に従って、 pyodbc
をインストール、構成、および使用します。
pyodbc
の詳細については、 pyodbc Wiki を参照してください。
Databricks は、pyodbc
の代わりに Databricks SQL Connector for Python を提供しています。Databricks SQL Connector for Python は、 pyodbc
よりもセットアップと使用が簡単で、より堅牢なコーディング コンストラクトのセットを備えています。 ただし pyodbc
10 MB を超えるクエリ結果をフェッチすると、パフォーマンスが向上する可能性があります。
これらの手順は、 Databricks ODBC ドライバー 2.7.5、 pyodbc 5.0.1、 および unixODBC 2.3.12 でテストされています。
必要条件
-
次のいずれかを実行しているローカル開発マシン。
- macOSの
- Windows
.rpm
または.deb
ファイルをサポートする Unix または Linux ディストリビューション
-
Databricks クラスター、Databricks SQL ウェアハウス、またはその両方。詳細については、「コンピュート構成リファレンス」および「SQLウェアハウスへの接続」を参照してください。
ステップ 1: ソフトウェアのダウンロード、インストール、および構成
この手順では、Databricks ODBC ドライバー、 unixodbc
パッケージ、および pyodbc
モジュールをダウンロードしてインストールします。 ( pyodbc
モジュールには、Unix、Linux、macOS の unixodbc
パッケージが必要です。 また、 ODBC データソース名 (DSN) を設定して、クラスターまたはウェアハウスで認証および接続 SQL。
- Databricks ODBC ドライバーをダウンロードしてインストール し、オペレーティング システム用の ODBC DSN を構成します 。
- Unix、Linux、およびmacOSの場合は、
unixodbc
パッケージをインストールします:ターミナルから、Homebrewを使用してコマンドを実行しますbrew install unixodbc
。 詳細については、Homebrew Web サイトの unixodbc を参照してください。 pyodbc
モジュールをインストールします:ターミナルまたはコマンドプロンプトから、pip
を使用してコマンドを実行しますpip install pyodbc
。pyodbc詳細については、PyPI Web サイトの およびpyodbcWiki のインストールを参照してください 。
ステップ2: 設定をテストしてください
このステップでは、Python DatabricksクラスターまたはDatabricks SQL ウェアハウスを使用して カタログのtrips
スキーマのsamples
nyctrips
テーブルをクエリし、結果を表示するための コードを記述して実行します。
-
次の内容で
pyodbc-demo.py
という名前のファイルを作成します。<dsn-name>
を前に作成した ODBC DSN の名前に置き換え、ファイルを保存してから、Python インタープリターでファイルを実行します。Pythonimport pyodbc
# Connect to the Databricks cluster by using the
# Data Source Name (DSN) that you created earlier.
conn = pyodbc.connect("DSN=<dsn-name>", autocommit=True)
# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute(f"SELECT * FROM samples.nyctaxi.trips")
# Print the rows retrieved from the query.
for row in cursor.fetchall():
print(row) -
コードの実行を高速化するには、DSN の
HTTPPath
設定に対応するクラスターを開始します。 -
Pythonインタプリタで
pyodbc-demo.py
ファイルを実行します。 テーブルのローに関する情報が表示されます。
次のステップ
- Python別のクラスターまたはSQL ウェアハウスに対して テストコードを実行するには、別のDSNを作成し、
<dsn-name>
をDSNの名前に変更します。 - Python テスト・コードを別の SQL クエリーで実行するには、
execute
コマンド文字列を変更します。
DSN レス接続の使用
DSN 名を使用する代わりに、接続設定をインラインで指定することもできます。 次の例は、Databricks の個人用アクセス トークン認証に DSN なしの接続文字列を使用する方法を示しています。 この例では、次の環境変数があることを前提としています。
DATABRICKS_SERVER_HOSTNAME
をワークスペース インスタンス名に設定します (例:dbc-a1b2345c-d6e7.cloud.databricks.com
)。DATABRICKS_HTTP_PATH
を、ワークスペース内のターゲット クラスターまたはウェアハウスの HTTP パス 値 SQL設定します。 HTTP パス の値を取得するには、「Databricks コンピュート リソースの接続の詳細を取得する」を参照してください。DATABRICKS_TOKEN
をターゲット ユーザーの Databricks 個人用アクセス トークンに設定します。個人用アクセス トークンを作成するには、「ワークスペース ユーザー向けの個人用アクセス トークンDatabricks」を参照してください。
環境変数を設定するには、ご利用になっているオペレーティングシステムのドキュメントを参照してください。
import pyodbc
import os
conn = pyodbc.connect(
"Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
f"Host={os.getenv('DATABRICKS_HOST')};" +
"Port=443;" +
f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
"SSL=1;" +
"ThriftTransport=2;" +
"AuthMech=3;" +
"UID=token;" +
f"PWD={os.getenv('DATABRICKS_TOKEN')}",
autocommit = True
)
# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")
# Print the rows retrieved from the query.
for row in cursor.fetchall():
print(row)
次の例では、Databricks 個人用アクセス トークンの代わりに OAuth ユーザー間 (U2M) または OAuth 2.0 ブラウザーベースの認証を使用します。 この例では、前述の DATABRICKS_SERVER_HOSTNAME
環境変数と DATABRICKS_HTTP_PATH
環境変数を既に設定していることを前提としています。
import pyodbc
import os
conn = pyodbc.connect(
"Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
f"Host={os.getenv('DATABRICKS_HOST')};" +
"Port=443;" +
f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
"SSL=1;" +
"ThriftTransport=2;" +
"AuthMech=11;" +
"Auth_Flow=2;" +
"PWD=1234567",
autocommit = True
)
# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")
# Print the rows retrieved from the query.
for row in cursor.fetchall():
print(row)
次の例では、OAuth マシン間 (M2M) または OAuth 2.0 クライアント資格情報認証を使用しています。 この例では、前述の DATABRICKS_SERVER_HOSTNAME
環境変数と DATABRICKS_HTTP_PATH
環境変数、および次の環境変数を既に設定していることを前提としています。
DATABRICKS_CLIENT_ID
をサービスプリンシパルの UUID / Application ID 値に設定します。DATABRICKS_OAUTH_SECRET
をサービスプリンシパルの OAuth Secret 値に設定します。
詳細については、「 OAuth マシン間 (M2M) 認証」を参照してください。
import pyodbc
import os
conn = pyodbc.connect(
"Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
f"Host={os.getenv('DATABRICKS_HOST')};" +
"Port=443;" +
f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
"SSL=1;" +
"ThriftTransport=2;" +
"AuthMech=11;" +
"Auth_Flow=1;" +
f"Auth_Client_ID={os.getenv('DATABRICKS_CLIENT_ID')};" +
f"Auth_Client_Secret={os.getenv('DATABRICKS_OAUTH_SECRET')}",
autocommit = True
)
# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")
# Print the rows retrieved from the query.
for row in cursor.fetchall():
print(row)
トラブルシューティング
このセクションでは、Databricks で pyodbc
を使用する場合の一般的な問題について説明します。
Unicode デコード エラー
問題 :次のようなエラーメッセージが表示されます。
<class 'pyodbc.Error'> returned a result with an error set
Traceback (most recent call last):
File "/Users/user/.pyenv/versions/3.7.5/lib/python3.7/encodings/utf_16_le.py", line 16, in decode
return codecs.utf_16_le_decode(input, errors, True)
UnicodeDecodeError: 'utf-16-le' codec can't decode bytes in position 2112-2113: illegal UTF-16 surrogate
原因 : pyodbc
バージョン 4.0.31 以下に問題があり、長い名前の列または長いエラー メッセージを返すクエリを実行すると、このような症状が発生する可能性があります。 この問題は、新しいバージョンの pyodbc
で修正されています。
ソリューション : pyodbc
のインストールをバージョン 4.0.32 以降にアップグレードします。