TERR_xxx関数、TERRAggregation_xxx関数の使い方

2024年07月16日 01:06
更新

本資料はSpotfire内の式（計算カラム、カスタム演算式など）で利用できるTERR_xxx 関数、TERRAggregation_xxx 関数の使い方について説明します。

動作確認環境

Spotfire Analyst 14.0 LTS

本件記事記載の内容は Spotfire 10.10 LTS 以降に参照できます。

また、TERR_xxx 関数、TERRAggregation_xxx 関数に関しては、AnalystやTERRサービス、Spotfire Statistics Servicesのいずれにも同じ動きになります。

関数一覧

Spotfire内で利用できるTERR_xxx 関数、TERRAggregation_xxx 関数の一覧は以下です。

関数名の後ろの「xxx」部分は該当関数の戻り値のデータ型を示しています。

TERR_xxx 関数
- TERR_Binary
- TERR_Boolean
- TERR_DateTime
- TERR_Integer
- TERR_Real
- TERR_String
- TERR_TimeSpan
TERRAggregation_xxx 関数
- TERRAggregation_Binary
- TERRAggregation_Boolean
- TERRAggregation_DateTime
- TERRAggregation_Integer
- TERRAggregation_Real
- TERRAggregation_String
- TERRAggregation_TimeSpan

TERR_xxx 関数は、入力データの各行に対応する複数個の結果を算出するもので、TERRAggregation_xxx 関数は入力データの各行を集計した結果を算出します。

引数（共通）

TERR_xxx 関数とTERRAggregation_xxx 関数のいずれにも以下のように引数を指定します。

TERR_xxx("TERR式", 引数1, 引数2, 引数3, ...)

TERRAggregation_xxx("TERR式", 引数1, 引数2, 引数3, ...)

引数の説明：

"TERR式"の部分にはダブルクォーテーション（またはシングルクォーテーション）で囲んでTERR言語の計算式を書きます。
- 必須です。
- 式の出力は「output 」で表します。
- 式への入力は「input1」、「input2」、「input3」などで表します。
- 例：
  - output <- input1 + input2
  - output <- input1 * 100
  - output <- max(input1)
- 複数のコマンドの場合はセミコロンで区切って記載します。
- 式の文字数には特に制限はありません。ただし、文字数が多い場合は式の評価に時間がかかることが予想されます。
引数1、引数2、引数3には指定された順番で「input1」、「input2」、「input3」に対応する実際の入力値を指定します。
- - 必須です。（少なくとも1つ以上指定が必要）
  - カラムまたは固定値（数字、文字列など）を渡します。
    - 引数に固定値を渡した場合、その値が計算対象データの行数分で繰り返されます。
  - 引数の数には特に制限はありません。
    - ただし、引数の数が多すぎると、処理に時間がかかり、TERRがクラッシュする可能性があります。
    - 記事作成時の検証環境では5000個の引数を渡した場合に正しく計算できたことを確認できています。
  - 引数で渡されたデータ（Spotfire内のデータ型）はTERR内のデータ型に変換して使用されます。
    - Spotfire内のデータ型とTERR内のデータ型のマッピングについてはAnalyst のヘルプトピックスの以下の章を参照ください。
      - ツール ⇒ データ関数 ⇒ データ型のマッピング

注意事項：

TERR式内で指定された引数（input1、input2、…）の数と引数1、引数2、…の数は一致する必要があります。特にTERR式内で指定された引数の数が実際の引数よりも多い場合には正しく計算できません。

また、TERR_xxx 関数やTERRAggregation_xxx 関数は、対象データテーブル（計算カラムの場合）またはビジュアライゼーション（カスタム演算式の場合）に対して１回のみ計算されます。データの各行ごとに計算されるわけではありません。

TERR_xxx関数

TERR_xxx 関数の場合、TERR式の出力「output」は引数で指定された入力値と同じ長さのカラムになります。

例１

引数で指定されたカラムは配列としてTERR式に渡され、計算結果の配列が返されて元のデータに対応する各行に反映されます。通常はこちらのパターンになります。

下記例では「売上」カラムと100の掛け算を算出しています。

TERR_Real("output <- input1 *100",[売上])

例２

TERR式の算出結果「output」が単一値の場合、その値が最初の値とし、それ以降は計算対象データと同じ長さまで空白で埋めます。

下記例では「売上」カラムの全行値の合計を算出しています。「output」が単一値となっているため、算出結果が入力データの先頭行にのみ反映され、それ以降はすべて空白になります。

TERR_Real("output <- max(input1)",[売上])

例３

引数に固定値を渡した場合、その値が計算対象データの行数分で繰り返されます。

下記例では固定値「123」を引数として渡していますが、その値が計算対象データの全行に反映されます。

TERR_Real("output <- input1",123)

TERRAggregation_xxx関数

TERRAggregation_xxx 関数の場合、TERR式の出力「output」は単一値になり、その値が計算対象データの各行に反映されます。

例１

TERR式の出力「output」は単一値になり、その値が計算対象データの各行に反映されます。

下記例では「売上」の最大値を取得していて、その結果がすべての行に反映されます。

TERRAggregation_Real("output <- max(input1)",[売上])

例２

OVER関数と組み合わせて使うことも可能です。
下記例では「製品カテゴリ１」ごとに「売上」の合計を算出しています。算出された合計値が「製品カテゴリ１」ごとに反映されます。

TERRAggregation_Real("output <- sum(input1)",[売上]) over ([製品カテゴリ１])

例３

TERR式の出力「output」が単一値でない場合にはエラーが発生してしまい、正しく計算できません。

例：

TERRAggregation_Real("output <- input1 * 100",[売上])

エラーメッセージ：

Error in vapply(seq_len(envir$`_groupCount`), FUN = FUN, FUN.VALUE = : values must be length 1, but FUN(X[[1]]) result is length 8