public interface IRangeQuery
Note: There are implementations of this interface for both local indices and for distributed scale-out indices.
Modifier and Type | Field and Description |
---|---|
static int |
ALL
|
static int |
CURSOR
Flag specifies that the base iterator will support the full
ITupleCursor API, including traversal with concurrent
modification, bi-directional tuple navigation and random seeks within the
key range. |
static int |
DEFAULT
The flags that should be used by default [
KEYS , VALS ]
in contexts where the flags are not explicitly specified by the
application such as rangeIterator(byte[], byte[]) . |
static int |
DELETED
Flag specifies that deleted index entries for a key are visited by the
iterator (by default the iterator will hide deleted index entries).
|
static int |
FIXED_LENGTH_SUCCESSOR
There are two ways in which the successor of an unsigned byte[] key may
be computed.
|
static int |
KEYS
Flag specifies that keys in the key range will be returned.
|
static int |
NONE
Flag specifies no data (the #of scanned index entries matching the optional
filter will still be reported).
|
static int |
PARALLEL
Flag indicates that the iterator may process multiple index partitions in
parallel.
|
static int |
READONLY
Flag specifies that the iterator, including any
ITupleFilter s,
will not write on the index. |
static int |
REMOVEALL
Flag specifies that entries visited by the iterator in the key range will
be removed from the index.
|
static int |
REVERSE
Flag specifies that the entries will be visited using a reverse scan.
|
static int |
VALS
Flag specifies that values in the key range will be returned.
|
Modifier and Type | Method and Description |
---|---|
long |
rangeCount()
Return the #of tuples in the index.
|
long |
rangeCount(byte[] fromKey,
byte[] toKey)
Return the #of tuples in a half-open key range.
|
long |
rangeCountExact(byte[] fromKey,
byte[] toKey)
Return the exact #of tuples in a half-open key range.
|
long |
rangeCountExactWithDeleted(byte[] fromKey,
byte[] toKey)
Return the exact #of tuples in a half-open key range, including any
deleted tuples.
|
ITupleIterator |
rangeIterator()
Visits all tuples in key order.
|
ITupleIterator |
rangeIterator(byte[] fromKey,
byte[] toKey)
Return an iterator that visits the entries in a half-open key range.
|
ITupleIterator |
rangeIterator(byte[] fromKey,
byte[] toKey,
int capacity,
int flags,
IFilter filterCtor)
Designated variant (the one that gets overridden) for an iterator that
visits the entries in a half-open key range.
|
static final int NONE
static final int KEYS
ITupleIterator#getKey()
only
when this flag is given.static final int VALS
ITupleIterator.next()
and
ITupleIterator#getValue()
only when this flag is given.static final int DELETED
static final int DEFAULT
KEYS
, VALS
]
in contexts where the flags are not explicitly specified by the
application such as rangeIterator(byte[], byte[])
.static final int ALL
static final int READONLY
ITupleFilter
s,
will not write on the index. Various optimizations may be applied when
this flag is present. (Read only can be inferred if CURSOR
flag
is NOT specified AND there are NO ITupleFilter
s).static final int REMOVEALL
KEYS
or VALS
in order to return the keys and/or values
for the deleted entries. When a IFilter
is specified, the filter
stack will be applied first and then REMOVEALL
will cause a
TupleRemover
to be layered on top. You can achieve other stacked
iterator semantics using IFilter
, including causing
ITuple
s to be removed at a different layer in the stack. Note
however, that removal for a local BTree
will require that the
TupleRemover
is stacked directly over an ITupleCursor
.
Note: This semantics of this flag require that the entries are atomically
removed within the isolation level of the operation. In particular, if
the iterator is running against an IDataService
using an
unisolated view then the entries MUST be buffered and removed as the
ResultSet
is populated.
Note: The BigdataFileSystem.deleteHead(String, int)
relies on
this atomic guarantee.
static final int CURSOR
ITupleCursor
API, including traversal with concurrent
modification, bi-directional tuple navigation and random seeks within the
key range. There are several pragmatic reasons why you would or would not
specify this flag.
Striterator
construction for the BTree
is faster than the newer AbstractBTreeTupleCursor
. It
is used by default when this flag is NOT specified and the iterator is
running across a BTree
. (The IndexSegment.IndexSegmentTupleCursor
is
used for IndexSegment
s regardless of the value of this flag
since it exploits the double-linked leaves of the IndexSegment
and is therefore MORE efficient than the Striterator
based
construct.)Iterator.remove()
) when used with a local BTree
.
Scale-out iterators always support traversal with concurrent modification
since they heavily buffer the iterator with ResultSet
s.static final int REVERSE
This flag may be used to realize a number of interesting constructions, including atomic operations on the tail of a queue and obtaining the last key in the key range.
static final int FIXED_LENGTH_SUCCESSOR
The other choice is to treat the unsigned byte[] as a fixed length bit string and to add ONE (1) with rollover. This works in some special circumstances, primarily because you are actually seeking to skip over all keys that have a given key as their prefix and continue the iterator at the next possible prefix having the same length.
Note: This option is applied by AbstractChunkedTupleIterator
,
which is responsible for issuing continuation queries.
static final int PARALLEL
IClientIndex
implementation. This flag has no effect on an
ILocalBTreeView
and is not passed through to the
IDataService
.long rangeCount()
Note: If the index supports deletion markers then the range count will be an upper bound and may double count tuples which have been overwritten, including the special case where the overwrite is a delete.
ISimpleIndexAccess.rangeCount()
long rangeCount(byte[] fromKey, byte[] toKey)
Note: If the index supports deletion markers then the range count will be an upper bound and may double count tuples which have been overwritten, including the special case where the overwrite is a delete.
fromKey
- The lowest key that will be counted (inclusive). When
null
there is no lower bound.toKey
- The first key that will not be counted (exclusive). When
null
there is no upper bound.long rangeCountExact(byte[] fromKey, byte[] toKey)
Note: If the index supports deletion markers then this operation will require a key-range scan.
fromKey
- The lowest key that will be counted (inclusive). When
null
there is no lower bound.toKey
- The first key that will not be counted (exclusive). When
null
there is no upper bound.long rangeCountExactWithDeleted(byte[] fromKey, byte[] toKey)
When the view is just an AbstractBTree
the result is the same as
for rangeCount(byte[], byte[])
, which already
reports all tuples regardless of whether or not they are deleted.
When the index is a view with multiple sources, this operation requires a key-range scan where both deleted and undeleted tuples are visited.
fromKey
- The lowest key that will be counted (inclusive). When
null
there is no lower bound.toKey
- The first key that will not be counted (exclusive). When
null
there is no upper bound.rangeCountExact(byte[], byte[])
ITupleIterator rangeIterator()
rangeIterator(null, null)
ITupleIterator rangeIterator(byte[] fromKey, byte[] toKey)
fromKey
- The first key that will be visited (inclusive lower bound).
When null
there is no lower bound.toKey
- The first key that will NOT be visited (exclusive upper
bound). When null
there is no upper bound.RuntimeException
- if fromKey is non-null
and orders LT
the inclusive lower bound for an index partition.RuntimeException
- if toKey is non-null
and orders GTE
the exclusive upper bound for an index partition.SuccessorUtil, which may be used to compute the successor of a value
before encoding it as a component of a key.
,
BytesUtil#successor(byte[]), which may be used to compute the
successor of an encoded key.
,
EntryFilter, which may be used to filter the entries visited by the
iterator.
ITupleIterator rangeIterator(byte[] fromKey, byte[] toKey, int capacity, int flags, IFilter filterCtor)
fromKey
- The first key that will be visited (inclusive lower bound).
When null
there is no lower bound.toKey
- The first key that will NOT be visited (exclusive upper
bound). When null
there is no upper bound.capacity
- The #of entries to buffer at a time. This is a hint and MAY be
zero (0) to use an implementation specific default
capacity. A non-zero value may be used if you know that you
want at most N results or if you want to override the default
#of results to be buffered before sending them across a
network interface. (Note that you can control the default
value using
IBigdataClient.Options#DEFAULT_CLIENT_RANGE_QUERY_CAPACITY
).flags
- A bitwise OR of KEYS
, VALS
, etc.filterCtor
- An optional object used to construct a stacked iterator. When
CURSOR
is specified in flags, the base
iterator will implement ITupleCursor
and the first
filter in the stack can safely cast the source iterator to an
ITupleCursor
. If the outermost filter in the stack
does not implement ITupleIterator
, then it will be
wrapped an ITupleIterator
.SuccessorUtil, which may be used to compute the successor of a value
before encoding it as a component of a key.
,
BytesUtil#successor(byte[]), which may be used to compute the
successor of an encoded key.
,
IFilterConstructor, which may be used to construct an iterator stack
performing filtering or other operations.
Copyright © 2006–2019 SYSTAP, LLC DBA Blazegraph. All rights reserved.