適用於 Python 的 Databricks SQL 連接器

發行項
10/10/2024

適用於 Python 的 Databricks SQL 連接器是一個 Python 程式庫，可讓您使用 Python 程式碼在 Azure Databricks 叢集和 Databricks SQL 倉儲上執行 SQL 命令。適用於 Python 的 Databricks SQL 連接器比類似的 Python 程式庫 (例如 pyodbc) 更容易設定和使用。此程式庫遵循 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 連接器。設定和使用虛擬環境不屬於本文的討論範圍。如需詳細資訊，請參閱建立虛擬環境。
現有的叢集或 SQL 倉儲。

開始使用

透過執行 pip install databricks-sql-connector 或 python -m pip install databricks-sql-connector，在您的開發機器上安裝適用於 Python 的 Databricks SQL 連接器程式庫。
針對想要使用的叢集或 SQL 倉儲，收集下列資訊：

Cluster
- 叢集的伺服器主機名稱。您可以從叢集的 [進階選項 > JDBC/ODBC] 索引標籤中的 [伺服器主機名稱] 值取得此值。
- 叢集的 HTTP 路徑。您可以從叢集的 [進階選項 > JDBC/ODBC] 索引標籤中的 [HTTP 路徑] 值取得此值。
SQL 倉儲
- SQL 倉儲的伺服器主機名稱。您可以從 SQL 倉儲的 [連線詳細資料] 索引標籤中的 [伺服器主機名稱] 值取得此值。
- SQL 倉儲的 HTTP 路徑。您可以從 SQL 倉儲的 [連線詳細資料] 索引標籤中的 [HTTP 路徑] 值取得此值。

驗證

適用於 Python 的 Databricks SQL 連接器支援下列 Azure Databricks 驗證類型：

Databricks 個人存取權杖驗證
Microsoft Entra ID 權杖驗證
OAuth 機器對機器 (M2M) 驗證
OAuth 使用者對機器 (U2M) 驗證

適用於 Python 的 Databricks SQL 連接器尚不支援下列 Azure Databricks 驗證類型：

Databricks 個人存取權杖驗證

若要搭配 Azure Databricks 個人存取權杖驗證使用適用於 Python 的 Databricks SQL 連接器，您必須首先建立 Azure Databricks 個人存取權杖，如下所示：

在 Azure Databricks 工作區中，按一下頂端列中的 Azure Databricks 使用者名稱，然後從下拉式清單中選取 [設定]。
按一下 [開發人員]。
在 [存取權杖] 旁，按一下 [管理]。
按一下 產生新權杖。
(選擇性) 輸入可協助您之後識別此權杖的註解，並變更權杖的預設存留期 90 天。若要建立沒有存留期的權杖 (不建議)，請將 [存留期 (天)] 方塊留空 (空白)。
按一下產生。
將顯示的權杖複製到安全位置，然後選取 [完成]。

注意

請務必將複製的權杖儲存在安全位置。請勿與其他人共用複製的權杖。如果您遺失複製的權杖，就無法重新產生完全相同的權杖。相反地，您必須重複此程序來建立新的權杖。如果您遺失複製的權杖，或您認為權杖已遭入侵，Databricks 強烈建議您按一下 [存取權杖] 頁面上權杖旁邊的垃圾桶 (撤銷) 圖示，立即從工作區中刪除該權杖。

注意：如果您無法在工作區中建立或使用 PAT，這可能是因為您的工作區系統管理員已停用權杖，或未授與您建立或使用權杖的權限。請諮詢您的工作區系統管理員或參閱下列主題：

若要驗證適用於 Python 的 Databricks SQL 連接器，請使用下列程式碼片段。此片段假設您已設定下列環境變數：

將 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 的 Databricks SQL 連接器 2.7.0 版和更新版本支援 OAuth 機器對機器 (M2M) 驗證。您也必須安裝適用於 Python 的 Databricks SDK 0.18.0 或更新版本 (例如透過執行 pip install databricks-sdk 或 python -m pip install databricks-sdk)。

