Databricks JDBC ドライバー (OSS)

プレビュー

このドライバーは パブリック プレビュー 段階であり、一般提供 (GA) になるとオープンソースとして利用できるようになります。

最新バージョンのドライバーであるDatabricks JDBC(OSS)を使用すると、データベース管理システムにアクセスするための業界標準仕様であるJava Database Connectivity(JDBC)を介して、 DataGripDBeaverSQL Workbench/J などのツールをDatabricksに接続できます。

このドライバーはJDBC APIsを実装しており、 OAuth 、クラウド Fetch、 Unity Catalogボリューム取り込みなどのコア機能を提供します。 ネイティブ クエリ モードを実行し、ネイティブ パラメータ化クエリをサポートし、便利なクエリ結果保持機能、つまり Thrift を提供する ステートメント実行APIsを使用して実行できます。

この記事では、 Databricks JDBCドライバー (OSS) のインストールと使用に関する情報を提供します。 非 OSS Databricks JDBCドライバーの詳細については、 Databricks JDBCドライバー」を参照してください。

要件

Databricks JDBC ドライバー (OSS) を使用するには、次の要件を満たす必要があります。

  • Java Runtime環境 (JRE) 11.0 以上。 CI テストは、JRE 11、17、および 21 でサポートされています。

注:

JDK 16 での変更により、JDBC ドライバーで使用される Apache Arrow ライブラリとの互換性の問題が発生したため、JDK 16 以上で JDBC ドライバーを使用すると、ランタイム エラーが発生する可能性があります。 これらのエラーを回避するには、次の JVM コマンドオプションを使用してアプリケーションまたはドライバーを再起動します。

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

ドライバーをインストールする

Databricks JDBC Driver (OSS) は Maven リポジトリで公開されています。 最新バージョンは 0.9.6-oss です。

ドライバーをインストールするには、次のいずれかの操作を行います。

  • Maven プロジェクトの場合、プロジェクトのpom.xmlファイルに次の依存関係を追加して、指定されたバージョンの JDBC ドライバーを自動的にダウンロードするように Maven に指示します。

    <dependency>
      <groupId>com.databricks</groupId>
      <artifactId>databricks-jdbc</artifactId>
      <version>0.9.6-oss</version>
      <scope>runtime</scope>
    </dependency>
    
  • Gradle プロジェクトの場合、プロジェクトのビルド ファイルに次の依存関係を追加して、指定されたバージョンの JDBC ドライバーを自動的にダウンロードするように Gradle に指示します。

    implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
    

他のプロジェクト タイプの依存関係構文を表示し、Databricks JDBC ドライバー (OSS) の最新バージョン番号を取得するには、 Maven リポジトリを参照してください。

接続 URL を構成する

Databricksドライバーを使用して ワークスペースに接続するには、JDBC JDBCDatabricksスペースのサーバーのホスト名、コンピュート リソースの設定、ワークスペースに接続するための認証資格情報などのさまざまな接続設定を含む 接続 URL を指定する必要があります。 。

これらのプロパティの値は、JDBC 接続 URL で設定するか、 DriverManager.getConnection メソッドに設定して渡すか、またはその両方の組み合わせで行うことができます。 特定のアプリ、クライアント、SDK、API、または SQL ツールを使用して接続する最適な方法については、プロバイダーのドキュメントを参照してください。

JDBC 接続 URL は次の形式である必要があります。 プロパティは大文字と小文字を区別しません。

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

または、 java.util.Properties クラスまたは組み合わせを使用して設定を指定します。

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);
String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

接続 URL 要素については、次の表で説明します。 認証プロパティを含む追加のプロパティの詳細については、以下のセクションを参照してください。 URL 要素とプロパティは大文字と小文字を区別しません。

URL 要素またはプロパティ

説明

<server-hostname>

Databricksコンピュート リソースのサーバーホスト名の値。

<port>

Databricksコンピュート リソースのポート値。 デフォルト値は443です。

<schema>

スキーマの名前。 または、 ConnSchema プロパティを設定することもできます。 「接続プロパティ」を参照してください。

httpPath

