適用於 Python 的 Databricks SQL 連接器
Databricks SQL Connector for Python 是一個 Python 連結庫，可讓您使用 Python 程式代碼在 Azure Databricks 叢集和 Databricks SQL 倉儲上執行 SQL 命令。 適用於 Python 的 Databricks SQL Connector 比 pyodbc 之類的類似 Python 連結庫更容易設定及使用。 此連結庫遵循 PEP 249 – Python 資料庫 API 規格 v2.0。
注意
適用於 Python 的 Databricks SQL 連接器也包含 適用於 Azure Databricks 的 SQLAlchemy 方言。 請參閱 搭配 Azure Databricks 使用 SQLAlchemy。
需求
- 執行 Python >=3.8 和 <=3.11 的開發計算機。
- Databricks 建議您使用 Python 虛擬環境，例如 Python 隨附的 venv 所提供的環境。 虛擬環境可協助您確保同時使用正確的 Python 版本和適用於 Python 的 Databricks SQL Connector。 設定和使用虛擬環境不在本文的範圍內。 如需詳細資訊，請參閱 建立虛擬環境。
- 現有的 叢集 或 SQL 倉儲。
開始使用
執行
pip install databricks-sql-connector或python -m pip install databricks-sql-connector，在您的開發計算機上安裝 Databricks SQL Connector for Python 連結庫。針對您想要使用的叢集或 SQL 倉儲，收集下列資訊：
Cluster
- 叢集的伺服器主機名。 您可以從叢集的 [進階選項 > JDBC/ODBC] 索引標籤中的 [伺服器主機名] 值取得此值。
- 叢集的 HTTP 路徑。 您可以從叢集的 [進階選項 > JDBC/ODBC] 索引標籤中的 [HTTP 路徑] 值取得此值。
SQL 倉儲
- SQL 倉儲的伺服器主機名。 您可以從 SQL 倉儲的 [連線詳細資料] 索引標籤中的 [伺服器主機名] 值取得此值。
- SQL 倉儲的 HTTP 路徑。 您可以從 SQL 倉儲的 [連線詳細資料] 索引標籤中的 [HTTP 路徑] 值取得此值。
驗證
適用於 Python 的 Databricks SQL 連接器支援下列 Azure Databricks 驗證類型：
- Databricks 個人存取令牌驗證
- Microsoft Entra ID （先前稱為 Azure Active Directory） 令牌驗證
- OAuth 機器對機器 (M2M) 驗證
- OAuth 使用者對電腦 （U2M） 驗證
適用於 Python 的 Databricks SQL 連接器尚不支援下列 Azure Databricks 驗證類型：
Databricks 個人存取令牌驗證
若要搭配 Azure Databricks 個人存取令牌驗證使用適用於 Python 的 Databricks SQL 連接器，您必須先建立 Azure Databricks 個人存取令牌，如下所示：
- 在 Azure Databricks 工作區中，按兩下頂端列中的 Azure Databricks 使用者名稱，然後從下拉式清單中選取 [設定 ]。
- 按兩下 [ 開發人員]。
- 按兩下 [存取令牌] 旁的 [管理]。
- 按一下 [產生新權杖]。
- （選擇性）輸入批注，協助您在未來識別此令牌，並變更令牌的預設存留期 90 天。 若要建立沒有存留期的令牌（不建議），請將 [ 存留期（天）] 方塊保留空白（空白）。
- 按一下 [產生]。
- 將顯示的令牌複製到安全的位置，然後按兩下 [ 完成]。
注意
請務必將複製的令牌儲存在安全的位置。 請勿與其他人共享複製的令牌。 如果您遺失複製的令牌，就無法重新產生完全相同的令牌。 相反地，您必須重複此程式來建立新的令牌。 如果您遺失複製的令牌，或您認為令牌已遭入侵，Databricks 強烈建議您按兩下存取令牌頁面上令牌旁邊的垃圾桶 （Revoke） 圖示，立即從工作區中刪除該令牌。
如果您無法在工作區中建立或使用令牌，這可能是因為您的工作區系統管理員已停用令牌，或未授與您建立或使用令牌的許可權。 請參閱您的工作區管理員或下列專案：
若要驗證適用於 Python 的 Databricks SQL Connector，請使用下列代碼段。 此代碼段假設您已設定下列環境變數：
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 Connector 支援 OAuth 機器對機器 （M2M） 驗證。 您也必須安裝 Databricks SDK for Python 0.18.0 或更新版本（例如執行 pip install databricks-sdk 或 python -m pip install databricks-sdk）。
若要搭配 OAuth M2M 驗證使用適用於 Python 的 Databricks SQL Connector，您必須執行下列動作：
在 Azure Databricks 工作區中建立 Azure Databricks 服務主體，併為該服務主體建立 OAuth 秘密。
若要建立服務主體及其 OAuth 秘密，請參閱 使用服務主體向 Azure Databricks 進行驗證。 記下服務主體的 UUID 或應用程式識別碼值，以及服務主體 OAuth 秘密的秘密值。
為該服務主體提供叢集或倉儲的存取權。
若要驗證適用於 Python 的 Databricks SQL Connector，請使用下列代碼段。 此代碼段假設您已設定下列環境變數：
DATABRICKS_SERVER_HOSTNAME設定為叢集或 SQL 倉儲的伺服器 主機名 值。DATABRICKS_HTTP_PATH，設定為 叢集或 SQL 倉儲的 HTTP 路徑 值。DATABRICKS_CLIENT_ID，設定為服務主體的 UUID 或 應用程式識別碼 值。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:
# ...
Microsoft Entra ID （先前稱為 Azure Active Directory） 令牌驗證
若要使用 Databricks SQL Connector for Python 搭配 Microsoft Entra ID （先前稱為 Azure Active Directory） 令牌驗證，您必須提供 Databricks SQL Connector for Python 搭配 Microsoft Entra ID 令牌。 若要建立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 識別碼令牌的預設存留期約為 1 小時。 若要建立新的Microsoft Entra ID 令牌，請重複此程式。
若要驗證適用於 Python 的 Databricks SQL Connector，請使用下列代碼段。 此代碼段假設您已設定下列環境變數：
- 設定
DATABRICKS_SERVER_HOSTNAME為叢集或 SQL 倉儲的伺服器 主機名 值。 - 設定
DATABRICKS_HTTP_PATH為 叢集或 SQL 倉儲的 HTTP 路徑 值。 - 設定
DATABRICKS_TOKEN為 Microsoft Entra ID 令牌。
若要設定環境變數，請參閱作業系統的檔。
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 Connector 支援 OAuth 使用者對計算機 （U2M） 驗證。 您也必須安裝 Databricks SDK for Python 0.19.0 或更新版本（例如執行 pip install databricks-sdk 或 python -m pip install databricks-sdk）。
若要使用 OAuth U2M 驗證來驗證適用於 Python 的 Databricks SQL Connector，請使用下列代碼段。 OAuth U2M 驗證會使用即時人類登入和同意來驗證目標 Azure 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:
# ...
範例
下列程式代碼範例示範如何使用適用於 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 Connector，在叢集或 SQL 倉儲上執行基本 SQL 命令。 此命令會從trips目錄nyctaxi架構中的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()
管理 Unity 目錄磁碟區中的檔案
Databricks SQL 連接器可讓您將本機檔案寫入 Unity 目錄 磁碟區、從磁碟區下載檔，以及從磁碟區刪除檔案，如下列範例所示：
from databricks import sql
import os
# For writing local files to volumes and downloading files from volumes,
# you must set the staging_allows_local_path argument to the path to the
# local folder that contains the files to be written or downloaded.
# For deleting files in volumes, you must also specify the
# staging_allows_local_path argument, but its value is ignored,
# so in that case its value can be set for example to an empty string.
with sql.connect(server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
http_path = os.getenv("DATABRICKS_HTTP_PATH"),
access_token = os.getenv("DATABRICKS_TOKEN"),
staging_allowed_local_path = "/tmp/") as connection:
with connection.cursor() as cursor:
# Write a local file to the specified path in a volume.
# Specify OVERWRITE to overwrite any existing file in that path.
cursor.execute(
"PUT '/temp/my-data.csv' INTO '/Volumes/main/default/my-volume/my-data.csv' OVERWRITE"
)
# Download a file from the specified path in a volume.
cursor.execute(
"GET '/Volumes/main/default/my-volume/my-data.csv' TO '/tmp/my-downloaded-data.csv'"
)
# Delete a file from the specified path in a volume.
cursor.execute(
"REMOVE '/Volumes/main/default/my-volume/my-data.csv'"
)
設定記錄
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()
測試
若要測試程序代碼，請使用 Python 測試架構，例如 pytest。 若要在模擬條件下測試程序代碼，而不呼叫 Azure Databricks REST API 端點，或變更 Azure Databricks 帳戶或工作區的狀態，您可以使用 Python 模擬連結庫，例如 unittest.mock。
例如，假設下列名為 helpers.py 的檔案，其中包含使用 get_connection_personal_access_token Azure Databricks 個人存取令牌傳回 Azure Databricks 工作區連線的函式，以及 select_nyctaxi_trips 使用連線從 trips 目錄架構中 samples 數據表取得指定數據列數目的 nyctaxi 函式：
# helpers.py
from databricks import sql
from databricks.sql.client import Connection, List, Row, Cursor
def get_connection_personal_access_token(
server_hostname: str,
http_path: str,
access_token: str
) -> Connection:
return sql.connect(
server_hostname = server_hostname,
http_path = http_path,
access_token = access_token
)
def select_nyctaxi_trips(
connection: Connection,
num_rows: int
) -> List[Row]:
cursor: Cursor = connection.cursor()
cursor.execute(f"SELECT * FROM samples.nyctaxi.trips LIMIT {num_rows}")
result: List[Row] = cursor.fetchall()
return result
並指定下列名為 的檔案，該檔案會 main.py 呼叫 get_connection_personal_access_token 和 select_nyctaxi_trips 函式：
# main.py
from databricks.sql.client import Connection, List, Row
import os
from helpers import get_connection_personal_access_token, select_nyctaxi_trips
connection: Connection = get_connection_personal_access_token(
server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME"),
http_path = os.getenv("DATABRICKS_HTTP_PATH"),
access_token = os.getenv("DATABRICKS_TOKEN")
)
rows: List[Row] = select_nyctaxi_trips(
connection = connection,
num_rows = 2
)
for row in rows:
print(row)
下列名為 test_helpers.py 的檔案會測試函 select_nyctaxi_trips 式是否傳回預期的回應。 此測試會模擬 Connection 物件，而不是建立與目標工作區的實際連線。 測試也會模擬一些符合實際數據的架構和值的數據。 測試會透過模擬連接傳回仿真的數據，然後檢查其中一個仿真的數據列值是否符合預期的值。
# test_helpers.py
import pytest
from databricks.sql.client import Connection, List, Row
from datetime import datetime
from helpers import select_nyctaxi_trips
from unittest.mock import create_autospec
@pytest.fixture
def mock_data() -> List[Row]:
return [
Row(
tpep_pickup_datetime = datetime(2016, 2, 14, 16, 52, 13),
tpep_dropoff_datetime = datetime(2016, 2, 14, 17, 16, 4),
trip_distance = 4.94,
fare_amount = 19.0,
pickup_zip = 10282,
dropoff_zip = 10171
),
Row(
tpep_pickup_datetime = datetime(2016, 2, 4, 18, 44, 19),
tpep_dropoff_datetime = datetime(2016, 2, 4, 18, 46),
trip_distance = 0.28,
fare_amount = 3.5,
pickup_zip = 10110,
dropoff_zip = 10110
)
]
def test_select_nyctaxi_trips(mock_data: List[Row]):
# Create a mock Connection.
mock_connection = create_autospec(Connection)
# Set the mock Connection's cursor().fetchall() to the mock data.
mock_connection.cursor().fetchall.return_value = mock_data
# Call the real function with the mock Connection.
response: List[Row] = select_nyctaxi_trips(
connection = mock_connection,
num_rows = 2)
# Check the value of one of the mocked data row's columns.
assert response[1].fare_amount == 3.5
因為函 select_nyctaxi_trips 式包含 SELECT 語句，因此不會變更數據表的狀態 trips ，所以在此範例中不需要模擬。 不過，模擬可讓您快速執行測試，而不需要等待實際連線與工作區建立。 此外，模擬可讓您針對可能會變更資料表狀態的函式執行模擬測試多次，例如 INSERT INTO、 UPDATE和 DELETE FROM。
API 參考
套件
databricks-sql-connector
使用方式：pip install databricks-sql-connector
另 請參閱 Python 套件索引 （PyPI） 中的 databricks-sql-connector 。
模組
databricks.sql
使用方式：from databricks import sql
類別
選取的類別包括下列專案：
| 類別 |
|---|
ConnectionAzure Databricks 計算資源的會話。 |
Cursor周遊數據記錄的機制。 |
RowSQL 查詢結果中的數據列。 |
Connection 類別
若要建立 Connection 物件，請使用下列參數呼叫 databricks.sql.connect 方法：
| 參數 |
|---|
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, 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。如果 use_cloud_fetch 設定為 True ，但網路存取遭到封鎖，則提取要求將會失敗。自 2.8 版起 |
選取 Connection 的方法包括下列專案：
| 方法 |
|---|
close關閉資料庫的連線，並釋放伺服器上的所有相關聯資源。 對這個連線的任何其他呼叫都會擲回 Error。無參數。 沒有傳回值。 |
cursor傳回可周游資料庫中記錄的新 Cursor 物件。無參數。 |
Cursor 類別
若要建立 Cursor 物件，請呼叫 Connection 類別的 cursor 方法。
選取 Cursor 的屬性包括下列專案：
| 屬性 |
|---|
arraysize與 方法搭配 fetchmany 使用，指定內部緩衝區大小，這也是一次從伺服器擷取的數據列數目。 預設值是 10000。 對於窄的結果（其中每個數據列不包含大量數據的結果），您應該增加此值以提升效能。讀寫存取權。 |
description包含物件的 Python list tuple 。 每個 tuple 物件都包含 7 個值，其中每個 tuple 物件的前 2 個專案包含描述單一結果數據行的資訊，如下所示：* name：數據行的名稱。* type_code：字串，表示數據行的類型。 例如，整數資料行的類型代碼 int會是 。不會實作每個 7 個專案對象的其餘 5 個專案 tuple ，而且不會定義其值。 它們通常會傳回為 4None 值後面接著單 True 一值。唯讀存取權。 |
選取 Cursor 的方法包括下列專案：
| 方法 |
|---|
cancel中斷執行數據指標已啟動的任何資料庫查詢或命令。 若要釋放伺服器上的相關聯資源，請呼叫 close 呼叫 方法之後的 cancel 方法。無參數。 沒有傳回值。 |
close關閉數據指標，並釋放伺服器上的相關聯資源。 關閉已經關閉的數據指標可能會擲回錯誤。 無參數。 沒有傳回值。 |
execute準備然後執行資料庫查詢或命令。 沒有傳回值。 參數： operation類型: 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 參數序列來執行資料庫查詢或命令。 只會保留最終的結果集。沒有傳回值。 參數： operation類型: str (英文)要準備然後執行的查詢或命令。 此為必要參數。 seq_of_parameters類型： list 的 dict要搭配 使用的許多參數值集合序列 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.4 LTS 和更新版本以及 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取得查詢的所有（或所有剩餘）數據列。 無參數。 以 Python list 傳回查詢的所有（或所有剩餘）數據列Row 物件。Error如果先前對 方法的execute呼叫未傳回任何資料，或execute尚未進行呼叫，則擲回 。 |
fetchmany取得查詢的下一個數據列。 最多 size會傳回查詢下一個數據列的下一個數據列作為 物件的 Python list Row，或 arraysize 屬性size。如果擷取的數據列少於 size 剩餘的數據列，則會傳回所有剩餘的數據列。Error如果先前對 方法的execute呼叫未傳回任何資料，或execute尚未進行呼叫，則擲回 。參數： size類型: int (英文)要取得的下一個數據列數目。 這是選擇性參數。 如果未指定，則會使用 屬性的值 arraysize 。範例: cursor.fetchmany(10) |
fetchone取得數據集的下一個數據列。 無參數。 以 Python 的形式傳回數據集的下一個數據列作為單一序列 tuple 物件，如果沒有可用的數據，則傳回 None 。Error如果先前對 方法的execute呼叫未傳回任何資料，或execute尚未進行呼叫，則擲回 。 |
fetchall_arrow取得查詢的所有（或所有剩餘）數據列，做為 PyArrow Table 物件。 傳回非常大量數據的查詢應該改用 fetchmany_arrow 以減少記憶體耗用量。無參數。 以 PyArrow 數據表的形式傳回查詢的所有（或所有剩餘）數據列。 Error如果先前對 方法的execute呼叫未傳回任何資料，或execute尚未進行呼叫，則擲回 。自 2.0 版起 |
fetchmany_arrow取得查詢的下一個數據列做為 PyArrow Table 物件。以 size Python PyArrow 傳回查詢下一個資料列的自變數（如果size未指定，則arraysize傳回 屬性）Table 物件Error如果先前對 方法的execute呼叫未傳回任何資料，或execute尚未進行呼叫，則擲回 。自 2.0 版起 參數： size類型: int (英文)要取得的下一個數據列數目。 這是選擇性參數。 如果未指定，則會使用 屬性的值 arraysize 。範例: cursor.fetchmany_arrow(10) |
Row 類別
數據列類別是類似 Tuple 的數據結構，代表個別的結果數據列。
如果資料列包含名稱"my_column"為的數據行，您可以透過 row.my_column存取 "my_column" 的row欄位。 您也可以使用數值索引來存取欄位，例如 row[0]。
如果不允許資料列名稱做為屬性方法名稱（例如，其開頭為數位），則您可以將欄位存取為 row["1_my_column"]。
自 1.0 版起
選取 Row 的方法包括：
| 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、floatbytearray、int和str） - Python 網站上的 datetime （for
datetime.dateanddatatime.datetime） - Python 網站上的十進位 （for
decimal.Decimal） - Python 網站上的內建常數 （for
NoneType）
意見反映
即將推出：我們會在 2024 年淘汰 GitHub 問題，並以全新的意見反應系統取代並作為內容意見反應的渠道。 如需更多資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交及檢視以下的意見反映：