若要搭配 OAuth M2M 驗證使用適用於 Python 的 Databricks SQL 連接器，您必須執行下列動作：

在 Azure Databricks 工作區中建立 Azure Databricks 服務主體，並為該服務主體建立 OAuth 祕密。

若要建立服務主體及其 OAuth 祕密，請參閱使用 OAuth (OAuth M2M) 透過服務主體對 Azure Databricks 的存取進行驗證。記下服務主體的 [UUID] 或 [應用程式 ID] 值，以及服務主體 OAuth 祕密的 [祕密]值。
為服務主體提供叢集或倉儲的存取權。

若要授與服務主體對叢集或倉儲的存取權，請參閱計算權限或管理 SQL 倉儲。

若要驗證適用於 Python 的 Databricks SQL 連接器，請使用下列程式碼片段。此片段假設您已設定下列環境變數：

將 DATABRICKS_SERVER_HOSTNAME 設定為叢集或 SQL 倉儲的 [伺服器主機名稱] 值。
DATABRICKS_HTTP_PATH，設定為叢集或 SQL 倉儲的 HTTP 路徑 值。
DATABRICKS_CLIENT_ID，設定為服務主體的 [UUID] 或 [應用程式 ID] 值。
DATABRICKS_CLIENT_SECRET，設定為 Azure Databricks 服務主體的 OAuth [祕密] 值。

若要設定環境變數，請參閱您的作業系統文件。

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 權杖驗證

若要使用適用於 Python 的 Databricks SQL 連接器搭配 Microsoft Entra ID 權杖驗證，您必須提供適用於 Python 的 Databricks SQL 連接器和 Microsoft Entra ID 權杖。若要建立 Microsoft Entra ID 存取權杖，請按照下列步驟操作：

針對 Azure Databricks 使用者，您可使用 Azure CLI。請參閱使用 Azure CLI 取得使用者的 Microsoft Entra ID 權杖。
如需 Microsoft Entra ID 服務主體，請參閱使用 Azure CLI 取得Microsoft Entra ID 存取權杖。若要建立 Microsoft Entra ID 受控服務主體，請參閱管理服務主體。

Microsoft Entra ID 權杖的預設存留期約為 1 小時。若要建立新的 Microsoft Entra ID 權杖，請重複此程序。

若要驗證適用於 Python 的 Databricks SQL 連接器，請使用下列程式碼片段。此片段假設您已設定下列環境變數：

將 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 的 Databricks SQL 連接器 2.7.0 版和更新版本支援 OAuth 使用者對機器 (M2M) 驗證。您也必須安裝適用於 Python 的 Databricks SDK 0.19.0 或更新版本 (例如透過執行 pip install databricks-sdk 或 python -m pip install databricks-sdk)。

若要使用 OAuth U2M 驗證來驗證適用於 Python 的 Databricks SQL 連接器，請使用下列程式碼片段。 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 連接器來查詢和插入資料、查詢中繼資料、管理資料指標和連線，以及設定記錄。

注意

下列程式碼範例示範如何使用 Azure Databricks 個人存取權杖進行驗證。若要改用其他可用的 Azure Databricks 驗證類型，請參閱驗證。

這些程式碼範例會從下列環境變數擷取其 server_hostname、http_path 和 access_token 連線變數值：

DATABRICKS_SERVER_HOSTNAME，代表來自需求的 [伺服器主機名稱] 值。
DATABRICKS_HTTP_PATH，代表來自需求的 [HTTP 路徑] 值。
DATABRICKS_TOKEN，代表來自需求的存取權杖。

您可使用其他方法來擷取這些連線變數值。使用環境變數只是眾多方法之一。

查詢資料
插入資料
查詢中繼資料
管理資料指標和連線
管理 Unity 目錄磁碟區中的檔案
設定記錄

查詢資料

