com.bigdata.relation

Interface IRelation<E>

All Superinterfaces:

ILocatableResource<IRelation<E>>

All Known Subinterfaces:

IMutableRelation<E>

All Known Implementing Classes:

AbstractRelation, BigdataSubjectCentricFullTextIndex, BigdataValueCentricFullTextIndex, FullTextIndex, LexiconRelation, R, RelationFusedView, SPORelation

public interface IRelation<E>
extends ILocatableResource<IRelation<E>>

An abstraction corresponding to a set of elements using some schema (think a table containing a set of rows). Each relation is backed by one or more indices and knows how to return the IAccessPath that is most efficient given an IPredicate expressing a query against the IRelation.

Version:

$Id$

Author:

Bryan Thompson

Method Summary

Methods

Modifier and Type	Method and Description
IAccessPath<E>	getAccessPath(IIndexManager localIndexManager, IKeyOrder<E> keyOrder, IPredicate<E> predicate) Return the IAccessPath for an IRelation using the specified IIndexManager and IKeyOrder (core impl).
IAccessPath<E>	getAccessPath(IKeyOrder<E> keyOrder, IPredicate<E> predicate) Return the IAccessPath for an IRelation using the specified IKeyOrder.
IAccessPath<E>	getAccessPath(IPredicate<E> predicate) Return the best IAccessPath for a relation given a predicate with zero or more unbound variables.
Class<E>	getElementClass() Return the class for the generic type of this relation.
ExecutorService	getExecutorService() The service used to run asynchronous or parallel tasks for the IRelation.
String	getFQN(IKeyOrder<? extends E> keyOrder) The fully qualified name of the index.
IIndex	getIndex(IKeyOrder<? extends E> keyOrder) Return the index for associated with the specified IKeyOrder this view of the relation.
IIndexManager	getIndexManager() The IIndexManager for the IRelation.
Set<String>	getIndexNames() Deprecated. by getKeyOrders(). However, note that some odd ball cases exist such as the free text index of the LexiconRelation and the justifications index of the SPORelation. These are currently enumerated by getIndexNames() but they are not enumerated by getKeyOrders() since they are not a simple transform of the original relation.
IKeyOrder<E>	getKeyOrder(IPredicate<E> predicate) Return the IKeyOrder for the predicate corresponding to the perfect access path.
Iterator<IKeyOrder<E>>	getKeyOrders() Return the IKeyOrders corresponding to the registered indices for this relation.
IKeyOrder<E>	getPrimaryKeyOrder() Return the IKeyOrder for the primary index for the relation.
E	newElement(List<BOp> args, IBindingSet bindingSet) Create and return a new element.

Methods inherited from interface com.bigdata.relation.locator.ILocatableResource

getContainerNamespace, getNamespace, getTimestamp, init

Method Detail

getIndexManager

IIndexManager getIndexManager()

The IIndexManager for the IRelation.

getExecutorService

ExecutorService getExecutorService()

The service used to run asynchronous or parallel tasks for the IRelation.

getElementClass

Class<E> getElementClass()

Return the class for the generic type of this relation. This information is used to dynamically create arrays of that generic type.

newElement

E newElement(List<BOp> args,
           IBindingSet bindingSet)

Create and return a new element. The element is constructed from the ordered list of variables and constants. Variables are replaced using the given the bindings. The element is NOT inserted into the relation.

Parameters:

args - An ordered list of variables and/or constants.

bindingSet - A set of bindings.

Returns:

The new element.

Throws:

IllegalArgumentException - if any parameter is null.

IllegalArgumentException - if any of a is neither an IVariable nor an IPredicate.

IllegalStateException - if there exists a variable which is not bound given those bindings.

getIndexNames

Set<String> getIndexNames()

Deprecated. by getKeyOrders(). However, note that some odd ball cases exist such as the free text index of the LexiconRelation and the justifications index of the SPORelation. These are currently enumerated by getIndexNames() but they are not enumerated by getKeyOrders() since they are not a simple transform of the original relation.

Return the fully qualified name of each index maintained by this relation.

Returns:

An immutable set of the index names for the relation.

getPrimaryKeyOrder

IKeyOrder<E> getPrimaryKeyOrder()

Return the IKeyOrder for the primary index for the relation.

