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

この記事では、 Databricks JDBC ドライバー (OSS) でサポートされている接続プロパティについて説明します。

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

次の認証プロパティとプロキシ プロパティは、 Databricks JDBC ドライバー (OSS) でサポートされています。プロパティは大文字と小文字を区別しません。

属性	デフォルト値	説明
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 はメカニズムが Databricks 個人用アクセス トークンであることを指定し、 11 はメカニズムが 2.0 トークンであること OAuth 指定します。 各メカニズムには、追加のプロパティが必要です。「ドライバーの認証」を参照してください。
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 の 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 に使用されます。カスタムクライアントIDは、高度なOAuth構成に必要です。
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 トラスト・ストア構成プロパティー

次の SSL トラスト ストア構成プロパティは、 Databricks JDBC ドライバー (OSS) でサポートされています。プロパティは大文字と小文字を区別しません。

属性	デフォルト値	説明
AcceptUndeterminedRevocation	0	1に設定すると、証明書失効チェックが有効なときに、失効ステータスが未確定の証明書を受け入れます。
AllowSelfSignedCerts	0	1に設定すると、ドライバーは自己署名 SSL 証明書を持つサーバーへの接続を許可します。
CheckCertificateRevocation	0	1に設定すると、ドライバーは SSL 証明書が失効したかどうかを確認します。
SSL	1	コネクタが SSL 対応ソケットを介して Spark サーバーと通信するかどうか。
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に設定します。このモードでは、任意の証明書を受け入れる trust-all ソケット ファクトリを使用します。

カスタムトラストストア

カスタム・トラスト・ストアを使用するには、 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のデフォルトのかわりにこのトラスト・ストア・ファイルが使用されます。システム・プロパティが設定されていない場合は、 $JAVA_HOME/lib/security/cacerts または同様のパスでocatedされているJDKのデフォルトのトラスト・ストア(cacerts)を使用します。

JDK のデフォルト・トラスト・ストア (cacerts)

JDK には、有名な認証局からの証明書を含む cacerts と呼ばれる組み込みのトラストストアが付属しており、これらの CA によって発行された証明書を検証できます。このトラストストアは通常、デフォルトのパスワード「changeit」または「changeme」で $JAVA_HOME/lib/security/cacerts にあります。

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 ドライバー (OSS) でサポートされています。プロパティは大文字と小文字を区別しません。

属性	デフォルト値	説明
RateLimitRetry	1	1に設定すると、レート制限エラーの再試行が有効になります。
RateLimitRetryTimeout	120	レート制限の再試行タイムアウト (秒単位)。
TemporarilyUnavailableRetry	1	1に設定すると、一時的に使用できないエラーの再試行が有効になります。
TemporarilyUnavailableRetryTimeout	900	一時的に使用できないエラーの再試行タイムアウト (秒単位)。
VolumeOperationRetryableHttpCode	408,429,500,502,503,504	Unity Catalog ボリューム インジェストの再試行可能な HTTP コードのコンマ区切りリスト。
VolumeOperationRetryTimeout	15	Unity Catalog ボリューム インジェスト HTTP 要求の再試行タイムアウト (分単位)。

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

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

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

SQL 構成プロパティ

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

属性	デフォルト値	説明
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 秒から 172800 秒の間で設定します。
timezone	UTC	ローカルタイムゾーンを設定します。area/city形式の地域 ID (America/Los_Angeles など)、または (+|-)HH、(+|-)HH 形式のゾーン オフセット または (+|-)HH:mm(例: -08、+01:00、-13:33:33)。また、 UTC は +00:00 のエイリアスとしてサポートされています
use_cached_result	true	Databricks SQL が可能な限り結果をキャッシュして再利用するかどうか。

ログ記録のプロパティ

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

