Microsoft Fabric Data Engineering用Microsoft ODBCドライバー

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

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

主要な機能

• ODBC 3.x 準拠: ODBC 3.x 仕様の完全な実装
• Microsoft Entra ID認証: Azure CLI、対話型、クライアント資格情報、証明書ベース、アクセス トークン認証を含む複数の認証フロー
• Spark SQL クエリのサポート: Spark SQL ステートメントの直接実行
• 包括的なデータ型のサポート: 複合型 (ARRAY、MAP、STRUCT) を含むすべての Spark SQL データ型のサポート
• セッションの再利用: パフォーマンスを向上するための組み込みのセッション管理
• 高並行性モード:共有のウォームサーバーサイドLivyセッションにオプトインし、接続開始遅延やSparkクラスターの広がりを削減します
• 大きなテーブルのサポート: 構成可能なページ サイズを持つ大規模な結果セットの処理を最適化しました
• 非同期プリフェッチ: パフォーマンス向上のためのバックグラウンド データ読み込み
• プロキシのサポート: エンタープライズ環境の HTTP プロキシ構成
• マルチスキーマレイクハウスサポート:レイクハウス内の特定のスキーマに接続
• OneLake統合:OneLakeに保存されたレイクハウスデータ(複数のスキーマにまたがるテーブルを含む)に、統一されたODBCインターフェースを通じて、個別のストレージ構成なしでアクセス可能です
• Environment 項目のサポート: ジョブの実行中にFabric環境項目をアタッチして、ワークスペース ライブラリ、Spark プロパティ、変数を各セッションに適用します
• Custom Spark 構成: 接続文字列を介して Spark 構成プロパティを直接渡してセッションの動作を調整する

[前提条件]

Microsoft ODBC Driver for Microsoft Fabric Data Engineering を使用する前に、次のことを確認してください。

• オペレーティング システム: Windows 10/11 または Windows Server 2016 以降
• Fabricアクセス:Fabricワークスペースへのアクセス
• Microsoft Entra ID資格情報: 認証に適した資格情報
• ワークスペースおよびレイクハウスID:FabricのワークスペースおよびレイクハウスのGUID識別子
• Azure CLI (省略可能): Azure CLI 認証方法に必要

ダウンロードと MSI のインストール

• Microsoft ODBC Driver for Microsoft Fabric Data Engineering (zip) のダウンロード

1. Microsoft ODBC Driver for Microsoft Fabric Data Engineering MSI パッケージをダウンロードする
2. MicrosoftFabricODBCDriver-2.0.msiをダブルクリックします。
3. インストール ウィザードに従い、使用許諾契約書に同意します
4. インストール ディレクトリの選択 (既定値: C:\Program Files\Microsoft ODBC Driver for Microsoft Fabric Data Engineering\)
5. インストールを完了する

サイレント インストール

# Silent installation
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /quiet

# Installation with logging
msiexec /i "MicrosoftFabricODBCDriver-2.0.msi" /l*v install.log

インストールを検証する

インストール後、ドライバーが登録されていることを確認します。

1. odbcad32.exeの実行 (ODBC データ ソース 管理者)
2. [ ドライバー ] タブに移動します
3. "Microsoft ODBC Driver for Microsoft Fabric Data Engineering" が一覧表示されていることを確認する

クイックスタートの例

この例は、Microsoft ODBCドライバー(Microsoft Fabric Data Engineering)を使ってFabricに接続しクエリを実行する方法を示しています。 このコードを実行する前に、前提条件が満たされ、ドライバーがインストールされていることを確認してください。

C/C++の例

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

int main() {
    SQLHENV environment = SQL_NULL_HENV;
    SQLHDBC connection = SQL_NULL_HDBC;
    SQLHSTMT statement = SQL_NULL_HSTMT;

    SQLAllocHandle(SQL_HANDLE_ENV, SQL_NULL_HANDLE, &environment);
    SQLSetEnvAttr(
        environment,
        SQL_ATTR_ODBC_VERSION,
        (SQLPOINTER)SQL_OV_ODBC3,
        0);
    SQLAllocHandle(SQL_HANDLE_DBC, environment, &connection);

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

    SQLRETURN result = SQLDriverConnectA(
        connection,
        NULL,
        (SQLCHAR*)connectionString,
        SQL_NTS,
        NULL,
        0,
        NULL,
        SQL_DRIVER_NOPROMPT);

    if (SQL_SUCCEEDED(result)) {
        SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);
        result = SQLExecDirectA(
            statement,
            (SQLCHAR*)"SELECT 'Hello from Fabric!' AS message",
            SQL_NTS);

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

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

        SQLFreeHandle(SQL_HANDLE_STMT, statement);
        SQLDisconnect(connection);
    }

    SQLFreeHandle(SQL_HANDLE_DBC, connection);
    SQLFreeHandle(SQL_HANDLE_ENV, environment);
    return 0;
}

