式のプロパティ

Spotfire で使用できるプロパティには、式で使用したり、さまざまな設定を制御するのに使用したりできる、3 つのタイプがあります。ドキュメントプロパティ、データテーブルプロパティ、カラムプロパティです。プロパティは、2 つの異なる方法で解釈できます。つまり、実際の値として、またはカラム名または統計量の代わりに使用できるテキスト値として解釈できます。

さまざまなタイプのプロパティに関する一般的な情報については、「文書のプロパティ、カラムのプロパティ、およびデータテーブルのプロパティ」を参照してください。

注: ここで説明する機能の一部は、インストールされた Spotfire クライアントを使用してのみ作成またはアクセスできます。 Web クライアントで言及されているすべての式を記述できますが、インストール済みクライアントには、ブラウザで使用できないショートカットとインターフェイスがいくつかあります。

テキストとして挿入

カラム名または統計量として解釈される必要がある式内で文字列プロパティを使用する場合、特定の構文を使用する必要があります。これは、プリプロセッサ式と呼ばれることもあります。

注: この機能は、テキストエリア (インストール済みクライアントのみ) に文書プロパティコントロールを簡単に追加し、ダッシュボードユーザーがこれらのコントロールを使用してカラムなどを変更したり、分析でのビジュアライゼーションを更新したりできるようにするために導入されました。式でプロパティの値を使用するだけの場合は、代わりに以下の「値として挿入」を参照してください。プリプロセッサ式を使用する代わりに、DocumentProperty() などの標準プロパティ関数を使用して式を記述できる場合は、これが一般的に推奨されます。

テキストとして挿入する場合、プロパティの名前は、"${" および "}" で囲む必要があります。したがって、文書プロパティの場合は、${MyProperty}を使用して検索するときに使用できるメタデータです。データテーブルプロパティの場合は、${My Data Table}.{MyProperty}を使用して検索するときに使用できるメタデータです。カラムプロパティの場合、カラム名も必要です。${My Data Table}.{Column Name}.{MyProperty}を使用して検索するときに使用できるメタデータです。

注: 自動的に追加されたプリプロセッサ構文で使用される項目に変更が必要な場合は、式を手動で更新する必要があります。たとえば、プリプロセッサ式で使用されるカラムまたはデータテーブルの名前が変更された場合 (たとえば、式 [MyColumn] * ${Multiplier} があり、MyColumn の名前が変更された場合)、新しい名前を使用するには式を手動で更新する必要があります。これは、プリプロセッサ ($-syntax) を使用する式は、値として使用されるプロパティとは異なり、カラム名やデータテーブル名などの個々の部分に自動的に分解できないためです。プリプロセッサは、解析または型チェックが実行される前にテキストを処理するため、そのような文字列のどの部分がカラム名で、どの部分がカラム名でないかを知ることはできません。ただし、プリプロセッサを使用すると、他の方法では記述が困難または不可能な式を記述できます。


式でのプロパティ呼び出し	説明
`${MyProperty}`	MyProperty という文書プロパティを表します。
`${My Data Table}.{MyProperty}`	データテーブル "My Data Table" で定義された MyProperty というデータテーブルプロパティを表します。
`${My Data Table}.{Column Name}.{MyProperty}`	データテーブル "My Data Table" のカラム "Column Name" で定義された MyProperty というカラムプロパティを表します。
`$map("template", "concatenation string")`	`$map()` 関数は、リスト値のプロパティを 1 つの文字列にマップするために使用します。1 つ目の引数はリスト内の値ごとに使用されるテンプレートであり、2 つ目の引数はリスト値を結果の式に関連付ける方法を指定するものです。詳細については、下記の「リスト値のプロパティ (複数選択)」を参照してください。例: `$map("sum([${PropertyName}])", ",")` `<$map("[${PropertyName}]", "NEST")>`
`$esc(expression)`	カラム名に含まれる "]" を "]]" に置換して、エスケープされるカラム名を "[" および "]" で囲みます。引数は、プロパティ値になる式、またはドル記号 ($) で始まるプロパティ関数になる式です。例: `$esc(${MyProperty})` `$esc($csearch([Data Table], "Col*"))`
`$csearch([Data Table], "search string")`	`$csearch()` 関数は、検索の制限式を使用して、データテーブルから多数のカラムを選択する場合に使用します。1 つ目の引数はデータテーブルで、2 つ目の引数は返されるカラム名を決定する検索式を含む文字列です。この関数によって、検索式に一致した (エスケープされていない) カラム名のリストがデータテーブルから返されます。例: `$csearch([Data Table],"")` `$csearch([Data Table], "Col")`

