Foundry データセット用 ODBC および JDBC ドライバー

Foundry データセット用の ODBC および JDBC ドライバーは、クライアントアプリケーション（BI ツールや ETL ツールなど）からデータセットにアクセスするための、読み取り専用の SQL ベースのインターフェースを提供します。ユーザーは Foundry 内のプロジェクトやデータセットを探索し、SQL クエリを実行して表形式のデータにアクセスできます。ドライバーはサーバー側で Foundry SQL Server を利用して、SQL クエリを処理および実行します。

JDBC と ODBC のどちらを使うべきですか？

クライアントアプリケーションが両方のプロトコルをサポートしている場合は、ODBC よりも JDBC の使用を推奨します。JDBC ドライバーはインストールと設定が容易で、データの読み込みのパフォーマンスも優れています。

Foundry SQL Server

ドライバーは Foundry SQL Server を使用して、Foundry データセットに対する SQL クエリを処理および実行します。アーキテクチャやクエリのパフォーマンスを改善する方法について、詳しくは Foundry SQL Server のアーキテクチャのドキュメントを参照してください。

システム要件

ODBC

JDBC

Java 16以降は、追加の設定を行うことでサポートされます。詳細については、Java 16以降で JDBC ドライバーを使用するを参照してください。

セットアップガイド

ODBC

パート1. ODBC ドライバーをインストールする

ダウンロード：ODBC ドライバーの手順に従って、ODBC ドライバーのインストーラーを実行します。

パート2. データソース名（DSN）の設定を行う

クライアントアプリケーション内でドライバーを使用するには、まず Foundry 環境のデータソース名（DSN）の設定を行います。

1. 開始メニューで ODBC を検索し、ODBC データソースツールを開きます。64ビットバージョンを選択します。
2. ユーザー DSN タブまたはシステム DSN タブで、追加… をクリックします。
3. ドライバーの一覧から FoundrySqlDriver を選択します。
4. 次の必須パラメーターを入力します。
   1. データソース名： マシン上のデータソースの名前です。
   2. サーバー： Foundry 環境の URL です。例：https://<SUBDOMAIN>.palantirfoundry.com。
   3. トークン： Foundry 内の設定ページで生成されるセキュリティトークンです。トークンの取得手順については、ユーザー生成トークンのドキュメントを参照してください。その他の認証オプションについては、OAuth を使用して認証するガイドを参照してください。
5. テスト… をクリックして接続が成功することを確認し、OK をクリックして DSN の設定を保存します。

追加の設定パラメーターと接続 URL を作成する手順については、設定パラメーターを参照してください。

パート3. クライアントアプリケーション内で DSN を設定する

DSN を作成したので、ODBC ソースをサポートするクライアントアプリケーションから参照できます。ODBC ソースに関するクライアントアプリケーションのドキュメントを参照してください。以下は、Foundry とともによく使用されるアプリケーションのセットアップガイドです。

• Excel
• Power BI
• Microsoft Report Builder

（任意）パート4：SQL クエリを実行する

クライアントアプリケーションがサポートしている場合は、Foundry データセットから行を返す SQL クエリをテストします。

Copied!
1
SELECT * FROM "/Path/To/Dataset" LIMIT 10

クライアントアプリケーションによっては、代わりにプロジェクトの一覧を見てデータセットを選択し、データにアクセスできる場合があります。

JDBC

パート1：JDBC ドライバーをインストールする

ダウンロード：JDBC ドライバーページから JDBC ドライバー（.jar ファイル）をダウンロードします。ダウンロードしたら、クライアントアプリケーションの JDBC 接続設定に関するドキュメントで指定されている適切な場所にファイルを配置します。

パート2：JDBC 接続文字列を作成する

JDBC 接続文字列の形式は次のとおりです。

jdbc:foundrysql://<FOUNDRY_HOSTNAME>?Password=<TOKEN>

