Microsoft ODBC 驅動程式，適用於 Linux 上的 Microsoft Fabric 資料工程

ODBC（開放資料庫連接性）是一項廣泛採用的標準，使客戶端應用程式能夠連接並操作來自資料庫及大數據平台的資料。

Microsoft ODBC Driver for Fabric Data Engineering 讓你能以 ODBC 標準的可靠性與簡便性，在 Fabric 中連接、查詢並管理 Spark 工作負載。 該驅動程式建立在 Fabric 的 Livy API 之上，為你的 C/C++、.NET、Python 及其他 ODBC 相容應用程式提供安全且靈活的 Spark SQL 連接。

主要功能

• 符合 ODBC 3.x 標準：完整實作 ODBC 3.x 規範。
• Microsoft Entra ID 認證：多重認證流程，包括 Azure CLI、客戶端憑證、憑證式及存取權杖認證。
• Spark SQL 查詢支援：直接執行 Spark SQL 語句。
• 全面的資料型態支援：支援所有 Spark SQL 資料型態，包括複雜型別（ARRAY、 MAP和 STRUCT）。
• 會話重用：內建會話管理以提升效能。
• 高並行模式：選擇共享、溫暖的伺服器端 Livy 會話，以降低連線啟動延遲及 Spark 叢集擴散。
• 大型資料表支援：針對可配置頁面大小的大型結果集進行最佳化處理。
• 非同步預取：背景資料載入以提升效能。
• 代理支援：企業環境的 HTTP 代理設定。
• 支援多個結構描述的 Lakehouse：連線至 Lakehouse 內的特定結構描述。

Prerequisites

在使用 Microsoft ODBC 驅動程式於 Linux 上進行 Microsoft Fabric 資料工程之前，請確保您具備以下先決條件：

• 作業系統：Ubuntu 22.04 或更新版本，Debian 11 或更新版本，或 Red Hat Enterprise Linux （RHEL） 8 或更新版本，支援 x86-64。
• unixODBC：Linux 的 ODBC 驅動管理器。 安裝 unixodbc and unixodbc-dev 套件。
• libcurl：HTTP 執行階段相依性，例如 libcurl4 或您所使用發行版的對應套件。
• OpenSSL：TLS 與密碼學執行時相依性，例如 openssl and libssl3 或等效套件。
• Fabric 存取權：對 Fabric 工作區的存取權。
• Microsoft Entra ID 憑證：適合的憑證用於驗證。
• 工作區與湖屋 ID：您 Fabric 工作區與湖屋的 GUID 識別碼。
• Azure CLI （optional）：使用 Azure CLI 認證時必須。

在 Linux 上下載並安裝

• 下載 Microsoft ODBC 驅動程式，適用於 Linux 上的 Microsoft Fabric Data Engineering （tar）

若要安裝驅動程式：

1. 擷取 ms-sparksql-odbc-linux-2.0.0.tar。

2. 在解壓的目錄中開啟終端機。

3. 安裝 Debian 套件：

   sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb
   

該套件可安裝以下檔案：

安裝 RPM 套件

在 RHEL、Fedora 或 CentOS 上，從解壓驅動程式壓縮檔安裝 RPM 套件：

sudo dnf install ./microsoft-fabric-odbc-driver-*.x86_64.rpm

或者，可以使用 rpm：

sudo rpm -i microsoft-fabric-odbc-driver-*.x86_64.rpm

確認 RPM 是否已註冊驅動程式：

odbcinst -q -d | grep "Microsoft"

要解除安裝 RPM 套件，請執行：

sudo dnf remove microsoft-fabric-odbc-driver

安裝瀝青球

對於不支援 Debian 或 RPM 套件的發行版，或是自訂安裝地點，請解壓套件 .tar.gz 並執行其安裝腳本：

tar -xzf microsoft-fabric-odbc-driver-2.0.0-linux-x86_64.tar.gz
cd microsoft-fabric-odbc-driver-2.0.0

# Install to /opt/microsoft/fabricodbc.
sudo ./install.sh

# Or install to a custom writable location.
./install.sh --prefix=$HOME/fabricodbc

安裝腳本支援以下選項：

若要驗證預設的 tarball 安裝，請執行：

odbcinst -q -d
ls -la /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so

要卸載它，請從解壓的套件目錄執行 sudo ./install.sh --uninstall 。