式で $ 記号が検出されると、実際の式が評価される前にプロパティがその対応する値で置換されます (プリプロセッシングステップ)。つまり、${Property1}-${Property2} のような式を入力し、Property1 の値がカラム名 Column1、Property2 の値が Column2 の場合、結果の式は次のようになります。[Column1]-[Column2]を使用して検索するときに使用できるメタデータです。

プロパティ値をカラム名ではなく、リテラル文字列値として解釈されるようにする場合、プロパティ呼び出しを引用符で囲む必要があります。たとえば、値 "MyValue" を持つ "MyProperty" というプロパティがある場合、式 ${MyProperty} は、結果として式 MyValue を返します。この場合、"MyValue" というカラムが取得されます。しかし、式 "${MyProperty}" は、代わりにテキスト文字列 "MyValue" を返します。文字列値が複数の単語 (「My Value」など) で構成されている場合、カラムを返すためには、$esc() を使用するか、次のようにプロパティ式を括弧で囲んでカラムを返す必要があります: [${MyProperty}].カラム名の詳細については、「演算式言語の詳細」を参照してください。

常に式の正しい構文を使用することが非常に重要です。そうしないと、最終的に得られる結果が期待していたものと異なる可能性があります。式で文字列が想定されている場合に、カラムとしてプロパティが挿入されると、指定したカラムの最初の値が取得されます。文字列カラムの場合、結果は有効な式になる可能性がありますが、別のデータ型のカラムの場合、エラーが表示される可能性があります。

インストールされたクライアントで、[計算カラムの追加] ダイアログまたは [カスタム演算式] ダイアログの [プロパティの挿入] ボタンを使用してプロパティを挿入する場合、そのプロパティは、テキスト (プリプロセッサ) 構文を使用して自動的に追加されます。

[カラムに使用できるプロパティ] フィールドのプロパティを右クリックして、ポップアップメニューから [テキストとして挿入] を選択することもできます。

カラム名を含むプロパティを軸で使用する場合、[プロパティから設定] というショートカットをカラムセレクターのポップアップメニューから使用することができます (インストールされたクライアントのみ)。自動的に追加された構文を変更する必要がある場合は、[カスタム演算式] ダイアログを使用して式を変更する必要があります。軸からプロパティ式を削除する場合は、カラムセレクターを右クリックして、[すべて削除] を選択します。

プロパティは、集計統計量を指定する場合にも使用できます。たとえば、既定値 ”sum” を使用して MyMeasure というプロパティを定義できます。このようなプロパティを式で使用する場合、式の必要な場所に丸かっこと統計量の引数を手動で追加する必要があります。軸の式で使用できる固定された集計統計量のリストを表示するプロパティセレクターをテキストエリアに作成でき、Web クライアントユーザーがそのプロパティセレクターを使用して軸の式を変更できるようにすることができます。

ほとんどの場合、テキストとして挿入された文字列プロパティはカラム名として解釈されるため、カスタム演算式の作成時は、期待した結果にならない場合があります。文字列プロパティが (条件式などで) 値として解釈される場合、引用符で囲む必要があります。たとえば、Sum(if(([Product])=("ProductA"),[Quantity],null)), のような軸の式条件で使用される文字列 "ProductA" を文書プロパティに置換する場合、式を機能させるには、文書プロパティを引用符で囲む必要があります。

Sum(if ([Product] = "${MyProduct}",[Quantity],null))

プロパティをテキストではなくて関数として挿入しても、同じ結果を得ることができます (下記の「値として挿入」も参照)。

Sum(if ([Product] = DocumentProperty("MyProduct"),[Quantity],null))

値として挿入

プロパティの値が式の一部になる場合は、標準のプロパティ関数を使用することをお勧めします。ColumnProperty()、DataTableProperty() および DocumentProperty() を使用して、プロパティ名をカプセル化します。たとえば、この構文を使用して、変換が必要な一部の通貨で指定される通貨換算レートと値カラムの積を保持する文書プロパティを持つ式を記述します。

DocumentProperty("ExchangeRate")*[Value Column]

プロパティ関数を適用する場合、プロパティ名は、常に引用符内に記述する必要があります。インストールされたクライアントを使用するときにプロパティが値として解釈されるようにする場合、[カラムに使用できるプロパティ] フィールドのプロパティを右クリックして、ポップアップメニューから [値として挿入] を選択することができます。

当然ながら、プロパティの構文を直接手動で入力または編集することもできます。

リスト値のプロパティ (複数選択) – インストールされたクライアントのみ

