次の方法で共有

サポートされている接続プロパティ

この記事では、 Databricks JDBC Driver バージョン 3 以降でサポートされる接続プロパティについて説明します。

認証とプロキシのプロパティ

Databricks JDBC Driver では、次の認証プロパティとプロキシ プロパティがサポートされています。 プロパティの大文字と小文字は区別されません。

プロパティ 既定値 説明
AsyncExecPollInterval 200 非同期クエリ実行ステータスを確認するポーリング間隔の時間 (ミリ秒単位)。 ここでいう非同期は、Spark に対するクエリ実行のための RPC 呼び出しが非同期に処理されるという事実を指します。 JDBC 非同期操作のサポートを意味するものではありません。
Auth_Flow 0 ドライバー接続の OAuth2 認証フロー。 このプロパティは、AuthMech が 11 である場合に必須です。
Auth_JWT_Alg RS256 秘密キー JWT 認証のアルゴリズム。 サポートされるアルゴリズムは、RSA: RS256、RS384、RS512、PS256、PS384、PS512、EC: ES256、ES384、ES512 です。
Auth_JWT_Key_File null JWT 認証用の秘密キー ファイル (PEM 形式) へのパス。
Auth_JWT_Key_Passphrase null 暗号化された秘密キーを復号化するためのパスフレーズ。
Auth_KID null JWT 認証に必要なキー識別子 (KID)。 これは、秘密キー JWT を使用する場合に必須です。
Auth_RefreshToken null 新しいアクセス トークンの取得に使用される OAuth2 更新トークン。
Auth_Scope all-apis OAuth2 フローの認証スコープ。
AuthMech 必須 認証メカニズム。3 はメカニズムが Azure Databricks 個人用アクセス トークンであること、11 はメカニズムが OAuth 2.0 トークンであることを示します。 いずれのメカニズムにも、追加のプロパティが必要です。 「ドライバーの認証」を参照してください。
AzureTenantId null Azure 固有の認証用の Azure テナント ID。
CFProxyAuth 0 1 に設定した場合、ドライバーは、CFProxyUID と CFProxyPwd で表されたプロキシ認証ユーザーとパスワードを使用します。
CFProxyHost null UseCFProxy も 1 に設定されている場合に使用する、プロキシ ホストの名前を表す文字列。
CFProxyPort null UseCFProxy も 1 に設定されている場合に使用する、プロキシ ポートの番号を表す整数。
CFProxyPwd null CFProxyAuth と UseCFProxy も 1 に設定されている場合に使用する、プロキシ認証用のパスワードを表す文字列。
CFProxyUID null CFProxyAuth と UseCFProxy も 1 に設定されている場合に使用する、プロキシ認証用のユーザー名を表す文字列。
ConnCatalog または catalog SPARK 使う既定のカタログの名前。
ConnSchema または schema default 使う既定のスキーマの名前。 これを指定するには、使用するスキーマの名前で URL 内の <schema> を置き換えるか、ConnSchema プロパティに使用するスキーマの名前を設定します。
EnableOIDCDiscovery 1 1に設定すると、OpenID Connect 検出 URL が使用されます。
EnableTokenCache 1 1に設定すると、OAuth トークンのキャッシュが有効になり、パフォーマンスが向上します。
GoogleCredentialsFile null Google サービス アカウント認証用の JSON キー ファイルへのパス。
GoogleServiceAccount null Google サービス アカウントを使用した認証を有効にします。
OAuth2ClientId null 認証用の OAuth2 クライアント ID。 既定では、 databricks-sql-jdbc は AWS、GCP、Azure に使用されます。 高度な OAuth 構成には、カスタム クライアント ID が必要です。
OAuth2ConnAuthAuthorizeEndpoint null OAuth2 フローで使用される承認エンドポイント URL。
OAuth2ConnAuthTokenEndpoint null OAuth2 フローのトークン エンドポイント URL。
OAuth2RedirectUrlPort 8020 ブラウザー ベースの認証フローの OAuth2 リダイレクト URL ポート。
OIDCDiscoveryEndpoint null OIDC 構成を取得するための OpenID Connect 検出 URL。
ProxyAuth 0 1 に設定した場合、ドライバーは、ProxyUID と ProxyPwd で表されたプロキシ認証ユーザーとパスワードを使用します。
ProxyHost null UseProxy も 1 に設定されている場合に使用する、プロキシ ホストの名前を表す文字列。
ProxyPort null UseProxy も 1 に設定されている場合に使用する、プロキシ ポートの番号を表す整数。
ProxyPwd null ProxyAuth と UseProxy も 1 に設定されている場合に使用する、プロキシ認証用のパスワードを表す文字列。
ProxyUID null ProxyAuth と UseProxy も 1 に設定されている場合に使用する、プロキシ認証用のユーザー名を表す文字列。
TokenCachePassPhrase null OAuth U2M トークン キャッシュ暗号化に使用するパスフレーズ。
UseCFProxy 0 1 に設定した場合、ドライバーは、クラウド フェッチ プロキシ設定が提供されていればそれを使用し、そうでない場合は通常のプロキシを使用します。
UseJWTAssertion false クライアント シークレット認証が制限されている M2M ユース ケースに対して秘密キー JWT 認証を有効にします。
UseProxy 0 1 に設定した場合、ドライバーは、指定されたプロキシ設定を使用します (例: ProxyAuth、ProxyHost、ProxyPort、ProxyPwd、ProxyUID)。
UseSystemProxy 0 1 に設定した場合、ドライバーは、システム レベルで設定されたプロキシ設定を使用します。 接続 URL 内に追加のプロキシ プロパティが設定されている場合、それらの追加のプロキシ プロパティは、システム レベルで設定されたプロキシ プロパティよりも優先されます。

