Linux上のMicrosoft Fabric Data Engineering用Microsoft ODBCドライバー

ODBC (Open Database Connectivity) は、クライアント アプリケーションがデータベースやビッグ データ プラットフォームのデータに接続して操作できるようにする、広く採用されている標準です。

Microsoft ODBCドライバー for Fabric Data Engineeringは、ODBC標準の信頼性とシンプルさでFabric上でSparkワークロードの接続、クエリ、管理を可能にします。 FabricのLivy APIを基に構築されたこのドライバーは、Linux上のC/C++、.NET、Python、その他のODBC互換アプリケーションに対して安全かつ柔軟なSpark SQL接続を提供します。

主要な機能

• ODBC 3.x準拠:ODBC 3.x仕様の完全実装。
• Microsoft Entra ID認証:Azure CLI、クライアント認証、証明書ベース、アクセストークン認証を含む複数の認証フロー。
• Spark SQLクエリサポート:Spark SQL文の直接実行。
• 包括的なデータ型サポート:複雑な型(ARRAY、 MAP、 STRUCTを含むすべてのSpark SQLデータ型をサポートしています)。
• セッション再利用:パフォーマンス向上のための組み込みセッション管理機能。
• 高並行性モード:接続開始遅延やSparkクラスターの拡散を減らすために、共有のウォームサーバーサイドLivyセッションにオプトインしてください。
• 大規模テーブルサポート:設定可能なページサイズを持つ大規模な結果セットの最適化された処理。
• 非同期プリフェッチ:性能向上のためのバックグラウンドデータロード。
• プロキシサポート:エンタープライズ環境向けのHTTPプロキシ設定。
• マルチスキーマレイクハウスサポート:レイクハウス内の特定のスキーマに接続します。

前提条件

Linux上でMicrosoft ODBCドライバー(Microsoft Fabric Data Engineering用)を使用する前に、以下の前提条件を確認してください。

• オペレーティングシステム:Ubuntu 22.04以降、Debian 11以降、またはRed Hat Enterprise Linux(RHEL)8以降(x86-64)を搭載。
• unixODBC:Linux用のODBCドライバーマネージャーです。 unixodbcとunixodbc-devパッケージをインストールしてください。
• libcurl: libcurl4 やあなたのディストリビューションの同等パッケージのようなHTTPランタイム依存関係です。
• OpenSSL:TLSおよび暗号のランタイム依存関係、例えば openssl や libssl3 、または同等のパッケージです。
• Fabricアクセス:Fabricワークスペースへのアクセス。
• Microsoft Entra IDの認証情報:認証に適切な認証情報。
• ワークスペースおよびレイクハウスID:FabricのワークスペースとレイクハウスのGUID識別子です。
• Azure CLI (optional):Azure CLI 認証を使用する際に必須。

Linuxでダウンロード・インストール

