カスタム集計を作成する

関数を使用すると、オントロジー内のデータに基づいてカスタム集計を計算し、Workshop のチャートウィジェットに表示できます。このガイドでは、オントロジーから集計データを読み込み、結果を操作して将来の結果を予測し、変更した結果を返すカスタム集計ロジックの記述方法を説明します。

このページでは TypeScript v1 を扱います。Python についてはPython 関数でカスタム集計を作成するを、TypeScript v2 についてはオントロジー SDK リファレンスの集計を参照してください。

このセクションを進める際には、次のリファレンスが役立ちます。

オブジェクトセットの集計のリファレンス
集計データ型のリファレンス
このガイドの Python 版であるPython 関数でカスタム集計を作成する
TypeScript v2 の集計で使用する語彙を説明した、TypeScript オントロジー SDK リファレンスの集計

集計を読み込む

TypeScript v1 では、Objects.search() に対して .groupBy()、.segmentBy()、メトリクスメソッドをチェーンさせて集計を構築します。TypeScript v1 の集計メトリクスは、検索可能に指定されたプロパティのみを受け付けます。文字列プロパティには2つのバケット化戦略があり、どちらも最大バケット数が設定されていて、それを超えると近似になります。.topValues() は上位1,000個の値でバケット化して迅速に応答し、.exactValues() は最大10,000個のバケットを考慮するため、その分遅くなります。

TypeScript v2 の集計で使用する語彙については、TypeScript オントロジー SDK リファレンスの集計を参照してください。移行ガイドでは、TypeScript v1 のすべてのバケット化メソッドと集計メトリクスを TypeScript v2 の対応するものにマッピングし、TypeScript v2 に対応するものがない機能を一覧で示しています。

この例では、経費からなるオントロジーがあり、それぞれの expense オブジェクトに部門名、経費の date、経費の amount のプロパティがあるとします。今後6か月間の部門別の月次支出を見積もるには、まず月次支出の集計データを読み込みます。

Copied!1
2
3
4
5
const result = await Objects.search()
    .expenses()
    .groupBy(expense => expense.departmentName.topValues())
    .segmentBy(expense => expense.date.byMonth())
    .sum(expense => expense.amount);

集計結果を操作する

.groupBy() の後に .segmentBy() を呼び出すと ThreeDimensionalAggregation が生成されるため、result.buckets はすでに部門ごとに1個のバケットを持つネスト構造になっています。内側の各バケットのキーは、月の両端を保持する IRange<Timestamp> で、min はその値を含み、max はその値を含みません。また、各 Timestamp 値は、.plusMonths() などのメソッドによる暦に基づく計算をサポートしています。

次に、各部門の今後6か月間の支出を外挿できます。この例では、最後の月の値を今後6か月間の見積もりとして使用する単純な方法を取ります。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
const modifiedBuckets = result.buckets.map(bucket => {
    // 直近の月に対応するバケットを見つけます
    const lastBucket = bucket.value[bucket.value.length - 1];

    let nextSixMonths: IBaseBucket<IRange<Timestamp>, Double>[] = [];
    let currentMonth = lastBucket.key.max!;
    // 6回ループします
    for (let i = 0; i < 6; i++) {
        // この範囲の終端（翌月）を見つけます
        const nextMonth = currentMonth.plusMonths(1);
        // 日付範囲として翌月を使用し、
        // 値として直近の月を使用する新しいバケットを追加します
        nextSixMonths.push({
            key: {
                min: currentMonth,
                max: nextMonth,
            },
            value: lastBucket.value,
        });
        currentMonth = nextMonth;
    }

    // 変更した結果を返します
    return { key: bucket.key, value: nextSixMonths };
});

TypeScript v2 では、.aggregate() はネストされたバケットではなくフラットな行の配列を返すため、3次元集計を返す必要がある関数は、ネスト構造を自ら再構築する必要があります。移行ガイドのグループ化を参照してください。

集計を返す

今後6か月間の見積もりを作成できたので、これらの見積もり値を返せます。

Copied!1
return { buckets: modifiedBuckets };

TypeScript v1 は、オブジェクト内の buckets キーの下にバケットを格納し、ネストされたレベルには value キーを使用します。戻り値の型は TypeScript v1、TypeScript v2、Python のいずれでも ThreeDimensionalAggregation のままです。各バージョンでは関数内で異なる方法でこの値を構築するため、この関数を使用する Workshop のチャートは移行後も引き続き動作します。各バージョンで想定される形式については集計データ型を、Python の NestedBucket クラスと SingleBucket クラスについてはPython 関数でカスタム集計を作成するを参照してください。

この関数の完全なコード例は次のとおりです。

Copied!1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
@Function()
public async estimatedDepartmentExpenses(): Promise<ThreeDimensionalAggregation<string, IRange<Timestamp>, Double>> {
    const result = await Objects.search()
        .expenses()
        .groupBy(expense => expense.departmentName.topValues())
        .segmentBy(expense => expense.date.byMonth())
        .sum(expense => expense.amount);

    const modifiedBuckets = result.buckets.map(bucket => {
        // 直近の月に対応するバケットを見つけます
        const lastBucket = bucket.value[bucket.value.length - 1];

        let nextSixMonths: IBaseBucket<IRange<Timestamp>, Double>[] = [];
        let currentMonth = lastBucket.key.max!;
        // 6回ループします
        for (let i = 0; i < 6; i++) {
            // この範囲の終端（翌月）を見つけます
            const nextMonth = currentMonth.plusMonths(1);
            // 日付範囲として翌月を使用し、
            // 値として直近の月を使用する新しいバケットを追加します
            nextSixMonths.push({
                key: {
                    min: currentMonth,
                    max: nextMonth,
                },
                value: lastBucket.value,
            });
            currentMonth = nextMonth;
        }

        // 変更した結果を返します
        return { key: bucket.key, value: nextSixMonths };
    });

    return { buckets: modifiedBuckets };
}

この集計結果を Workshop のチャートで使用すると、今後6か月間の月次支出の見積もりを表示できます。

←

PREVIOUSオブジェクト識別子

NEXTオブジェクトとリンクタイプをインポートする

→