第17章 クエリー

クエリーモジュールは Lucene クエリー上で構築されるため、ユーザーはすべての Lucene クエリータイプを使用できます。クエリーが構築されると、Infinispan Query は org.infinispan.query.CacheQuery をクエリー操作 API として使用して、さらにクエリー処理を続行します。

Lucene API では、クエリーパーサー (簡単なクエリー) または Lucene プログラム API (複雑なクエリー) を使用します。詳細は、Lucene のオンラインドキュメント Lucene in Action または Hibernate Search in Action を参照してください。

Infinispan Query は構築後に HQL や Criteria クエリーと同様に実行できます。同じパラダイムとオブジェクトセマンティックが Lucene クエリーおよび list() などの一般的な操作すべてに適用されます。

list() を使用すると妥当な数の結果を受信し (たとえば、ページネーションを使用する場合など)、すべてに対応することができます。 list() は batch-size エンティティーが適切に設定されている場合に最適に動作します。list() が使用されると、クエリーモジュールはページネーション内ですべての Lucene Hits 要素を処理します。

ユースケースによっては、一致するドキュメントの合計数に関する情報が必要になります。以下の例について考えてみましょう。

一致するドキュメントをすべて読み出すには大量のリソースを消費します。Lucene ベースのクエリー API は、ページネーションのパラメーターに関係なく、一致するドキュメントをすべて読み出します。一致するドキュメントをすべて読み出すには大量のリソースが必要であるため、Lucene ベースのクエリー API はページネーションのパラメーターに関係なく、一致するドキュメントの合計数を読み出しできます。一致するすべての要素は、オブジェクトのロードを発生せずに読み出されます。

CacheQuery cacheQuery = Search.getSearchManager(cache).getQuery(luceneQuery,
                Book.class);
//return the number of matching books without loading a single one
assert 3245 == cacheQuery.getResultSize();

CacheQuery cacheQueryLimited =
        Search.getSearchManager(cache).getQuery(luceneQuery, Book.class);
cacheQuery.maxResults(10);
List results = cacheQuery.list();
assert 10 == results.size();
//return the total number of matching books regardless of pagination
assert 3245 == cacheQuery.getResultSize();

インデックスが適切にデータベースと同期されていない場合、結果の数は近似値になります。この場合の例の 1 つとして非同期クラスターが挙げられます。

Luke を使用すると、想定されるクエリー結果で結果が表示される (または表示されない) 理由を判断できます。また、クエリーモジュールは指定の結果 (指定のクエリーの) に対する Lucene Explanation オブジェクトも提供します。 これは上級クラスです。次のように Explanation オブジェクトにアクセスします。

Apache Lucene は、カスタムのフィルター処理に従ってクエリーの結果をフィルターすることができます。これは、フィルターをキャッシュおよび再使用できるため、データの制限を追加で適用する強力な方法です。該当するユースケースには以下が含まれます。

Lucene ベースのクエリー API には、パラメーターが含まれる filters という名前の透過キャッシュが含まれます。この API は Hibernate Core フィルターと似ています。

cacheQuery = Search.getSearchManager(cache).getQuery(query, Driver.class);
cacheQuery.enableFullTextFilter("bestDriver");
cacheQuery.enableFullTextFilter("security").setParameter("login", "andre");
cacheQuery.list(); //returns only best drivers where andre has credentials

この例では、クエリーで 2 つのフィルターが有効になっています。フィルターを有効または無効にしてクエリーをカスタマイズします。

@FullTextFilterDef アノテーションを使用してフィルターを宣言します。このアノテーションは、フィルターのクエリーに関係なく @Indexed エンティティーに適用されます。フィルター定義はグローバルであるため、各フィルターに一意な名前を付ける必要があります。同じ名前を持つ 2 つの @FullTextFilterDef アノテーションが定義された場合、SearchException が発生します。名前の付いた各フィルターにはそのフィルター実装を指定する必要があります。

@FullTextFilterDefs({
    @FullTextFilterDef(name = "bestDriver", impl = BestDriversFilter.class),
    @FullTextFilterDef(name = "security", impl = SecurityFilterFactory.class)
})
public class Driver { ... }

