org.apache.jackrabbit.oak.spi.query

Interface QueryIndex

All Known Subinterfaces:

QueryIndex.AdvanceFulltextQueryIndex, QueryIndex.FulltextQueryIndex

All Known Implementing Classes:

AggregateIndex, org.apache.jackrabbit.oak.plugins.index.search.spi.query.FulltextIndex, LuceneIndex, LucenePropertyIndex

public interface QueryIndex

Represents an index. The index should use the data in the filter if possible to speed up reading.

The query engine will pick the index that returns the lowest cost for the given filter conditions.

The index should only use that part of the filter that speeds up data lookup. All other filter conditions should be ignored and not evaluated within this index, because the query engine will in any case evaluate the condition (and join condition), so that evaluating the conditions within the index would actually slow down processing. For example, an index on the property "lastName" should not try to evaluate any other restrictions than those on the property "lastName", even if the query contains other restrictions. For the query "where lastName = 'x' and firstName = 'y'", the query engine will set two filter conditions, one for "lastName" and another for "firstName". The index on "lastName" should not evaluate the condition on "firstName", even thought it will be set in the filter.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	QueryIndex.AdvancedQueryIndex An query index that may support using multiple access orders (returning the rows in a specific order), and that can provide detailed information about the cost.
static interface	QueryIndex.AdvanceFulltextQueryIndex
static interface	QueryIndex.FulltextQueryIndex A marker interface which means this index supports may support more than just the minimal fulltext query syntax.
static interface	QueryIndex.IndexPlan An index plan.
static interface	QueryIndex.NativeQueryIndex A marker interface which means this index supports executing native queries
static interface	QueryIndex.NodeAggregator
static class	QueryIndex.OrderEntry A sort order entry.

Method Summary

Modifier and Type	Method and Description
double	getCost(Filter filter, NodeState rootState) Estimate the worst-case cost to query with the given filter.
java.lang.String	getIndexName() Get the generic index name (normally the index type).
default java.lang.String	getIndexName(Filter filter, NodeState rootState) Get the specific index name (the path of the index definition, or the index type if that one is unique).
double	getMinimumCost() Returns the minimum cost which getCost(Filter, NodeState) would return in the best possible case.
java.lang.String	getPlan(Filter filter, NodeState rootState) Get the query plan for the given filter.
Cursor	query(Filter filter, NodeState rootState) Query the index.

Method Detail

getMinimumCost

double getMinimumCost()

Returns the minimum cost which getCost(Filter, NodeState) would return in the best possible case.

The implementation should return a static/cached value because it is called very often.

Returns:

the minimum cost for the index

getCost

double getCost(Filter filter,
               NodeState rootState)

Estimate the worst-case cost to query with the given filter. The returned cost is a value between 1 (very fast; lookup of a unique node) and the estimated number of entries to traverse, if the cursor would be fully read, and if there could in theory be one network roundtrip or disk read operation per node (this method may return a lower number if the data is known to be fully in memory).

The returned value is supposed to be an estimate and doesn't have to be very accurate. Please note this method is called on each index whenever a query is run, so the method should be reasonably fast (not read any data itself, or at least not read too much data).

If an index implementation can not query the data, it has to return Double.MAX_VALUE.

Parameters:

filter - the filter

rootState - root state of the current repository snapshot

Returns:

the estimated cost in number of read nodes

query

Cursor query(Filter filter,
             NodeState rootState)

Query the index. The returned cursor is supposed to return as few nodes as possible, but may return more nodes than necessary.

An implementation should only filter the result if it can do so easily and efficiently; the query engine will verify the data again (in memory) and check for access rights.

The method is only called if this index is used for the given query and selector, which is only the case if the given index implementation returned the lowest cost for the given filter. If the implementation returned Double.MAX_VALUE in the getCost method for the given filter, then this method is not called. If it is still called, then it is supposed to throw an exception (as it would be an internal error of the query engine).

Parameters:

filter - the filter

rootState - root state of the current repository snapshot

Returns:

a cursor to iterate over the result

getPlan

java.lang.String getPlan(Filter filter,
                         NodeState rootState)

Get the query plan for the given filter. This method is called when running an EXPLAIN SELECT query, or for logging purposes. The result should be human readable.

Parameters:

filter - the filter

rootState - root state of the current repository snapshot

Returns:

the query plan

getIndexName

java.lang.String getIndexName()

Get the generic index name (normally the index type).

Returns:

the index name

getIndexName

default java.lang.String getIndexName(Filter filter,
                                      NodeState rootState)

Get the specific index name (the path of the index definition, or the index type if that one is unique).

Returns:

the index name