Google
Cloud Platform
Amazon Web Services
Microsoft AzureDatabricks JDBC ドライバー (OSS)
プレビュー
このドライバーは パブリック プレビュー 段階であり、一般提供 (GA) になるとオープンソースとして利用できるようになります。
最新バージョンのドライバーであるDatabricks JDBC(OSS)を使用すると、データベース管理システムにアクセスするための業界標準仕様であるJava Database Connectivity(JDBC)を介して、 DataGrip、 DBeaver、 SQL Workbench/J などのツールをDatabricksに接続できます。
このドライバーはJDBC APIsを実装しており、 OAuth 、クラウド Fetch、 Unity Catalogボリューム取り込みなどのコア機能を提供します。 ネイティブ クエリ モードを実行し、ネイティブ パラメータ化クエリをサポートし、便利なクエリ結果保持機能、つまり Thrift を提供する ステートメント実行APIを使用して実行できます。
この記事では、 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ドライバーを使用して ワークスペースに接続するには、 Databricksワークスペースのサーバーのホスト名、コンピュートリソースの設定、ワークスペースに接続するための認証資格情報などのさまざまな接続設定を含むJDBC 接続 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 要素またはプロパティ |
説明 |
|---|---|
|
Databricksコンピュート リソースのサーバーホスト名の値。 |
|
Databricksコンピュート リソースのポート値。 デフォルト値は |
|
スキーマの名前。 または、 |
|
Databricksコンピュート リソースの HTTP パス値。 コネクタは、接続 URL で指定されたホストとポートに |
Databricksクラスターの JDBC 接続 URL を取得するには:
Databricksワークスペースにログインします。
サイドバーでコンピュートをクリックし、ターゲットのクラスターの名前をクリックします。
構成タブで、 詳細オプションを展開します。
JDBC/ODBCタブをクリックします。
JDBC 接続 URL として使用するJDBC URLをコピーするか、サーバー ホスト名、ポート、およびHTTP パスフィールドの値から URL を構築します。
Databricks SQLウェアハウスの JDBC 接続 URL を取得するには:
Databricksワークスペースにログインします。
サイドバーでSQLウェアハウスをクリックし、対象のウェアハウスの名前をクリックします。
接続の詳細タブをクリックします。
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 オブジェクトに次のプロパティを追加するだけです。
属性 |
値 |
|---|---|
|
|
|
|
OAuthマシン間（M2M）認証
JDBCOAuthドライバーは、Databricks サービスプリンシパルを使用した マシン間 (M2M) 認証をサポートしています。これは、OAuth 2.0 クライアント資格情報 認証とも呼ばれます。 OAuth (OAuth M2M)を用いて、サービスプリンシパルによるDatabricksへのアクセスを認証する を参照してください。
OAuth M2M または OAuth 2.0 クライアント資格情報認証を構成するには:
DatabricksワークスペースにDatabricks サービスプリンシパルを作成し、そのサービスプリンシパルのOAuthシークレットを作成します。「 OAuth (OAuth M2M)を用いて、サービスプリンシパルによるDatabricksへのアクセスを認証する を参照してください。サービスプリンシパルの UUID または Application ID の値と、サービスプリンシパルの シークレットの SecretOAuth 値をメモします。
サービスプリンシパルにクラスターまたはウェアハウスへのアクセスを許可します。 コンピュートの権限またはSQLウェアハウスの管理を参照してください。
既存の JDBC 接続 URL またはjava.util.Propertiesオブジェクトに次のプロパティを追加します。
属性 |
値 |
|---|---|
|
|
|
|
|
サービスプリンシパルのUUIDまたはアプリケーション ID の値。 |
|
サービスプリンシパルのOAuth Secret値。 |
Databricksパーソナルアクセストークン
Databricksのパーソナルアクセストークン を用いて、JDBCドライバー接続を認証するには、次のプロパティをJDBC 接続 URL またはjava.util.Properties オブジェクトに追加します。
属性 |
値 |
|---|---|
|
|
|
値 |
|
Databricksの個人的なアクセス内部の値 (文字列として)。 |
接続プロパティ
次の追加の接続プロパティは、JDBC ドライバーによってサポートされています。 プロパティは大文字と小文字を区別しません。
属性 |
デフォルト値 |
説明 |
|---|---|---|
|
必須 |
認証メカニズム。ここで、 |
|
|
ドライバー接続の OAuth2 認証フロー。 このプロパティは、 |
|
|
コネクタが SSL 対応ソケットを介して Spark サーバーと通信するかどうか。 |
|
|
使用するデフォルトカタログの名前。 |
|
|
使用するデフォルトのスキーマの名前。 これを指定するには、URL の URL の |
|
|
|
|
|
|
|
|
また、 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
また、 |
|
|
|
|
|
|
|
|
非同期クエリ実行ステータスの各ポーリング間の時間 (ミリ秒単位)。 非同期とは、Spark に対してクエリを実行するために使用される RPC 呼び出しが非同期であることを意味します。 これは、JDBC 非同期操作がサポートされていることを意味するものではありません。 |
|
|
HTTP 要求に含める User-Agent エントリ。 この値は次の形式です。 |
|
|
JDBCドライバーがThriftクライアントを使用してAll-Purposeクラスターに接続する必要があるかどうか。デフォルト値は SQLウェアハウスで機能します。 |
SQL 構成プロパティ
次の SQL 構成プロパティは、JDBC ドライバーによってサポートされています。 これらについては、 「構成」でも説明されています。 プロパティは大文字と小文字を区別しません。
属性 |
デフォルト値 |
説明 |
|---|---|---|
|
|
特定の関数およびキャスト規則に対して厳密な ANSI SQL 動作を有効にするかどうか。 |
|
|
Photon ベクトル化クエリ エンジンを有効にするかどうか。 |
|
|
日付とタイムスタンプの解析と書式設定に使用されるメソッド。 有効な値は、 |
|
|
ファイルベースのソースから読み取るときに、単一のパーティションにパックする最大バイト数。 この設定は任意の正の整数にすることができ、オプションで |
|
|
外部メタストアを読み取り専用として扱うかどうかを制御します。 |
|
|
SQL ステートメントのタイムアウトを 0 ～ 172800 秒の間で設定します。 |
|
|
ローカルタイムゾーンを設定します。 |
|
|
Databricks SQL が可能な限り結果をキャッシュして再利用するかどうか。 |
ログ記録のプロパティ
次のログ プロパティは、JDBC ドライバーによってサポートされています。 プロパティは大文字と小文字を区別しません。
属性 |
デフォルト値 |
説明 |
|---|---|---|
|
|
ロギング・レベル (0 から 6 までの値):
このプロパティを使用して、コネクタでのログ記録を有効または無効にしたり、ログ ファイルに含まれる詳細の量を指定したりします。 |
|
ログのデフォルトパスを決定するために、ドライバーはこれらのシステムプロパティに設定された値を次の優先順位で使用します。
|
ログ記録が有効になっているときにコネクタがログファイルを保存するフォルダへの絶対パス (文字列)。 接続 URL がすべての JDBC アプリケーションと互換性があることを確認するには、別のバックスラッシュを入力して、ファイルパスのバックスラッシュ (
|
|
上限なし |
許容される最大ログ・ファイル・サイズ (MB 単位) |
|
上限なし |
許可されるログ・ファイルの最大数 |
ログ記録の有効化と構成
JDBC ドライバは、 Simple Logging Facade for Java (SLF4J) および java.util.logging (JUL) フレームワークをサポートしています。 ドライバーは、デフォルトで JUL ロギングフレームワークを使用します。
JDBC ドライバーのログ記録を有効にして構成するには、次のようにします。
使用するロギングフレームワークを有効にします。
SLF4J ロギングの場合は、システムプロパティーを
-Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGERに設定し、SLF4J バインディング実装 (SLF4J バージョン 2.0.13 以上と互換性あり) と対応する構成ファイルをクラスパスに含めます。JUL ロギングの場合は、システム・プロパティーを
-Dcom.databricks.jdbc.loggerImpl=JDKLOGGERに設定します。 これがデフォルトです。
接続文字列の
LogLevelプロパティを、ログ ファイルに含める情報レベルに設定します。接続文字列の
LogPathプロパティを、ログ ファイルを保存するフォルダーへのフル パスに設定します。たとえば、次の接続 URL はロギング レベル 6 を有効にし、ログファイルを C:temp フォルダに保存します。
jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
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();
}
}
}