このページでは、 Databricks ODBC ドライバーの特別なドライバー機能設定と高度なドライバー機能設定を構成する方法について説明します。
Databricks ODBC ドライバーには、次の特殊かつ高度なドライバー機能設定が用意されています。
ODBC で初期スキーマを設定する
ODBC ドライバーでは、接続構成として Schema=<schema-name> を設定することにより、スキーマを指定できます。 これは、USE <schema-name> の実行に相当します。
追跡用のクエリ タグ
Important
この機能は、プライベート プレビューにあります。 アクセス権を要求するには、アカウント チームにお問い合わせください。
追跡と分析のために、SQL クエリにキー値タグをアタッチします。 クエリタグは、クエリの識別と分析のために system.query.history テーブルに表示されます。
接続にクエリ タグを追加するには、ODBC 接続構成に ssp_query_tags パラメーターを含めます。
クエリ タグをコンマ区切りのキーと値のペアとして定義します。各キーと値はコロンで区切られます。 たとえば、「 ssp_query_tags=team:engineering,env:prod 」のように入力します。
ODBC での ANSI SQL-92 クエリのサポート
従来の Spark ODBC ドライバーは、ANSI SQL-92 方言で SQL クエリを受け入れ、それらを Databricks SQL に変換してからサーバーに送信します。
アプリケーションで Databricks SQL が直接生成される場合、またはAzure Databricksに固有の ANSI SQL-92 以外の構文を使用している場合は、接続構成で UseNativeQuery=1 を設定します。 この設定は、SQL クエリを翻訳なしでAzure Databricksするように逐語的に渡します。
ODBC で大きなクエリ結果を抽出する
大規模なクエリ結果を抽出するときに最適なパフォーマンスを実現するには、最新バージョンの ODBC ドライバーを使用します。これには、次の最適化が含まれます。
ODBC での Arrow シリアル化
ODBC ドライバー バージョン 2.6.15 以降では、Apache Arrow を使う最適化されたクエリ結果のシリアル化形式がサポートされています。
ODBC での Cloud Fetch
ODBC ドライバー バージョン 2.6.17 以降では、Cloud Fetch がサポートされています。Cloud Fetch は、Azure Databricksデプロイで構成されたクラウド ストレージを介してクエリ結果をフェッチする機能です。
クエリを実行すると、Azure Databricksワークスペースのクラウド ストレージに、最大 20 MB の方向シリアル化ファイルとして結果が格納されます。 クエリが完了すると、ドライバーはフェッチ要求を送信し、Azure Databricksは結果ファイル共有アクセス署名 (SAS) URL を返します。 その後、ドライバーはこれらの URL を使用して、Azureストレージから直接結果をダウンロードします。
クラウド フェッチは、1 MB を超えるクエリ結果にのみ適用されます。 ドライバーは、Azure Databricksから直接小さな結果を取得します。
Azure Databricks、24 時間後に削除対象としてマークし、24 時間後に完全に削除することで、蓄積されたファイルを自動的にガベージ コレクションします。
ネットワーク前提条件
ネットワークがプライベートの場合は、Cloud Fetch が機能するように次の設定を構成する必要があります。
- ネットワーク環境で
*.blob.core.windows.netと*.store.core.windows.netを許可します。 - 必要な 証明書のダウンロードと失効を 許可リストに追加します。
- Azure Databricks ワークスペース ストレージ アカウントでファイアウォールのサポートが有効になっている場合は、仮想ネットワーク データ ゲートウェイまたはオンプレミス データ ゲートウェイを構成して、ストレージ アカウントへのプライベート アクセスを許可します。
Cloud Fetch を無効にするには、接続構成で EnableQueryResultDownload=0 を設定します。
低速なダウンロードを診断する
LogLevelを 4 (INFO) に設定し、ログ フォルダーの完全なパスにLogPathして、Cloud Fetch のダウンロード速度メトリックを確認します。 ドライバーはチャンクごとのダウンロード速度をログに記録するため、結果セットが大きいと複数のログ行が生成されます。 また、速度が約 1 MB/秒を下回ると、ドライバーによって警告が記録されます。 この機能は、2025 年 11 月以降にリリースされた ODBC ドライバー バージョンで使用できます。
ダウンロードが遅いかストールしている場合、ドライバーがすべての結果ファイルのダウンロードを完了する前に、SAS トークンの有効期限が切れる可能性があります。 クライアントとAzure Blob Storage間の帯域幅調整またはネットワークの輻輳を確認します。
ログの有効化
ODBC ドライバーでログ記録を有効にするには、 LogLevel プロパティを 1 (重大なイベントのみ) と 6 (すべてのドライバー アクティビティ) の間の値に設定します。
LogPath プロパティを、ログ ファイルを保存するフォルダーの完全なパスに設定します。
詳細については、「Databricks ODBC ドライバー ガイド」の「非Windows コンピューターのログ オプションの構成」を参照してください。