データシステムのデータを読み書きする

クエリパネルでは、データソースにクエリを実行できます。このパネルでは、クエリテンプレートの設定が、関連するイベント、スケジュール、制約から分離されています。JSON ベースのテンプレートでは、パネルが構文を検証し、デプロイ前にクエリをテストするための統合されたクエリプレビューを提供します。

データソースの種類に応じて、クエリパネルでさまざまなクエリを記述できます。以下では、さまざまな種類のクエリの記述方法に関する概要と例、各種類のクエリで Handlebars を使用する際のセキュリティ上の考慮事項、およびクエリパーシャルと条件付きクエリの概要を説明します。

データソースでクエリを絞り込む

アプリケーションに複数のデータソースがある場合は、検索入力の横にフィルターアイコンが表示されます。アイコンを選択し、チェックボックスを選択またはクリアすると、特定のデータソースのクエリが表示されます。すべてのデータソースを選択またはクリアすることもできます。データソースフィルターと検索語を組み合わせると、クエリの一覧をさらに絞り込めます。

クエリのセキュリティの概要

Foundry クエリは Foundry Synchronizer を使用し、同期されたすべてのテーブルに読み取り専用権限を適用します。また、個々のテーブルへのアクセスには、Foundry のデータセットレベルで付与されたアクセス権が適用されます。

Foundry 外部のデータソースの場合、クエリで Handlebars を使用すると、悪意のあるユーザーがテンプレートの内容を有害なコードに置き換えてインジェクション攻撃を実行できるため、セキュリティ上の懸念が生じます。そのため、これらのクエリでは Handlebars の使用に関する追加のセキュリティルールが必要です。これらのルールについては、以下の SQL クエリと HTTP JSON クエリのセクションで詳しく説明します。

また、ユーザー変数（たとえば {{user.firstName}}）を参照するテンプレートは、ログイン時にブラウザーに渡された値を受け入れるのではなく、サーバーから値を取得します。

SQL セキュリティエラーの例：

HTTP JSON セキュリティエラーの例：

API Gateway クエリ

API Gateway データソースを使用すると、Foundry API とやり取りできます。各サービスとエンドポイントのドキュメントはインラインで表示されます。完全なドキュメントは API リファレンスで確認できます。

ペイロードの種類ごとの具体例は、リクエスト入力の横にある説明文表示の切り替えで確認できます。これらのエンドポイントには、HTTP JSON データソースの種類のクエリとは異なるセキュリティ保護が適用されるため、Handlebars の入力に jsonStringify を適用する必要はありません。

利用可能なエンドポイントを見つける

呼び出せるエンドポイントは、データソースで有効になっている Foundry API の一部であるため、クエリエディターには利用可能なサービスとエンドポイントのみが表示されます。呼び出すエンドポイントを見つけるには、次の手順を実行します。

1. クエリパネルで新しいクエリを作成し、ソースドロップダウンから種類が API Gateway のデータソースを選択します。
2. サービスを選択します。各サービスは、関連するエンドポイントをグループ化したものです。
3. メソッドを選択して、そのサービス内のエンドポイントを選択します。
4. 説明文表示を選択すると、選択したサービス、エンドポイント、またはパラメーターのインラインドキュメントが展開されます。説明はデフォルトでは折りたたまれています。エンドポイントの説明には HTTP メソッドとパスが記載され、エンドポイントが非推奨の場合は警告が表示されます。

想定しているエンドポイントが一覧にない場合、そのデータソースで有効になっていないか、お使いのエンロールメントで利用できません。利用をご希望の場合は、Palantir 担当者にお問い合わせください。エンドポイントの完全な一覧については、API リファレンスを参照してください。

失敗したクエリの解決方法については、API Gateway クエリのトラブルシューティングを参照してください。

よく使用されるデータエンドポイント

