オントロジーの構築関数Functions on Objectsオブジェクトセット（TSv1）

注: 以下の翻訳の正確性は検証されていません。AIPを利用して英語版の原文から機械的に翻訳されたものです。

API：オブジェクトセット

このページでは、TypeScript v1 (TSv1) について説明します。TypeScript v2 (TSv2) と Python では、オントロジー SDK を通じてオントロジーにクエリを実行します。TypeScript および Python の OSDK リファレンスを参照してください。移行ガイドでは、TSv1 の各演算子を対応する TSv2 の形式にマッピングしています。

オブジェクトセットは、単一のタイプのオブジェクトを順序なしでまとめたものです。関数 API を使用すると、オブジェクトセットの絞り込み、定義されたリンクタイプに基づくほかのオブジェクトタイプへの関連検索、集計値の計算、または具体的なオブジェクトの取得ができます。個々のオブジェクトを関数への入力として渡すだけでなく、オブジェクト検索 API を使用していつでもオブジェクトセットを検索できます。

TypeScript v1 では、絞り込み、並べ替え、集計は、検索可能のレンダリングヒントが有効なプロパティに対してのみ機能します。これらのプロパティは検索用にインデックス化済みであるためです。このレンダリングヒントは Ontology Manager で有効にできます。

関数の入力としては、オブジェクトセットは必要になるまで読み込みを遅延するため、オブジェクト配列よりも効率的です。オブジェクトセットを効率的に使用するためのベストプラクティスについては、パフォーマンスを最適化するを参照してください。

オブジェクト検索

Objects.search() インターフェースを使用すると、プロジェクトにインポートされた任意のオブジェクトタイプの検索を開始できます。この例では、指定された airportCode を使用して、その空港を出発したすべてのフライトを検索します。次に、それらのフライトの到着地を重複なくすべて取得し、返します。

TSv2 については、絞り込みを参照してください。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
import { Function } from "@foundry/functions-api";
import { Objects } from "@foundry/ontology-api";

export class FlightFunctions {
    @Function()
    public currentFlightDestinations(airportCode: string): Set<string> {
        const flightsFromAirport = Objects.search()
            .flights()
            .filter(flight => flight.departureAirportCode.exactMatch(airportCode))
            .all();

        const destinations = flightsFromAirport.map(flight => flight.arrivalAirportCode!);

        return new Set(destinations);
    }
}

検索対象のオブジェクトタイプに、オブジェクトのリスト、オブジェクトのリソース識別子のリスト、またはオブジェクトセットのリソース識別子を引数として渡すことでも、オブジェクトセットを作成できます。例：Objects.search().flights([flight])。

特定のタイプのオブジェクトセットを取得したら、以下で説明するさまざまな操作をそのセットに対して実行できます。

絞り込み

TypeScript v1 では、オブジェクトセットの .filter() メソッドを使用して、オブジェクトの検索可能なプロパティに基づいてオブジェクトセットを絞り込めます。このフィルターメソッドは、絞り込みの対象となるプロパティのデータ型に基づくフィルター定義を受け取ります。TypeScript v2 で同等の機能については、移行ガイドのフィルター演算子の対応表を参照してください。TypeScript v1 のフィルターメソッドは次のとおりです。