SSL 信頼ストアの構成プロパティ

Databricks JDBC Driver では、次の SSL 信頼ストア構成プロパティがサポートされています。 プロパティの大文字と小文字は区別されません。

プロパティ 既定値 説明
AcceptUndeterminedRevocation 0 1に設定されている場合は、証明書失効チェックが有効になっているときに、未確定の失効状態の証明書を受け入れます。
AllowSelfSignedCerts 0 1に設定すると、ドライバーは自己署名 SSL 証明書を持つサーバーへの接続を許可します。
CheckCertificateRevocation 0 1に設定すると、ドライバーは SSL 証明書が失効しているかどうかを確認します。
SSL 1 コネクタが Spark サーバーとの通信を SSL 対応ソケット経由で行うかどうか。
SSLKeyStore null クライアント証明書認証用の SSL キー ストア ファイルへのパス。 既定では、サーバーのみの TLS 認証が実行されるため、クライアント証明書は必要ありません。
SSLKeyStorePwd null SSL キー ストア ファイルのパスワード。
SSLKeyStoreType JKS SSL キー ストアの種類。 有効な値は、 JKS、 PKCS12、 JCEKS、 DKS 、および PKCS11です。
SSLTrustStore null SSL 証明書検証用の信頼ストア ファイルへのパス。
SSLTrustStorePassword null 信頼ストア ファイルのパスワード (パスワードで保護されている場合)。
SSLTrustStoreType JKS 信頼ストアの種類 (JKS や PKCS12 など)。 指定しない場合、ドライバーは既定で JKS 信頼ストアに設定されます。 有効な型は、 JKS、 PKCS12、および BCFKSです。
UseSystemTrustStore 0 1に設定すると、ドライバーはシステムの既定の信頼ストアを使用して SSL 証明書の検証を行います。

信頼ストアの種類

JDBC ドライバーでは、次の SSL モードと信頼ストアの種類がサポートされています。

自己署名証明書モード

自己署名証明書モードを使用するには、接続プロパティを AllowSelfSignedCerts=1設定します。 このモードでは、任意の証明書を受け入れる信頼できるソケット ファクトリが使用されます。

カスタム信頼ストア

カスタム信頼ストアを使用するには、 SSLTrustStore 接続プロパティでカスタム信頼ストア ファイルを指定します。 この信頼ストアは、指定されたパスから直接読み込まれ、SSL 証明書の検証に証明書を使用します。 JKS、PKCS12、またはその他のサポートされている形式にすることができます。

次の追加の接続プロパティを指定する必要があります。

  • SSLTrustStore: トラスト ストア ファイルへのパス
  • SSLTrustStorePassword: 信頼ストアのパスワード (必要な場合)
  • SSLTrustStoreType: トラスト ストアの種類 (省略可能、指定されていない場合は既定で JKS)

Java システム プロパティ信頼ストア