API Gateway データソースは、データセットの最終更新日時やヘルスチェックに合格しているかどうかなど、Foundry リソースに関する運用メタデータを取得するためによく使用されます。以下のエンドポイントは、最も一般的なケースに対応しています。エンドポイントを選択すると、リクエストとレスポンスの完全なドキュメントを表示できます。

リクエストを設定する

Slate はクエリエディターでの選択内容からリクエストを構成するため、HTTP リクエストを手動で組み立てる必要はありません。サービスとエンドポイントを選択すると、エディターには、パスパラメーター、クエリパラメーター、ヘッダー、リクエスト本文を含め、エンドポイントが受け取るパラメーターごとに1個の入力欄が表示されます。パラメーターの横にある説明文表示を選択すると、期待されるデータ型を表示できます。

各パラメーター入力には、固定値、またはウィジェット、変数、関数への Handlebars 参照を指定できます。API Gateway クエリには HTTP JSON クエリとは異なるセキュリティ保護が適用されるため、セキュリティヘルパーを使用せずに値を直接参照できます。リクエスト本文では、プレーンテキストと JSON の切り替えを使用して、Slate が値を文字列として送信するか、JSON オブジェクトとして送信するかを制御します。

選択内容から生成されるリクエストを確認するには、クエリパネルでレンダリングされたクエリのプレビューを選択します。Slate は、Handlebars の参照を現在の値に解決した読み取り専用のリクエストを表示します。エディターに戻るには、クエリ Template を表示を選択します。

Foundry クエリ

Slate で Foundry のデータをクエリするには、オントロジーの使用を推奨します。Slate では、オントロジー SDK、オブジェクトセットパネル、またはオブジェクトコンテキストパネルを使用してオントロジーオブジェクトを利用できます。または、API ゲートウェイクエリを使用できます。

Slate でデータをクエリするレガシー方式では、SQL クエリを使用して、Foundry の Postgres インスタンスに同期されたデータセットからデータを取得します。この方式は、エンロールメントでデータセットの同期が有効になっている場合にのみ利用可能です。この機能は引き続きサポートされていますが、開発は行われなくなりました。新しい機能を利用し、今後もサポートを受けられるように、オントロジーを使用してデータをクエリすることを推奨します。

SQL セキュリティヘルパーを使用する必要はありません。

データセットの同期を作成するには、次の手順を実行します。

1. データセットの同期パネルでデータセットを追加し、Postgres に同期セクションに移動します。
2. テーブル名を入力します。
3. 適用して同期を選択します。

同期が完了すると、データセットの同期タブの Postgres に同期セクションに、クエリタブに貼り付けられるサンプル SQL クエリが表示されます。

SQL クエリ

セキュリティに関する考慮事項

SQL クエリ内のすべての Handlebars テンプレート（Foundry データソースを使用するものを除く）は、SQL セキュリティヘルパーまたは Handlebars 組み込みヘルパー ↗で囲む必要があります。各 SQL セキュリティヘルパーの使用方法と使用すべき状況の詳細については、SQL ヘルパーを参照してください。

ヘルパーは、schema、table、column、alias、param の5個です。

• schema、table: schema ヘルパーと table ヘルパーは、ほぼ同じように動作します。名前と許可された名前のリストを指定すると、名前が許可された名前のリストと、対応する情報スキーマテーブルに存在することをヘルパーが確認します。たとえば、table ヘルパーは、テーブル名が許可された名前のリストと、information_schema.tables またはデータベース内の対応するスキーマテーブルに存在するかどうかを確認します。許可された名前のリストを指定することで、アクセスすべきでないスキーマやテーブルにクエリがアクセスするのを防ぎます。許可された名前をテンプレート化することはできません。テンプレート化すると、検証の意味がなくなるためです。

Copied!
1
SELECT column1 FROM {{schema someSchemaName 'allowedSchemaName1' 'allowedSchemaName2'}}.{{table someTableName 'allowedTableName1'}};

• column: column ヘルパーは、名前が information_schema.columns またはデータベース内の対応するスキーマテーブルに存在することを確認します。