下列程式碼範例示範如何呼叫適用於 Python 的 Databricks SQL 連接器，在叢集或 SQL 倉儲上執行基本 SQL 命令。此命令會從 samples 目錄的 nyctaxi 結構描述中的 trips 資料表傳回前兩個資料列。

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 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()

測試

若要測試程式碼，請使用 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 函式，該函式使用連線從 samples 目錄 nyctaxi 結構描述中的 trips 資料表取得指定資料列數目：

# 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。

套件

databricks-sql-connector

使用方式：pip install databricks-sql-connector

另請參閱 Python 套件索引 (PyPI) 中的 databricks-sql-connector。

模組

databricks.sql

使用方式：from databricks import sql

類別

選取的類別包括下列項目：

類別
`Connection` Azure Databricks 計算資源的工作階段。
`Cursor` 周遊資料記錄的機制。
`Row` SQL 查詢結果中的資料列。

`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 倉儲的 `/sql/1.0/warehouses/a1b234c567d8e9fa`。
`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` 包含 `tuple` 物件的 Python `list`。其中每個 `tuple` 物件都包含 7 個值，每個 `tuple` 物件的前 2 個項目包含描述單一結果資料行的資訊，如下所示： - `name`：資料行名稱。 - `type_code`：表示資料行類型的字串。例如，整數資料行的類型代碼為 `int`。不會實作每個 7 項目 `tuple` 物件的其餘 5 個項目，而且不會定義其值。它們通常會傳回為 4 `None` 值後面接著單一 `True` 值。唯讀存取權。

arraysize

與 fetchmany 方法搭配使用，指定內部緩衝區大小，也就是每次從伺服器擷取的資料列數目。預設值是 10000。對於窄的結果 (其中每個資料列不包含大量資料的結果)，您應增加此值以提升效能。

讀寫存取權。

description

包含 tuple 物件的 Python list。其中每個 tuple 物件都包含 7 個值，每個 tuple 物件的前 2 個項目包含描述單一結果資料行的資訊，如下所示：

- name：資料行名稱。
- type_code：表示資料行類型的字串。例如，整數資料行的類型代碼為 int。

不會實作每個 7 項目 tuple 物件的其餘 5 個項目，而且不會定義其值。它們通常會傳回為 4
None 值後面接著單一 True 值。

唯讀存取權。

選取的 Cursor 方法包括如下項目：

方法
`cancel` 中斷執行已啟動資料指標的任何資料庫查詢或命令。要釋放伺服器上的相關聯資源，請呼叫呼叫 `cancel` 方法之後的 `close` 方法。無參數。沒有傳回值。
`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` 物件。如果先前對 `execute` 方法的呼叫未傳回任何資料，或 `execute` 尚未進行呼叫，則擲回 `Error`。
`fetchmany` 取得查詢的下一個資料列。以 `Row` 物件的 Python `list` 的形式傳回查詢的下一資料列中最多為 `size` (如果未指定 `size`，則返回 `arraysize` 屬性)。如果擷取的剩餘資料列少於 `size`，則會傳回所有剩餘的資料列。如果先前對 `execute` 方法的呼叫未傳回任何資料，或 `execute` 尚未進行呼叫，則擲回 `Error`。參數： `size` 類型:`int` (英文) 要取得的下一個資料列數目。這是選用參數。如果未指定，會使用 `arraysize` 屬性的值。範例: `cursor.fetchmany(10)`
`fetchone` 取得資料集的下一個資料列。無參數。以 Python 的形式作為單一序列傳回資料集的下一個資料列 `tuple` 物件，如果沒有可用的資料，則傳回 `None`。如果先前對 `execute` 方法的呼叫未傳回任何資料，或 `execute` 尚未進行呼叫，則擲回 `Error`。
`fetchall_arrow` 取得查詢的所有 (或所有剩餘) 資料列，作為 PyArrow `Table` 物件。傳回非常大量資料的查詢應該改用 `fetchmany_arrow` 以減少記憶體使用量。無參數。以 PyArrow 資料表的形式傳回查詢的所有 (或所有剩餘) 資料列。如果先前對 `execute` 方法的呼叫未傳回任何資料，或 `execute` 尚未進行呼叫，則擲回 `Error`。自 2.0 版起
`fetchmany_arrow` 以 PyArrow `Table` 物件的形式，取得查詢的下一資料列。以 Python PyArrow 的形式傳回查詢的下一資料列中最多為 `size` 個引數 (如果未指定 `size`，則返回 `arraysize` 屬性) `Table` 物件如果先前對 `execute` 方法的呼叫未傳回任何資料，或 `execute` 尚未進行呼叫，則擲回 `Error`。自 2.0 版起參數： `size` 類型:`int` (英文) 要取得的下一個資料列數目。這是選用參數。如果未指定，會使用 `arraysize` 屬性的值。範例: `cursor.fetchmany_arrow(10)`

`Row` 類別

資料列類別是類似元組的資料結構，代表個別結果資料列。如果資料列包含名稱為 "my_column" 的資料行，可以透過 row.my_column 存取 row 的 "my_column" 欄位。您也可以使用數值索引來存取欄位，例如 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 筆記本上使用連接器時，會看到訊息 Error during request to server: IpAclValidation。

可能的原因：您可能已為 Azure Databricks 工作區啟用 IP 允許清單。使用 IP 允許清單時，預設不允許從 Spark 叢集連線回到控制平面。

建議修正：要求系統管理員將計算平面子網路新增至 IP 允許清單。

其他資源

如需詳細資訊，請參閱

GitHub 上的適用於 Python 的 Databricks SQL 連接器存放庫
資料類型
Python 網站上的內建類型 (適用於 bool、、bytearray、float、int和 str)
Python 網站上的日期時間 (適用於 datetime.date 和 datatime.datetime)
Python 網站上的 decimal (對於 decimal.Decimal)
Python 網站上的內建常數 (對於 NoneType)

共用方式為

適用於 Python 的 Databricks SQL 連接器

需求

開始使用

Cluster

SQL 倉儲

驗證

Databricks 個人存取權杖驗證

OAuth 機器對機器 (M2M) 驗證

Microsoft Entra ID 權杖驗證

OAuth 使用者對機器 (U2M) 驗證

範例

查詢資料

插入資料

查詢中繼資料

管理資料指標和連線

管理 Unity 目錄磁碟區中的檔案

設定記錄

測試

API 參考

套件

模組

類別

`Connection` 類別

`Cursor` 類別

`Row` 類別

類型轉換

疑難排解

`tokenAuthWrapperInvalidAccessToken: Invalid access token` 訊息

`gaierror(8, 'nodename nor servname provided, or not known')` 訊息

`IpAclError` 訊息

其他資源

意見反應

其他資源

共用方式為

適用於 Python 的 Databricks SQL 連接器

需求

開始使用

Cluster

SQL 倉儲

驗證

Databricks 個人存取權杖驗證

OAuth 機器對機器 (M2M) 驗證

Microsoft Entra ID 權杖驗證

OAuth 使用者對機器 (U2M) 驗證

範例

查詢資料

插入資料

查詢中繼資料

管理資料指標和連線

管理 Unity 目錄磁碟區中的檔案

設定記錄

測試

API 參考

套件

模組

類別

Connection 類別

Cursor 類別

Row 類別

類型轉換

疑難排解

tokenAuthWrapperInvalidAccessToken: Invalid access token 訊息

gaierror(8, 'nodename nor servname provided, or not known') 訊息

IpAclError 訊息

其他資源

意見反應

其他資源

`Connection` 類別

`Cursor` 類別

`Row` 類別

`tokenAuthWrapperInvalidAccessToken: Invalid access token` 訊息

`gaierror(8, 'nodename nor servname provided, or not known')` 訊息

`IpAclError` 訊息