手動註冊驅動程式

該套件會自動將驅動程式註冊到 unixODBC。 若要手動登記駕駛員，請執行：

sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template

確認安裝情況

確認驅動程式已註冊且函式庫已安裝：

odbcinst -q -d
ls -la /usr/lib/libmicrosoftfabricodbc.so

odbcinst指令應該會列出 [Microsoft ODBC Driver for Microsoft Fabric Data Engineering]。

卸載驅動程式

要解除安裝驅動程式，請執行以下指令：

sudo dpkg -r microsoft-fabric-odbc-driver

此指令會移除驅動程式檔案，並將驅動程式從 unixODBC 中取消註冊。

快速入門範例

以下範例連接 Fabric 並執行 Spark SQL 查詢。 先完成前置條件並安裝驅動程式，再執行範例。

Python 範例

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
)

conn = pyodbc.connect(connection_string, timeout=30)
cursor = conn.cursor()

cursor.execute("SELECT 'Hello from Fabric!' AS message")
row = cursor.fetchone()
print(row.message)

conn.close()

C/C++ 範例

#include <sql.h>
#include <sqlext.h>
#include <iostream>

int main() {
    SQLHENV henv = SQL_NULL_HENV;
    SQLHDBC hdbc = SQL_NULL_HDBC;
    SQLHSTMT hstmt = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &henv);
    SQLSetEnvAttr(henv, SQL_ATTR_ODBC_VERSION, (SQLPOINTER)SQL_OV_ODBC3, 0);
    SQLAllocHandle(SQL_HANDLE_DBC, henv, &hdbc);

    const char* connectionString =
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;";

    SQLRETURN result = SQLDriverConnect(
        hdbc,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        std::cout << "Connected successfully!" << std::endl;

        SQLAllocHandle(SQL_HANDLE_STMT, hdbc, &hstmt);
        result = SQLExecDirect(
            hstmt,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

        if (SQL_SUCCEEDED(result)) {
            char message[256];
            SQLLEN indicator;

            while (SQLFetch(hstmt) == SQL_SUCCESS) {
                SQLGetData(
                    hstmt,
                    1,
                    SQL_C_CHAR,
                    message,
                    sizeof(message),
                    &indicator);
                std::cout << message << std::endl;
            }
        }

        SQLFreeHandle(SQL_HANDLE_STMT, hstmt);
        SQLDisconnect(hdbc);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, hdbc);
    SQLFreeHandle(SQL_HANDLE_ENV, henv);
    return 0;
}

請建立並執行範例：

g++ -o fabric_test fabric_test.cpp -lodbc -std=c++17
./fabric_test

.NET 範例

using System.Data.Odbc;

string connectionString =
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
    "WorkspaceId=<workspace-id>;" +
    "LakehouseId=<lakehouse-id>;" +
    "AuthFlow=AZURE_CLI;";

using var connection = new OdbcConnection(connectionString);
await connection.OpenAsync();

Console.WriteLine("Connected successfully!");

using var command = new OdbcCommand(
    "SELECT 'Hello from Fabric!' AS message",
    connection);
using var reader = await command.ExecuteReaderAsync();

if (await reader.ReadAsync())
{
    Console.WriteLine(reader.GetString(0));
}

連接字串格式

基本連接字串

請使用以下 連接字串 格式：

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};<parameter1>=<value1>;<parameter2>=<value2>;...

連接串組成部分

範例連接字串

基本連接

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI

與表演選項的關聯

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;ReuseSession=true;LargeTableSupport=true;PageSizeBytes=18874368

與伐木的關聯

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LogLevel=DEBUG;LogFile=/tmp/odbc_driver.log

與高並行模式的關聯

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

完整配置指引請參見 高並行（HC）模式。

Authentication

適用於 Microsoft Fabric 資料工程的 Microsoft ODBC 驅動程式支援透過 Microsoft Entra ID 進行多種驗證。 透過使用 AuthFlow 連接字串 或 DSN 中的參數來設定認證。

驗證方法

Azure CLI 認證

開發和互動應用程式使用 Azure CLI 認證。

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "Scope=https://api.fabric.microsoft.com/.default;"
)
conn = pyodbc.connect(connection_string)

連線前，請確認 Azure CLI 已安裝並登入：

az --version
az login