すべてのプロパティタイプは .exactMatch() フィルターをサポートしており、そのプロパティ値が完全一致するオブジェクトに絞り込みます。これは、文字列の完全一致で絞り込む場合（上記の例のように）や、オブジェクトの主キーで絞り込む場合（たとえば、.filter(object => object.primaryKey.exactMatch(PrimaryKey))）に便利です。
- プロパティが null または undefined かどうかを確認するには、hasProperty() メソッドを使用します。
- 複数の値を渡すには、スプレッド演算子 .exactMatch(...listVariable) を使用します。空の配列が渡された場合、フィルターは無視されます。
文字列プロパティは、いくつかのキーワードフィルターをサポートしています。詳細については、Code Assist の各メソッドのドキュメントを参照してください。
- .phrase() は、検索クエリをトークンに分割します。トークンは通常、個々の単語です。すべてのトークンが順番どおりに含まれ、トークン間にほかのトークンがない値に絞り込みます。アンダースコアとピリオドでは、プロパティ値は別々のトークンに分割されません。たとえば、banana を検索しても、banana_pudding や banana.pudding は返されません。
- .phrasePrefix() は phrase() とほぼ同じですが、最後のトークンは、そのトークンで始まるトークンにも一致します。たとえば、fresh banana を .phrasePrefix() で検索すると、プロパティ値 fresh banana_pudding には一致しますが、プロパティ値 banana_pudding fresh には一致しません。pudding を .phrasePrefix() で検索しても、プロパティ値 banana_pudding には一致しません。
- .prefixOnLastToken() は、検索クエリをトークンに分割し、指定されたすべてのトークンが含まれているかどうかに基づいて値を絞り込みます。最後のトークンは、そのトークンで始まるトークンにも一致します。たとえば、big app は big apples と apples from the big tree に一致しますが、apples from the biggest tree には一致しません。
- .matchAnyToken() と .fuzzyMatchAnyToken() は、検索クエリをトークンに分割し、指定されたトークンのいずれかが含まれているかどうかに基づいて値を絞り込みます。fuzzy バージョンでは、近似値も一致とみなされます。
- .matchAllTokens() と .fuzzyMatchAllTokens() は、検索クエリをトークンに分割し、指定されたすべてのトークンが含まれているかどうかに基づいて値を絞り込みます。fuzzy バージョンでは、近似値も一致とみなされます。
  - あいまいフィルターは、@foundry/functions-api からインポートした任意の Fuzziness パラメーターを受け取ることができます。
  - 利用可能な Fuzziness の選択肢の説明は、ElasticSearch のドキュメント ↗にあります。詳細は以下にも記載されています。
数値、日付、タイムスタンプのプロパティは、.range() フィルターをサポートしています。
- 範囲フィルターには、より小さい比較を行う .lt()、以下の比較を行う .lte()、より大きい比較を行う .gt()、以上の比較を行う gte() メソッドがあります。
ブールプロパティは、.isTrue() と .isFalse() フィルターをサポートしています。
Geopoint プロパティは、.withinDistanceOf()、.withinPolygon()、.withinBoundingBox() フィルターをサポートしています。
Geoshape プロパティは、.withinBoundingBox()、.intersectsBoundingBox()、.doesNotIntersectBoundingBox()、.withinPolygon()、.intersectsPolygon()、doesNotIntersectPolygon() フィルターをサポートしています。
リンクフィルターでは、.isPresent() メソッドを使用して、特定のタイプのリンクされたオブジェクトが存在する、または存在しないオブジェクトに絞り込めます。
配列プロパティは .contains() フィルターをサポートしており、配列プロパティの値に指定された値の_いずれか_が含まれるオブジェクトに絞り込みます。

フィルターを組み合わせる

TypeScript v1 では、@foundry/functions-api からエクスポートされる Filters API を使用して、フィルターを組み合わせることができます。利用可能なメソッドは次のとおりです。

and() は、指定されたすべてのフィルターを満たすオブジェクトにオブジェクトセットを絞り込みます
or() は、指定されたフィルターのいずれかを満たすオブジェクトにオブジェクトセットを絞り込みます
not() は、指定されたフィルターを否定します

TSv2 については、Not、And、Or フィルターを参照してください。

以下の例では、and() を使用して、フライトのオブジェクトセットをフライトの到達点で絞り込めます。

Copied!1
2
3
4
5
6
7
8
import { Filters } from "@foundry/functions-api";

Objects.search()
    .flights()
    .filter(flight => Filters.or(
        Filters.and(flight.destination.exactMatch("SFO"), flight.passengerCount.gt(100)),
        Filters.and(flight.destination.exactMatch("LAX"), flight.passengerCount.gt(300)),
    ))

上記のコードは、乗客数が100人を超え、SFO に到着したフライト、または乗客数が300人を超え、LAX に到着したフライトに絞り込みます。

論理演算子ではなく Filters メソッドでフィルターを組み合わせる

TypeScript v1 では、オブジェクトセットの .filter() メソッドは && や || 演算子を使用しません。複数のフィルターを適用するには、上記の Filters のメソッドのいずれかを使用する必要があります（または、.filter() を複数回呼び出して and 条件を実現します）。