システム プロパティ信頼ストアを使用するには、 UseSystemTrustStore=1 設定し、カスタム信頼ストアを指定していないことを確認します。 代わりに、Java システム プロパティ javax.net.ssl.trustStoreを使用して信頼ストアを指定します。 このプロパティは、 -D フラグを使用して JVM レベルで設定されます。次に例を示します。

java -Djavax.net.ssl.trustStore=/path/to/truststore.jks -Djavax.net.ssl.trustStorePassword=changeit ...

JDBC ドライバーは、最初に Java システム プロパティの javax.net.ssl.trustStoreを確認します。 設定されている場合は、JDK の既定値ではなく、この信頼ストア ファイルが使用されます。 システム プロパティが設定されていない場合は、JDK の既定の信頼ストア (cacerts) を使用します。このストアは、 $JAVA_HOME/lib/security/cacerts または同様のパスで処理されます。

JDK の既定の信頼ストア (cacerts)

JDK には、既知の証明機関からの証明書を含む cacerts と呼ばれる組み込みの信頼ストアが付属しています。これにより、それらの CA によって発行された証明書の検証が可能になります。 通常、この信頼ストアは $JAVA_HOME/lib/security/cacerts にあり、デフォルトのパスワード「changeit」または「changeme」を使用します。

JDK の既定の信頼ストアを使用するには、 UseSystemTrustStore=1 を設定し、カスタム信頼ストアまたは Java システム プロパティ信頼ストアを指定していないことを確認します。 信頼ストアが Java システム プロパティ javax.net.ssl.trustStoreを使用して指定されている場合は無視されます。これにより、ドライバーは既定の JDK 信頼ストアからの証明書のみを使用します。

信頼ストアの優先順位

ドライバーは、次の優先順位を使用して、使用する信頼ストアを決定します。

  1. SSLTrustStore接続プロパティで指定されたカスタム信頼ストア
  2. Java システム プロパティ javax.net.ssl.trustStore で指定された信頼ストア ( UseSystemTrustStore=1時)
  3. JDK の既定の信頼ストア (cacerts)

セキュリティに関する推奨事項

接続をセキュリティで保護するために、Databricks では次のことをお勧めします。

  • 運用環境の場合:

    • 自己署名証明書モード (AllowSelfSignedCerts=1) は使用しないでください。
    • 正式な CA 署名付き証明書を使用します。
    • カスタム信頼ストアが必要な場合を除き、 UseSystemTrustStore=1 を使用します。

  • カスタム信頼ストアの場合:

    • 既定の信頼ストアにない証明書を使用してサーバーに接続する場合に使用します。
    • 信頼ストアに完全な証明書チェーンが含まれていることを確認します。
    • 信頼ストア ファイルを適切なアクセス許可で保護します。

再試行戦略のプロパティ

Databricks JDBC Driver (OSS) では、次の再試行戦略プロパティがサポートされています。 プロパティの大文字と小文字は区別されません。

プロパティ 既定値 説明
RateLimitRetry 1 1に設定されている場合は、レート制限エラーの再試行を有効にします。
RateLimitRetryTimeout 120 レート制限の再試行タイムアウト (秒単位)。
TemporarilyUnavailableRetry 1 1に設定されている場合は、一時的に使用できないエラーの再試行を有効にします。
TemporarilyUnavailableRetryTimeout 900 一時的に使用できないエラーの再試行タイムアウト (秒単位)。
VolumeOperationRetryableHttpCode 408,429,500,502,503,504 Unity カタログ ボリューム インジェストの再試行可能な HTTP コードのコンマ区切りの一覧。
VolumeOperationRetryTimeout 15 Unity カタログ ボリューム インジェスト HTTP 要求の再試行タイムアウト (分単位)。

パフォーマンスと接続管理のプロパティ

Databricks JDBC Driver (OSS) では、次のパフォーマンスと接続管理のプロパティがサポートされています。 プロパティの大文字と小文字は区別されません。

プロパティ 既定値 説明
CloudFetchThreadPoolSize 16 クラウド フェッチ操作のスレッド プール サイズ。
DefaultStringColumnLength 255 メタデータ レポートの STRING 列に含めることができる最大文字数。
HttpConnectionPoolSize 100 HTTP 接続プールの最大サイズ。
IdleHttpConnectionExpiry 60 アイドル状態の HTTP 接続の有効期限 (秒単位)。
RowsFetchedPerBlock 2000000 クエリが一度に返す行の最大数。 これはインライン結果にのみ適用されます。
SocketTimeout 900 ネットワーク操作のソケット タイムアウト (秒単位)。