要在 Debian 或 Ubuntu 安裝 Azure CLI，請使用套件管理器：

sudo apt-get update
sudo apt-get install -y azure-cli

用戶端憑證認證

針對自動化服務和背景作業，請使用用戶端憑證驗證。

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CREDENTIAL;"
    f"TenantId={tenant_id};"
    f"ClientId={client_id};"
    f"ClientSecret={client_secret};"
)

提供下列參數：

• TenantId： Microsoft Entra 租戶 ID。
• ClientId：應用程式 （用戶端） 識別碼。
• ClientSecret：用戶端密碼。

將秘密儲存在安全的秘密儲存庫或環境變數中。 不要把秘密存放在純文字連線字串或 INI 檔案中。

憑證式驗證

對於需要憑證憑證的企業應用程式，請使用憑證式認證。

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=CLIENT_CERTIFICATE;"
    "TenantId=<tenant-id>;"
    "ClientId=<client-id>;"
    "CertificatePath=/path/to/cert.pfx;"
    "CertificatePassword=<password>;"
)

提供下列參數：

• TenantId： Microsoft Entra 租戶 ID。
• ClientId：應用程式 （用戶端） 識別碼。
• CertificatePath：前往 PFX 或 PKCS12 憑證檔案的路徑。
• CertificatePassword：憑證密碼。

存取令牌驗證

當你的應用程式透過其他機制取得憑證時，請使用存取權杖認證。

access_token = acquire_token_from_custom_source()

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=ACCESS_TOKEN;"
    f"AccessToken={access_token};"
)

檔案權杖驗證

在容器化環境與自動化管線中使用檔案令牌認證，當另一個程序將持有令牌寫入驅動程式已知的令牌檔時：

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=FILE_TOKEN;"
)

如需了解支援的跨驅動程式屬性別名，請參閱 跨驅動程式屬性別名。

組態參數

必要參數

在每個 連接字串 中包含以下參數：

可選參數

連線設定

效能設定

記錄設定

代理伺服器設定

高並行（HC）設定

利用這些參數啟用並設定高並行（HC）模式。 HC 模式需主動啟用。 如果你沒有設定 LivyMode 或 UseHighConcurrency，驅動程式會使用經典的單會話路徑。 有關指引與範例，請參見 高並發（HC）模式。

模式優先順序與驗證

• 當你同時設定這兩個參數時，LivyMode 的優先順序高於 UseHighConcurrency
• 參數值不區分大小寫。
• UseHighConcurrency 接受 true、 1、 yes或 on 以啟用 HC 模式。 它接受 false、0、no 或 off 以停用 HC 模式。
• 若為其他非空值，SQLDriverConnect 會回傳錯誤。 僅 SQLConnect DSN 會記錄驗證失敗，並使用經典路徑。

相容性設定

驅動程式接受 TenantPrincipal 和 PoolMax，以及它們對應的環境變數後備值，以便與較早期的 HC 組態相容。 驅動程式會解析並驗證這些值，但它們不會影響 HC 會話匹配或執行時池容量。 不要依賴它們來實現租戶隔離或連線限制。

環境變數後備機制

當對應的 DSN 或連接字串參數未設定時，驅動程式才會使用以下環境變數：

對於 FABRIC_ODBC_USE_HC，僅限環境的啟用會將 true、1 或 yes 識別為有效值（不區分大小寫）。 其他數值則會關閉 HC 模式。 on與off別名僅適用於 DSN 與 connection-string 值。

高並行（HC）模式

高並行（HC）模式允許同一工作空間與湖屋的 ODBC 連線連接到共享的暖伺服器端 Livy Spark 會話，而不必為每個連線配置獨立叢集。 適用於 BI 儀表板、筆記本核心程序和 ETL 扇出等工作負載；這些工作負載會開啟大量短生命週期的連線，並可共用由伺服器管理的 Spark 容量。

HC 模式需主動啟用。 如果你沒有設定 HC 設定，驅動程式會使用經典的單會話路徑。

選擇連線模式

以下情況下使用 HC 模式：

• 你的工作負載會開啟許多短暫的 ODBC 連線，例如 BI 儀表板、筆記本核心或 ETL 輸出。
• 連線針對相同的工作空間和湖庫，並可共用由伺服器管理的 Spark 會話。
• 降低每連線的冷啟動延遲非常重要。

