com.bigdata.bop

Interface IPredicate.Annotations

All Superinterfaces:

BOp.Annotations, BufferAnnotations, ILocatableResourceAnnotations, ITimestampAnnotations

All Known Subinterfaces:

Predicate.Annotations, SPOPredicate.Annotations, SPOStarJoin.Annotations

Enclosing interface:

IPredicate<E>

public static interface IPredicate.Annotations
extends BOp.Annotations, BufferAnnotations, ILocatableResourceAnnotations

Interface declaring well known annotations.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ACCESS_PATH_EXPANDER Access path expander pattern.
static String	ACCESS_PATH_FILTER An optional BOpFilterBase to be applied to the elements of the relation as they are materialized from the index.
static String	CUTOFF_LIMIT Limits the number of elements read from the access path for this predicate when used in a join (HTreeHashJoinOp, JVMHashJoinOp, PipelineJoin).
static long	DEFAULT_CUTOFF_LIMIT Deault is to not cut off the join.
static int	DEFAULT_FLAGS The default flags will visit the keys and values of the non-deleted tuples.
static int	DEFAULT_FULLY_BUFFERED_READ_THRESHOLD Default for FULLY_BUFFERED_READ_THRESHOLD.
static boolean	DEFAULT_OPTIONAL
static int	DEFAULT_PARTITION_ID
static boolean	DEFAULT_REMOTE_ACCESS_PATH
static String	FLAGS Specify the IRangeQuery flags for the IAccessPath ( default is IRangeQuery.KEYS, IRangeQuery.VALS).
static String	FULLY_BUFFERED_READ_THRESHOLD If the estimated rangeCount for an AccessPath.iterator() is LTE this threshold then use a fully buffered (synchronous) iterator.
static String	INDEX_LOCAL_FILTER An optional IFilter that will be evaluated local to the to the index.
static String	KEY_ORDER Optional property overrides the IKeyOrder to use for the access path.
static String	OPTIONAL true iff the predicate has SPARQL optional semantics (default false).
static String	PARTITION_ID The partition identifier -or- -1 if the predicate does not address a specific shard.
static String	RANGE Note: This annotation is not currently integrated.
static String	REMOTE_ACCESS_PATH Boolean option determines whether the predicate will use a data service local access path (partitioned index view) or a remote access path (global index view) (default true).

Fields inherited from interface com.bigdata.bop.BOp.Annotations

BOP_ID, CONTROLLER, DEFAULT_CONTROLLER, DEFAULT_EVALUATION_CONTEXT, DEFAULT_TIMEOUT, EVALUATION_CONTEXT, NAMESPACE, TIMEOUT

Fields inherited from interface com.bigdata.bop.BufferAnnotations

CHUNK_CAPACITY, CHUNK_OF_CHUNKS_CAPACITY, CHUNK_TIMEOUT, chunkTimeoutUnit, DEFAULT_CHUNK_CAPACITY, DEFAULT_CHUNK_OF_CHUNKS_CAPACITY, DEFAULT_CHUNK_TIMEOUT

Fields inherited from interface com.bigdata.bop.ILocatableResourceAnnotations

RELATION_NAME

Fields inherited from interface com.bigdata.bop.ITimestampAnnotations

TIMESTAMP

Field Detail

KEY_ORDER

static final String KEY_ORDER

Optional property overrides the IKeyOrder to use for the access path. Sometimes changing which index is used for a join can change the locality of the join and improve join performance.

This property mostly makes sense for the quads mode of the database where there is typically more than one SPOKeyOrder which begins with the same key component. E.g., SPOKeyOrder.POCS versus SPOKeyOrder.PCSO.

An IKeyOrder override can also make sense when reading on a fully bound access path if there is an alternative key order which might provide better temporal locality. For example, by reading on the same IKeyOrder as the previous join.

WARNING: DO NOT override the IKeyOrder unless you are also taking control of (or taking into account) the join order -or- if a hash join will be used against the predicate. Failure to heed this advice can result in an extremely bad access path as the join ordering may cause the variables which are actually bound when the predicate is evaluated to be quite different from what you might otherwise expect.

See Also:

(chosing the index for testing fully bound access paths based on index locality)

OPTIONAL

static final String OPTIONAL

true iff the predicate has SPARQL optional semantics (default false).

Note: When a JOIN is associated with an optional predicate and there are IConstraints attached to that join, the constraints are evaluated only for solutions which join. Solutions which do not join (or which join but fail the constraints) are output without testing the constraints a second time.

Note: JOIN and SUBQUERY operators will route optional solutions to the altSink if the altSink is specified and to the default sink otherwise.

DEFAULT_OPTIONAL

static final boolean DEFAULT_OPTIONAL

See Also:

Constant Field Values

INDEX_LOCAL_FILTER

static final String INDEX_LOCAL_FILTER

An optional IFilter that will be evaluated local to the to the index. When the index is remote, the filter will be sent to the node on which the index resides and evaluated there. This makes it possible to efficiently filter out tuples which are not of interest for a given access path.

Note: The filter MUST NOT change the type of data visited by the iterator - it must remain an ITupleIterator. An attempt to change the type of the visited objects will result in a runtime exception. This filter must be "aware" of the reuse of tuples within tuple iterators. See BOpTupleFilter, TupleFilter and ElementFilter for starting points.

You can chain BOpFilterBase filters by nesting them inside of one another. You can chain FilterBase filters together as well.

See Also:

ACCESS_PATH_FILTER, IRangeQuery.rangeIterator(byte[], byte[], int, int, IFilter)

ACCESS_PATH_FILTER