あいまい検索で文字列プロパティを絞り込む

任意の fuzziness パラメーターを指定すると、あいまい一致の動作をより細かく制御できます。fuzziness を指定しない場合、検索対象のトークンの長さに基づいて、許容される編集距離が自動的に設定されます。編集距離を指定するには、@foundry/functions-api から Fuzziness をインポートする必要があります。

Fuzziness は TypeScript v1 の概念であり、TypeScript v2 に対応するものはありません。詳細については、移行ガイドの TypeScript v2 に同等の機能がないものを参照してください。

いずれかのトークンにあいまい一致

Copied!1
Objects.search().employee().filter(employee => employee.firstName.fuzzyMatchAnyToken("Michael", { fuzziness: Fuzziness.LEVENSHTEIN_TWO })).all();

上記のコードは、指定された検索語から2回以内の編集で表せる名前を持つ従業員を返します（レーベンシュタイン距離が2）。この例では、Michael、Micheal、Mikhael、Michel、Mikhail、Mihail が含まれます（ただし、たとえば Miguel は含まれません）。検索語の正確さにより確信がある場合は、編集距離を小さくして（異なるレーベンシュタイン距離で）検索し、検索結果をさらに絞り込めます。

すべてのトークンにあいまい一致

Copied!1
Objects.search().employee().filter(employee => employee.fullName.fuzzyMatchAllTokens("Michael Smith", { fuzziness: Fuzziness.LEVENSHTEIN_ONE })).all();

複数のトークンからなるフレーズにも、あいまいフィルターを使用できます。上記のコードは、フルネームに Michael と Smith の両方が含まれ、各トークンにつき最大1回の編集が許容される従業員に一致します。たとえば、Mikhael Smitt が該当します（つまり、各トークンのレーベンシュタイン距離が1）。fuzzyMatchAllTokens または fuzzyMatchesAllTokens フィルターでは、トークンの順序は考慮されません。

文字列配列プロパティのあいまい一致

配列ベースのプロパティに対するすべてのフィルターでは、その要素のデータ型で利用可能なメソッドを使用できます。たとえば、文字列配列プロパティは、文字列プロパティで利用可能な任意のメソッドに基づいて絞り込めますが、メソッド名は少し異なる場合があります。配列プロパティで絞り込む場合、そのオブジェクトが返されるには、配列要素の中に1件の一致が必要です。

K 近傍法（KNN）

KNN の制限

KNN は、OSv2 にインデックス化されたオブジェクトタイプでのみサポートされます。TypeScript v1 では、k 値は 0 < K <= 100 の範囲に制限されます。また、検索ベクトルはインデックス化に使用したベクトルと同じサイズである必要があり、次元数の上限は2048です。これらの制限のいずれかを超えると、エラーがスローされます。

埋め込みプロパティを持つオブジェクトタイプは、KNN 検索に利用できます。これらの検索は、指定された埋め込みパラメーターに最も近い埋め込みプロパティを持つオブジェクトを k 個返します。次の例では、指定された映画の脚本に最も類似する映画を返します。埋め込みは、Pipeline Builder などの変換ツールで生成することも、関数のクエリ時に Palantir が提供する埋め込みモデルを使用するか、関数内で独自のモデルを使用して生成することもできます。

関数リポジトリの functions.json 設定ファイルで、enableVectorProperties エントリーが true に設定されていることを確認してください。

どちらのバージョンも nearestNeighbors() を呼び出しますが、シグネチャは異なります。TypeScript v1 では、ベクトルプロパティと検索ベクトルを指定するコールバックを渡します。一方、TSv2 はクエリ、近傍数、プロパティを位置引数として受け取り、近傍数の上限は100ではなく500です。最近傍を参照してください。

Copied!1
2
3
4
5
6
7
8
9
10
import { Objects } from "@foundry/ontology-api";

const kValue: number = 2;
// ベクトルは FML Live から生成するか、既存のオブジェクトから取得できます
const vector: Double[] = [0.7, 0.1, 0.3];
const movies: Movies[] = Objects.search()
        .movies()
        .nearestNeighbors(obj => obj.vectorProperty.near(vector, { kValue }))
        .orderByRelevance()
        .take(kValue);