Databricksコンピュート リソースの HTTP パス値。 コネクタは、接続 URL で指定されたホストとポートに httpPath 値を付加して、接続先の HTTP アドレスを形成します。 たとえば、HTTP アドレス http://localhost:10002/cliserviceに接続するには、次の接続 URL を使用します。 jdbc:databricks://localhost:10002;httpPath=cliservice

Databricksクラスターの JDBC 接続 URL を取得するには:

  1. Databricksワークスペースにログインします。

  2. サイドバーで「コンピュート」をクリックし、ターゲットのクラスターの名前をクリックします。

  3. [構成]タブで、 [詳細オプション]を展開します。

  4. JDBC/ODBCタブをクリックします。

  5. JDBC 接続 URL として使用するJDBC URLをコピーするか、サーバー ホスト名ポート、およびHTTP パスフィールドの値から URL を構築します。

Databricks SQLウェアハウスの JDBC 接続 URL を取得するには:

  1. Databricksワークスペースにログインします。

  2. サイドバーでSQLウェアハウス」をクリックし、対象のウェアハウスの名前をクリックします。

  3. [接続の詳細]タブをクリックします。

  4. JDBC 接続 URL として使用するJDBC URLをコピーするか、サーバー ホスト名ポート、およびHTTP パスフィールドの値から URL を構築します。

ドライバーを認証する

次のいずれかの認証メカニズムを使用して、JDBC ドライバー接続を認証できます。

OAuthユーザー対マシン(U2M)認証

JDBCOAuthドライバーは、リアルタイム ヒューマン サインインとターゲット ユーザーDatabricks アカウントの認証に同意するための ユーザー対マシン (U2M) 認証をサポートしています。これは、 ブラウザベースの OAuth 認証とも呼ばれます。

Databricks は、顧客向けの OAuth クライアント ID databricks-sql-jdbc を作成しました。 これは、JDBC ドライバーで使用されるデフォルトの OAuth クライアント ID でもあります。 OAuth U2M 認証を設定するには、既存の JDBC 接続 URL または java.util.Properties オブジェクトに次のプロパティを追加するだけです。

属性

AuthMech

11

Auth_Flow

2

OAuthマシン間(M2M)認証

JDBCOAuthドライバーは、Databricks サービスプリンシパルを使用した マシン間 (M2M) 認証をサポートしています。これは、OAuth 2.0 クライアント資格情報 認証とも呼ばれます。 「 Databricksを使用してサービスプリンシパルで へのアクセスを認証するOAuth (OAuth M2M)」 を参照してください。

OAuth M2M または OAuth 2.0 クライアント資格情報認証を構成するには:

  1. DatabricksワークスペースにDatabricks サービスプリンシパルを作成し、そのサービスプリンシパルのOAuthシークレットを作成します。「 Databricksを使用してサービスプリンシパルで へのアクセスを認証するOAuth (OAuth M2M)」 を参照してください。サービスプリンシパルの UUID または Application ID の値と、サービスプリンシパルの シークレットの SecretOAuth 値をメモします。

  2. サービスプリンシパルにクラスターまたはウェアハウスへのアクセスを許可します。 「コンピュート権限」または「 SQLウェアハウスの管理」を参照してください。

既存の JDBC 接続 URL またはjava.util.Propertiesオブジェクトに次のプロパティを追加します。

属性

AuthMech

11

Auth_Flow

1

OAuth2ClientID

サービスプリンシパルのUUIDまたはアプリケーション ID の値。

OAuth2Secret

サービスプリンシパルのOAuth Secret値。

Databricksパーソナルアクセスポイント

JDBCDatabricks個人アクセス権 を使用して ドライバー接続を認証するには、次のプロパティをJDBC 接続 URL またはjava.util.Properties オブジェクトに追加します。

属性

AuthMech

3

user

token (文字列)。

PWD または password

Databricksの個人的なアクセス内部の値 (文字列として)。

接続プロパティ

次の追加の接続プロパティは、JDBC ドライバーによってサポートされています。 プロパティは大文字と小文字を区別しません。

属性

デフォルト値

説明

AuthMech

必須

認証メカニズム。ここで、3 はメカニズムがDatabricks個人アクセスアセトンであることを指定し、11 はメカニズムがOAuth 2.0 ウイルスであることを指定します。 各メカニズムには、追加のプロパティが必要です。 「ドライバーの認証」を参照してください。