public class BestDriversFilter extends org.apache.lucene.search.Filter {

    public DocIdSet getDocIdSet(IndexReader reader) throws IOException {
        OpenBitSet bitSet = new OpenBitSet(reader.maxDoc());
        TermDocs termDocs = reader.termDocs(new Term("score", "5"));
        while (termDocs.next()) {
            bitSet.set(termDocs.doc());
        }
        return bitSet;
    }
}

BestDriversFilter はドライバーへの結果セットを減らす Lucene フィルターで、スコアは 5 になります。この例では、フィルターは直接 org.apache.lucene.search.Filter を実装し、引数がないコンストラクターが含まれます。

フィルターの作成に追加の手順が必要であったり、フィルターに引数がないコンストラクターがない場合は、以下のファクトリーパターンを使用します。

@FullTextFilterDef(name = "bestDriver", impl = BestDriversFilterFactory.class)
public class Driver { ... }

public class BestDriversFilterFactory {

    @Factory
    public Filter getFilter() {
        //some additional steps to cache the filter results per IndexReader
        Filter bestDriversFilter = new BestDriversFilter();
        return new CachingWrapperFilter(bestDriversFilter);
    }
}

Lucene ベースのクエリー API は @Factory アノテーションが付いたメソッドを使用してフィルターインスタンスを構築します。ファクトリーには引数がないコンストラクターが含まれる必要があります。

名前付きフィルターは、パラメーターをフィルターに渡す必要がある場合に便利です。たとえば、セキュリティーフィルターが、適用するセキュリティーレベルを認識する場合を考えてみます。

cacheQuery = Search.getSearchManager(cache).getQuery(query, Driver.class);
cacheQuery.enableFullTextFilter("security").setParameter("level", 5);

対象となる名前付きフィルター定義のフィルターまたはフィルターファクトリーのいずれかで、関連付けられたセッターが各パラメーターに含まれる必要があります。

public class SecurityFilterFactory {
    private Integer level;

    /**
     * injected parameter
     */
    public void setLevel(Integer level) {
        this.level = level;
    }

    @Key
    public FilterKey getKey() {
        StandardFilterKey key = new StandardFilterKey();
        key.addParameter(level);
        return key;
    }

    @Factory
    public Filter getFilter() {
        Query query = new TermQuery(new Term("level", level.toString()));
        return new CachingWrapperFilter(new QueryWrapperFilter(query));
    }
}

@Key アノテーションの付いたメソッドは FilterKey オブジェクトを返します。返されたオブジェクトには特別なコントラクトがあります。キーオブジェクトは equals() / hashCode() を実装して、特定の Filter タイプが同じでパラメーターのセットが同じ場合でのみ 2 つのキーが等しくなるようにします。つまり、キーが生成されるフィルターが交換可能な場合のみ 2 つのフィルターキーは等しくなります。キーオブジェクトはキャッシュメカニズムでキーとして使用されます。

@Key メソッドは以下の場合のみ必要です。

StandardFilterKey は equals() / hashCode() 実装をパラメーター equals および hashcode メソッドに委譲します。

定義されたフィルターはデフォルトでキャッシュされ、キャッシュはハード参照とソフト参照の組み合わせを使用して必要な場合にメモリーの破棄を許可します。ハード参照キャッシュは最後に使用されたフィルターを追跡し、使用頻度が最も低いフィルターを必要に応じて SoftReferences に変換します。ハード参照キャッシュの制限に達すると、追加のフィルターは SoftReferencesと してキャッシュされます。ハード参照キャッシュのサイズを調整するには、 default.filter.cache_strategy.size (デフォルト値は 128) を使用します。フィルターキャッシュの高度な使用については、独自の FilterCachingStrategy を実装してください。クラス名は default.filter.cache_strategy によって定義されます。

このフィルターキャッシュメカニズムを実際のフィルター結果と混同しないでください。Lucene では、CachingWrapperFilter に IndexReader を使用してフィルターをラップすることが一般的です。このラッパーは、コストがかかる再計算を回避するために getDocIdSet(IndexReader reader) メソッドから返された DocIdSet をキャッシュします。リーダーは開いたときのインデックスの状態を表すため、計算される DocIdSet は同じ IndexReader インスタンスに対してのみキャッシュできることに注意してください。ドキュメントリストは開いた IndexReader 内で変更できません。ただし、別または新しい IndexReader インスタンスが Document の別のセット (別のインデックスのもの、またはインデックスが変更されたため) で動作することがあります。この場合、キャッシュされた DocIdSet は再計算する必要があります。