上記の例では、先頭の kValue 件の結果を取得する前に、関連度による並べ替えも行っています。

セマンティック検索ワークフロー全体の例については、セマンティック検索ワークフローガイドを参照してください。

集合演算

TypeScript v1 では、集合演算を使用して、同じオブジェクトタイプのオブジェクトセットをさまざまな方法で組み合わせることができます。

.union() は、指定されたオブジェクトセットのいずれかに存在するオブジェクトで構成される新しいオブジェクトセットを作成します。
.intersect() は、指定されたオブジェクトセットのすべてに存在するオブジェクトで構成される新しいオブジェクトセットを作成します。
.subtract() は、指定されたオブジェクトセットに存在するオブジェクトを除外します。

TSv2 でも、同じ3つのメソッドを同じ名前で利用できます。集合演算を参照してください。

すべてのオブジェクトを取得する

TypeScript v1 では、.all() メソッドと .allAsync() メソッドはオブジェクトセット内のすべてのオブジェクトを取得しますが、一度に読み込もうとするオブジェクトが多すぎると、関数の実行が失敗します。TypeScript v1 で読み込めるオブジェクトの最大数は100,000個です。ただし、10,000個を超えるオブジェクトを読み込む場合も、関数の実行がタイムアウトする可能性があります。関数の時間とメモリー容量の制限について詳しくはこちら。

.allAsync() メソッドを使用すると、オブジェクトセット内のすべてのオブジェクトに解決される Promise を取得できます。.allAsync() は .all() と同じデータを読み込み、ブロッキングを回避します。互いに独立したオブジェクトセットを並列で読み込む場合に便利です。オブジェクトセットを1つずつ順に読み込むのではなく、それぞれの .allAsync() 呼び出しを開始してから、Promise.all() でまとめて待機します。

どちらのメソッドも、すべてのオブジェクトをその全内容とともにメモリーに読み込むため、小規模であることがわかっているオブジェクトセットに対してのみ使用してください。.all() または .allAsync() を呼び出す前に、必要な処理が次のいずれに当たるかを検討してください。

件数、合計、またはグループ化の計算： 代わりに、オブジェクトを読み込まない .count() や .groupBy() などのバックエンド集計を使用します。
件数を限定した結果、サンプル、または表示用リストを返す： 代わりに、.orderBy(...).take(n) を使用します。
すでに範囲が限定されている入力を処理する： Workshop が関数ベースの列に渡す表示中の行など、入力が小規模であることがわかっている場合は、.all() が適しています。
条件に一致するすべてのオブジェクトを処理する： .all() をそのまま使用します。完全にたどる必要がある処理を、通知せずに結果を切り詰める .take(n) に置き換えないでください。

ページングの整合性とスナップショット

.all() と .allAsync() は、オブジェクトセット内のすべてのオブジェクトを取得する Object Set Service (OSS) エンドポイントを使用して、結果をページ単位で読み込みます。これらのエンドポイントは、整合性のあるスナップショットからページを順次読み取ります。ストリーミングデータソースでは、整合性のあるスナップショットは保証されません。これらのエンドポイントでは、ページングの整合性チェックを無効にすることはできません。ページ間の不整合をサービスが検出すると、走査が PagingInconsistencyDetected で失敗する場合があります。走査が長時間にわたる場合は、スナップショットが期限切れになることで失敗する場合もあります。件数を限定した .take(n) による読み取りでは、ページ間の整合性は必要ありませんが、n は最大10,000です。アクションがスナップショット分離モードで実行される場合など、関数の実行自体にスナップショットがある場合は、.take(n) を含め、その実行内のすべての読み取りがそのスナップショットに固定されます。

全件の走査がスナップショットエラーで失敗した場合は、次の選択肢を検討してください。