當以下情況使用經典模式：

• 每個連線都需要一個隔離的 Spark 會話，因為 Spark 配置不同或資源嚴格隔離。
• 目標工作空間和湖屋的 Fabric Livy 端點不支援 HC 模式。

啟用高並行模式

在 DSN 或 連接字串 中加入一個高並行模式參數。

建議：設定 LivyMode

請明確選擇 LivyMode 會話擷取模式：

LivyMode=HighConcurrency

支援值為 Classic、 HighConcurrency、 Auto和 。 值不區分大小寫。 Auto 目前選擇經典模式。

替代方案：Set UseHighConcurrency

請使用布林設定來與現有配置相容：

UseHighConcurrency=true

要啟用高並行模式，請使用 true、 1、 yes或 on。 要停用它，請使用 false、 0、 no或 off。 值不區分大小寫。 SQLDriverConnect 以 SQLSTATE HY024 拒絕其他非空值。 僅 SQLConnect DSN 會記錄驗證失敗並使用經典模式。

你也可以透過環境變數為目前 shell 啟用高並行模式：

export FABRIC_ODBC_USE_HC=true
export FABRIC_ODBC_WORKSPACE_ID=<workspace-id>
export FABRIC_ODBC_LAKEHOUSE_ID=<lakehouse-id>
export FABRIC_ODBC_SESSION_TAG=bi-dashboard

HC 模式下的必要參數

啟用 HC 需要以下有效識別碼：

包含 SessionTag 是因為它會影響伺服器端的熱場匹配。

會話匹配

HC 模式並不保證每個連線都會重複使用現有的會話。 對於每個會話擷取請求，驅動程式會發送：

• SessionTag 值。
• 有效的 Spark 配置，包括 conf.* 設定和 EnvironmentId。

Fabric Livy 服務會評估這些值，並決定是否將連線連接到預熱工作階段，或建立新的工作階段。 為了提升會話重用，應在旨在共享伺服器管理的 Spark 容量的連線間使用一致的數值。

範例連接字串

使用 Azure CLI 驗證的最簡 HC 連線：

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=bi-dashboard

已調整逾時設定的 HC 連線：

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;SessionTag=etl-prod;AcquireTimeoutSeconds=180;HeartbeatTimeoutInSecond=600

HC 與環境的連接及 Spark 設定覆寫：

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;LivyMode=HighConcurrency;EnvironmentId=<environment-id>;SessionTag=ml-team;conf.spark.sql.shuffle.partitions=200;conf.spark.executor.memory=8g

Python 搭配pyodbc：

import pyodbc

conn = pyodbc.connect(
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LivyMode=HighConcurrency;"
    "SessionTag=notebook-kernel"
)

在 Linux DSN 中設定 HC 模式

與其在每個 連接字串 重複 HC 設定，不如將它們儲存~/.odbc.ini在使用者專屬的 DSN 或/etc/odbc.ini系統整體的 DSN 中。

[FabricHCDSN]
Description               = Microsoft Fabric Data Engineering with HC mode
Driver                    = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId               = <workspace-id>
LakehouseId               = <lakehouse-id>
AuthFlow                  = AZURE_CLI
LivyMode                  = HighConcurrency
SessionTag                = bi-dashboard
AcquireTimeoutSeconds     = 300
HeartbeatTimeoutInSecond  = 600

儲存 DSN 後，驗證並測試連線。

odbcinst -q -s
isql -k -v "DSN=FabricHCDSN;"

當 連接字串 未指定值時，驅動程式會從 DSN 讀取以下設定：

• LivyMode
• UseHighConcurrency
• EnvironmentId
• SessionTag
• IdempotencyKey
• HeartbeatTimeoutInSecond
• AcquireTimeoutSeconds

驅動程式也會讀取僅供相容性使用的 TenantPrincipal 和 PoolMax 設定。 請使用 HC設定表中的參數名稱。

關閉 HC 模式

你可以停用新的 HC 會話擷取，而不必重新部署驅動程式。 使用與你啟用 HC 模式相符的方法：

連線字串與 DSN 設定優先於環境變數的備援。 這些變更只影響新連線。 現有的 HC 課程會持續進行，直到釋出為止。

了解 HC 執行時的行為

