Foundry Datasets のための ODBC & JDBC ドライバー

概要

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

JDBC または ODBC ？

クライアントアプリケーションが両方のプロトコルをサポートしている場合、JDBC の使用を ODBC よりも推奨します。JDBC ドライバーはインストールや設定が簡単で、データのローディングがより高性能です。

Foundry SQL Server

ドライバーは、Foundry データセットに対する SQL クエリを処理し実行するために Foundry SQL Server に依存しています。アーキテクチャやクエリパフォーマンスの向上方法について詳しく知るために、Foundry SQL Server のアーキテクチャ の文書を参照してください。

システム要件

ODBC

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 クエリをテストします：

-- データセットから最初の10件のデータを選択する
SELECT * FROM "/Path/To/Dataset" LIMIT 10

クライアントアプリケーションでは、プロジェクトを閲覧し、データにアクセスするためのデータセットを選択できるかもしれません。

JDBC

パート 1: JDBC ドライバーのインストール

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

パート 2: JDBC 接続文字列の作成

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

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

上記のコードは、Foundryデータベースに接続するためのJDBC (Java Database Connectivity) 接続文字列です。

• <FOUNDRY_HOSTNAME> はデータベースのホスト名を指定します。ここには、データベースがホストされているサーバーのホスト名を入力します。
• <TOKEN> はデータベースへの接続に必要なパスワードを指定します。この部分には、あなたが持っている特定のデータベースへのアクセス権を証明するためのトークンを入力します。

この形式の接続文字列は、Javaでデータベースに接続するための標準的な方法です。

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

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

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

（オプション）パート 3：SQLクエリの実行

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

-- 以下のクエリでは、指定されたデータセットから最初の10件のデータを取得します。
SELECT * FROM "/Path/To/Dataset" LIMIT 10

クライアントアプリケーションは、代わりにプロジェクトを閲覧し、データにアクセスするためのデータセットを選択することを可能にします。

リファレンス

設定パラメーター

利用可能な設定パラメーターはODBCとJDBCで同じです。各ドライバーは、クライアントアプリケーション内で接続文字列を使用するか、クライアントアプリケーション外で設定するかのどちらかの方法で設定できます：

パラメーター参照

型の取り扱い

次の表は、Foundryの型がODBCとJDBCの型にどのようにマッピングされるかを示しています。

SQL方言

次の表は、利用可能なSQL方言（設定パラメーターのDialectパラメーター参照）の一部のSQL構文と機能を概説しています。

使用ガイド

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

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

SPARK方言

-- 基本的な SELECT
SELECT * FROM `/Path/To/Dataset`
-- データセットから全てのデータを選択します

-- WHERE 句を使用してフィルタリング
SELECT * FROM `/Path/To/Dataset`
WHERE years < 13 AND category = 'Z';
-- yearsが13未満で、カテゴリが'Z'のデータを選択します

-- JOIN の使用
SELECT * 
FROM `/Path/To/Dataset_A` a
JOIN `/Path/To/Dataset_B` b
    ON a.id = b.fk_id;
-- データセットAとBを結合し、それぞれのidと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ベースのオプションをトークン生成よりも優先して使用することをお勧めします。これらのオプションは、より安全であり、埋め込まれた接続文字列の共有使用を個々のユーザーのトークンを共有することなく可能にします。

個々のユーザー（ODBCはWindowsのみ）

ODBCドライバーは、Windowsで実行されている場合、自動OAuthログインおよび承認フローをサポートしています。以下の手順に従って、このフローを設定してください。

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>
3. （オプション）Windows ODBC Administratorアプリでこれらの設定を構成している場合は、テストオプションを選択してログインプロンプトをトリガーし、ログインが正常に機能していることを確認できます。

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

サービスユーザー

個々のユーザーに関連付けられていないワークフロー（ダッシュボードのデータをスケジュールに従って更新するなど）については、OAuth Client Credentials付与タイプを持つサードパーティアプリケーションを利用した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>

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

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

アプリケーション開発者は、ODBCおよびJDBCドライバーを、自分のOAuthクライアントを実行してサードパーティアプリケーションとのOAuthログインフローを管理するアプリケーションに統合できます。このオプションにより、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. 設定ウィンドウでLogging Optionsを選択します。
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: "org.slf4j.impl.StaticLoggerBinder" クラスのロードに失敗しました。
SLF4J: Defaulting to no-operation (NOP) logger implementation // SLF4J: 操作なし（NOP）ロガー実装にデフォルト設定されます。
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details. // SLF4J: 詳細は http://www.slf4j.org/codes.html#StaticLoggerBinder を参照してください。
SLF4J: Failed to load class "org.slf4j.impl.StaticMDCBinder". // SLF4J: "org.slf4j.impl.StaticMDCBinder" クラスのロードに失敗しました。
SLF4J: Defaulting to no-operation MDCAdapter implementation. // SLF4J: 操作なし MDCAdapter 実装にデフォルト設定されます。
SLF4J: See http://www.slf4j.org/codes.html#no_static_mdc_binder for further details. // SLF4J: 詳細は http://www.slf4j.org/codes.html#no_static_mdc_binder を参照してください。

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 バージョン 15 をサポートしています。Java バージョン 16 以降でドライバを使用するには、アプリケーション内の --add-opens Java ランタイムオプションを java.base/java.nio=ALL-UNNAMED に設定してください。

例：Java コマンド

Copied!
1
2
3
4
5
// java --add-opens=オプションはJavaモジュールの特定のパッケージを開くために使用されます。
// java.base/java.nioはJavaの基本モジュールで、java.nioパッケージを開きます。
// ALL-UNNAMEDは開いたパッケージをすべての無名モジュールに利用可能にします。
// -jarオプションはjarファイルを実行します。ここではyour_application.jarというjarファイルを実行しています。
java --add-opens=java.base/java.nio=ALL-UNNAMED -jar your_application.jar

例：環境変数

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

# Javaの環境変数を設定します。このコマンドはjava.baseパッケージ内のjava.nioパッケージを無名モジュールに開放します。
export _JAVA_OPTIONS="--add-opens=java.base/java.nio=ALL-UNNAMED"