• FOUNDRY_HOSTNAME は Foundry 環境のホスト名です（例：subdomain.palantirfoundry.com）。
• TOKEN は Foundry 内の設定ページで生成されるセキュリティトークンです。トークンの取得手順については、ユーザー生成トークンのドキュメントを参照してください。その他の認証オプションについては、OAuth を使用して認証するガイドを参照してください。

任意のパラメーターは、接続文字列に &OptionalParam=<VALUE> を追加することで指定できます。利用可能なパラメーターの全一覧については、設定パラメーターを参照してください。

JDBC クライアントでドライバークラスを明示的に指定する必要がある場合は、com.palantir.foundry.sql.jdbc.FoundryJdbcDriver を指定します。

（任意）パート3：SQL クエリを実行する

クライアントアプリケーションがサポートしている場合は、Foundry データセットから行を返す SQL クエリをテストします。

Copied!
1
SELECT * FROM "/Path/To/Dataset" LIMIT 10

クライアントアプリケーションによっては、代わりにプロジェクトの一覧を見てデータセットを選択し、データにアクセスできる場合があります。

リファレンス

設定パラメーター

利用可能な設定パラメーターは ODBC と JDBC で共通です。各ドライバーは、クライアントアプリケーション内で接続文字列を使用する方法、またはクライアントアプリケーションの外部で設定する方法のいずれかで設定できます。

パラメーターリファレンス

データ型の扱い

次のテーブルは、Foundry のデータ型が ODBC および JDBC のデータ型にどのようにマッピングされるかを示しています。

SQL 方言

次のテーブルは、利用可能な SQL 方言の SQL 構文および機能の一部を示しています（設定パラメーターの Dialect パラメーターを参照してください）。

使用ガイド

SQL を使用して Foundry データセットをクエリする

SQL クエリでは、パスまたは RID でデータセットを参照できます。SQL 構文は、接続に設定された方言によって異なります（設定パラメーターを参照）。

SPARK 方言

-- 基本的な SELECT
SELECT * FROM `/Path/To/Dataset`

-- WHERE 句で絞り込む
SELECT * FROM `/Path/To/Dataset`
WHERE years < 13 AND category = 'Z';

-- JOIN を使用する
SELECT *
FROM `/Path/To/Dataset_A` a
JOIN `/Path/To/Dataset_B` b
    ON a.id = b.fk_id;

ODBC & ANSI 方言

-- 基本的な SELECT
SELECT * FROM "/Path/To/Dataset";

-- WHERE 句で絞り込む
SELECT * FROM "/Path/To/Dataset"
WHERE years < 13 AND category = 'Z';

-- JOIN を使用する
SELECT *
FROM "/Path/To/Dataset_A" a
JOIN "/Path/To/Dataset_B" b
    ON a.id = b.fk_id;

データセット識別子の使用方法の詳細については、ガイド：データセットの RID またはファイルパスを特定するを参照してください。

OAuth を使用して認証する

単一の Foundry アカウントに紐づく認証トークンを手動で生成する方法に加えて、ODBC および JDBC ドライバーは、追加の認証オプションとして OAuth 2.0 フローをサポートしています。

• 個人ユーザー： ドライバーがブラウザーでログインプロンプトを開き、Foundry に認証できるようにします。
• サービスユーザー：ドライバーは、Foundry に登録されたサードパーティアプリケーションにアタッチされたサービスユーザーとして Foundry に接続します。
• 外部アプリケーション（開発者向け）：サードパーティアプリケーションが Foundry の OAuth システムと連携し、ユーザーに代わってトークンを取得します。

可能な場合は、トークンの生成よりも、これらの OAuth ベースのオプションを使用することを推奨します。セキュリティが高く、個人ユーザーのトークンを共有せずに、埋め込み接続文字列を共同で使用できるためです。

個人ユーザー（Windows 上の ODBC のみ）

ODBC ドライバーは、Windows 上で実行される場合、自動の OAuth ログインおよび認可フローをサポートします。このフローは、コンピューターにインストールされたデスクトップアプリケーションでのみサポートされ、Web ブラウザーを通じてアクセスするアプリケーションではサポートされません。

このフローを設定するには、次の手順に沿って進めます。