• 驗證：SQLDriverConnect 拒絕無效的 HC 布林值及正整數值，使用 SQLSTATE HY024。 它會以 SQLSTATE HY000 拒絕無效的 LivyMode，以及無效或過大的 IdempotencyKey、WorkspaceId 和 LakehouseId 值。 過大的相容性值 TenantPrincipal 也會回傳 HY000。 對於僅限 DSN 的情況 SQLConnect，驅動程式會記錄一般 HC 驗證失敗，並使用傳統模式。 過大的安全性敏感值仍會導致連線失敗。
• 敏感資料： 驅動程式會從 HC 記錄和診斷輸出中排除或遮罩 IdempotencyKey 及其他敏感欄位。
• 取消： 陳述式取消是協作式的。 伺服器正在進行的工作會乾淨利落地結束，而非立即終止。
• 斷路器： HC 模式與經典模式使用不同的斷路器。 用盡其中一種模式不會影響另一種模式。
• 初始資料庫：HC 連線不會針對 USE 參數執行初始的 Database 陳述式。 連線後執行 USE <database>，或使用完全限定資料表名稱。
• 診斷：將 LogLevel=DEBUG 設定為記錄 HC 的取得、輪詢、釋放及錯誤對應決策。 若要進行針對性的疑難排解，請將 LIVY_HC_VERBOSE=1 設定為包含額外的、已去除敏感資訊的 HC HTTP 診斷資訊。

DSN 配置

在 Linux 上，請將資料來源名稱（DSN）配置為 INI 檔案，而非 Windows 登錄檔。

建立 DSN

如果 ~/.odbc.ini 存在，新增 DSN 區段即可，但不替換現有檔案。 只有在建立檔案時才複製已安裝的範本：

if [ -e "$HOME/.odbc.ini" ]; then
    echo "Preserve ~/.odbc.ini and add the new DSN section manually."
else
    cp /usr/share/microsoft-fabric-odbc-driver/odbc.ini.template "$HOME/.odbc.ini"
fi

編輯 ~/.odbc.ini，填入你的 Fabric 工作區詳細資料：

[FabricDSN]
Description    = Microsoft Fabric Data Engineering
Driver         = Microsoft ODBC Driver for Microsoft Fabric Data Engineering
WorkspaceId    = <workspace-id>
LakehouseId    = <lakehouse-id>
AuthFlow       = AZURE_CLI
LogLevel       = INFO
# LogFile      = /tmp/fabric_odbc.log
# LargeTableSupport = true
# ReuseSession = true

驗證DSN

列出已設定的 DSN，然後測試連線：

odbcinst -q -s
isql -k -v "DSN=FabricDSN;"

此 isql 指令需要 unixODBC 命令列工具。 此 -k 選項使用 SQLDriverConnect，讓驅動程式能處理 DSN 連線屬性。

在應用程式中使用 DSN

conn = pyodbc.connect("DSN=FabricDSN")

using var connection = new OdbcConnection("DSN=FabricDSN");
await connection.OpenAsync();

SQLRETURN result = SQLConnect(
    hdbc,
    (SQLCHAR*)"FabricDSN",
    SQL_NTS,
    NULL,
    0,
    NULL,
    0);

使用範例

使用 isql 測試連線

開始互動式 SQL 會議：

isql -k -v "DSN=FabricDSN;"

執行一個查詢：

echo "SELECT 1 AS test" | isql -k -v "DSN=FabricDSN;" -b

將 -k 用於 Fabric DSN，讓 isql 透過 SQLDriverConnect 而非 SQLConnect 連線。

處理大型結果集的工作

import pyodbc

connection_string = (
    "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
    "WorkspaceId=<workspace-id>;"
    "LakehouseId=<lakehouse-id>;"
    "AuthFlow=AZURE_CLI;"
    "LargeTableSupport=true;"
    "PageSizeBytes=18874368;"
    "EnableAsyncPrefetch=1;"
)

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()
cursor.execute("SELECT * FROM large_table")

row_count = 0
while True:
    rows = cursor.fetchmany(1000)
    if not rows:
        break

    for row in rows:
        row_count += 1

    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

print(f"Total rows processed: {row_count}")
conn.close()

探索結構與資料表

import pyodbc

conn = pyodbc.connect(connection_string)
cursor = conn.cursor()

cursor.execute("SHOW TABLES")
for table in cursor.fetchall():
    print(table)