Pythonの例

import pyodbc

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

# Connect and execute query
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()

.NET の例

using System.Data.Odbc;

// Connection string with required parameters
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));
}

接続文字列の形式

基本的な接続文字列

Microsoft ODBC Driver for Microsoft Fabric Data Engineering では、次の接続文字列形式が使用されます。

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

接続文字列コンポーネント

接続文字列の例

基本接続 (Azure CLI 認証)

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=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

完全な設定ガイダンスについては 「High-Concurrency(HC)モード 」セクションを参照してください。

認証

Microsoft ODBC Driver for Microsoft Fabric Data Engineering では、Microsoft Entra ID (旧称 Azure Active Directory) を使用した複数の認証方法がサポートされています。 認証は、接続文字列の AuthFlow パラメーターを使用して構成されます。

認証方法

認証値は、大文字のスネークケース、パスカルケース、または数値形式で指定できます。 ドライバーはまた、 Browser、 Interactive、 CLI、 Certificate、 Token、 Fileなどの短い別名も受け入れます。 ドライバーは値を比較する際にアンダースコアを無視します。

Azure CLI 認証

最適な用途: 開発と対話型アプリケーション

# Python Example
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

対話型ブラウザーの認証

最適な用途: ユーザー向けのアプリケーション

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

動作:

• ユーザー認証用のブラウザー ウィンドウを開きます
• 資格情報は後続の接続用にキャッシュされます

クライアント資格情報 (サービス プリンシパル) 認証

最適: 自動化されたサービスとバックグラウンドの作業

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: Azure テナント ID
• ClientId: Microsoft Entra ID からのアプリケーション (クライアント) ID
• ClientSecret: Microsoft Entra ID からのクライアント シークレット

ベスト プラクティス

• シークレットを安全に格納する (Azure Key Vault、環境変数)
• 可能な場合はマネージド ID を使用する
• シークレットを定期的にローテーションする

証明書ベースの認証

最適な対象: 証明書ベースの認証を必要とするエンタープライズ アプリケーション

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=C:\\certs\\mycert.pfx;"
    "CertificatePassword=<password>;"
)

必須パラメーター:

• TenantId: Azure テナント ID
• ClientId: アプリケーション (クライアント) ID
• CertificatePath: PFX/PKCS12 証明書ファイルへのパス
• CertificatePassword: 証明書パスワード

アクセス トークン認証

最適な用途: カスタム認証シナリオ

# Acquire token through custom mechanism
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;"
)

このドライバはWindowsおよびLinux上でトークンファイルの位置を解決します。

クロスドライバーのプロパティエイリアス

ODBCドライバーは、ネイティブのODBC名に加え、選択されたADO.NETおよびJDBCプロパティ名も受け入れます。 このサポートにより、Fabricドライバー間を移動する際の接続ストリングの変更を減らすことができます。

ドライバーは接続時に17のクロスドライバーエイリアスを解決します。

構成パラメータ

必須のパラメーター

これらのパラメーターは、すべての接続文字列に存在する必要があります。

省略可能なパラメーター

接続の設定

パフォーマンス設定

ログ記録の設定

プロキシの設定

ハイコンカレンシー(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および接続文字列の値にのみ適用されます。

環境設定

Fabric環境項目は、ドライバーによって開始された Spark セッションにアタッチできます。 選択した環境のライブラリ、Spark プロパティ、変数は、セッションの作成時に自動的に適用されます。

環境項目を含む接続文字列の例:

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

カスタム Spark 構成

Spark 構成プロパティは、接続文字列で直接渡すことができます。 spark.でプレフィックスが付いたパラメーターはすべて、作成時に Spark セッションに自動的に適用され、ワークスペースまたはランタイムの既定値をオーバーライドできます。

Spark 構成の例:

spark.sql.shuffle.partitions=200
spark.sql.adaptive.enabled=true
spark.sql.autoBroadcastJoinThreshold=10485760

カスタム Spark プロパティを使用したExample 接続文字列:

DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};WorkspaceId=<workspace-id>;LakehouseId=<lakehouse-id>;AuthFlow=AZURE_CLI;spark.sql.shuffle.partitions=200;spark.sql.adaptive.enabled=true