代わりにバックエンド集計で結果を計算します。
関数の要件上、部分的な結果を許容できる場合は、最大10,000個のオブジェクトを対象とする、件数を限定した .take(n) による読み取りを使用します。
データを安定したサブセットに絞り込みます。
走査が短時間で完了するように、入力を小規模に保ちます。
関数を安全に繰り返し実行できる場合は、最初から再試行して新しい走査を開始します。
スナップショットの有効期間には限りがあります。長時間実行される関数がスナップショットの期限切れによって失敗する場合は、読み取り間で整合性のあるビューがワークフローに必要かどうかを再検討してください。必要ない場合は、関数の設定でスナップショットを無効にできます。スナップショット分離を使用する関数ベースのアクションでは、スナップショットを有効にしておく必要があります。.all() メソッドと .allAsync() メソッドは関数の設定にかかわらずページングの整合性を強制するため、この設定でページングの不整合エラーを完全に防ぐことはできません。

TSv2 での同等の処理については、オブジェクトをメモリーに読み込むを参照してください。

並べ替えと件数制限

すべてのオブジェクトを取得する代わりに、オブジェクトセットに並べ替え句を適用してから、読み込むオブジェクトの数を指定することで、件数を制限して読み込めます。TypeScript v1 では、次のメソッドを使用できます。

.orderBy() は、並べ替え基準となる検索可能なプロパティを指定し、並べ替えの方向も指定できます。このメソッドで選択できるのは、並べ替え可能なデータ型（数値、日付、文字列）のプロパティのみです。.orderBy() を複数回呼び出すと、複数のプロパティで並べ替えられます。
.orderByRelevance() は、指定されたフィルターへの一致度に基づき、関連性の高いオブジェクトから順に返すよう指定します。クエリの語句と、あるオブジェクトのプロパティ値との関連性は、そのプロパティ値内での語句の出現頻度、すべてのオブジェクトにわたる語句の出現頻度などを考慮して、複雑な判定によって決まります。.exactMatch() フィルターのみを使用する場合や、文字列以外のプロパティで絞り込む場合には、関連性はあまり適していません。1回の検索で使用できるのは、.orderBy() と .orderByRelevance() のいずれか一方のみです。
.take() と .takeAsync() を使用すると、セットから指定した数のオブジェクトを取得できます。これらのメソッドは、並べ替えを指定した後にのみ利用可能です。

.orderBy(...).take(n) は最大 n 個のオブジェクトを返し、残りは通知せずに除外します。これは、オブジェクトセットをページ分割して取得するための方法ではありません。一部の結果のみを返すことが正しい場合に限って使用してください。関数で概要のみが必要な場合は、バックエンドの集計を使用します。変化しないオブジェクトセットをバッチで処理するには、範囲フィルターをサポートする、一意かつ null でないプロパティで昇順に並べ替えます。バッチの最後の値より後に進んだときに、同じ値を持つほかのオブジェクトを飛ばさないようにするため、並べ替えキーは一意である必要があります。後続の各バッチでは、.range().gt(lastValue) を使用して、前のバッチの最後の値より大きい値に絞り込みます。このパターンは、クエリ間で一致するオブジェクトとその並べ替えキーの値が変化しないことを前提としています。TypeScript v1 では文字列プロパティが範囲フィルターをサポートしていないため、このパターンに文字列の主キーは使用できません。

TSv2 については、並べ替えた結果を読み込むを参照してください。並べ替えと読み込みには、TSv2 に対応する形式がない TSv1 の機能が記載されています。

たとえば、次のコードは入社日が最も早い従業員を10人取得します。

Copied!1
2
3
4
Objects.search()
    .employees()
    .orderBy(e => e.startDate.asc())
    .take(10)

別の例として、保険会社の事故に関する保険金請求のテキストを含むオブジェクトタイプ claims を考えてみます。赤い車と鹿が関係する特定の保険金請求を探すとします。.orderByRelevance() の行がなければ、red、car、collision、with、deer のいずれかの単語を含む結果が、上位10件の結果として返される可能性があります。.orderByRelevance() の行がある場合、最初の10件は検索語を最も多く含む保険金請求となるため、関連性が最も高い保険金請求が先頭に表示されます。

次の例では、保険金請求を絞り込み、関連性で並べ替えます。

Copied!1
2
3
4
5
const results = Objects.search()
    .claims()
    .filter(doc => doc.text.matchAnyToken("red car collision with deer"))
    .orderByRelevance()
    .take(10)

集計を計算する

TypeScript v1 の集計の制限

TypeScript v1 Objects API から返される集計は、合計10,000個のバケットに制限されています。この制限を超えるとエラーがスローされます。