属性	デフォルト値	説明
LogFileCount	10	許可されるログ・ファイルの最大数
LogFileSize	10	許容される最大ログ・ファイル・サイズ (MB 単位)
LogLevel	OFF	ロギング・レベル (0 から 6 までの値): 0: すべてのログ記録を無効にします。 1: FATAL レベルでログ記録を有効にすると、コネクタが中止される原因となる非常に重大なエラー イベントがログに記録されます。 2: ERROR レベルでログ記録を有効にすると、コネクタの実行を続行できる可能性のあるエラー イベントがログに記録されます。 3: WARNING レベルでログ記録を有効にし、アクションが実行されない場合にエラーになる可能性のあるイベントをログに記録します。 4: INFO レベルでログ記録を有効にし、コネクタの進行状況を説明する一般情報をログに記録します。 5: DEBUG レベルでログ記録を有効にし、コネクタのデバッグに役立つ詳細情報をログに記録します。 6: TRACE レベルでログ記録を有効にし、すべてのコネクタ アクティビティをログに記録します。 このプロパティを使用して、コネクタでのログ記録を有効または無効にしたり、ログ ファイルに含まれる詳細の量を指定したりします。
LogPath	ログのデフォルトパスを決定するために、ドライバーはこれらのシステムプロパティに設定された値を次の優先順位で使用します。 user.dir java.io.tmpdir つまり、現在のディレクトリ .	ログ記録が有効になっているときにコネクタがログファイルを保存するフォルダへの絶対パス (文字列)。接続 URL がすべての JDBC アプリケーションと互換性があることを確認するには、別のバックスラッシュを入力して、ファイルパスのバックスラッシュ (\) をエスケープします。 LogPath値が無効な場合、コネクタはログに記録された情報を標準出力ストリーム (System.out) に送信します。

ログ記録の有効化と構成

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 に保存します フォルダ：

   jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp

4. JDBC アプリケーションを再起動し、サーバーに再接続して設定を適用します。

その他の機能プロパティ

次のプロパティを使用すると、 Databricks JDBC ドライバー (OSS) の機能が有効になります。プロパティは大文字と小文字を区別しません。

属性	デフォルト値	説明
EnableArrow	1	0に設定すると、結果の矢印のシリアル化が無効になり、クラウドフェッチには矢印形式が必要なため、クラウドフェッチの動作も無効になります。
EnableComplexDatatypeSupport	0	1に設定すると、文字列の代わりにネイティブ Java オブジェクトとしての複合データ型 (ARRAY、STRUCT、MAP) のサポートが有効になります。
EnableDirectResults	1	1に設定すると、直接結果が有効になり、クエリのパフォーマンスが向上します。
EnableTelemetry	0	1に設定すると、テレメトリが有効になります。「テレメトリ」を参照してください。
EnableVolumeOperations	1または true	ストリーム上でボリューム操作を有効にするクライアント情報プロパティ。「Databricks JDBC ドライバー (OSS) を使用してボリューム内のファイルを管理する」を参照してください。デフォルトでは、このプロパティによりボリュームに対する REMOVE 操作も有効になります。 重要: これをクライアント情報プロパティとして設定する必要があります。接続 URL でのみ指定すると、ストリームのボリューム操作は有効になりません。
MaxBatchSize	500	バッチ操作とデータ処理の最大バッチ サイズ。
QueryResultCompressionType	1	有効な値は、0 (圧縮なしの場合) と 1 (LZ4 圧縮の場合) です。ドライバーは、構成された設定に関係なく、インライン結果に対して自動的に 0 (圧縮なし) にオーバーライドされます
UserAgentEntry	browser	HTTP 要求に含める User-Agent エントリ。この値は次の形式です。 [ProductName]/[ProductVersion] [Comment]
UseThriftClient	1	JDBC ドライバーが Thrift クライアントとステートメント実行APIのどちらを使用するか .
VolumeOperationAllowedLocalPaths	``	Unity Catalog ボリューム インジェスト ファイルのダウンロードとアップロードに許可されるローカル パスのコンマ区切りの一覧。パスにはサブディレクトリも含まれます。指定しない場合、これは StagingAllowedLocalPathsの値にフォールバックし、次に制限を指定しない空の文字列にフォールバックします。ボリューム を使用したファイルの管理を参照してください。 大事な： セットアップがマルチテナント環境 ( BI ツールや開発者サービスなど) にあり、ユーザーが完全な JDBC URL を制御する場合、サービスはこのプロパティをサンドボックスの場所または存在しないパスに設定する必要があります。 これにより、ユーザーが任意のファイルを書き込んだり、サービスの内部デプロイに干渉したりすることがなくなります。

テレメトリ コレクション

テレメトリーにより、Databricks は以下を収集することで、デバッグを効率化し、タイムリーなトラブルシューティングを提供できます。

• クライアント環境の詳細 (ドライバーのバージョン、ランタイム、OS の詳細)
• JDBC 接続設定 (PII データは除く)
• 操作のレイテンシ測定
• 実行結果の形式(インラインJSON、Arrowなど)
• 操作の種類 (実行クエリ、メタデータ クエリ、ボリューム操作)
• エラー分類データ
• 再試行回数

注記

Databricks は厳格なプライバシー基準を維持しており、クエリコンテンツ、結果、または個人を特定できる情報(PII)が収集されないようにしています。