データソース関数一覧

コネクターデータソースは、抽象Java class AbstractDataSourceの実装です。データソースを定義するためには、以下の関数を実装しなくてはいけません。

public abstract String getDataSourceName();
public abstract Collection<AbstractDataSet> getDataSets();
public abstract JDBCMetaData getDataSourceMetaData();
public abstract boolean authenticate() throws Exception;
public abstract void disconnect();
public abstract Map<String, Object> testConnection() throws Exception

以下の関数は、オプションで上書きすることができます。

public ScheduleDefinition getScheduleDefinition();
public boolean autoRun();

以下の関数は、ユーティリティ関数として使用することができます。

protected final byte[ ] loadBlob(String key);
protected final boolean saveBlob(String key, byte[ ] data);
protected final boolean areBlobsAvailable();
public final Object getAttribute(String key);
public final Integer getSourceId();

データソース関数の定義

public abstract String getDataSourceName();

DataSourceNameをStringとして返します。

public abstract Collection<AbstractDataSet> getDataSets();

このデータソースで使用できるデータセットのcollectionを返します。データセットの定義については、データセット項目を参照してください。

public abstract JDBCMetaData getDataSourceMetaData();

このデータソースに必要なcollectionメタデータを返します。データソースのメタデータの定義については、メタデータ項目を参照してください。

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」で、マップ値に保存されているエラーの説明でなくてはいけません。

public ScheduleDefinition getScheduleDefinition();

このコネクターのためにバックグラウンドタスクを実行しなくてはいけない場合の、ScheduleDefinitionを返します。ScheduleDefinitionは、以下のようにインスタンス化されます。

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日に実行します。

例えば、毎週日曜に実行されるバックグラウンドタスクのスケジュールを作成する場合は、以下の通りです。

public ScheduleDefinition getScheduleDefinition() {
 
        return new ScheduleDefinition("WEEKLY", null, 1);
 
}

毎時実行されるバックグラウンドタスクのスケジュールを作成する場合は、以下の通りです。

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()」へ投入することで実行できます。

throw new ThirdPartyException("Unable to connect to the Twitter API at this time.");

カスタムエラーメッセージは、通常、レポートがレンダリングされる標準の「Oh No」エラーとして表示されます。これは通常、データセットの「execute()」関数から投入されます。

前項：コネクターメタデータの定義

後項：データセットの定義