SQL 構成プロパティ

Databricks JDBC Driver では、次の SQL 構成プロパティがサポートされています。 これらは 、「構成パラメーター」でも説明されています。 プロパティの大文字と小文字は区別されません。

プロパティ 既定値 説明
ansi_mode TRUE 特定の関数とキャスト ルールに関して、厳密な ANSI SQL 動作を有効にするかどうか。
enable_photon TRUE Photon ベクター化クエリ エンジンを有効にするかどうか。
legacy_time_parser_policy EXCEPTION 日付とタイムスタンプの解析と書式設定に使用するメソッド。 有効な値は、EXCEPTION、LEGACY、および CORRECTEDです。
max_file_partition_bytes 128m ファイル ベースのソースからの読み取り時に 1 つのパーティションに取り込める最大バイト数です。 この設定には任意の正の整数を使用でき、オプションとして、単位 b (バイト)、k または kb (1024 バイト) などを付けることもできます。
query_tags "" (空の文字列) system.query.historyでの追跡と分析のために SQL クエリにアタッチするキー値タグのコンマ区切りの一覧。
read_only_external_metastore false 外部メタストアを読み取り専用として扱うかどうかを制御します。
statement_timeout 172800 SQL ステートメントのタイムアウトを 0 から 172,800 秒までの範囲で設定します。
timezone UTC ローカル タイムゾーンを設定します。 area/city 形式 (America/Los_Angeles など) のリージョン ID、または (+|-)HH、(+|-)HH:mm または (+|-)HH:mm:ss 形式 (例: -08、+01:00、-13:33:33) のゾーン オフセット。 また、UTC は、+00:00 の別名としてサポートされています。
use_cached_result true 可能な限り Databricks SQL が結果をキャッシュして再利用するかどうか。

ログのプロパティ

Databricks JDBC Driver では、次のログ記録プロパティがサポートされています。 プロパティの大文字と小文字は区別されません。

プロパティ 既定値 説明
LogFileCount 10 許可されるログ ファイルの最大数
LogFileSize 10 許可されるログ ファイルの最大サイズ (MB 単位)
LogLevel OFF ログ レベル (0 から 6 までの値):
  • 0: すべてのログ記録を無効にします。
  • 1: 致命的なレベルでログ記録を有効にします。これは、コネクタを中止する非常に重大なエラー イベントをログに記録します。
  • 2: ERROR レベルでログ記録を有効にします。これにより、コネクタの実行を続行できる可能性があるエラー イベントがログに記録されます。
  • 3: 警告レベルでログ記録を有効にします。このレベルでは、アクションが実行されなかった場合にエラーが発生する可能性のあるイベントをログに記録します。
  • 4: INFO レベルでログ記録を有効にします。このレベルでは、コネクタの進行状況を説明する一般的な情報がログに記録されます。
  • 5: DEBUG レベルでログ記録を有効にします。これは、コネクタのデバッグに役立つ詳細情報をログに記録します。
  • 6: すべてのコネクタ アクティビティをログに記録する TRACE レベルでログ記録を有効にします。

このプロパティでは、コネクタでのログ記録を有効または無効に設定することや、ログ ファイルに含める詳細情報の量を指定することができます。
LogPath ログの既定のパスを決定するために、ドライバーは、次の優先順位で、これらのシステム プロパティに設定された値を使用します。
  • user.dir
  • java.io.tmpdir
  • つまり、現在のディレクトリ .
 ログ記録を有効にした場合にコネクタのログ ファイルを保存するフォルダの絶対パス (文字列)。 接続 URL がすべての JDBC アプリケーションと互換性があることを確認するには、別の円記号を入力して、ファイル パス内の円記号 (\) をエスケープします。
LogPath値が無効な場合、コネクタはログに記録された情報を標準出力ストリーム (System.out) に送信します。

ログ記録を有効にして構成する

JDBC ドライバーは、Java (SLF4J) および java.util.logging (JUL) フレームワーク用の Simple Logging Facade をサポートしています。 ドライバーは、既定で 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 アプリケーションを再起動し、サーバーに再接続して設定を適用します。

その他の機能プロパティ

次のプロパティを使用すると、 Databricks JDBC Driver の機能が有効になります。 プロパティの大文字と小文字は区別されません。