1. （Foundry 管理者が実施） Foundry にサードパーティアプリケーションを登録し、次の設定オプションを指定します。
   1. クライアントのタイプ： ほとんどの場合、パブリッククライアントを推奨します。ユースケースで必要な場合は、機密クライアントもサポートされます。
   2. 認可グラントのタイプ： 認可コードグラントを有効にし、リダイレクト URL を http://127.0.0.1/foundrydriver/oauthredirect に設定します。
   3. アプリケーションが登録済みかつ有効であることを確認します。
   4. アプリケーションの詳細画面からアプリケーションのクライアント ID をコピーし、自分のマシンで ODBC 接続を設定するユーザーに共有します。
2. Foundry 管理者からクライアント ID を受け取ったら、次の ODBC 接続パラメーターを設定します。
   1. AuthMethod = OauthFlow
   2. OauthClientId = <YOUR_CLIENT_ID>
      または、OauthClientId の代わりにアプリケーションのユーザー名項目にクライアント ID を設定して、アプリ内で資格情報を設定できるようにすることもできます。この場合も AuthMethod の設定は必要です。
3. （任意）Windows の ODBC 管理者アプリでこれらの設定を行う場合は、テストを選択してログインプロンプトを表示し、ログインが機能することを確認できます。

次にクライアントアプリケーションでドライバーを使用すると、ブラウザーで Foundry へのログインを求められます。その後は、ドライバーを使用するたびにログインする必要はありませんが、ときどき再度ログインを求められる場合があります。

サービスユーザー

個人ユーザーに関連付けられていないワークフロー（ダッシュボードのデータをスケジュールに従って更新する場合など）には、OAuth クライアント資格情報グラントタイプを持つサードパーティアプリケーションを活用した、OAuth ベースのサービスユーザーを推奨します。ドライバーは、有効期間の長いクライアント ID とシークレットのペアを使用して Foundry に認証します。このペアは、手動で作成したサービスアカウントと生成したトークンよりも管理が容易です。

サービスユーザーの OAuth を設定するには、次の手順に沿って進めます。

1. （Foundry 管理者が実施） Foundry にサードパーティアプリケーションを登録します。
   1. クライアントのタイプ： 機密クライアントを選択します。
   2. 認可グラントのタイプ： クライアント資格情報グラントを有効にし、クライアント ID とクライアントシークレットのペアを安全な場所に必ず保管してください。
   3. アプリケーションが登録済みかつ有効であることを確認します。
   4. 生成されたサービスユーザーに、ODBC または JDBC ドライバー経由でアクセスするすべてのデータセットへのアクセス権が付与されていることを確認します。アプリケーション用に生成されたサービスユーザーは、クライアント資格情報グラントの詳細パネルに表示されます。
2. ドライバーを設定する際に、次の設定パラメーターを設定します。
   1. AuthMethod = ClientCredentials
   2. OauthClientId = <YOUR_CLIENT_ID>
   3. OauthClientSecret = <YOUR_CLIENT_SECRET>
      または、OauthClientId と OauthClientSecret の代わりにアプリケーションのユーザー名項目とパスワード項目にクライアント ID とクライアントシークレットを設定して、アプリ内で資格情報を設定できるようにすることもできます。この場合も AuthMethod の設定は必要です。

これで、ドライバーは OAuth アプリのサービスユーザーとして Foundry に接続します。

外部アプリケーション（開発者向け）

アプリケーション開発者は、独自の OAuth クライアントを実行してサードパーティアプリケーションとの OAuth ログインフローを管理するアプリケーションに、ODBC および JDBC ドライバーを統合できます。このオプションでは、Foundry での認証にユーザーをリダイレクトする処理や、ユーザーが認証と認可を完了した後の認可レスポンスの処理など、ログインフローを完全に制御できます。Foundry ユーザーに代わってアクセストークンを取得するには、Foundry 用の OAuth2 クライアントを作成するドキュメントを参照してください。

アプリケーションがユーザーに代わってアクセストークンを取得したら、標準のパスワードプロパティを通じてドライバーに渡すことができます。