• Linux 用 Microsoft Fabric Data Engineering 向け Microsoft ODBC Driver をダウンロード (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

インストールスクリプトは以下のオプションをサポートしています:

デフォルトのタールボール設置を確認するには、以下を実行します:

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 ODBCドライバー for Microsoft Fabric Data Engineeringは、Microsoft Entra IDを通じた複数の認証方法をサポートしています。 認証は、接続文字列またはDSNのAuthFlowパラメータを使って設定します。

認証方法

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: アプリケーション (クライアント) ID。
• 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: アプリケーション (クライアント) ID。
• 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 HCモードを有効にするために true、 1、 yes、または on を受け入れます。 HCモードを無効にするには false、 0、 no、 off を受け入れています。
• 空でない他の値は、 SQLDriverConnect エラーを返します。 DSNのみの SQLConnect は検証失敗を記録し、クラシックパスを使用します。

互換性の設定

ドライバーは TenantPrincipal および PoolMax、環境変数のフォールバックも受け入れ、以前のHC構成との互換性を確保します。 ドライバーはこれらの値を解析・検証しますが、HCセッションのマッチングやランタイムプール容量には影響しません。 入居者の隔離や接続制限に頼らないでください。

環境変数のフォールバック

ドライバは対応するDSNまたは接続文字列パラメータが設定されていない場合にのみ、以下の環境変数を使用します。

FABRIC_ODBC_USE_HC では、環境のみの有効化で true、1、または yes を認識します（大文字と小文字を区別しません）。 他の値はHCモードを無効にします。 onおよびoffエイリアスはDSNおよび接続文字列の値にのみ適用されます。

高並行性(HC)モード

ハイコンカレンシー(HC)モードは、同じワークスペースとレイクハウスへのODBC接続を、各接続ごとに別々のクラスタをプロビジョニングするのではなく、共有されたウォームサーバーサイドのLivy Sparkセッションに接続できるようにします。 多数の短時間接続を確立し、サーバーによって管理される Spark キャパシティを共有できる、BI ダッシュボード、ノートブック カーネル、ETL ファンアウトなどのワークロードに使用できます。

HCモードはオプトイン制です。 HC設定を設定していない場合、ドライバーは従来のシングルセッションパスを使用します。

接続モードを選択する

HCモードを使う場合:

• あなたのワークロードは、BIダッシュボードやノートブックカーネル、ETLファンアウトなど、多くの短命なODBC接続を開きます。
• 接続は同じワークスペースとレイクハウスを対象にし、サーバー管理のSparkセッションを共有することができます。
• 1回あたりのコールドスタート遅延を減らすことが重要です。

クラシックモードを使う場合:

• 各接続は、異なる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 で他の空でない値を却下します。 DSNのみの SQLConnect は検証失敗を記録し、クラシックモードを使用します。

また、環境変数を使って現在のシェルで高同時実行モードを有効にすることもできます:

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

環境および Spark 構成のオーバーライドを使用した HC 接続:

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

pyodbcとPython:

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設定を繰り返すのではなく、ユーザー固有のDSNの~/.odbc.iniやシステム全体のDSNの/etc/odbc.iniに保存してください。

[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 SQLSTATE HY024で無効なHCブール値および正整数値を拒否します。 無効な LivyMode や、無効または過剰な WorkspaceId、 LakehouseId、 IdempotencyKey の値をSQLSTATE HY000で却下します。 過剰な互換性 TenantPrincipal 値も HY000返します。 DSN のみの SQLConnect の場合、ドライバーは通常の HC 検証の失敗をログに記録し、クラシック モードを使用します。 セキュリティに敏感な過大な値でも接続に失敗します。
• 機密データ: ドライバーはHCログや診断出力から IdempotencyKey やその他の敏感なフィールドを除外または削除します。
• キャンセル: ステートメントのキャンセルは協調的です。 すでに進行中のサーバー作業は、すぐに終了するのではなく、きれいに終わらせます。
• サーキットブレーカー: HCモードとクラシックモードは別々のサーキットブレーカーを使用します。 一方のモードを使い果たしてももう一方には影響しません。
• 初期データベース:HC接続はDatabaseパラメータの最初のUSE文を実行しません。 接続後に USE <database> を実行するか、完全に条件付きのテーブル名を使ってください。
• 診断: HC の取得、ポーリング、リリース、およびエラーマッピングの判定をログに記録するように LogLevel=DEBUG を設定します。 重点的なトラブルシューティングのために、LIVY_HC_VERBOSE=1 に、機密情報を除去した HC HTTP 診断情報が追加で含まれるよう設定してください。

DSN の構成

Linuxでは、WindowsレジストリではなくINIファイルでデータソース名(DSN)を設定しましょう。

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

Fabric DSNには-kを使用し、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 型にマップします。

プラットフォームの違い

Troubleshooting

運転手が見つからない

問題: [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を実行してパッケージを再インストールしてください。

タールボール設置後にドライバーが見つからない

問題:ドライバーは登録されているが、共有ライブラリが登録経路に存在しない。

解決策:

1. /opt/microsoft/fabricodbc/lib/libmicrosoftfabricodbc.soが存在することを確認します。
2. sudo ./install.sh --prefix=/opt/microsoft/fabricodbcを再実行します。
3. カスタムプレフィックスを使っている場合は、登録されたドライバーパスが同じプレフィックスを使用しているか確認してください。

DSN が見つかりません

問題: [IM002] Data source name not foundで接続が失敗します。

解決策:

1. DSNの設定は odbcinst -q -sを実行して確認してください。
2. ~/.odbc.ini または /etc/odbc.ini に DSN セクションが含まれていることを確認してください。
3. Driverの価値が登録されたドライバー名と正確に一致していることを確認してください。

接続の失敗

問題:ドライバーがFabricに接続できません。

解決策:

1. ワークスペースIDとレイクハウス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 Fabric Data Engineering 用 Microsoft ODBC ドライバー
• Fabric の Apache Spark ランタイム
• ファブリック ランタイム 1.3
• データ エンジニアリング用 Livy API とは
• Microsoft Fabric Data Engineering 向け Microsoft JDBC Driver
• ユニックスODBC