カスタム関数

概要

カスタム関数は、XML形式で記述され、Yellowfinサーバに格納されている関数です。これらの関数は通常、式ビルダーでは作成することが難しい、高度なSQL文で構成されており、システム管理者により設定されます。

XMLスキーマは、カスタムSQL関数にパラメーターを組込むことができるため、レポートにカラム（列）を挿入する際に、数値やカラム値を割り当てることができます。

新規カスタム関数の追加

Yellowfinに新しくXML関数を追加する方法は、以下の通りです。

「Yellowfin/appserver/webapps/ROOT/WEB-INF/」配下にある、「custom-functions.xml」ファイルに、XMLをコピーします。
XMLをコピーしたら、Yellowfinを再起動して、これを利用可能にします。

Yellowfinでのカスタム関数の使用について、さらに詳細な情報が必要な際には、計算フィールドを参照してください。

スキーマ

親オブジェクト	オブジェクト	説明
	`<custom-function>`	最上位階層のオブジェクトであり、ドキュメント全体をカプセル化します。子タイプは、`<function>の`ひとつのみです。
`<custom-function>`	`<function>`	独自の関数を定義し、その関数の定義に必要なデータフィールドをカプセル化します。子オブジェクトは、`<name>`、`<argument>`、`<sql>`、`<return>` 、`<aggregate>`です。
`<function>`	`<name>`	nameには、アプリケーション内で表示するカスタム関数の名前を定義します。これは各カスタム関数のプライマリ識別子のため、それぞれにユニークな名前を付けなくてはいけません。各関数には、ひとつの名前しか付けることはできません。
`<function>`	`<argument>`	argumentには、レポート作成時にカスタムSQLに挿入する引数（または、パラメーター）を定義します。argumentは、`<index>`、`<name>`、`<datatype>の`3つの属性で定義されています。
`<argument>`	`<index>`	argumentのindexパラメーターは、関数のコンテキストで引数をユニークに特定するものであり、必ず正の整数値でなくてはいけません。indexは、カスタムSQL文内で定義された箇所に引数を挿入するために使用します。indexが「1」の場合、SQL文内のすべての「$1」を引数に置換します。
`<argument>`	`<name>`	argumentのnameパラメーターは、アプリケーションで表示する引数の名前です。
`<argument>`	`<datatype>`	argumentのdatatypeパラメーターには、引数のデータタイプを定義します。このパラメーターを指定すると、引数と互換性のあるカラム（列）や値のみ、入力することができます。データタイプは、以下のうちの、いずれかひとつを使用してください。 TEXT NUMERIC DATE TIME DATETIME TIMESTAMP GEOMETRY
`<function>`	`<sql>`	SQLには、このカスタム関数のために生成される実際のデータベースSQL文を定義します。このフィールド内のSQLは、単一のカラム（列）として親SQL文に挿入されるため、完全なSELECT FROM WHEREの構文は必要ありませんが、単一カラム（列）構文との互換性が必要です。以下に、単一カラム（列）カスタム関数の、シンプルなCASE WHEN ELSE ENDの例を示します。このSQLには、引数を挿入するための変数を含めることができます。「$1」は、index 1の引数を割り当てられらたカラム（列）やデータ値で置換されます。
`<function>`	`<aggregate>`	aggregateパラメーターには、カスタム関数内で、どのカラムを（列）を集約するかを定義します。このパラメーターを指定すると、レポートSQL作成時に、これらのカラム（列）をGROUP BY節に配置しないよう、アプリケーションに伝えることができます。aggregateパラメーター値は、引数変数として使用することもでき、例えば、index 1の場合は「$1」を記述します。
`<function>`	`<groupby>`	groupbyパラメーターには、アプリケーションがレポートSQLを作成する時に、どのカラム（列）をGROUP BY節に挿入すべきか定義します。group byパラメーター値は、引数変数として使用することもでき、例えば、index 1の場合は「$1」を記述します。
`<function>`	`<database>`	これは、どのデータベースで関数を使用可能にするかを指定します。何も指定しない場合は、すべてのデータベースで表示することが可能になります。複数のデータベースで表示させるためには、データベースごとに、ひとつのオブジェクトを定義するようにしてください。例としては、SQLServer、PostgreSQL、OpenEdge、Progress、Oracle、DB2、Access、Notes、ODBC、HSQL、MySQLがあります。
`<function>`	`<return>`	functionのreturnには、カスタム関数そのものが返す、データ型を定義します。データ型には、以下のうちの、いずれかのひとつを使用してください。 TEXT NUMERIC DATE TIME DATETIME TIMESTAMP GEOMETRY

CASE文の例

custom-functions.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<custom-functions>

<!-- functions are stored by name, so names must be unique, even across different databases -->
  
  <!-- ratio function -->
  <function>
    <name>Ratio</name>
    <argument>
      <index>1</index>
      <name>Numerator</name>
      <datatype>numeric</datatype> <!-- numeric, text, datetime -->
    </argument>
    <argument>
      <index>2</index>
      <name>Denominator</name>
      <datatype>numeric</datatype> <!-- numeric, text, datetime -->
    </argument>
    <sql>
      <![CDATA[
        CASE
          WHEN SUM($2) != 0 THEN SUM($1) / SUM($2)
          ELSE NULL
          END
      ]]>
    </sql>
    <aggregate>$1</aggregate>
    <aggregate>$2</aggregate>
    <database>SQLServer</database> <!-- Available for what DBs? SQLServer, PostgreSQL, OpenEdge, Progress, Oracle, DB2, Access, Notes, ODBC, HSQL, MySQL -->
    <database>HSQL</database>
    <return>numeric</return> <!-- numeric, text, datetime -->
  </function>

</custom-functions>