Copied!
1
SELECT {{column someColumnName}} FROM table1;

• alias: alias ヘルパーは、エイリアスを付けたスキーマ、テーブル、または列の名前をテンプレート化するときに使用します。エイリアス名は情報スキーマに存在しないため、alias ヘルパーを使用して Slate に登録する必要があります。登録しないと、その名前を検証できません。alias ヘルパーは定数文字列でのみ使用でき、参照では使用できません。つまり、{{alias 'someConstantString'}} は許可されますが、{{alias someReference}} は許可されません。テンプレート化すると、schema、table、column での検証の意味がなくなります。これらが同じものを参照する可能性があるためです。

Copied!
1
2
3
4
5
6
SELECT
column1 as {{alias 'aliasedColumnName'}}
FROM table1
ORDER BY {{column someColumnName}}

where someColumnName is 'aliasedColumnName' and 'aliasedColumnName' is not a valid column name in the database's schema.

• param: param ヘルパーは、テンプレートを「?」に置き換え、後から preparedStatement を使用して値を設定できるようにします。PreparedStatement は、SQL インジェクションを防ぐ最も安全な方法の1つです。フロントエンドから渡されるすべての値は数値または文字列であるため、クエリで数値または文字列以外のデータ型の値を使用するには、そのデータ型に値をキャストする必要があることに注意してください。

Copied!
1
SELECT column1 FROM table1 WHERE column1 > {{param value1}} and dateColumn1 < {{param value2}}::date

どのような場合にどのヘルパーを使用すべきですか？

• スキーマ、テーブル、列の名前をテンプレート化する場合は、対応する schema、table、column ヘルパーのいずれかを使用します。
• エイリアスを付けたテーブルや列をテンプレート化する場合は、alias ヘルパーでエイリアスを登録します。
• パラメーター値、つまり where 句の比較に使用する値をテンプレート化する場合は、param ヘルパーを使用します。

SQL クエリを記述する

SQL データソースに対してクエリを実行する場合、エディターでは任意の SQL コマンドを使用できます。通常は SELECT 文を実行します。例を示します。

Copied!
1
SELECT name,diameter,period FROM allNamed;

Slate は、結果の行を列ごとにキーを持つ JSON にパースし、Handlebars からアクセスできるようにします。

Copied!
1
2
3
4
5
{
    "name": ["Undina", "Hekate"],
    "diameter": [126.42, 88.66],
    "period": [5.68801089633658, 5.42957878301233]
}

SQL の組み込み関数 ↗を使用して、基本的な文字列演算や数値演算などのデータ変換を実行できます。

HTTP JSON クエリ

セキュリティに関する考慮事項

すべての HTTP JSON クエリは、次の要件に準拠する必要があります。

• すべての Handlebars テンプレートを jsonStringify ヘルパーで囲む必要があります。jsonStringify ヘルパーは、テンプレートの値が現在のスコープから逸脱できないようにします。たとえば、ブロックを閉じてリクエストに余分なプロパティを追加することはできません。
  プロパティをテンプレート化する例を示します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "path": "path/to/api",
    "method": "POST",
    "bodyJson": {
        "filter": {{jsonStringify w1.text}}
    },
    "extractors": {
        "result": "$"
    },
    "headers": {
        "Custom_Header": "my custom header value"
    }
}