static final String ACCESS_PATH_FILTER

An optional BOpFilterBase to be applied to the elements of the relation as they are materialized from the index. ITuples are automatically resolved into relation "elements" before this filter is applied.

Unlike INDEX_LOCAL_FILTER, this an ACCESS_PATH_FILTER is never sent to a remote index for evaluation. This makes it possible to impose DistinctFilter across a REMOTE_ACCESS_PATH.

You can chain BOpFilterBase filters by nesting them inside of one another. You can chain FilterBase filters together as well.

ACCESS_PATH_EXPANDER

static final String ACCESS_PATH_EXPANDER

Access path expander pattern. This allows you to wrap or replace the IAccessPath.

Note: Access path expanders in scale-out are logically consistent when used with a REMOTE_ACCESS_PATH. However, remote access paths often lack the performance of a local access path. In order for the expander to be consistent with a local access path it MUST NOT rewrite the predicate in such a manner as to read on data onto found on the shard onto which the predicate was mapped during query evaluation.

In general, scale-out query depends on binding sets being mapped onto the shards against which they will read or write. When an expander changes the bindings on an IPredicate, it typically changes the access path which will be used. This is only supported when the access path is REMOTE_ACCESS_PATH.

Note: If an expander generates nested IAccessPaths then it typically must strip off both the ACCESS_PATH_EXPANDER and the ACCESS_PATH_EXPANDER from the IPredicate before generating the inner IAccessPath and then layer the ACCESS_PATH_FILTER back onto the expanded visitation pattern.

See Also:

IAccessPathExpander

PARTITION_ID

static final String PARTITION_ID

The partition identifier -or- -1 if the predicate does not address a specific shard.

DEFAULT_PARTITION_ID

static final int DEFAULT_PARTITION_ID

See Also:

Constant Field Values

REMOTE_ACCESS_PATH

static final String REMOTE_ACCESS_PATH

Boolean option determines whether the predicate will use a data service local access path (partitioned index view) or a remote access path (global index view) (default true).

Note: "Remote" has the semantics that the access path has a total view of the index. In scale-out this is achieved using RMI and an IClientIndex. "Local" has the semantics that the access path has a partitioned view of the index. In scale-out, this corresponds to a shard. In standalone, there is no difference between "local" and "remote" index views since the indices are not partitioned.

Local access paths (in scale-out) are much more efficient and should be used for most purposes. However, it is not possible to impose certain kinds of filters on a partitioned index. For example, a DISTINCT filter requires a global index view.

When the access path is local (aka partitioned), the parent operator must be annotated to use a shard wise or node-wise mapping of the binding sets.

Remote access paths (in scale-out) use a scale-out index view. This view makes the scale-out index appear as if it were monolithic rather than partitioned. The monolithic view of a scale-out index can be used to impose a DISTINCT filter since all tuples will flow back to the caller.

When the access path is remote the parent operator should use BOpEvaluationContext.ANY to prevent the binding sets from being moved around when the access path is remote. Note that the BOpEvaluationContext is basically ignored for standalone since there is only one place for the operator to run - on the query controller.

See Also:

BOpEvaluationContext

DEFAULT_REMOTE_ACCESS_PATH

static final boolean DEFAULT_REMOTE_ACCESS_PATH

See Also:

Constant Field Values

FULLY_BUFFERED_READ_THRESHOLD

static final String FULLY_BUFFERED_READ_THRESHOLD

If the estimated rangeCount for an AccessPath.iterator() is LTE this threshold then use a fully buffered (synchronous) iterator. Otherwise use an asynchronous iterator whose capacity is governed by BufferAnnotations.CHUNK_OF_CHUNKS_CAPACITY.

See Also:

DEFAULT_FULLY_BUFFERED_READ_THRESHOLD

DEFAULT_FULLY_BUFFERED_READ_THRESHOLD

static final int DEFAULT_FULLY_BUFFERED_READ_THRESHOLD

Default for FULLY_BUFFERED_READ_THRESHOLD.

See Also:

Constant Field Values

FLAGS

static final String FLAGS

Specify the IRangeQuery flags for the IAccessPath ( default is IRangeQuery.KEYS, IRangeQuery.VALS).

Note: Most access paths are read-only so it is nearly always a good idea to set the IRangeQuery.READONLY flag.

Note: Access paths used to support high-level query can nearly always use IRangeQuery.PARALLEL iterator semantics, which permits the iterator to run in parallel across index partitions in scale-out. This flag only effects operations which use a global index view in scale-out ( pipeline joins do something different).

Note: Some expanders may require the IRangeQuery.CURSOR flag. For example, Advancer patterns use an ITupleCursor rather than an ITupleIterator. However, since the cursors are slightly slower, they should only be specified when their semantics are necessary.

See Also:

DEFAULT_FLAGS

DEFAULT_FLAGS

static final int DEFAULT_FLAGS

The default flags will visit the keys and values of the non-deleted tuples.

See Also:

Constant Field Values

RANGE

static final String RANGE

Note: This annotation is not currently integrated. It is intended to provide a means to constrain the key-range of the predicate based on an allowable value range for some slot in that predicate.

CUTOFF_LIMIT

static final String CUTOFF_LIMIT

Limits the number of elements read from the access path for this predicate when used in a join (HTreeHashJoinOp, JVMHashJoinOp, PipelineJoin). Note that this is limiting INPUT to a join, it says nothing about the output from a join.

DEFAULT_CUTOFF_LIMIT

static final long DEFAULT_CUTOFF_LIMIT

Deault is to not cut off the join.

See Also:

Constant Field Values