getKeyOrders

Iterator<IKeyOrder<E>> getKeyOrders()

Return the IKeyOrders corresponding to the registered indices for this relation. [rather than getIndexNames?]

getKeyOrder

IKeyOrder<E> getKeyOrder(IPredicate<E> predicate)

Return the IKeyOrder for the predicate corresponding to the perfect access path. A perfect access path is one where the bound values in the predicate form a prefix in the key space of the corresponding index.

Parameters:

p - The predicate.

Returns:

The IKeyOrder for the perfect access path -or- null if there is no index which provides a perfect access path for that predicate.

getAccessPath

IAccessPath<E> getAccessPath(IPredicate<E> predicate)

Return the best IAccessPath for a relation given a predicate with zero or more unbound variables.

If there is an IIndex that directly corresponds to the natural order implied by the variable pattern on the predicate then the access path should use that index. Otherwise you should choose the best index given the constraints and make sure that the IAccessPath incorporates additional filters that will allow you to filter out the irrelevant ITuples during the scan - this is very important when the index is remote!

If there are any IElementFilters then the access path MUST incorporate those constraints such that only elements that satisfy the constraints may be visited.

Whether the constraints arise because of the lack of a perfect index for the access path or because they were explicitly specified for the IPredicate, those constraints should be translated into constraints imposed on the underlying ITupleIterator and sent with it to be evaluated local to the data.

Note: Filters should be specified when the IAccessPath is constructed so that they will be evaluated on the data service rather than materializing the elements and then filtering then. This can be accomplished by adding the filter as a constraint on the predicate when specifying the access path.

Parameters:

predicate - The constraint on the elements to be visited.

Returns:

The best IAccessPath for that IPredicate.

See Also:

getAccessPath(IKeyOrder, IPredicate)

getAccessPath

IAccessPath<E> getAccessPath(IKeyOrder<E> keyOrder,
                           IPredicate<E> predicate)

Return the IAccessPath for an IRelation using the specified IKeyOrder.

Parameters:

keyOrder - Identifies which index to use (required).

predicate - The predicate (required).

Returns:

The IAccessPath.

See Also:

getAccessPath(IIndexManager, IKeyOrder, IPredicate)

getAccessPath

IAccessPath<E> getAccessPath(IIndexManager localIndexManager,
                           IKeyOrder<E> keyOrder,
                           IPredicate<E> predicate)

Return the IAccessPath for an IRelation using the specified IIndexManager and IKeyOrder (core impl).

Predicate annotations

Together, this method and AccessPath is responsible for interpreting the following IPredicate IPredicate#Annotations:

• IPredicate.Annotations#ACCESS_PATH_EXPANDER

Access paths and a Standalone Database

There is only one IIndexManager when running against a standalone database. That IIndexManager is available from getIndexManager().

Access Paths and Scale-Out Operators

Scale-out operators which are BOpEvaluationContext.SHARDED or BOpEvaluationContext.HASHED require access to the local index manager on the data service and signal this using:

• The BOpEvaluationContext.SHARDED or BOpEvaluationContext.HASHED (on a join); and
• The IPredicate.Annotations#PARTITION_ID (for a shard-wise access path).

In order to service a request for a local access path in scale-out, the caller MUST specify the localIndexManager.

Scale-out operators MAY use remote access paths and signal this using:

• The BOpEvaluationContext.ANY (on a join); and
• Setting IPredicate.Annotations#REMOTE_ACCESS_PATH to true.

When a remote access path is required, the localIndexManager is ignored and getIndexManager() is used to obtain the IBigdataFederation from which the IRelation definition was materialized.

Parameters:

localIndexManager - The local index manager (optional).

keyOrder - Identifies which index to use (required).

predicate - The predicate (required).

Returns:

The IAccessPath.

getFQN

String getFQN(IKeyOrder<? extends E> keyOrder)

The fully qualified name of the index.

Parameters:

keyOrder - The natural index order.

Returns:

The index name.

getIndex

IIndex getIndex(IKeyOrder<? extends E> keyOrder)

Return the index for associated with the specified IKeyOrder this view of the relation.

Parameters:

keyOrder - The natural index order.

Returns:

The index -or- null iff the index does not exist as of the timestamp for this view of the relation.

See Also:

#getIndex(String)