高並行性(HC)モード

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

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

接続モードを選択する

HCモードを使う場合:

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

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

• 各接続は、異なるSpark構成や厳格なリソース隔離のために、孤立したSparkセッションを必要とします。
• ターゲットワークスペースとレイクハウス用のFabric LivyエンドポイントはHCモードをサポートしていません。

高並行性モードを有効にする

DSNまたは接続文字列に高並行性モードパラメータを追加します。

おすすめ: LivyMode に設定

LivyModeを使ってセッション取得モードを明示的に選択してください:

LivyMode=HighConcurrency

サポートされている値は、 Classic、 HighConcurrency、および Autoです。 値は大文字と小文字が区別されません。 Auto 現在はクラシックモードを選択しています。

代替案:設定 UseHighConcurrency

既存の構成との互換性のためにブール設定を活用してください:

UseHighConcurrency=true

高同時進行モードを有効にするには、 true、 1、 yes、または onを使用します。 無効化するには、 false、 0、 no、または offを使ってください。 値は大文字と小文字が区別されません。 SQLDriverConnect SQLSTATE HY024 で他の空でない値を却下します。 DSNのみの SQLConnect は検証失敗を記録し、クラシックモードを使用します。

HCモードでの必要なパラメータ

HCの有効化には以下の有効な識別子が必要です:

ウォームセッションのサーバーサイドマッチングに影響を与えるため SessionTag 含めてください。

セッションマッチング

HCモードはすべての接続が既存のセッションを再利用することを保証するわけではありません。 各セッション取得リクエストに対して、ドライバーは以下を送信します:

• SessionTag の値。
• 効果的なSpark構成、 conf.* 設定や EnvironmentIdが含まれます。

Fabric Livyサービスはこれらの値を評価し、接続をウォームセッションに付けるか新しいセッションを作成するかを決定します。 セッションの再利用を改善するために、サーバー管理のSpark容量を共有することを意図した接続間で一貫した値を使いましょう。

接続文字列の例

最小限の HC 接続（Azure CLI 認証）:

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

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

DSNでHCモードの設定

HC設定を各接続文字列で繰り返すのではなく、DSNに保存できます。 接続文字列に値が指定されていない場合、ドライバーはDSNから以下の設定を読み込みます。

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

ドライバーは互換性のみの TenantPrincipal や PoolMax 設定も読み込みます。 これらの設定を保存するには、 odbcad32.exe でDSNを編集するか SQLWritePrivateProfileStringを使ってください。 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の設定

システム DSN を作成する

1. ODBC 管理者を開く

   %SystemRoot%\System32\odbcad32.exe
   

2. 新しいシステム DSN の作成

   • [システム DSN] タブに移動する
   • [追加] の選択
   • [Microsoft ODBC Driver for Microsoft Fabric Data Engineering] を選択する
   • [完了] を選択する

3. DSN 設定の構成

   • データ ソース名: 一意の名前を入力します (例: FabricODBC)
   • 説明: 省略可能な説明
   • ワークスペース ID: Fabric ワークスペース GUID
   • Lakehouse ID: あなたのFabricレイクハウスGUID
   • 認証: 認証方法を選択する
   • Environment ID (省略可能): セッションの作成時にアタッチするFabric環境項目の GUID を入力します
   • リビーモード (オプション): HighConcurrency に設定してHCモードを有効にする
   • セッションタグ (任意):HCセッションマッチング用に非機密の操作ラベルを入力
   • 必要に応じて追加の設定を構成する

4. [接続テスト]

   • [テスト接続] を選択して設定を確認する
   • [OK] を選択して保存する

アプリケーションで DSN を使用する

# Python - Connect using DSN
conn = pyodbc.connect("DSN=FabricODBC")

// .NET - Connect using DSN
using var connection = new OdbcConnection("DSN=FabricODBC");
await connection.OpenAsync();

使用例

基本的な接続とクエリ

Python

import pyodbc