.topValues() を使用してバケット化する場合、データに1,000個を超える異なる値があると、結果は近似値になります。その場合、上位値のリストは正確でない可能性があります。

プロパティでオブジェクトをグループ化する

多くの場合、オブジェクトセット内のすべてのオブジェクトを読み込む必要はありません。代わりに、バケット化された値の集計だけを読み込んで、さらに分析できます。

集計の計算を開始するには、オブジェクトセットで .groupBy() メソッドを呼び出します。これにより、オブジェクトセット内のオブジェクトタイプの検索可能なプロパティの1つでバケット化を指定できます。

TSv2 については、グループ化の種類を参照してください。

たとえば、次のコードは従業員を入社日でグループ化します。

Copied!1
2
3
Objects.search()
    .employees()
    .groupBy(e => e.startDate.byDays())

バケット化に使用するプロパティを指定するときは、プロパティタイプに応じて、バケット化の方法に関する追加情報を指定する必要があります。TSv2 については、グループ化戦略の対応表を参照してください。TypeScript v1 のバケット化メソッドは次のとおりです。

boolean プロパティでは、唯一の選択肢は .topValues() です。これは true 用と false 用の2個のバケットを返します。
文字列プロパティでは、2つの選択肢があります。
- .topValues()：短いレスポンス時間が必要な場合や、カーディナリティが小さいプロパティに使用します。文字列プロパティの上位1,000個の値でバケット化します。この制限は、返される集計が過度に大きくならないようにするためのものです。
- .exactValues()：より正確な集計や、カーディナリティが高いプロパティで最大10,000個のバケットを対象にしたい場合に使用します。対象となるバケット数は .exactValues({"maxBuckets": numBuckets}) で指定できます。numBuckets は0以上10,000以下の整数値である必要があります。対象とする結果が多くなるため、このメソッドのレスポンス時間は長くなる可能性があります。
数値型のプロパティ（たとえば、Integer、Long、Float、Double）では、バケット化の選択肢は次の2つです。
- .byRanges() では、使用する範囲を正確に指定できます。たとえば、.byRanges({ min: 0, max: 50 }, { min: 50, max: 100 }) を使用すると、ここで指定した [0, 50] と [50, 100] の2つの範囲にオブジェクトをバケット化できます。範囲の min はその値を含み、max はその値を含みません。min を省略すると -∞ から max までの値を含むバケットを表し、max を省略すると min から ∞ までの値を含むバケットを表します。
- .byFixedWidth() は、各バケットの幅を指定します。たとえば、.byFixedWidth(50) を使用すると、幅が50の範囲にオブジェクトをバケット化できます。
LocalDate プロパティでは、簡単にバケット化できるように、さまざまな便利なメソッドが用意されています。
- .byYear()
- .byQuarter()
- .byMonth()
- .byWeek()
- .byDays() は、値を日単位でバケット化します。バケットの幅に使用する日数を渡すことができます。
Timestamp プロパティでは、LocalDate と同じバケット化の選択肢に加えて、次の選択肢も使用できます。
- .byHours() は、値を時間単位でバケット化します。バケットの幅に使用する時間数を渡すことができます。
- .byMinutes() は、値を分単位でバケット化します。バケットの幅に使用する分数を渡すことができます。
- .bySeconds() は、値を秒単位でバケット化します。バケットの幅に使用する秒数を渡すことができます。
Array プロパティでは、バケット化の選択肢は配列内の要素のデータ型によって決まります。具体的には、Array<PropertyType> では PropertyType と同じバケット化メソッドを使用できます（たとえば、Array<boolean> では boolean と同じバケット化メソッドを使用できます）。
- たとえば、Alice と Bob からなる employeeSet というオブジェクトセットがあり、Array<string> プロパティの pastCountries に Alice は ["US", "UK"]、Bob は ["US"] を保持している場合、employeeSet.groupBy(e => e.pastCountries.exactValues()).count() は { "US": 2, "UK": 1 } を返します。