プロパティの一部をテンプレート化する例を示します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
{
    "path": "path/to/api",
    "method": "POST",
    "bodyJson": {
        "filter": {{#jsonStringify}}some text plus {{w1.text}}{{/jsonStringify}}
    },
    "extractors": {
        "result": "$"
    },
    "headers": {
        "Custom_Header": "my custom header value"
    }
}

• パスに .. を使用することはできません。これにより、クエリパスが親スコープを参照し、アクセスすべきでない情報にアクセスするのを防ぎます。

HTTP JSON クエリを記述する

HTTP JSON データソースのクエリは、path、method、bodyJson、extractors のプロパティを含むオブジェクトです。

• path: データソースへの URL パスです。
• queryParams:（任意）リクエストの作成時に URL に追加するキーと値のペアのマップです（たとえば、"query": "something" を指定すると、path に ?query=something が追加されます）。このマップが空でない場合、path にクエリパラメーターを指定しないでください。
• method: リクエストの実行に使用する HTTP メソッドです。GET、POST、DELETE、PUT がサポートされています。
• bodyJson:（任意）API エンドポイントにデータとして送信する JSON です（たとえば、データのフォーマット方法や集計方法など）。データソースのエンドポイントが JSON を想定していない場合、このフィールドは必須ではありません。
• extractors: クエリが返す結果です。JSONPath ↗ を使用して、抽出する内容を指定します。たとえば、結果全体を表示するには、"result": "$" を使用します。JSONPath の記述については、こちらのテスター ↗を参照してください。JSONPath の詳細については、JSONPath の例 ↗を参照してください。
• headers:（任意）リクエストに設定するヘッダーのマップです。認証ヘッダーがある場合は、このリストに追加されます。
  例を示します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
    "path": "astronomy/_comets",
    "queryParams": {
        "limit": 5,
        "text": "searchabc"
    },
    "method": "GET",
    "bodyJson": {
        "fields": ["name", "type", "date"],
        "query": {
            "type": "dust"
        }
    },
    "extractors": {
        "name": "$.results[*].fields.name"
    },
    "headers": {
        "Custom_Header": "my custom header value"
    }
}

Elasticsearch

以下は Elasticsearch を使用する例です。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "path": "geologist/_search",
    "method": "POST",
    "bodyJson": {
        "query": {
            "prefix": {
                "request": "/daily/api/permalinks/"
            }
        },
        "aggs": {
            "views": {
                "terms": {
                    "field": "auth",
                    "size": 0
                }
            }
        }
    },
    "extractors": {
        "Users": "$.aggregations.views.buckets[*].key",
        "Views": "$.aggregations.views.buckets[*].doc_count"
    }
}

Elasticsearch の詳細については、Query DSL のドキュメント ↗を参照してください。

クエリ結果のサイズ制限

SQL および Foundry のクエリ結果は、デフォルトで5,000,000バイト (5 MB) に制限されています。結果がこれを超えると予想される場合は、複数のクエリに分割します。結果が制限を超えるクエリは、部分的なデータを返すのではなく失敗するため、基になるデータが増加すると、以前は成功していたクエリが失敗し始めることがあります。

クエリパネルでテストを選択すると、エラーを確認できます。エラーには、Size of query result exceeded specified maximum size of に続いて、設定された制限値がバイト単位で表示されます。

結果のサイズを減らすには、アプリケーションが使用する列のみを返す、LIMIT 句やフィルターを適用する、またはクエリ内で集計します。ワークフローで設定された制限を超えるサイズの結果が必要な場合は、Palantir サポートにお問い合わせください。

クエリパーシャル

クエリパーシャルを使うと、ドキュメント内の複数のクエリで再利用できるクエリコードを記述できます。パーシャルを作成するには、クエリパネルの + 新規パーシャルボタンをクリックします。

{{>partialName}} と記述すると、クエリにパーシャルを挿入できます。たとえば、WHERE column={{param w8.selectedValue}} を内容とする columnFilter という名前のパーシャルがあるとします。SELECT * from table {{>columnFilter}} というコードで別のクエリを作成できます。これは SELECT * from table WHERE column={{param w8.selectedValue}} というクエリとして展開されます。

{{>partialName arg1=value1 arg2=value2 arg3=value3}} という構文で、パーシャルに引数を渡すこともできます。パーシャルのコンテキスト内の引数の値は、個々のクエリで指定した値に置き換えられます。値には固定値（文字列や数値など）や Handlebars 参照（w8.selectedValue など）を使用できます。上記の例で、2つのクエリが異なる2つの選択値で絞り込まれる点以外はまったく同じであれば、columnFilter を WHERE column={{param columnValue}} として再定義し、クエリを SELECT * from table {{>columnFilter columnValue=w8.selectedValue}} にできます。これは以前と同じように SELECT * from table WHERE column={{param w8.selectedValue}} として展開されます。