Lucene ベースのクエリー API は @FullTextFilterDef の cache フラグを使用し、FilterCacheModeType.INSTANCE_AND_DOCIDSETRESULTS に設定します。これは、フィルターインスタンスを自動的にキャッシュし、CachingWrapperFilter の Hibernate 固有の実装にフィルターをラッピングします。Lucene バージョンのこのクラスとは異なり、 SoftReference はハード参照数 (フィルターキャッシュに関する説明を参照) とともに使用されます。ハード参照数は、default.filter.cache_docidresults.size を使用して調整できます (デフォルト値は 5)。ラッピングは @FullTextFilterDef.cache パラメーターを使用して調整されます。このパラメーターには以下の 3 つの値があります。

フィルターは次の状況でキャッシュされる必要があります。

シャード化された環境にて、利用可能なシャードのサブセットでクエリーを実行するには、以下の手順にしたがいます。

以下は、customer フィルターがアクティベートされた場合に特定のシャードをクエリーするシャードストラテジーの例になります。

public class CustomerShardingStrategy implements IndexShardingStrategy {

    // stored IndexManagers in a array indexed by customerID
    private IndexManager[] indexManagers;

    public void initialize(Properties properties, IndexManager[] indexManagers) {
        this.indexManagers = indexManagers;
    }

    public IndexManager[] getIndexManagersForAllShards() {
        return indexManagers;
    }

    public IndexManager getIndexManagerForAddition(
        Class<?> entity, Serializable id, String idInString, Document document) {
        Integer customerID = Integer.parseInt(document.getFieldable("customerID")
                                                      .stringValue());
        return indexManagers[customerID];
    }

    public IndexManager[] getIndexManagersForDeletion(
        Class<?> entity, Serializable id, String idInString) {
        return getIndexManagersForAllShards();
    }

    /**
     * Optimization; don't search ALL shards and union the results; in this case, we
     * can be certain that all the data for a particular customer Filter is in a single
     * shard; return that shard by customerID.
     */
    public IndexManager[] getIndexManagersForQuery(
        FullTextFilterImplementor[] filters) {
        FullTextFilter filter = getCustomerFilter(filters, "customer");
        if (filter == null) {
            return getIndexManagersForAllShards();
        }
        else {
            return new IndexManager[] { indexManagers[Integer.parseInt(
                filter.getParameter("customerID").toString())] };
        }
    }

    private FullTextFilter getCustomerFilter(FullTextFilterImplementor[] filters,
                                             String name) {
        for (FullTextFilterImplementor filter: filters) {
            if (filter.getName().equals(name)) return filter;
        }
        return null;
    }
}

この例では、customer フィルターが存在する場合、クエリーはカスタマー専用のシャードのみを使用します。customer フィルターが見つからない場合は、クエリーはすべてのシャードを返します。シャードストラテジーは提供されたパラメーターに応じて各フィルターに反応します。

クエリーの実行が必要なときに、フィルターをアクティベートします。フィルターは、クエリーの後に Lucene の結果をフィルターする通常のフィルターです (フィルターにて定義)。この代わりに、シャードストラテジーに渡され、クエリーの実行中は無視される特別なフィルターを使用できます。ShardSensitiveOnlyFilter クラスを使用してそのフィルターを宣言します。

@Indexed
@FullTextFilterDef(name = "customer", impl = ShardSensitiveOnlyFilter.class)
public class Customer {
   ...
}

CacheQuery cacheQuery = Search.getSearchManager(cache).getQuery(query,
    Customer.class);
cacheQuery.enableFullTextFilter("customer").setParameter("CustomerID", 5);
@SuppressWarnings("unchecked")
List results = cacheQuery.list();

ShardSensitiveOnlyFilter フィルターが使用される場合、Lucene フィルターを実装する必要はありません。これらのフィルターに反応するフィルターとシャードストラテジーを使用して、シャード化された環境でクエリーを迅速に実行します。