cursor.execute("DESCRIBE employees")
for column in cursor.fetchall():
    print(column)

cursor.execute("SHOW SCHEMAS")
for schema in cursor.fetchall():
    print(schema)

conn.close()

數據類型映射

驅動程式將 Spark SQL 資料型態映射到 ODBC SQL 型別：

平台差異

故障排除

找不到司機

問題：連線於 [IM002] Data source name not found and no default driver specified 失敗。

解決方案：

1. 透過執行 odbcinst -q -d確認駕駛人登記。
2. 確認 /usr/lib/libmicrosoftfabricodbc.so 是否存在。
3. 透過執行 sudo odbcinst -i -d -f /usr/share/microsoft-fabric-odbc-driver/odbcinst.ini.template來註冊驅動程式。
4. 透過執行 sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb 來重新安裝套件。

安裝 tarball 套件後找不到驅動程式

問題：驅動程式已註冊，但共用函式庫不存在於註冊路徑上。

解決方案：

1. 確認 /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.so 存在。
2. 重新執行 sudo ./install.sh --prefix=/opt/microsoft/fabricodbc。
3. 如果你用了自訂前綴，請確認註冊的驅動路徑是否使用相同的前綴。

找不到 DSN

問題：連線在使用 [IM002] Data source name not found 時失敗。

解決方案：

1. 透過執行 odbcinst -q -s來驗證 DSN 設定。
2. 請確認 ~/.odbc.ini 或 /etc/odbc.ini 是否包含 DSN 區段。
3. 確保 Driver 數值與登記駕駛人姓名完全一致。

連線失敗

問題：驅動程式無法連接到 Fabric。

解決方案：

1. 確認工作區 ID 和 Lakehouse ID 是否為有效的 GUID。
2. 執行 az account show 以檢查 Azure CLI 驗證。
3. 確保你擁有所需的 Fabric 工作區權限。
4. 檢查網路連線和代理設定。

認證錯誤

問題：Azure CLI 認證失敗。

解決方案：

1. 執行 az login 以重新整理您的認證資料。
2. 透過執行 az account set --subscription <subscription-id>來設定正確的訂閱。
3. 透過執行 az account get-access-token --resource https://api.fabric.microsoft.com來檢查該令牌。
4. 請確保您的帳號擁有所需的 Fabric 工作區權限。

共享函式庫錯誤

問題：駕駛報告 error while loading shared libraries: libmicrosoftfabricodbc.so。

解決方案：

1. 執行 sudo dpkg -i microsoft-fabric-odbc-driver-2.0.0-Linux.deb 以重新安裝套件。
2. 確認 /usr/lib/libmicrosoftfabricodbc.so 存在。
3. 執行 sudo ldconfig 以刷新共享函式庫快取。

查詢逾時

問題：大型資料表上的查詢會逾時。

解決方案：

1. 將 LargeTableSupport=true 新增到連接字串。
2. 根據結果大小調整 PageSizeBytes。
3. 將 EnableAsyncPrefetch=1 新增至連線字串中。
4. 使用 LIMIT 子句來限制結果大小。

啟用記錄功能

在 DSN 中啟用詳細日誌：

[FabricDSN]
LogLevel = DEBUG
LogFile  = /tmp/fabric_odbc_debug.log

或者，可以在 連接字串 中加入日誌參數：

LogLevel=DEBUG;LogFile=/tmp/fabric_odbc_debug.log;

驅動程式支援以下日誌等級：

• DEBUG：包含詳細的除錯資訊，是最詳細的驅動程式日誌層級。
• INFO：包含一般資訊，為預設。
• WARN：僅包含警告。
• ERROR：僅包含錯誤。

啟用 unixODBC 追蹤

若要對低層級 ODBC 呼叫進行診斷，請將下列組態新增至 /etc/odbcinst.ini：

[ODBC]
Trace     = yes
TraceFile = /tmp/odbc_trace.log

完成故障排除後關閉追蹤，以避免不必要的效能負擔。

相關內容

• Microsoft ODBC 驅動程式適用於 Microsoft Fabric 數據工程
• Fabric 中的 Apache Spark 執行階段
• Fabric 執行階段 1.3
• 什麼是 Livy API 用於資料工程
• Microsoft Fabric 數據工程的 Microsoft JDBC 驅動程式
• UNIXODBC