Class SizeStatisticsCollectorCursor
- java.lang.Object
-
- com.apple.foundationdb.record.provider.foundationdb.cursors.SizeStatisticsCollectorCursor
-
- All Implemented Interfaces:
RecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
,AutoCloseable
,Iterator<SizeStatisticsCollectorCursor.SizeStatisticsResults>
@API(EXPERIMENTAL) public class SizeStatisticsCollectorCursor extends Object implements RecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
A cursor that collects various distribution statistics on the keys and values within a record store or within an index. The cursor performs a full scan of the subspace backing whatever it is collecting statistics on. It should therefore be run relatively sparingly, and it should not be expected to finish within a single transaction. Note that this class makes no attempt at keeping its results transactional. As a result, if this is run on an actively mutating data set, there are no guarantees that the values it returns were ever actually true for any version in the transaction history. However, as long as the data set is not too volatile, it should produce an approximate answer for the statistics it yields.Note that the cursor emits only a single cursor result containing a value. That value represents full statistics for all keys and values in the specified subspace. Any cursor results emitted prior to that are a manifestation of hitting an execution limit while scanning the subspace. These results provide a continuation that can be used to resume aggregating the remaining keys and values of the subspace.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
SizeStatisticsCollectorCursor.SizeStatisticsResults
Encapsulates the distribution statistics returned by a SizeStatisticsCollectorCursor.-
Nested classes/interfaces inherited from interface com.apple.foundationdb.record.RecordCursor
RecordCursor.NoNextReason
-
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods Modifier and Type Method Description boolean
accept(RecordCursorVisitor visitor)
Accept a visit from hierarchical visitor, which implementsRecordCursorVisitor
.void
close()
byte[]
getContinuation()
Deprecated.Executor
getExecutor()
RecordCursor.NoNextReason
getNoNextReason()
Deprecated.SizeStatisticsCollectorCursor.SizeStatisticsResults
next()
Deprecated.static SizeStatisticsCollectorCursor
ofIndex(FDBRecordStore store, Index index, FDBRecordContext context, ScanProperties scanProperties, byte[] continuation)
Create a statistics collector cursor of all keys used by index within a givenFDBRecordStore
.static SizeStatisticsCollectorCursor
ofIndex(FDBRecordStore store, String indexName, FDBRecordContext context, ScanProperties scanProperties, byte[] continuation)
Create a statistics collector cursor of all keys used by index within a givenFDBRecordStore
.static SizeStatisticsCollectorCursor
ofRecords(FDBRecordStore store, FDBRecordContext context, ScanProperties scanProperties, byte[] continuation)
Create a statistics collector cursor of all records stored within a givenFDBRecordStore
.static SizeStatisticsCollectorCursor
ofStore(FDBRecordStore store, FDBRecordContext context, ScanProperties scanProperties, byte[] continuation)
Create a statistics collector cursor of all keys used by a givenFDBRecordStore
.static SizeStatisticsCollectorCursor
ofSubspace(Subspace subspace, FDBRecordContext context, ScanProperties scanProperties, byte[] continuation)
Create a statistics collector cursor of all keys used by index within a givenSubspace
.CompletableFuture<Boolean>
onHasNext()
Deprecated.CompletableFuture<RecordCursorResult<SizeStatisticsCollectorCursor.SizeStatisticsResults>>
onNext()
Asynchronously return the next result from this cursor.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface java.util.Iterator
forEachRemaining, remove
-
Methods inherited from interface com.apple.foundationdb.record.RecordCursor
asIterator, asList, filter, filterAsync, filterAsyncInstrumented, filterAsyncInstrumented, filterInstrumented, filterInstrumented, first, flatMapPipelined, forEach, forEachAsync, forEachResult, forEachResultAsync, getCount, getNext, hasNext, limitRowsTo, limitTo, map, mapEffect, mapEffect, mapPipelined, orElse, reduce, skip, skipThenLimit
-
-
-
-
Method Detail
-
onNext
@Nonnull public CompletableFuture<RecordCursorResult<SizeStatisticsCollectorCursor.SizeStatisticsResults>> onNext()
Description copied from interface:RecordCursor
Asynchronously return the next result from this cursor. When complete, the future will contain aRecordCursorResult
, which represents exactly one of the following:-
The next object of type
T
produced by the cursor. In addition to the next record, this result includes aRecordCursorContinuation
that can be used to continue the cursor after the last record returned. The returned continuation is guaranteed not to be an "end continuation" representing the end of the cursor: specifically,RecordCursorContinuation.isEnd()
is alwaysfalse
on the returned continuation. -
The fact that the cursor is stopped and cannot produce another record and a
RecordCursor.NoNextReason
that explains why no record could be produced. The result include a continuation that can be used to continue the cursor after the last record returned. If the result'sNoNextReason
is anything other thanRecordCursor.NoNextReason.SOURCE_EXHAUSTED
, the returned continuation must not be an end continuation. Conversely, if the result'sNoNextReason
isSOURCE_EXHAUSTED
, then the returned continuation must be an an "end continuation".
RecordCursorContinuation
can be serialized to an opaque byte array usingRecordCursorContinuation.toBytes()
. This can be passed back into a new cursor of the same type, with all other parameters remaining the same.- Specified by:
onNext
in interfaceRecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
- Returns:
- a future for the next result from this cursor representing either the next record or an indication of why the cursor stopped
- See Also:
RecordCursorResult
,RecordCursorContinuation
-
The next object of type
-
getExecutor
@Nonnull public Executor getExecutor()
- Specified by:
getExecutor
in interfaceRecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
-
accept
public boolean accept(@Nonnull RecordCursorVisitor visitor)
Description copied from interface:RecordCursor
Accept a visit from hierarchical visitor, which implementsRecordCursorVisitor
. By contract, implementations of this method must return the value ofvisitor.visitLeave(this)
, which determines whether or not subsequent siblings of this cursor should be visited.- Specified by:
accept
in interfaceRecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
- Parameters:
visitor
- a hierarchical visitor- Returns:
true
if the subsequent siblings of thecursor
should be visited, andfalse
otherwise
-
onHasNext
@Nonnull @Deprecated public CompletableFuture<Boolean> onHasNext()
Deprecated.Description copied from interface:RecordCursor
Asynchronously check whether there are more records available from the cursor.- Specified by:
onHasNext
in interfaceRecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
- Returns:
- a future that when complete will hold
true
ifRecordCursor.next()
would return a record. - See Also:
AsyncIterator.onHasNext()
-
next
@Nullable @Deprecated public SizeStatisticsCollectorCursor.SizeStatisticsResults next()
Deprecated.Description copied from interface:RecordCursor
Return the next value.- Specified by:
next
in interfaceIterator<SizeStatisticsCollectorCursor.SizeStatisticsResults>
- Specified by:
next
in interfaceRecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
- Returns:
- the next value
-
getContinuation
@Nullable @Deprecated public byte[] getContinuation()
Deprecated.Description copied from interface:RecordCursor
Get a byte string that can be used to continue a query after the last record returned.- Specified by:
getContinuation
in interfaceRecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
- Returns:
- opaque byte array denoting where the cursor should pick up. This can be passed back into a new
cursor of the same type, with all other parameters remaining the same.
Returns
null
if the underlying source is completely exhausted, independent of any limit passed to the cursor creator. Since such creators generally acceptnull
to mean no continuation, that is, start from the beginning, one must check fornull
fromgetContinuation
to keep from starting over. Result is not always defined if called beforeonHasNext
or beforenext
afteronHasNext
has returnedtrue
. That is, a continuation is only guaranteed when called "between" records from awhile (hasNext) next
loop or after its end.
-
getNoNextReason
@Nonnull @Deprecated public RecordCursor.NoNextReason getNoNextReason()
Deprecated.Description copied from interface:RecordCursor
Get the reason that the cursor has reached the end and returnedfalse
forRecordCursor.hasNext()
. IfhasNext
was not called or returnedtrue
last time, the result is undefined and may be an exception.- Specified by:
getNoNextReason
in interfaceRecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
- Returns:
- the reason that the cursor stopped
-
close
public void close()
- Specified by:
close
in interfaceAutoCloseable
- Specified by:
close
in interfaceRecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>
-
ofStore
@Nonnull public static SizeStatisticsCollectorCursor ofStore(@Nonnull FDBRecordStore store, @Nonnull FDBRecordContext context, @Nonnull ScanProperties scanProperties, @Nullable byte[] continuation)
Create a statistics collector cursor of all keys used by a givenFDBRecordStore
. This includes records, indexes, and other meta-data.- Parameters:
store
- the store from which to collect statistics on key and value sizescontext
- the transaction context under which stats collection occursscanProperties
- scan direction, limits, etc. under which underlying record store scan is performedcontinuation
- the starting cursor location to start stats collection- Returns:
- a cursor for collecting statistics of that store
-
ofRecords
@Nonnull public static SizeStatisticsCollectorCursor ofRecords(@Nonnull FDBRecordStore store, @Nonnull FDBRecordContext context, @Nonnull ScanProperties scanProperties, @Nullable byte[] continuation)
Create a statistics collector cursor of all records stored within a givenFDBRecordStore
. This only looks at the records stored by that store, not any indexes.- Parameters:
store
- the store from which to collect statistics on key and value sizescontext
- the transaction context under which stats collection occursscanProperties
- scan direction, limits, etc. under which underlying record store scan is performedcontinuation
- the starting cursor location to start stats collection- Returns:
- a statistics collector of the records of that store
-
ofIndex
@Nonnull public static SizeStatisticsCollectorCursor ofIndex(@Nonnull FDBRecordStore store, @Nonnull String indexName, @Nonnull FDBRecordContext context, @Nonnull ScanProperties scanProperties, @Nullable byte[] continuation)
Create a statistics collector cursor of all keys used by index within a givenFDBRecordStore
. This includes only the key-value pairs within the index's primary subspace.- Parameters:
store
- a store with the given indexindexName
- the name of the index to collect statistics on key and value sizescontext
- the transaction context under which stats collection occursscanProperties
- scan direction, limits, etc. under which underlying record store scan is performedcontinuation
- the starting cursor location to start stats collection- Returns:
- a statistics collector of the given index
-
ofIndex
@Nonnull public static SizeStatisticsCollectorCursor ofIndex(@Nonnull FDBRecordStore store, @Nonnull Index index, @Nonnull FDBRecordContext context, @Nonnull ScanProperties scanProperties, @Nullable byte[] continuation)
Create a statistics collector cursor of all keys used by index within a givenFDBRecordStore
. This includes only the key-value pairs within the index's primary subspace.- Parameters:
store
- a store with the given indexindex
- the index to collect statistics on key and value sizescontext
- the transaction context under which stats collection occursscanProperties
- scan direction, limits, etc. under which underlying record store scan is performedcontinuation
- the starting cursor location to start stats collection- Returns:
- a statistics collector of the given index
-
ofSubspace
@Nonnull public static SizeStatisticsCollectorCursor ofSubspace(@Nonnull Subspace subspace, @Nonnull FDBRecordContext context, @Nonnull ScanProperties scanProperties, @Nullable byte[] continuation)
Create a statistics collector cursor of all keys used by index within a givenSubspace
.- Parameters:
subspace
- the subspace to collect statistics on key and value sizescontext
- the transaction context under which stats collection occursscanProperties
- scan direction, limits, etc. under which underlying record store scan is performedcontinuation
- the starting cursor location to start stats collection- Returns:
- a statistics collector of the given subspace
-
-