Amazon
Web Services
Microsoft Azure
Google Cloud PlatformDatabricks JDBC ドライバー (OSS)
プレビュー
このドライバーはパブリック プレビュー段階にあり、まだオープンソースとして利用できません。
Databricks 、データベース管理システムにアクセスするための業界標準仕様である Database Connectivity ( JDBC ) を介して、 DataGrip 、 DBeaver 、 SQL Workbench/JなどのツールをDatabricksJavaに接続できるようにするJDBCソース ソフトウェア (OSS) JDBC ドライバーを提供します。
このドライバーは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 でサポートされています。
ドライバーをインストールする
Databricks JDBC Driver (OSS) は Maven リポジトリで公開されています。 最新バージョンは 0.9.1-oss です。
ドライバーをインストールするには、次のいずれかの操作を行います。
Maven プロジェクトの場合、プロジェクトの
pom.xmlファイルに次の依存関係を追加して、指定されたバージョンの JDBC ドライバーを自動的にダウンロードするように Maven に指示します。<dependency> <groupId>com.databricks</groupId> <artifactId>databricks-jdbc</artifactId> <version>0.9.1-oss</version> <scope>runtime</scope> </dependency>
Gradle プロジェクトの場合、プロジェクトのビルド ファイルに次の依存関係を追加して、指定されたバージョンの JDBC ドライバーを自動的にダウンロードするように Gradle に指示します。
implementation 'com.databricks:databricks-jdbc:0.9.1-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 要素またはプロパティ |
説明 |
|---|---|
|
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 クライアント資格情報 認証とも呼ばれます。 「サービスプリンシパルを使用して Databricks (OAuth M2M) で認証する」を参照してください。
OAuth M2M または OAuth 2.0 クライアント資格情報認証を構成するには:
DatabricksワークスペースにDatabricks サービスプリンシパルを作成し、そのサービスプリンシパルのOAuthシークレットを作成します。「サービスプリンシパルを使用して Databricks (OAuth M2M) で認証する」を参照してください。サービスプリンシパルの UUID または Application ID の値と、サービスプリンシパルの シークレットの SecretOAuth 値をメモします。
サービスプリンシパルにクラスターまたはウェアハウスへのアクセスを許可します。 「コンピュート権限」または「 SQLウェアハウスの管理」を参照してください。
既存の JDBC 接続 URL またはjava.util.Propertiesオブジェクトに次のプロパティを追加します。
属性 |
値 |
|---|---|
|
|
|
|
|
サービスプリンシパルのUUIDまたはアプリケーション ID の値。 |
|
サービスプリンシパルのOAuth Secret値。 |
Databricksパーソナルアクセスポイント
JDBCDatabricks個人アクセス権 を使用して ドライバー接続を認証するには、次のプロパティを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 までの値):
このプロパティを使用して、コネクタでのログ記録を有効または無効にしたり、ログ ファイルに含まれる詳細の量を指定したりします。 |
|
|
ログ記録が有効な場合にコネクタがログ ファイルを保存するフォルダーへの完全なパス (文字列)。 |
例: 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();
}
}
}