Databricks JDBC ドライバー (Simba) のドライバー機能設定
このページは、Simba JDBC Driver（レガシー）のバージョン3未満のバージョンに適用されます。Databricksは、JDBC接続にはDatabricks JDBC Driverへの移行を強く推奨します。これには、 Unity Catalogメトリクス ビューのサポート、複数のSQLステートメントにまたがるトランザクション、ストアド プロシージャ、大量の結果の取得の高速化、クライアント テレメトリの組み込みなどの改善が含まれています。
このページでは、 Databricks JDBC ドライバーの特別な高度なドライバー機能設定を構成する方法について説明します。
Databricks JDBC ドライバーには、次の特殊で高度なドライバー機能設定が用意されています。
JDBC での ANSI SQL-92 クエリのサポート
従来の Spark JDBC ドライバーは、ANSI SQL-92 方言の SQL クエリを受け入れ、それをサーバーに送信する前に Databricks SQL に変換します。
アプリケーションが Databricks SQL を直接生成するか、Databricks 固有の非 ANSI SQL-92 構文を使用する場合は、接続構成でUseNativeQuery=1を設定します。この設定により、SQL クエリが変換されずにそのまま Databricks に渡されます。
デフォルトのカタログとスキーマ
デフォルトのカタログとスキーマを指定するには、JDBC接続URLにConnCatalog=<catalog-name>;ConnSchema=<schema-name>を追加します。
追跡用のクエリタグ
追跡と分析の目的で、 SQLクエリに key-value タグを添付します。 クエリ タグは、クエリの識別と分析のためにsystem.query.historyテーブルに表示されます。
接続にクエリ タグを追加するには、 JDBC接続 URL にssp_query_tagsパラメーターを含めます。
jdbc:databricks://<server-hostname>:443;httpPath=<http-path>;ssp_query_tags=key1:value1,key2:value2
クエリ タグを、コンマで区切られたキーと値のペアとして定義します。各キーと値はコロンで区切られます。たとえば、 key1:value1,key2:value2 。
JDBCで大きなクエリ結果を抽出する
大規模なクエリー結果を抽出するときに最高のパフォーマンスを実現するには、以下の最適化が含まれている最新バージョンのJDBCドライバーを使用してください。
JDBC でのArrowのシリアル化
JDBC ドライバー バージョン 2.6.16 以降では、 Apache Arrow を使用した最適化されたクエリ結果のシリアル化形式がサポートされています。
JDBC での Cloud Fetch
JDBCドライバー バージョン 2.6.19 以降は、 Databricksデプロイメントで構成されたクラウド ストレージを通じてクエリ結果をフェッチする機能であるクラウド フェッチをサポートしています。
クエリーを実行すると、Databricksは結果をワークスペースのクラウドストレージに、最大20 MBのArrowシリアル化ファイルとして保存します。クエリーが完了すると、ドライバーは取得リクエストを送信し、Databricksは結果ファイルへの署名付きURLを返します。その後、ドライバーはこれらのURLを使用して、Google Cloud Storage（GCS）から結果を直接downloadします。
Cloud Fetch は、1 MB を超えるクエリ結果にのみ適用されます。 ドライバーは Databricks から小さな結果を直接取得します。
Databricksは、蓄積されたファイルを自動的にガベージコレクションし、24時間後に削除対象としてマークし、さらに24時間後に完全に削除します。
ネットワークの前提条件
Cloud Fetchは結果ファイルをGCSから直接downloadします。クライアントマシンがGCSに到達できない場合、Cloud Fetchは失敗します。次のことを確認してください。
- プロキシおよびファイアウォールルールは、
storage.googleapis.comへのHTTPSトラフィックを許可する必要があります。 - ワークスペースのストレージバケットでバケットIPフィルタリングを使用している場合、フィルターでクライアントマシンのIPアドレスを許可する必要があります。
- ワークスペースのストレージバケットがVPC Service Controlsの境界内にある場合、その境界に、クライアントマシンからのリクエストを許可するアクセスレベルまたはイングレスルールが必要です。
クラウド Fetchを無効にするには、接続構成でEnableQueryResultDownload=0を設定します。
ダウンロード速度が遅い原因を診断する
Cloud Fetch のダウンロード速度のメトリクスを確認するには、 LogLevel 4 (情報) に設定し、 LogPathログ フォルダーのフル パスに設定します。 ドライバはチャンクごとにダウンロード速度をログに記録するため、結果セットが大きい場合は複数のログ行が生成されます。ドライバーは、速度が約1MB/秒を下回った場合にも警告をログに記録します。この機能は、2025年12月以降にリリースされたJDBC（Simba）ドライバのバージョンで利用可能です。
downloadが遅い場合や停止している場合、ドライバーがすべての結果ファイルのdownloadを完了する前に署名付き URL の有効期限が切れる可能性があります。クライアントと GCS の間の帯域幅の制限やネットワークの混雑を確認してください。
ログ記録を有効にする
JDBC ドライバーでのログ記録を有効にするには、 LogLevelプロパティを1 (重大なイベントのみ) から6 (すべてのドライバー アクティビティ) までの値に設定します。LogPathプロパティを、ログ ファイルを保存するフォルダーの完全パスに設定します。
詳細については、 Databricks JDBCドライバー ガイドの「ログ記録の構成」を参照してください。