Auth_Flow

0

ドライバー接続の OAuth2 認証フロー。 このプロパティは、 AuthMech が [ 11] の場合に必要です。

SSL

1

コネクタが SSL 対応ソケットを介して Spark サーバーと通信するかどうか。

ConnCatalog または catalog

SPARK

使用するデフォルトカタログの名前。

ConnSchema または schema

default

使用するデフォルトのスキーマの名前。 これを指定するには、URL の URL の <schema> を使用するスキーマの名前に置き換えるか、 ConnSchema プロパティを使用するスキーマの名前に設定します。

ProxyAuth

0

1に設定すると、ドライバーはプロキシ認証ユーザーとパスワード (ProxyUIDProxyPwdで表されます) を使用します。

ProxyHost

null

UseProxy1に設定されている場合に、使用するプロキシ ホストの名前を表す文字列。

ProxyPort

null

また、 UseProxy1に設定されている場合に使用するプロキシ ポートの数を表す整数。

ProxyUID

null

ProxyAuthUseProxy1に設定されている場合にプロキシ認証に使用するユーザー名を表す文字列。

ProxyPwd

null

ProxyAuthUseProxy1に設定されている場合にプロキシ認証に使用するパスワードを表す文字列。

UseProxy

0

1に設定すると、ドライバーは指定されたプロキシ設定 (ProxyAuthProxyHostProxyPortProxyPwdProxyUIDなど) を使用します。

UseSystemProxy

0

1に設定すると、ドライバーはシステム レベルで設定されたプロキシ設定を使用します。接続 URL に追加のプロキシ プロパティが設定されている場合、これらの追加のプロキシ プロパティは、システム レベルで設定されているプロキシ プロパティを上書きします。

UseCFProxy

0

1に設定すると、ドライバーはクラウド フェッチ プロキシ設定が提供されている場合はそれを使用し、提供されていない場合は通常のプロキシを使用します。

CFProxyAuth

0

1に設定すると、ドライバーはプロキシ認証ユーザーとパスワード (CFProxyUIDCFProxyPwdで表されます) を使用します。

CFProxyHost

null

UseCFProxy1に設定されている場合に、使用するプロキシ ホストの名前を表す文字列。

CFProxyPort

null

また、 UseCFProxy1に設定されている場合に使用するプロキシ ポートの数を表す整数。

CFProxyUID

null

CFProxyAuthUseCFProxy1に設定されている場合にプロキシ認証に使用するユーザー名を表す文字列。

CFProxyPwd

null

CFProxyAuthUseCFProxy1に設定されている場合にプロキシ認証に使用するパスワードを表す文字列。

AsyncExecPollInterval

200

非同期クエリ実行ステータスの各ポーリング間の時間 (ミリ秒単位)。 非同期とは、Spark に対してクエリを実行するために使用される RPC 呼び出しが非同期であることを意味します。 これは、JDBC 非同期操作がサポートされていることを意味するものではありません。

UserAgentEntry

browser

HTTP 要求に含める User-Agent エントリ。 この値は次の形式です。 [ProductName]/[ProductVersion] [Comment]

UseThriftClient

0

JDBCドライバーがThriftクライアントを使用してAll-Purposeクラスターに接続する必要があるかどうか。デフォルト値は SQLウェアハウスで機能します。

SQL 構成プロパティ

次の SQL 構成プロパティは、JDBC ドライバーによってサポートされています。 これらについては、 「構成」でも説明されています。 プロパティは大文字と小文字を区別しません。

属性

デフォルト値

説明

ansi_mode

TRUE

特定の関数およびキャスト規則に対して厳密な ANSI SQL 動作を有効にするかどうか。

enable_photo

TRUE

Photon ベクトル化クエリ エンジンを有効にするかどうか。

legacy_time_parser_policy

EXCEPTION

日付とタイムスタンプの解析と書式設定に使用されるメソッド。 有効な値は、 EXCEPTIONLEGACY、および CORRECTEDです。

max_file_partition_bytes

128m

ファイルベースのソースから読み取るときに、単一のパーティションにパックする最大バイト数。 この設定は任意の正の整数にすることができ、オプションで b (バイト)、 kkb (1024 バイト) などのメジャーを含めることができます。

