Package com.apple.foundationdb.record.provider.foundationdb.cursors

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

Modifier and Type	Method	Description
boolean	accept(RecordCursorVisitor visitor)	Accept a visit from hierarchical visitor, which implements RecordCursorVisitor.
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 given FDBRecordStore.
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 given FDBRecordStore.
static SizeStatisticsCollectorCursor	ofRecords(FDBRecordStore store, FDBRecordContext context, ScanProperties scanProperties, byte[] continuation)	Create a statistics collector cursor of all records stored within a given FDBRecordStore.
static SizeStatisticsCollectorCursor	ofStore(FDBRecordStore store, FDBRecordContext context, ScanProperties scanProperties, byte[] continuation)	Create a statistics collector cursor of all keys used by a given FDBRecordStore.
static SizeStatisticsCollectorCursor	ofSubspace(Subspace subspace, FDBRecordContext context, ScanProperties scanProperties, byte[] continuation)	Create a statistics collector cursor of all keys used by index within a given Subspace.
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 a RecordCursorResult, which represents exactly one of the following:

1. The next object of type T produced by the cursor. In addition to the next record, this result includes a RecordCursorContinuation 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 always false on the returned continuation.
2. 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's NoNextReason is anything other than RecordCursor.NoNextReason.SOURCE_EXHAUSTED, the returned continuation must not be an end continuation. Conversely, if the result's NoNextReason is SOURCE_EXHAUSTED, then the returned continuation must be an an "end continuation".

In either case, the returned RecordCursorContinuation can be serialized to an opaque byte array using RecordCursorContinuation.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 interface RecordCursor<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

getExecutor

@Nonnull
public Executor getExecutor()

Specified by:

getExecutor in interface RecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>

accept

public boolean accept(@Nonnull
                      RecordCursorVisitor visitor)

Description copied from interface: RecordCursor

Accept a visit from hierarchical visitor, which implements RecordCursorVisitor. By contract, implementations of this method must return the value of visitor.visitLeave(this), which determines whether or not subsequent siblings of this cursor should be visited.

Specified by:

accept in interface RecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>

Parameters:

visitor - a hierarchical visitor

Returns:

true if the subsequent siblings of the cursor should be visited, and false 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 interface RecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>

Returns:

a future that when complete will hold true if RecordCursor.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 interface Iterator<SizeStatisticsCollectorCursor.SizeStatisticsResults>

Specified by:

next in interface RecordCursor<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 interface RecordCursor<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 accept null to mean no continuation, that is, start from the beginning, one must check for null from getContinuation to keep from starting over. Result is not always defined if called before onHasNext or before next after onHasNext has returned true. That is, a continuation is only guaranteed when called "between" records from a while (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 returned false for RecordCursor.hasNext(). If hasNext was not called or returned true last time, the result is undefined and may be an exception.

Specified by:

getNoNextReason in interface RecordCursor<SizeStatisticsCollectorCursor.SizeStatisticsResults>

Returns:

the reason that the cursor stopped

close

public void close()

Specified by:

close in interface AutoCloseable

Specified by:

close in interface RecordCursor<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 given FDBRecordStore. This includes records, indexes, and other meta-data.

Parameters:

store - the store from which to collect statistics on key and value sizes

context - the transaction context under which stats collection occurs

scanProperties - scan direction, limits, etc. under which underlying record store scan is performed

continuation - 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 given FDBRecordStore. 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 sizes

context - the transaction context under which stats collection occurs

scanProperties - scan direction, limits, etc. under which underlying record store scan is performed

continuation - 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 given FDBRecordStore. This includes only the key-value pairs within the index's primary subspace.

Parameters:

store - a store with the given index

indexName - the name of the index to collect statistics on key and value sizes

context - the transaction context under which stats collection occurs

scanProperties - scan direction, limits, etc. under which underlying record store scan is performed

continuation - 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 given FDBRecordStore. This includes only the key-value pairs within the index's primary subspace.

Parameters:

store - a store with the given index

index - the index to collect statistics on key and value sizes

context - the transaction context under which stats collection occurs

scanProperties - scan direction, limits, etc. under which underlying record store scan is performed

continuation - 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 given Subspace.

Parameters:

subspace - the subspace to collect statistics on key and value sizes

context - the transaction context under which stats collection occurs

scanProperties - scan direction, limits, etc. under which underlying record store scan is performed

continuation - the starting cursor location to start stats collection

Returns:

a statistics collector of the given subspace