1個のプロパティでグループ化した後、必要に応じて .segmentBy() メソッドを呼び出し、さらにバケット化できます。これにより、2個の検索可能なプロパティでバケット化された3次元集計を計算できます。TypeScript v2 では、同じ $groupBy オブジェクト内の2個目のキーを通じて2個目のプロパティでバケット化し、異なる形式の結果を返します。移行ガイドの TypeScript v2 に相当するものがない機能を参照してください。

たとえば、次のように従業員を入社日と役割でグループ化できます。

Copied!1
2
3
4
Objects.search()
    .employees()
    .groupBy(e => e.startDate.byDays())
    .segmentBy(e => e.role.topValues())

集計メトリクスを選択する

オブジェクトセットをグループ化した後、さまざまな集計メソッドを呼び出して、各バケットの集計メトリクスを計算できます。TypeScript v1 では、プロパティを必要とするメソッドは、検索可能として指定されたプロパティのみを受け付けます。TypeScript v2 の対応するメソッドについては、移行ガイドの集計メトリクスの対応表を参照してください。使用可能な TypeScript v1 の集計メソッドは次のとおりです。

.count() は、各バケット内のオブジェクト数を返します
.average() は、指定された数値、タイムスタンプ、日付プロパティの平均値を返します
.max() は、指定された数値、タイムスタンプ、日付プロパティの最大値を返します
.min() は、指定された数値、タイムスタンプ、日付プロパティの最小値を返します
.sum() は、指定された数値型のプロパティの値の合計を返します
.cardinality() は、指定されたプロパティの異なる値の近似数を返します

TypeScript v1 では、これらのメソッドのいずれかを呼び出すと、TwoDimensionalAggregation または ThreeDimensionalAggregation が返されます。最終的な集計メソッドのいずれかを呼び出す前に .segmentBy() を呼び出した場合は、ThreeDimensionalAggregation が返されます。

有効なバケット化のデータ型を含む、これらの集計のデータ型の構造について、詳しくはこちら。

集計を計算するにはリモートサービスからデータを読み込む必要があるため、結果の集計は Promise でラップされます。async/await ↗ 構文を使用して、Promise の結果を取り出せます。

以下は、集計を読み込んで結果として返す TypeScript v1 の完全な例です。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
import { Double, Function, ThreeDimensionalAggregation } from "@foundry/functions-api";
import { Objects } from "@foundry/ontology-api";

export class AggregationFunctions {
    @Function()
    public async employeesByRoleAndOffice(): Promise<ThreeDimensionalAggregation<string, string, Double>> {
        return Objects.search()
            .employee()
            .groupBy(e => e.title.topValues())
            .segmentBy(e => e.office.topValues())
            .count();
    }
}

TypeScript v1 では、グループ化された集計はすでに ThreeDimensionalAggregation の形式になっているため、上記のように関数から直接返すことができます。TSv2 では、.aggregate() は行のフラットな配列を返すため、関数内で集計のデータ型を組み立てる必要があります。集計のデータ型とグループ化を参照してください。

以下は、groupBy 文を使用せずに集計する完全な例です。TypeScript v1 では、?? 0 を使用して件数が未定義の場合に備えています。

Copied!1
2
3
4
5
6
7
8
9
10
import { Double, Function } from "@foundry/functions-api";
import { Objects } from "@foundry/ontology-api";

export class AggregationFunctions {
    @Function()
    public async employeesStats(): Promise<Double> {
        // すべての従業員の数です。count() が undefined を返す場合、デフォルトは0です
        return Objects.search().employee().count() ?? 0;
    }
}

上記の TypeScript v1 コード例の該当行を置き換えることで、groupBy を使用せずにほかの集計も実行できます。たとえば、次のような集計が可能です。

すべての従業員の件数：Objects.search().employee().count();（上記の例で使用）
従業員の平均在職期間：Objects.search().employee().average(e => e.tenure);
従業員の最長在職期間：Objects.search().employee().max(e => e.tenure);
従業員の最短在職期間：Objects.search().employee().min(e => e.tenure);
すべての従業員の給与の合計：Objects.search().employee().sum(e => e.salary);
オフィス数：Objects.search().employee().cardinality(e => e.office);

メモリー内で集計結果を操作する例については、カスタム集計を作成するためのガイドを試してください。

←

PREVIOUSオブジェクトとリンク（TSv1）

NEXT添付ファイル

→