...
コネクターデータセットは、抽象Java class AbstractDataSetの実装です。データセットを定義するためには、以下の関数を実装しなくてはいけません。
上書き可能なその他の関数です。
上書き可能な、その他の関数です。
データセット関数の定義
public abstract String getDataSetName();
DataSetNameをStringとして返します。これは国際化してはいけません。
public abstract List<ColumnMetaData> getColumns();
このデータセットで使用できるカラム（列）を定義するColumnMetaDataオブジェクトのcollectionを返します。カラム（列）は、フィルターとして使用するように定義することもできます。データセットで使用できるカラム（列）を定義するColumnMetaDataオブジェクトのcollectionを返します。カラム（列）は、フィルターとして使用されるように定義することもできます。
ColumnMetaDataオブジェクトは、以下のメタデータの定義が必要です。
属性 | 説明 |
|---|---|
columnName | カラム（列）の名前です。これは一意であり、国際化してはいけません。ユーザーフレンドリーな名前や国際化はYellowfinのメタデータレベルで適用することができます。カラム（列）の名前です。これは一意であり、国際化してはいけません。ユーザーフレンドリーな名前や国際化は、Yellowfinのメタデータレベルで適用することができます。 |
columnType | カラム（列）のデータ型です。カラム（列）のDataTypeです。より詳細な情報は、付録のデータ型を参照してください。 より詳細な情報は、付録のDataTypeを参照してください。 |
fieldType | カラム（列）のフィールド型です。カラム（列）のFieldTypeです。より詳細な情報は、付録のフィールド型を参照してください。 より詳細な情報は、付録のFieldTypeを参照してください。 |
availableAggregations | 集約型の配列です。これは、このカラム（列）に適用可能な集約を定義します。AggregationTypeの配列です。このカラム（列）に適用可能な集約を定義します。より詳細な情報は、付録の集約型を参照してください。 より詳細な情報は、付録のAggregationTypeを参照してください。 |
availableFilterOperators | フィルター演算子の配列です。これは、このカラム（列）がフィルターとして使用される場合に、適用できる演算子を定義します。このカラム（列）をフィルターとして使用できない場合は、「null」に設定しなくてはいけません。 より詳細な情報は、付録のフィルター演算子を参照してください。 |
...
FilterOperatorの配列です。このカラム（列）がフィルターとして使用される場合に、適用できる演算子を定義します。このカラム（列）をフィルターとして使用できない場合は、「null」に設定しなくてはいけません。 より詳細な情報は、付録のFilterOperatorを参照してください。 |
ColumnMetaDataには複数のconstructorがあり、このオブジェクトをJavaコードの一行で定義することができます。
public abstract List<FilterMetaData> getFilters();
このデータセットで使用できるフィルターを定義するFilterMetaDataオブジェクトのcollectionを返します。このコンテキスト内のフィルターはレポートにしようできるパラメーターであり、カラム（列）のようにデータを返すことはありません。データセットで使用できるフィルターを定義するFilterMetaDataオブジェクトのcollectionを返します。このコンテキスト内のフィルターはレポートに使用できるパラメーターであり、カラム（列）のようにデータを返すことはありません。
FilterMetaDataオブジェクトは、以下のメタデータの定義が必要です。
属性 | 説明 |
|---|---|
filterName | フィルターの名前です。 これは一意であり、国際化してはいけません。ユーザーフレンドリーな名前や国際化はYellowfinのメタデータレベルで適用することができます。 |
filterType | カラム（列）のフィルター型です。カラム（列）のFilterTypeです。より詳細な情報は、付録のフィールド型を参照してください。 より詳細な情報は、付録のFilterTypeを参照してください。 |
Mandatory | このフィルターが必須かどうかを定義します。このフィルターを設定することなくこのデータセットからデータを返すことはできません。このフィルターが必須かどうかを定義します。このフィルターを設定することなく、このデータセットからデータを返すことはできません。 |
availableAggregations | 集約型の配列です。これは、このフィルターに適用可能な集約を定義します。現状はサポートされていません。AggregationTypeの配列です。このフィルターに適用可能な集約を定義します。現状はサポートされていません。より詳細な情報は、付録の集約型を参照してください。 より詳細な情報は、付録のAggregationTypeを参照してください。 |
availableOperators | フィルター演算子です。これは、このフォルターに適用可能な演算子を定義します。FilterOperatorの配列です。このフォルターに適用可能な演算子を定義します。より詳細な情報は、付録のフィルター演算子を参照してください。 より詳細な情報は、付録のFilterOperatorを参照してください。 |
FilterMetaDataには複数のconstructorがあり、このオブジェクトをJavaコードの一行で定義することができます。
public abstract boolean authenticate() throws Exception;
データソースに対する認証が成功したかどうかに応じて、trueまたはfalseを返します。これが必須でない場合は、trueを返します。
public abstract void disconnect();
「disconnect()」は、コネクターへの接続が閉じられた時に呼び出されます。ここでクリーンアップを実行します。この関数は必須ではない場合、何もできません。
public abstract Map<String, Object> testConnection() throws Exception
成功した接続テストで表示されるテキストエントリーのマップを返します。マップへのキーは、Yellowfin UI内の接続テストに表示される説明です。
接続テストに失敗した場合は、エラーメッセージが表示されます。この場合のマップのキーは「ERROR」で、マップ値に保存されているエラーの説明でなくてはいけません。
...
| Anchor | ||||
|---|---|---|---|---|
|
public abstract Object[][] execute(List<ColumnMetaData> columns, List<FilterData> filters);
このコネクターのためにバックグラウンドタスクを実行しなくてはいけない場合の、ScheduleDefinitionを返します。ScheduleDefinitionは、以下のようにインスタンス化されます。このデータセットからの結果セットを返します。これがクエリーを処理するための主要な関数です。パラメーターカラム（列）は、クエリーのためにYellowfinから選択されるカラム（列）を指定します。パラメーターフィルターは、Yellowfinからクエリーへ割り当てられるフィルターを指定します。関数は、リクエストされたカラム（列）のコンテンツとともに、二次元オブジェクト配列を返さなくてはいけません。
| Code Block | ||
|---|---|---|
| ||
public ScheduleDefinition(FrequencyTypeCode frequencyTypeCode, String frequencyCode, Integer frequencyUnit); |
各frequencyTypeCode は、以下のように定義されます。nを必要とするタイプの場合、値はfrequencyUnitで定義されます。
frequencyUnit | 説明 |
|---|---|
MINUTES | 毎n分に実行します。 |
DAILY | 毎日実行します。 |
WEEKLY | 週次で、n曜日に実行します。 |
FORTNIGHTLY | 二週間に一度、frequencyCodeのONE、またはTWOで二週間のうちのどちらの週かを指定し、n曜日に実行します。 |
MONTHLY | 月次で、n日に実行します。 |
ENDOFMONTH | 月末に実行します。 |
QUARTERLY | 三ヶ月に一度、frequencyCodeのONE、TWO、THREEで三ヶ月のうちのどの月かを指定し、その月のn日に実行します。 |
BIANNUAL | 六ヶ月に一度、frequencyCodeのONE、TWO、THREE、FOUR、FIVE、SIXで半年のうちのどの月かを指定し、その月のn日に実行します。 |
ANNUAL | 年次で、frequencyCodeのJANUARY、FEBRUARY、MARCH、APRIL、MAY、JUNE、JULY、AUGUST、SEPTEMBER、OCTOBER、NOVEMBER、DECEMBERで一年のうちからどの月に実行するかを指定し、その月のn日に実行します。 |
例えば、毎週日曜に実行されるバックグラウンドタスクのスケジュールを作成する場合は、以下の通りです。
| Code Block | ||
|---|---|---|
| ||
public ScheduleDefinition getScheduleDefinition() {
return new ScheduleDefinition("WEEKLY", null, 1);
} |
毎時実行されるバックグラウンドタスクのスケジュールを作成する場合は、以下の通りです。
| Code Block | ||
|---|---|---|
| ||
public ScheduleDefinition getScheduleDefinition() {
return new ScheduleDefinition("MINUTES", null, 60);
} |
public boolean autoRun();
「autoRun」は、バックグラウンドタスクを実行するための呼び出しです。この関数は、「getScheduleDefinition()」に基づき呼び出されます。これは、ローカルでのデータのダウンロードやキャッシュに使用されることもあります。
...
protected final byte[ ] loadBlob(String key);
「loadBlob()」は、コネクターにより以前に保存された「blob(byte[])」を、通常バックグラウンドタスクで読み込みます。パラメーターキーは、データを読み込むための一意の識別子です。Blobは、保存されたデータソース上でのみ読み込むことができます。「areBlobsAvailable()」を使用して、blobアクセスが使用可能かどうかを確認することができます。
...
protected final boolean saveBlob(String key, byte[ ] data);
「saveBlob()」 は、後で使用するためにblob(byte[])を保存することができます。これは、あとで使用するためにバックグラウンドタスクからのデータを保存する方法です。パラメーターキーは、保存されるデータに一意の識別子です。デーはそのキーに関連するbyte[]です。データへのnullの記述は、指定されたキーに保存されたデータを削除します。Blobは、保存されたデータソース上でのみ読み込むことができます。「areBlobsAvailable()」を使用して、blobアクセスが使用可能かどうかを確認することができます。
protected final boolean areBlobsAvailable();
Blobは、保存されたデータソース上でのみ読み込むことができます。「areBlobsAvailable()」を使用して、blobアクセスが使用可能かどうかを確認することができます。Blobアクセスは、保存される前にコネクターがテストされている場合は使用することができません。
public final Object getAttribute(String key);
「getAttribute()」は、接続メータデータから属性をフェッチすることができます。例えば、Yellowfin UIを通して接続にユーザー名を指定することができます。パラメーターのキーを使用することで、ユーザー名メタデータフィールドのコンテンツは、外部APIからのデータ取得時にフェッチすることができます。
public final Integer getSourceId();
「getSourceId()」は、コネクターの関連するソースの一意の内部IDをフェッチするために使用することができます。これは、ある種の外部キャッシュや、データベースでの接続によるデータの分離に役立ちます。
saveBlob()、およびloadBlob() 使用時の推奨事項
保存された・キャッシュされたデータの最小化
外部ソースから確実に取得することのできないデータのみの保存を推奨します。これは、限られた量の履歴データしか利用できないデータへの「スライディングウィンドウ」アクセスであり、利用不可能になる前にダウンロードしなくてはいけません。非常に遅いデータセットも、クエリー速度を向上させるために、ローカルに保存されたデータセットを使用することができます。
膨大な量のデータをblobシステムに保存する場合は、一定期間後にデータを切り捨てることを推奨します。これは、特定の日数に達したすべてのデータを削除したり、古いデータに対して粒度の細かいデータを保存することを意味します。例えば、ローデータは三ヶ月、日次集約データは一年保存し、古いデータの週次集約データを保存します。これを実行するためには、バックグラウンドジョブでデータを再集約し、再保存しなくてはいけません。
Blobサイズの最小化
サイズの大きなBlobを保存し、読み込む場合、Yellowfinデータベースやサーバに多大な負荷がかかります。可能であれば、複数のblobに対して保存されたデータを分散させます。
例えば、blob保存システムに100,000ツイートが保存されたインスタンスがあるとします。これは、「ALL_TWEETS」というキーとともに保存されているでしょうが、blobの読み込み時間を最小化し、キャッシュシステムに過負荷をかけないようにするために、より小さなかたまりに分割し、保存をします。
方法のひとつして、月次でツイートを分割します。
「201601_TWEETS」
「201602_TWEETS」
「201603_TWEETS」
「201604_TWEETS」
コネクターからクエリーがリクエストされた場合、フィルターを使用して、どのBlobを使用する必要があるのかを決定し、Blob保存システムから読み込むことができます。例えば、2016-02-05 〜 2016-03-05という特定の日付範囲を持つクエリーは、「201602_TWEETS」と「201603_TWEETS」という2月と、3月のデータを読み込むだけで構いません。
blobからデータセットを結合するためには、膨大なオーバーヘッドが要求されるかもしれません。これを考慮し、複数の小さなblobと、ひとつの大きなblobのパフォーマンスを比較することを推奨します。
blobに最適なサイズはありません。Yellowfinデータベースからblobを読み込む速度は、使用しているハードウェアとDBMSに依存します。公開コネクターはすべてのサイズのYellowfinインストールに使用されるため、小さく、微力なシステムを考慮する必要があります。
アプリケーションレベルフィルターと集約
Yellowfinは、アプリケーションレベルのフィルター適用と集約をサポートします。これは、コネクターから結果セットを取得した後のデータを集約し、フィルター適用することができます。
アプリケーションレベルの集約は、コネクターの機能に基づき切り替えられます。（getColumns()により返される）任意のデータセットカラム（列）が、集約（コネクターが集約されたデータを返す）をサポートする場合、集約を使用することができます。
アプリケーションレベルフィルターは、コネクター内のカラム（列）の機能に基づき切り替えられます。（getColumns()により返される）任意のデータセットカラム（列）が、フィルター（コネクターが独自のフィルターを適用）をサポートする場合、アプリケーションレベルフィルターは無効化され、コネクターカラム（列）フィルターのみ使用することができます。コネクターフィルター（getFilters()により返される）は、アプリケーションレベルフィルターと共存することができます。
カスタムエラーメッセージ
コネクターレポート実行時にエラーが発生した場合に、Yellowfin UIへカスタムメッセージを返すことができます。これは、コネクタープラグインからのカスタムメッセージを「ThirdPartyException()」へ投入することで実行できます。
| Code Block | ||
|---|---|---|
| ||
throw new ThirdPartyException("Unable to connect to the Twitter API at this time."); |
カスタムエラーメッセージは、通常、レポートがレンダリングされる標準の「Oh No」エラーとして表示されます。これは通常、データセットの「execute()」関数から投入されます。
| Section | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
パラメーターカラム（列）の型はColumnMetaDataです。これは、選択されたカラム（列）に関する情報と、これらのカラム（列）に作成された集約修飾子が含まれます。
ColumnMetaData関数「getSelectedAggregation()」は、カラム（列）に適用された集約を返します。この型は、AggregationTypeです。
パラメーターフィルターの型は、FilterDataです。これは、選択されたフィルターに関する情報と、それらに割り当てられた値が含まれています。
FilterDataには以下の属性があります。
属性 | 説明 |
|---|---|
filterName | このフィルターが表すフィルター、またはカラム（列）の名前です。 |
metaData | フィルターのFilterMetaDataです。これは、getFilters()、またはフィルター適用をサポートするカラム（列）をまとめるために自動的に作成されるFilterMetaDataオブジェクト内で定義されたFilterMetaDataオブジェクトとリンクします。 |
filterValue | フィルターの値です。これは、フィルターのデータ型のデータを保持するJavaオブジェクトです。複数の値を保持するフィルターは、Java一覧内に返されます。これは、の間（〜）、の間ではない、一覧に含む、一覧に含まないを演算子に使用するフィルターのためにあります。 |
filterOperator | FilterOperator型のインスタンスです。このフィルターに適用された演算子を定義します。 |
aggregationType | AggregationOperator型のインスタンスです。このフィルターに適用された集約を定義します。 |
ThirdPartyException()投入時にエラーが発生した場合に、カスタムエラーメッセージを表示させることができます。より詳細な情報は、カスタムエラーメッセージを参照してください。
public abstract boolean getAllowsDuplicateColumns();
このデータセットが、1回以上選択された同一のカラム（列）をサポートするかどうかを返します。
trueが返された場合、データセットは必要に応じて、実行関数を介して複製されたカラム（列）を送信します。
falseに設定された場合は、各カラム（列）の単一のインスタンスのみが実行関数へ送信され、Yellowfinはデータ受領後に繰り返されるカラム（列）を複製します。
public abstract boolean getAllowsAggregateColumns();
このデータセットが集約をサポートするかどうかを返します。
falseの場合、Yellowfinはアプリケーションレベルの集約を行うことができません。Yellowfinは、データセットからデータが返された後に集約を行います。
trueの場合は、データセットはリクエストに応じて集約されたデータを返さなくてはいけません。カラム（列）は、レポート作成時にどの集約を適用することができるのかを定義することができます。これは、「getColumns()」で定義されます。
public boolean isFilterValueEnabled(String filter);
フィルター値が特定のフィルター（または、カラム（列）フィルター）へ返すことができるかどうかを定義します。trueの場合は、「getFilterValues()」を呼び出し、このフィルターの値の一覧を返します。
public List<Object> getFilterValues(String filter, HashMap<String, FilterData> appliedFilters);
「isFilterValueEnabled()」が、与えられたフィルター名にtrueを返す場合、この関数はユーザー選択で利用可能なフィルターオプションのJava一覧を返すために呼び出されます。パラメーター「appliedFilters」は、現在設定されている他のフィルターの値を保持するマップ（フィルター名によるキー）を保持します。この情報は、この関数により返される値をさらに制限するために使用することができます。
前項：データソースの定義
後項：コネクターのパッケージ化