複数選択プロパティ (リスト値のプロパティ) は、1 つの値ではなく値のリストに基づいています。それらのプロパティは、テキストエリアでリストボックス (複数選択) プロパティコントロールを定義する際に作成できます (インストールされたクライアントのみ)。リスト値のプロパティは、通常の単一値のプロパティが適用できるすべての場所で使用できるとは限りませんが、軸で複数のカラムを指定するには効率的な方法です。

多くの場合、リスト値のプロパティを式で使用する際には、さらに手動の作業が必要になります。ただし、ほとんどの場合、[プロパティの挿入] ボタンを使用してプロパティを挿入する際に、現在のコンテキストで式がどのように表されるべきかのヒントが得られます。

リスト値のプロパティをテキストとしてカスタム演算式に追加する場合 (たとえば、ラインチャートの Y 軸や棒グラフの値軸のような連続した軸で) 、構文は $map("sum([${PropertyName}])", ",") のようになります。この例では、既定の集計が "sum" に設定されているため、別の集計を使用する場合は、式を手動で編集する必要があります。連結文字列は、コンマに設定されています。したがって、各リスト値は別々のカラムとして解釈される必要があります。PropertyName プロパティに3 つのカラム "ColumnA"、"ColumnB" および "ColumnC" を持つリストが含まれる場合、展開後の結果の式は sum([ColumnA]),sum([ColumnB]),sum([ColumnC]) となります。連結文字列を "+" に変更すると、軸にはリストに含まれるすべてのカラムの値の合計が表示されます。sum([ColumnA])+sum([ColumnB])+sum([ColumnC])を使用して検索するときに使用できるメタデータです。

カテゴリ軸 (ラインチャートの X 軸や棒グラフのカテゴリ軸など) では、計算値ではなく階層を表示することが望ましいです。その場合は、map 式では、山かっこ "<>" と、NEST または CROSS を使用して、表示する組み合わせを定義する必要があります。次に例を示します。

<$map("[${PropertyName}]", " NEST")>

代わりの選択肢 NEST および CROSS の詳細については、「演算式言語の詳細」を参照してください。

注: いつもと同様に、複数のカラムを持つ式を設定する場合は、使用するカラムがすべて同じタイプであり、式の残り部分と一致することを確認する必要があります。たとえば、いくつかの軸ではカテゴリカラムと連続カラムを一緒に使用することはできません。また、任意のタイプの集計を使用して式でカテゴリカラムを使用することもできません。

その他の式の例

他に何も記述されていない限り、以下の式の例では、“Column 1”、”Column 2”、および “Sales” という 3 つの整数カラムを含む "Data Table" というデータテーブルがあるとします。

Column 1, Column 2, Sales
1,2,3
4,5,6


要求した結果	式の例	結果の式
Data Table というデータテーブルに含まれるすべての整数カラムを合計する。	`$map("sum([$csearch([Data Table],"datatype:int")])","+")`	`sum([Column 1])+sum([Column 2])+sum([Sales])`
Data Table というデータテーブルに含まれるすべてのカラムのリストを返す。	`$csearch([Data Table],"*")`	`Column1,Column 2,Sales`
値 "Column name with bracket (])" を指定したプロパティ (MyProperty) から、エスケープされたカラム名を返す。	`$esc(${MyProperty})`	`[Column name with bracket (]])]`
リスト値のプロパティ式を入力としてデータ関数に使用する。この例では、プロパティ MyListProperty に 3 つのカラム名Column 1、Column 2、および Sales が含まれている。	`$map("[Data Table].[${MyListProperty}]", ",")`	`[Data Table].[Column 1],[Data Table].[Column 2],[Data Table].[Sales]`
軸で複数のカラムを使用する。ここでは、プロパティコントロールを介してこれらのカラムの 1 つを取得する。この例では、プロパティ MyProperty に値 Column 2 が含まれる。	`[Column 1],[${MyProperty}]` または `<[Column 1] NEST [${MyProperty}]>` または `Sum([Column 1]), Sum(${MyProperty}])` など。	`[Column 1],[Column 2]` または `<[Column 1] NEST [Column 2]>` または `Sum([Column 1]), Sum(Column 2])` など。
リスト値のプロパティを使用して軸の複数のカラムの表示名を変更する。この例では、プロパティ MyListProperty に 3 つのカラム名Column 1、Column 2、および Sales が含まれている。	`$map("Sum([${MyListProperty}]) as [${MyListProperty}]", ",")` 式に含まれるすべてのリスト値のプロパティは、同じサイズでなければならない。	`Sum([Column 1]) as [Column 1],Sum([Column 2]) as [Column 2],Sum`