def main():
    connection_string = (
        "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};"
        "WorkspaceId=<workspace-id>;"
        "LakehouseId=<lakehouse-id>;"
        "AuthFlow=AZURE_CLI;"
        "ReuseSession=true;"
    )
    
    conn = pyodbc.connect(connection_string, timeout=30)
    cursor = conn.cursor()
    
    print("Connected successfully!")
    
    # Show available tables
    print("\nAvailable tables:")
    cursor.execute("SHOW TABLES")
    for row in cursor.fetchall():
        print(f"  {row}")
    
    # Query data
    print("\nQuery results:")
    cursor.execute("SELECT * FROM employees LIMIT 10")
    
    # Print column names
    columns = [desc[0] for desc in cursor.description]
    print(f"Columns: {columns}")
    
    # Print rows
    for row in cursor.fetchall():
        print(row)
    
    conn.close()

if __name__ == "__main__":
    main()

.NET

using System.Data.Odbc;

class Program
{
    static async Task Main(string[] args)
    {
        string connectionString = 
            "DRIVER={Microsoft ODBC Driver for Microsoft Fabric Data Engineering};" +
            "WorkspaceId=<workspace-id>;" +
            "LakehouseId=<lakehouse-id>;" +
            "AuthFlow=AZURE_CLI;" +
            "ReuseSession=true;";

        using var connection = new OdbcConnection(connectionString);
        await connection.OpenAsync();
        
        Console.WriteLine("Connected successfully!");

        // Show available tables
        Console.WriteLine("\nAvailable tables:");
        using (var cmd = new OdbcCommand("SHOW TABLES", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            while (await reader.ReadAsync())
            {
                Console.WriteLine($"  {reader.GetString(0)}");
            }
        }

        // Query data
        Console.WriteLine("\nQuery results:");
        using (var cmd = new OdbcCommand("SELECT * FROM employees LIMIT 10", connection))
        using (var reader = await cmd.ExecuteReaderAsync())
        {
            // Print column names
            var columns = new List<string>();
            for (int i = 0; i < reader.FieldCount; i++)
            {
                columns.Add(reader.GetName(i));
            }
            Console.WriteLine($"Columns: {string.Join(", ", columns)}");

            // Print rows
            while (await reader.ReadAsync())
            {
                var values = new object[reader.FieldCount];
                reader.GetValues(values);
                Console.WriteLine(string.Join("\t", values));
            }
        }
    }
}

大規模な結果セットを扱う

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;"  # 18 MB pages
    "EnableAsyncPrefetch=1;"
)

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

# Execute large query
cursor.execute("SELECT * FROM large_table")

# Process in batches
row_count = 0
while True:
    rows = cursor.fetchmany(1000)  # Fetch 1000 rows at a time
    if not rows:
        break
    
    for row in rows:
        # Process row
        row_count += 1
        
    if row_count % 10000 == 0:
        print(f"Processed {row_count} rows")

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

DML文の実行

bool executeDml(SQLHDBC connection, const char* sql, const char* description) {
    SQLHSTMT statement = SQL_NULL_HSTMT;
    SQLAllocHandle(SQL_HANDLE_STMT, connection, &statement);

    std::cout << "Executing: " << description << std::endl;
    SQLRETURN result = SQLExecDirectA(
        statement,
        (SQLCHAR*)sql,
        SQL_NTS);

    bool succeeded = SQL_SUCCEEDED(result);
    if (succeeded) {
        SQLLEN rowCount;
        SQLRowCount(statement, &rowCount);
        std::cout << "Rows affected: " << rowCount << std::endl;
    }

    SQLFreeHandle(SQL_HANDLE_STMT, statement);
    return succeeded;
}

INSERT、UPDATE、またはDELETE文にexecuteDmlを使いましょう。 報告された行数は、結果にドライバーが認識する更新数が含まれているかどうかに依存します。

スキーマ検出

import pyodbc

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

# List all tables
print("Tables in current default schema / database:")
cursor.execute("SHOW TABLES")
tables = cursor.fetchall()
for table in tables:
    print(f"  {table}")

# Describe table structure
print("\nTable structure for 'employees':")
cursor.execute("DESCRIBE employees")
for col in cursor.fetchall():
    print(f"  {col}")

# List schemas (for multi-schema Lakehouses)
print("\nAvailable schemas:")
cursor.execute("SHOW SCHEMAS")
for db in cursor.fetchall():
    print(f"  {db}")