パーシャルをネストすることもでき、再利用するコードの中でさらにコードを再利用できます。

パーシャルの名前を変更するには、エディターパネルでパーシャルを開き、名前を直接更新します。パーシャルの名前を変更すると、クエリ内のそのパーシャルへの Handlebars 参照は、新しい名前を反映するように自動的に更新されます。

パーシャルは Handlebars の概念であり、Slate の実装では Handlebars の構文を使用します。詳しくは、Handlebars パーシャルのドキュメント ↗を参照してください。

条件付きクエリ

トリガーとインタラクションタブでは、クエリが実行される条件を制御できます。条件付きでクエリを実行するには、2つの選択肢があります。すべての依存関係が null ではないを選択すると、クエリ内のすべての Handlebars 参照が null でない場合にのみクエリが実行されます。また、Handlebars 入力が true を返すを選択すると、Handlebars の条件を指定できます。この条件には、関数への参照、ウィジェットプロパティなど、クエリを実行できるタイミングのロジックを制御するための任意の参照を使用できます。この Handlebars 参照が true と評価された場合にのみクエリが実行されます。それ以外の場合、クエリは実行されません。

例1：すべての依存関係が null ではない

次のクエリを実行するには、w_visits_bar.selection.data に1つ以上の値が必要です。

値がない場合、Postgres へのリクエストは構文エラーで失敗します。

すべての依存関係が null でない場合にのみ実行する条件を追加すると、不正であることがわかっているリクエストが Postgres に送信されるのを防げます。このようなリクエストは、条件がなければ接続とリソースを消費します。

例2：これが true を返す場合にのみ実行する

次のクエリは、タブ付きコンテナ内のウィジェットに表示するデータを取得します。ページの読み込み時にはウィジェットが表示されていないものの、ページレベルのフィルターに依存しているとします。この場合、ウィジェットが表示される場合にのみ実行する条件をクエリに追加することを検討できます。これは、クエリ設定のHandlebars 入力が true を返すオプションを使用して設定できます。

API Gateway クエリの問題を解決する

API Gateway クエリに失敗したとき、プレビューパネルに表示されるエラーが、必ずしも問題の真の原因を示しているとは限りません。400、500、An error occurred だけが表示されるような汎用メッセージには、基盤となるサービスが返した、より具体的なエラーが含まれていることがよくあります。次の手順で実際の原因を特定します。

リクエストを確認する

レンダリングされたクエリのプレビューを選択して、Slate が送信するリクエストを表示します。各パラメーターに期待する値が入っていることと、空の値に解決された Handlebars 参照がないことを確認します。エディターに戻るには、クエリ Template を表示を選択します。

生のレスポンスを確認する

プレビューパネルで < / > を選択すると、パースされた結果の代わりに生の JSON レスポンスが表示されます。Foundry API のエラーでは、Slate にステータスコードしか表示されていない場合でも、具体的な問題を示す JSON 本文が返されます。

Copied!
1
2
3
4
5
6
7
8
{
    "errorCode": "NOT_FOUND",
    "errorName": "DatasetNotFound",
    "errorInstanceId": "00813215-0844-4716-be7b-a3fe0fce9e42",
    "parameters": {
        "datasetRid": "ri.foundry.main.dataset.example"
    }
}

まず errorName を確認します。これは失敗の詳細を特定するもので、parameters は原因となったリソースを示します。API エラーリファレンスには、プラットフォームが返すすべての errorName とその意味が記載されています。サポートチケットを提出する必要がある場合は、errorInstanceId を保存してください。Palantir サポートが該当するリクエストを特定するために使用できます。