継続的クエリーは、アプリケーションが現在クエリーと一致するエントリーを受信できるようにし、クエリーされたデータセットへの変更が継続して通知されるようにします。これには、追加のキャッシュ操作による、受信の一致 (セットに参加した値に対する) と送信の一致 (セットから離脱した値に対する) の両方が含まれます。継続的なクエリーを使用すると、アプリケーションは安定してイベントを受信するため、変更を発見するために同じクエリーを繰り返し実行しません。そのため、リソースをより効率的に使用できます。

たとえば、以下のユースケースはすべて継続的なクエリーを利用できます。

継続的クエリーは以下の場合に通知を受け取るリスナーを使用します。

クライアントが継続的クエリーリスナーを登録した直後、現在クエリーと一致する結果の受信が開始されます。前述のとおり、これは Join イベントとして受信されます。さらに、通常は creation、modification、removal、または expiration イベントを生成するキャッシュ操作の結果として、他のエントリーがクエリーに一致すると、Join イベントとして後続の通知も受信され、クエリーの一致が停止されると Leave イベントとして受信されます。

リスナーが Join または Leave イベントを受信するかを判断するため、以下の論理が使用されます。

以下の手順は、ライブラリーモードとリモートクライアントサーバーモードの両方に適用されます。

キャッシュに関連付けられた ContinuousQuery オブジェクトを取得するには、クライアントサーバーモードで実行している場合は静的メソッド org.infinispan.client.hotrod.Search.getContinuousQuery(RemoteCache<K, V> cache) を呼び出し、ライブラリーモードで実行している場合は org.infinispan.query.Search.getContinuousQuery(Cache<K, V> cache) を呼び出します。

ContinuousQueryListener が定義されたら、ContinuousQuery の addContinuousQueryListener メソッドを使用して追加できます。

continuousQuery.addContinuousQueryListener(query, listener)

以下の例は、ライブラリーモードで継続的クエリーを実装および追加する簡単なメソッドを表しています。

import org.infinispan.query.api.continuous.ContinuousQuery;
import org.infinispan.query.api.continuous.ContinuousQueryListener;
import org.infinispan.query.Search;
import org.infinispan.query.dsl.QueryFactory;
import org.infinispan.query.dsl.Query;

import java.util.Map;
import java.util.concurrent.ConcurrentHashMap;

[...]

// To begin we create a ContinuousQuery instance on the cache
ContinuousQuery<Integer, Person> continuousQuery = Search.getContinuousQuery(cache);

// Define our query. In this case we will be looking for any
// Person instances under 21 years of age.
QueryFactory queryFactory = Search.getQueryFactory(cache);
Query query = queryFactory.from(Person.class)
    .having("age").lt(21)
    .build();

final Map<Integer, Person> matches = new ConcurrentHashMap<Integer, Person>();

// Define the ContinuousQueryListener
ContinuousQueryListener<Integer, Person> listener = new ContinuousQueryListener<Integer, Person>() {
    @Override
    public void resultJoining(Integer key, Person value) {
        matches.put(key, value);
    }

    @Override
    public void resultLeaving(Integer key) {
        matches.remove(key);
    }
};

// Add the listener and generated query
continuousQuery.addContinuousQueryListener(query, listener);

[...]

// Remove the listener to stop receiving notifications
continuousQuery.removeContinuousQueryListener(listener);

Person インスタンスが 21 未満の Age が含まれるキャッシュへ追加されると matches に配置されます。これらのエントリーがキャッシュから削除されると、matches からも削除されます。

continuousQuery.removeContinuousQueryListener(listener);

継続的クエリーは、アプリケーションが常に最新の状態を保持するよう設計されているため、特に広範囲のクエリーに対して生成されたイベントの数が多くなる可能性があります。さらに、各イベントに対して新たにメモリーが割り当てられます。注意してクエリーを作成しないと、この挙動が原因でメモリーの負荷が発生し、エラーなどを引き起こす可能性があります。

この問題を防ぐため、各クエリーには必要な情報のみを指定し、各 ContinuousQueryListener が受信したすべてのイベントを迅速に処理できるようにすることが強く推奨されます。