read_only_external_metastore

false

外部メタストアを読み取り専用として扱うかどうかを制御します。

statement_timeout

172800

SQL ステートメントのタイムアウトを 0 ~ 172800 秒の間で設定します。

timezone

UTC

ローカルタイムゾーンを設定します。 area/city形式の地域 ID(例: America/Los_Angeles)や、(+|-)HH、(+|-)HH:mm、(+|-)HH:mm:ss(例: -08、+01:00、-13:33:33)の形式のゾーン オフセット。また、 UTC は +00:00 のエイリアスとしてサポートされています

use_cached_result

true

Databricks SQL が可能な限り結果をキャッシュして再利用するかどうか。

ログ記録のプロパティ

次のログ プロパティは、JDBC ドライバーによってサポートされています。 プロパティは大文字と小文字を区別しません。

属性

デフォルト値

説明

LogLevel

OFF

ロギング・レベル (0 から 6 までの値):

  • 0: すべてのログ記録を無効にします。

  • 1: FATAL レベルでログ記録を有効にすると、コネクタが中止される原因となる非常に重大なエラー イベントがログに記録されます。

  • 2: ERROR レベルでログ記録を有効にすると、コネクタの実行を続行できる可能性のあるエラー イベントがログに記録されます。

  • 3: WARNING レベルでログ記録を有効にし、アクションが実行されない場合にエラーになる可能性のあるイベントをログに記録します。

  • 4: INFO レベルでのログ記録を有効にします。これにより、コネクタの進行状況を示す一般的な情報がログに記録されます。

  • 5: DEBUG レベルでログ記録を有効にします。これにより、コネクタのデバッグに役立つ詳細な情報がログに記録されます。

  • 6: TRACE レベルでログ記録を有効にし、すべてのコネクタ アクティビティをログに記録します。

このプロパティを使用して、コネクタでのログ記録を有効または無効にしたり、ログ ファイルに含まれる詳細の量を指定したりします。

LogPath

ログのデフォルトパスを決定するために、ドライバーはこれらのシステムプロパティに設定された値を次の優先順位で使用します。

  1. user.dir

  2. java.io.tmpdir

  3. つまり、現在のディレクトリ .

ログ記録が有効になっているときにコネクタがログファイルを保存するフォルダへの絶対パス (文字列)。 接続 URL がすべての JDBC アプリケーションと互換性があることを確認するには、別のバックスラッシュを入力して、ファイルパスのバックスラッシュ (\) をエスケープします。

LogPath値が無効な場合、コネクタはログに記録された情報を標準出力ストリーム (System.out) に送信します。

LogFileSize

上限なし

許容される最大ログ・ファイル・サイズ (MB 単位)

LogFileCount

上限なし

許可されるログ・ファイルの最大数

ログ記録の有効化と構成

JDBC ドライバは、 Simple Logging Facade for Java (SLF4J) および java.util.logging (JUL) フレームワークをサポートしています。 ドライバーは、デフォルトで JUL ロギングフレームワークを使用します。

JDBC ドライバーのログ記録を有効にして構成するには、次のようにします。

  1. 使用するロギングフレームワークを有効にします。

    • SLF4J ロギングの場合は、システムプロパティーを -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER に設定し、SLF4J バインディング実装 (SLF4J バージョン 2.0.13 以上と互換性あり) と対応する構成ファイルをクラスパスに含めます。

    • JUL ロギングの場合は、システム・プロパティーを -Dcom.databricks.jdbc.loggerImpl=JDKLOGGERに設定します。 これがデフォルトです。

  2. 接続文字列の LogLevel プロパティを、ログ ファイルに含める情報レベルに設定します。

  3. 接続文字列の LogPath プロパティを、ログ ファイルを保存するフォルダーへのフル パスに設定します。

    たとえば、次の接続 URL はロギング レベル 6 を有効にし、ログファイルを C:temp フォルダに保存します。

    jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
    
  4. JDBC アプリケーションを再起動し、サーバーに再接続して設定を適用します。

例: JDBC ドライバーを使用してクエリを実行する

次の例は、JDBC ドライバーを使用して、Databricks SQL Databricksコンピュート リソースを使用して クエリを実行する方法を示しています。

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}