プロパティ 既定値 説明
EnableArrow 1 0に設定すると、結果の方向のシリアル化が無効になります。また、Cloud Fetch には方向の形式が必要であるため、Cloud Fetch の動作も無効になります。
EnableComplexDatatypeSupport 0 1に設定すると、文字列ではなくネイティブ Java オブジェクトとしての複合データ型 (ARRAY、STRUCT、MAP) のサポートが有効になります。
EnableDirectResults 1 1に設定すると、クエリのパフォーマンスを向上させるために直接結果が有効になります。
EnableGeoSpatialSupport 0 1に設定すると、地理空間データ型 (GEOMETRY および GEOGRAPHY) が構造化 Java オブジェクトとしてサポートされます。 EnableComplexDatatypeSupport=1とEnableArrow=1が必要です (矢印は既定で有効になっています)。 無効にすると、地理空間列は EWKT 形式の STRING として返されます。 ST 地理空間関数を参照してください。
EnableSqlScripting 1 または true 複合ステートメント ブロック (BEGIN...END) およびストアド プロシージャの呼び出しに対するSQLスクリプトのサポートを有効にします。 Databricks Runtime 16.3 以降でドライバー バージョン 1.0.10 以降で使用できます。
ストアド プロシージャには、Databricks Runtime 17.0 以降とドライバー バージョン 3.0.1 以降が必要です。 プロシージャを呼び出すには、 Statement または PreparedStatement を使用します。 CallableStatementはサポートされていません。 構文と例については、 SQL スクリプトを参照してください。
EnableMetricViewMetadata 0 1に設定すると、メトリック ビューの拡張メタデータ操作が有効になります。 Databricks JDBC ドライバーを使用したメトリック ビューメタデータの操作を参照してください。
EnableTelemetry 0 1に設定すると、テレメトリが有効になります。 テレメトリ を参照してください。
EnableVolumeOperations 1又は true ストリームでボリューム操作を有効にするクライアント情報プロパティ。 Databricks JDBC ドライバーを使用したボリューム内のファイルの管理を参照してください。 既定では、このプロパティはボリュームに対する REMOVE 操作も有効にします。
大事な： これをクライアント情報プロパティとして設定する必要があります。 接続 URL でのみ指定しても、ストリームのボリューム操作は有効になりません。
MaxBatchSize 500 バッチ操作とデータ処理の最大バッチ サイズ。
QueryResultCompressionType 1 有効な値は 0 (圧縮なし)、1 (LZ4 圧縮の場合) です。 ドライバーは、設定構成を無視して、インライン結果を自動的に 0 (圧縮なし) にオーバーライドします。
UserAgentEntry browser HTTP 要求に含められる User-Agent エントリ。 この値の形式は次のとおりです: [ProductName]/[ProductVersion] [Comment]
UseThriftClient 1 JDBC ドライバーで Thrift クライアント API と ステートメント実行 API のどちらを使用するか。
VolumeOperationAllowedLocalPaths `` Unity カタログ ボリューム インジェスト ファイルのダウンロードとアップロードに使用できるローカル パスのコンマ区切りの一覧。 パスには、サブディレクトリも含まれます。 指定しない場合、これは StagingAllowedLocalPathsの値にフォールバックし、制限を指定しない空の文字列にフォールバックします。 ボリュームを使用したファイルの管理を参照してください。
大事な： セットアップがマルチテナント環境 (BI ツールや開発者サービスなど) にあり、ユーザーが完全な JDBC URL を制御する場合、サービスはこのプロパティをサンドボックスの場所または存在しないパスに設定する必要があります。 これにより、ユーザーがアービトリティ ファイルを書き込み、サービスの内部展開を妨げることができなくなります。

テレメトリの収集

テレメトリを使用すると、Databricks は次の情報を収集してデバッグを効率化し、タイムリーなトラブルシューティングを提供できます。

  • クライアント環境の詳細 (ドライバーのバージョン、ランタイム、OS の詳細)
  • JDBC 接続構成 (PII データを除外)
  • 操作の待機時間の測定
  • 実行結果の形式 (インライン JSON、矢印など)
  • 操作の種類 (実行クエリ、メタデータ クエリ、ボリューム操作)
  • エラー分類データ
  • 再試行回数

注

Databricks は厳格なプライバシー基準を維持し、クエリの内容、結果、個人を特定できる情報 (PII) の収集を確実に行いません。

  • Last updated on