• ODBC Pwd / JDBC Password = <ACCESS_TOKEN_OBTAINED_FROM_TOKEN_ENDPOINT>

ODBC ドライバーでログ記録を有効にする

問題のトラブルシューティングのためにドライバーのログ記録を有効にする必要がある場合は、次の手順に沿って進めます。管理者権限が必要になる場合があります。

1. My Documents\Foundry Driver logs など、ログを保存するフォルダーを作成します。
2. Windows の ODBC データソースツールを開きます。Windows の検索バーで「ODBC」を検索すると見つかります。64ビット版を選択します。
3. システム DSN タブを開きます。FoundrySql ソースを選択し、設定を選択します。ログ記録の設定は Foundry ドライバーを使用するすべてのデータソースに適用されるため、どの Foundry データソースを選択してもかまいません。
4. 設定ウィンドウでログ記録オプションを選択します。
5. ログレベルを DEBUG に設定します。ログのパスを、先ほど作成したフォルダーに設定します。
6. OK を選択して設定を保存します。

クライアントアプリケーションを再起動し、トラブルシューティングの対象となる操作を実行します。選択したフォルダーにログが表示されるはずです。Palantir またはほかのサポートチームのサポートが必要な場合は、このフォルダーを zip ファイルに圧縮して共有できます。

トラブルシューティングが完了したら、ODBC データソースツールに戻り、ログレベルを OFF に設定してログ記録を無効にします。パフォーマンスを向上させるため、この手順を推奨します。

JDBC ドライバーでログ記録を有効にする

JDBC ドライバーは、Java アプリケーションがクラスパス上に提供する SLF4J ロガーを検出します。具体的には、アプリケーションで org.slf4j.impl.StaticLoggerBinder クラスと org.slf4j.impl.StaticMDCBinder クラスの実装を提供する必要があります。slf4j-simple（バージョン 1.X）をプロジェクトの依存関係に追加することで、デフォルトの実装を使用できます。

SLF4J ロガーを設定していない場合、ドライバーが初めて読み込まれたときに、次のメッセージが出力されます。

SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
SLF4J: Failed to load class "org.slf4j.impl.StaticMDCBinder".
SLF4J: Defaulting to no-operation MDCAdapter implementation.
SLF4J: See http://www.slf4j.org/codes.html#no_static_mdc_binder for further details.

foundry.ini 設定ファイルを使用して JDBC ドライバーを設定する

JDBC ドライバーは、接続文字列に加えて設定ファイルでも設定できます。設定ファイルを使用するには、JDBC の .jar ファイルがあるディレクトリと同じディレクトリに foundry.ini という名前のファイルを作成します。

.ini ファイルは、low-priority と high-priority の2つのセクションに分かれています。low-priority セクションで指定したプロパティは、接続文字列のプロパティよりも優先度が低くなります。つまり、low-priority セクションと接続文字列に同じプロパティが指定されている場合、接続文字列の値が使用されます。一方、high-priority セクションで指定したプロパティは、接続プロパティよりも優先されます。これは、開発用マシンからサーバーにレポートを公開し、開発用のプロパティよりもサーバーのプロパティを優先する必要がある場合に役立ちます。

foundry.ini ファイルの例：

[high-priority]
proxyHost=myproxy.abc
proxyPort=1234

[low-priority]
branch=production-branch

Java 16 以降で JDBC ドライバーを使用する

JDBC ドライバーがデフォルトでサポートする Java バージョンは、最大で Java 15 です。Java 16 以降でドライバーを使用するには、アプリケーション内で Java ランタイムの --add-opens オプションを java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED に設定します。

例：Java コマンド

Copied!
1
java --add-opens=java.base/java.nio=org.apache.arrow.memory.core,ALL-UNNAMED -jar your_application.jar

例：環境変数

場合によっては、_JAVA_OPTIONS 環境変数でオプションを指定する方が便利です。この環境変数は、一部の Java 環境で自動的に検出され、適用されます。Unix ベースのシステムでは、export コマンドを使用して設定できます。

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