conn.close()

データ型マッピング

ドライバーは、Spark SQL データ型を ODBC SQL 型にマップします。

BI ツールの統合

マイクロソフト Excel

1. Excel -> データを開く -> 他のソースからデータを取得する -> ODBC から>
2. 構成した DSN を選択します (例: FabricODBC)
3. メッセージが表示されたら認証する
4. テーブルを参照して選択する
5. Excel ワークシートにデータを読み込む

Power BI Desktop

1. Power BI Desktop を開く -> データの取得 -> ODBC
2. 構成した DSN を選択する
3. データ カタログを参照してテーブルを選択する
4. 必要に応じてデータを変換する
5. 視覚化を作成する

SQL Server Management Studio (リンク サーバー)

-- Create linked server
EXEC sp_addlinkedserver 
    @server = 'FABRIC_LINKED_SERVER',
    @srvproduct = 'Microsoft Fabric',
    @provider = 'MSDASQL',
    @datasrc = 'FabricODBC'

-- Configure RPC
EXEC master.dbo.sp_serveroption 
    @server = N'FABRIC_LINKED_SERVER',
    @optname = N'rpc out',
    @optvalue = N'true';

-- Query via linked server
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SHOW TABLES');
SELECT * FROM OPENQUERY(FABRIC_LINKED_SERVER, 'SELECT * FROM employees LIMIT 20');

-- Execute statements
EXEC('SELECT * FROM employees LIMIT 10') AT FABRIC_LINKED_SERVER;

トラブルシューティング

このセクションでは、Microsoft ODBC Driver for Microsoft Fabric Data Engineering を使用するときに発生する可能性のある一般的な問題を解決するためのガイダンスを提供します。

一般的な問題

次のセクションでは、一般的な問題とその解決策について説明します。

接続の失敗

問題:Fabricに接続できません

解決策:

1. ワークスペースIDとレイクハウスIDが正しいGUIDかどうかを確認してください
2. Azure CLI 認証を確認します。 az account show
3. 適切な Fabric ワークスペースのアクセス許可があることを確認する
4. ネットワーク接続とプロキシの設定を確認する

認証エラー

問題: Azure CLI で認証が失敗する

解決策:

• az loginを実行して資格情報を更新する
• 正しいテナントを確認します。 az account set --subscription <subscription-id>
• トークンの有効性を確認します。 az account get-access-token --resource https://api.fabric.microsoft.com

クエリ タイムアウト

問題: 大きなテーブルでクエリがタイムアウトする

解決策:

• LargeTableSupport=true を有効にする
• 最適なチャンク サイズに合わせて PageSizeBytes を調整する
• 非同期プリフェッチを有効にします。 EnableAsyncPrefetch=1
• LIMIT句を使用して結果のサイズを制限する

ログ記録を有効にする

問題のトラブルシューティングを行うときに、詳細なログ記録を有効にすると、問題の根本原因を特定するのに役立ちます。 接続文字列を使用してログ記録を有効にすることができます。

詳細なログ記録を有効にするには:

LogLevel=DEBUG;LogFile=C:\temp\odbc_driver_debug.log;

ログ レベル:

• DEBUG詳細なデバッグ情報と最も詳細なドライバーログレベル
• INFO: 一般的な情報 (既定)
• WARN: 警告のみ
• ERROR: エラーのみ

ODBC トレース

低レベルの診断では、Windows ODBC トレースを有効にして、詳細な ODBC API 呼び出しとドライバーの動作をキャプチャできます。 最適なパフォーマンスを維持するために必要ない場合は、トレースをオフにすることを忘れないでください。

ODBC トレースを有効にするには:

1. odbcad32.exeをオープンする
2. [トレース] タブに移動する
3. トレース ファイルのパスを設定する (例: C:\temp\odbctrace.log)
4. [今すぐトレースを開始] を選択する
5. 問題を再現する
6. [トレースを今すぐ停止] を選択する

関連するコンテンツ

• Linux上のMicrosoft Fabricデータエンジニアリング向けMicrosoft ODBCドライバー
• Fabric の Apache Spark Runtime
• ファブリック ランタイム 1.3
• データ エンジニアリング用 Livy API とは
• Microsoft Fabric Data Engineering 向け Microsoft JDBC Driver