Extracting a value from an object via an
Attribute can sometimes be expensive, for example if the attribute
is
virtual wherein the data it reads is not already stored in memory, but has to be uncompressed or decoded
on-the-fly, or if it reads the data on-the-fly from a remote datasource.
Often there may be an index on such attributes available locally, wherein a copy of the attribute values would be
available locally in already-decoded form. Indexes would typically report that they can accelerate standard CQEngine
queries on those attributes. However some queries cannot be accelerated by indexes in a straightforward manner; for
example queries which perform regular expressions or some other function on the raw data. Indexes are unlikely
to report that they can natively accelerate regular expression queries, because regular expressions must be evaluated
by filtering. Therefore CQEngine will typically fall back to evaluating regular expression queries on the fly by
filtering values returned by
the attribute from which the query reads. If reading from the attribute is
expensive, then it makes sense to allow the query to filter data from the index instead.
Queries which implement this interface are evaluated by filtering the data contained in an index built on
the attribute, as opposed to the data returned by the attribute.
Note that most standard CQEngine queries do not implement this interface, because CQEngine cannot know how expensive
user-defined attributes are (plus, ordinarily reading from attributes is cheap). If the application requires this
behaviour for some queries, it can subclass some of the existing queries and have them implement this interface,
or it can define custom queries which implement this interface.
Note that the existing
StringMatchesRegex and
StringEndsWith queries are already compatible with this
interface. To have those queries answered by filtering data in an index instead of from an attribute,
subclass
those queries and declare that they implement this interface. They already implement the required
matchesValue(Object, QueryOptions) method.