失敗したクエリはヘルスチェックダイアログにもまとめられており、問題を引き起こしたクエリに直接移動できます。

エラーの種類別の一般的な原因

失敗の原因となる入力を切り分ける

生のレスポンスを確認しても原因が不明な場合は、クエリ内の各 Handlebars 参照を一時的に固定値に置き換えて、再度実行します。それでクエリに成功する場合、問題はエンドポイントやリクエスト自体ではなく、参照先のウィジェット、変数、または関数が値を解決する方法にあります。デバッガーを使用すると、各依存関係が実行時に生成する値を追跡できます。

チュートリアル：Slate でデータを利用可能にする

このチュートリアルをはじめる前に、Foundry にアップロードした last-mile-flights と airports のデータセットを Slate で利用可能にする必要があります。変数パネルを開き、+追加を選択して Foundry リソースセレクターを開きます。

すべてのファイル > Getting started data を選択して last-mile-flights データセットに移動するか、リソースセレクターの検索ボックスを使用します。データセットが見つかったら、last-mile-flights を選択を選択してインポートの設定をはじめます。

設定オプションを表示するには、Postgres に同期の横にある矢印を選択します。

データアクセスのパターンがまだ定義されておらず、last-mile-flights データセットは比較的小さいため、テーブルにインデックスは作成しません。インデックスは後からいつでも追加できます。適用して同期を選択して同期を開始します。ステータスを確認ボタンを使用して同期を監視できます。

同期が完了すると、Slate で使用できる、以下のようなサンプルクエリが表示されます。ただし、データセット名の末尾に追加される数字は異なります。

Copied!
1
SELECT * FROM "foundry_sync"."Getting Started Data/last-mile-flights-master-9406" LIMIT 10

アプリケーションの作成時に使えるように、クエリをコピーしておきます。次に、airports データセットを Slate に同期します。

クエリを作成する

まず、同期済みのデータセットから必要なデータを取得する SQL クエリを作成します。

クエリを選択してパネルを開きます。

クエリリスト、Partial リスト、エディターが表示されます。まだクエリを作成していないため、リストは空です。 + 新規クエリを選択します。エディターにツールバー、テキストエディター、クエリ結果のプレビューパネルが表示されます。

名前テキストボックスに、クエリ名として q_allFlights を入力します。Slate の接続先をデータベースにするには、ソースドロップダウンから、データ型が FOUNDRY のデータソースを選択します。このデータソースは foundry-sync、foundry-postgate、foundry、または類似の名前になっている場合がありますが、データソース名の右側には必ず FOUNDRY というデータ型が表示されます。

このクエリでは、データベース内の last-mile-flights テーブルから数行のデータを取得します。そのために、先ほどコピーしたサンプルクエリをエディターで使用できます。

Copied!
1
SELECT * FROM "foundry_sync"."Getting Started Data/last-mile-flights-master-9406" LIMIT 10

テストを選択するか、Windows では Ctrl+Enter、macOS では Cmd+Enter を使用して、クエリが機能するかどうかをテストできます。これにより、プレビューパネルにクエリ結果が表示されます。

< / > を選択すると、生の JSON レスポンス構造で結果を表示できます。

エラーが発生した場合は、last-mile-flights を Slate で利用可能にしていることと、正しいパスを使用していることを確認してください。

クエリを更新を選択してクエリを保存します。

以下のクエリ例では、具体的なテーブル名の代わりに「変数」を使用します。たとえば、"foundry_sync"."Getting started data/last-mile-flights-master-9406" ではなく、"foundry_sync"."{{v_flightTable}}" と表示されます。

データセットには多くの列があるため、必要な数列のみを取得するようにクエリを調整します。

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
SELECT
    flight_id,
    carrier_code,
    tail_num,
    origin,
    dest,
    dep_ts_utc,
    arr_ts_utc,
    distance,
    actual_elapsed_time
FROM "foundry_sync"."{{v_flightTable}}"
LIMIT 10