Interface FDBRecordStoreBase<M extends Message>
-
- Type Parameters:
M
- type used to represent stored records
- All Superinterfaces:
RecordMetaDataProvider
- All Known Implementing Classes:
FDBRecordStore
,FDBTypedRecordStore
@API(MAINTAINED) public interface FDBRecordStoreBase<M extends Message> extends RecordMetaDataProvider
Base interface for typed and untyped record stores. This interface is the main front-end for most operations inserting, modifying, or querying data through the Record Layer. A record store combines:- A
Subspace
(often specified via aKeySpacePath
) - The
RecordMetaData
associated with the data stored with the data in that subspace - An
FDBRecordContext
which wraps a FoundationDBTransaction
All of the record store's data—including index data—are stored durably within the given subspace. Note that the meta-data is not stored by the record store directly. However, information about the store's current meta-data version is persisted with the store to detect when the meta-data have changed and to know if any action needs to be taken to begin using the new meta-data. (For example, new indexes might need to be built and removed indexes deleted.) The same meta-data may be used for multiple record stores, and separating the meta-data from the data makes updating the shared meta-data simpler as it only needs to be updated in one place. The
FDBMetaDataStore
may be used if one wishes to persist the meta-data into a FoundationDB cluster.All operations conducted by a record store are conducted within the lifetime single transaction, and no data is persisted to the database until the transaction is committed by calling
FDBRecordContext.commit()
orFDBRecordContext.commitAsync()
. Record Layer transactions inherit all of the guarantees and limitations of the transactions exposed by FoundationDB, including their durability and consistency guarantees as well as size and duration limits. See the FoundationDB known limitations for more details.The record store also allows the user to tweak additional parameters such as what the parallelism of pipelined operations should be (through the
FDBRecordStoreBase.PipelineSizer
) and what serializer should be used to read and write data to the database. See theFDBRecordStoreBase.BaseBuilder
interface for more details.- See Also:
FDBRecordStore
,FDBTypedRecordStore
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interface
FDBRecordStoreBase.BaseBuilder<M extends Message,R extends FDBRecordStoreBase<M>>
Builder forFDBRecordStoreBase
.static interface
FDBRecordStoreBase.PipelineSizer
Function for computing the number of elements to allow in the asynchronous pipeline for an operation of the given type.static class
FDBRecordStoreBase.RecordExistenceCheck
Action to take if the record being saved does / does not already exist.static class
FDBRecordStoreBase.StoreExistenceCheck
Action to take if the record store does / does not already exist.static interface
FDBRecordStoreBase.UserVersionChecker
Hook for checking if store state for client changes.static class
FDBRecordStoreBase.VersionstampSaveBehavior
Provided during record save (viasaveRecord(Message, FDBRecordVersion, VersionstampSaveBehavior)
), directs the behavior of the save w.r.t.
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated Methods Modifier and Type Method Description void
addRecordReadConflict(Tuple primaryKey)
Add a read conflict as if one had read the record with the given primary key.void
addRecordWriteConflict(Tuple primaryKey)
Add a write conflict as if one had modified the record with the given primary key.default CompletableFuture<Integer>
countRecords(Tuple low, Tuple high, EndpointType lowEndpoint, EndpointType highEndpoint)
Count the number of records in the database in a range.CompletableFuture<Integer>
countRecords(Tuple low, Tuple high, EndpointType lowEndpoint, EndpointType highEndpoint, byte[] continuation, ScanProperties scanProperties)
Count the number of records in the database in a range.default FDBQueriedRecord<M>
coveredIndexQueriedRecord(Index index, IndexEntry indexEntry, RecordType recordType, M partialRecord, boolean hasPrimaryKey)
Get a query result from a covering index entry.void
deleteAllRecords()
Delete all the data in the record store.default boolean
deleteRecord(Tuple primaryKey)
Delete the record with the given primary key.CompletableFuture<Boolean>
deleteRecordAsync(Tuple primaryKey)
Async version ofdeleteRecord(com.apple.foundationdb.tuple.Tuple)
.default void
deleteRecordsWhere(QueryComponent component)
Delete records and associated index entries matching a query filter.default void
deleteRecordsWhere(String recordType, QueryComponent component)
Delete records and associated index entries matching a query filter.CompletableFuture<Void>
deleteRecordsWhereAsync(QueryComponent component)
default CompletableFuture<Void>
deleteRecordsWhereAsync(String recordType, QueryComponent component)
Async version ofdeleteRecordsWhere(String, QueryComponent)
.default CompletableFuture<Tuple>
evaluateAggregateFunction(EvaluationContext evaluationContext, List<String> recordTypeNames, IndexAggregateFunction aggregateFunction, TupleRange range, IsolationLevel isolationLevel)
Evaluate anIndexAggregateFunction
against a range of the store.default CompletableFuture<Tuple>
evaluateAggregateFunction(List<String> recordTypeNames, IndexAggregateFunction aggregateFunction, Key.Evaluated value, IsolationLevel isolationLevel)
Evaluate anIndexAggregateFunction
against a group value.CompletableFuture<Tuple>
evaluateAggregateFunction(List<String> recordTypeNames, IndexAggregateFunction aggregateFunction, TupleRange range, IsolationLevel isolationLevel)
Evaluate anIndexAggregateFunction
against a range of the store.<T> CompletableFuture<T>
evaluateIndexRecordFunction(EvaluationContext evaluationContext, IndexRecordFunction<T> function, FDBRecord<M> record)
Evaluate aIndexRecordFunction
against a record.default <T> CompletableFuture<T>
evaluateRecordFunction(EvaluationContext evaluationContext, RecordFunction<T> function, FDBRecord<M> record)
Evaluate aRecordFunction
against a record.default <T> CompletableFuture<T>
evaluateRecordFunction(RecordFunction<T> function, FDBRecord<M> record)
Evaluate aRecordFunction
against a record.<T> CompletableFuture<T>
evaluateStoreFunction(EvaluationContext evaluationContext, StoreRecordFunction<T> function, FDBRecord<M> record)
Evaluate aStoreRecordFunction
against a record.default <T> CompletableFuture<T>
evaluateStoreFunction(StoreRecordFunction<T> function, FDBRecord<M> record)
Evaluate aStoreRecordFunction
against a record.default RecordCursor<FDBQueriedRecord<M>>
executeQuery(RecordQueryPlan query)
Execute a query.default RecordCursor<FDBQueriedRecord<M>>
executeQuery(RecordQueryPlan query, byte[] continuation, ExecuteProperties executeProperties)
Execute a query.default RecordCursor<FDBQueriedRecord<M>>
executeQuery(RecordQuery query)
Plan and execute a query.default RecordCursor<FDBQueriedRecord<M>>
executeQuery(RecordQuery query, byte[] continuation, ExecuteProperties executeProperties)
Plan and execute a query.default RecordCursor<FDBIndexedRecord<M>>
fetchIndexRecords(Index index, RecordCursor<IndexEntry> indexCursor, IndexOrphanBehavior orphanBehavior)
Deprecated.default RecordCursor<FDBIndexedRecord<M>>
fetchIndexRecords(Index index, RecordCursor<IndexEntry> indexCursor, IndexOrphanBehavior orphanBehavior, ExecuteState executeState)
Deprecated.default RecordCursor<FDBIndexedRecord<M>>
fetchIndexRecords(RecordCursor<IndexEntry> indexCursor, IndexOrphanBehavior orphanBehavior)
Given a cursor that iterates over entries in an index, attempts to fetch the associated records for those entries.default RecordCursor<FDBIndexedRecord<M>>
fetchIndexRecords(RecordCursor<IndexEntry> indexCursor, IndexOrphanBehavior orphanBehavior, ExecuteState executeState)
Given a cursor that iterates over entries in an index, attempts to fetch the associated records for those entries.FDBRecordContext
getContext()
Get the record context (transaction) to use for the record store.default Executor
getExecutor()
default int
getPipelineSize(PipelineOperation pipelineOperation)
Get the number of elements to allow in the asynchronous pipeline for an operation of the given type.FDBRecordStoreBase.PipelineSizer
getPipelineSizer()
Get the function for computing the number of elements to allow in the asynchronous pipeline for an operation of the given type.RecordSerializer<M>
getSerializer()
Get the serializer used to convert records into byte arrays.default CompletableFuture<Long>
getSnapshotRecordCount()
Get the number of records in the record store.CompletableFuture<Long>
getSnapshotRecordCount(KeyExpression key, Key.Evaluated value)
Get the number of records in a portion of the record store determined by a group key expression.CompletableFuture<Long>
getSnapshotRecordCountForRecordType(String recordTypeName)
Get the number of records in the record store of the given record type.default CompletableFuture<Long>
getSnapshotRecordUpdateCount()
default CompletableFuture<Long>
getSnapshotRecordUpdateCount(KeyExpression key, Key.Evaluated value)
SubspaceProvider
getSubspaceProvider()
Get the subspace provider.default FDBStoreTimer
getTimer()
default <N extends Message>
FDBTypedRecordStore<N>getTypedRecordStore(RecordSerializer<N> serializer)
Get a typed record store using the given typed serializer.FDBRecordStore
getUntypedRecordStore()
Get the untyped record store associated with this possibly typed store.default CompletableFuture<Boolean>
hasIndexEntryRecord(IndexEntry entry, IsolationLevel isolationLevel)
Determine if a given index entry points to a record.default CompletableFuture<Boolean>
hasIndexEntryRecord(Index index, IndexEntry entry, IsolationLevel isolationLevel)
Deprecated.usehasIndexEntryRecord(IndexEntry, IsolationLevel)
insteadstatic Tuple
indexEntryKey(Index index, Tuple valueKey, Tuple primaryKey)
Return a tuple to be used as the key for an index entry for the given value and primary key.static Tuple
indexEntryPrimaryKey(Index index, Tuple entry)
Deprecated.useIndex.getEntryPrimaryKey(Tuple)
insteaddefault FDBStoredRecord<M>
insertRecord(M record)
Save the given record and throw an exception if a record already exists with the same primary key.default CompletableFuture<FDBStoredRecord<M>>
insertRecordAsync(M record)
Save the given record and throw an exception if a record already exists with the same primary key.default CompletableFuture<FDBIndexedRecord<M>>
loadIndexEntryRecord(IndexEntry entry, IndexOrphanBehavior orphanBehavior)
Using the given index entry, resolve the primary key and asynchronously return the referenced record.default CompletableFuture<FDBIndexedRecord<M>>
loadIndexEntryRecord(IndexEntry entry, IndexOrphanBehavior orphanBehavior, ExecuteState executeState)
Using the given index entry, resolve the primary key and asynchronously return the referenced record.default CompletableFuture<FDBIndexedRecord<M>>
loadIndexEntryRecord(Index index, IndexEntry entry, IndexOrphanBehavior orphanBehavior)
Deprecated.default CompletableFuture<FDBIndexedRecord<M>>
loadIndexEntryRecord(Index index, IndexEntry entry, IndexOrphanBehavior orphanBehavior, ExecuteState executeState)
Deprecated.default FDBStoredRecord<M>
loadRecord(Tuple primaryKey)
Load the record with the given primary key.default FDBStoredRecord<M>
loadRecord(Tuple primaryKey, boolean snapshot)
Load the record with the given primary key.default CompletableFuture<FDBStoredRecord<M>>
loadRecordAsync(Tuple primaryKey)
Asynchronously load a record.default CompletableFuture<FDBStoredRecord<M>>
loadRecordAsync(Tuple primaryKey, boolean snapshot)
Asynchronously load a record.CompletableFuture<FDBStoredRecord<M>>
loadRecordInternal(Tuple primaryKey, ExecuteState executeState, boolean snapshot)
RecordQueryPlan
planQuery(RecordQuery query)
Plan a query.CompletableFuture<Void>
preloadRecordAsync(Tuple primaryKey)
Get record into FDB RYW cache.default FDBQueriedRecord<M>
queriedRecord(FDBIndexedRecord<M> indexedRecord)
Get a query result record from an indexed record.default FDBQueriedRecord<M>
queriedRecord(FDBStoredRecord<M> storedRecord)
Get a query result record from a stored record.default boolean
recordExists(Tuple primaryKey)
Check if a record exists in the record store with the given primary key.default boolean
recordExists(Tuple primaryKey, IsolationLevel isolationLevel)
Check if a record exists in the record store with the given primary key.default CompletableFuture<Boolean>
recordExistsAsync(Tuple primaryKey)
Check if a record exists in the record store with the given primary key.CompletableFuture<Boolean>
recordExistsAsync(Tuple primaryKey, IsolationLevel isolationLevel)
Check if a record exists in the record store with the given primary key.default CompletableFuture<Void>
resolveUniquenessViolation(Index index, Key.Evaluated indexKey, Tuple primaryKey)
Removes all of the records that have the given value set as their index index value (are thus causing a uniqueness violation) except for the one that has the given primary key (if the key is notnull
).CompletableFuture<Void>
resolveUniquenessViolation(Index index, Tuple valueKey, Tuple primaryKey)
Removes all of the records that have the given value set as their index value (and are thus causing a uniqueness violation) except for the one that has the given primary key (if the key is notnull
).default FDBStoredRecord<M>
saveRecord(M record)
Save the given record.default FDBStoredRecord<M>
saveRecord(M record, FDBRecordStoreBase.RecordExistenceCheck existenceCheck)
Save the given record.default FDBStoredRecord<M>
saveRecord(M record, FDBRecordStoreBase.RecordExistenceCheck existenceCheck, FDBRecordVersion version, FDBRecordStoreBase.VersionstampSaveBehavior behavior)
Save the given record with a specific version.default FDBStoredRecord<M>
saveRecord(M record, FDBRecordVersion version)
Save the given record with a specific version.default FDBStoredRecord<M>
saveRecord(M record, FDBRecordVersion version, FDBRecordStoreBase.VersionstampSaveBehavior behavior)
Save the given record with a specific version.default CompletableFuture<FDBStoredRecord<M>>
saveRecordAsync(M record)
Async version ofsaveRecord(Message)
.default CompletableFuture<FDBStoredRecord<M>>
saveRecordAsync(M record, FDBRecordStoreBase.RecordExistenceCheck existenceCheck)
Async version ofsaveRecord(Message, RecordExistenceCheck)
.CompletableFuture<FDBStoredRecord<M>>
saveRecordAsync(M record, FDBRecordStoreBase.RecordExistenceCheck existenceCheck, FDBRecordVersion version, FDBRecordStoreBase.VersionstampSaveBehavior behavior)
default CompletableFuture<FDBStoredRecord<M>>
saveRecordAsync(M record, FDBRecordVersion version)
Async version ofsaveRecord(Message, FDBRecordVersion)
.default CompletableFuture<FDBStoredRecord<M>>
saveRecordAsync(M record, FDBRecordVersion version, FDBRecordStoreBase.VersionstampSaveBehavior behavior)
Async version ofsaveRecord(Message, FDBRecordVersion, VersionstampSaveBehavior)
.RecordCursor<IndexEntry>
scanIndex(Index index, IndexScanType scanType, TupleRange range, byte[] continuation, ScanProperties scanProperties)
Scan the entries in an index.default RecordCursor<IndexEntry>
scanIndex(Index index, IndexScanType scanType, TupleRange range, byte[] continuation, ScanProperties scanProperties, RecordScanLimiter recordScanLimiter)
Deprecated.because theRecordScanLimiter
should be specified as part of theScanProperties
insteaddefault RecordCursor<FDBIndexedRecord<M>>
scanIndexRecords(String indexName)
Scan the records pointed to by an index.default RecordCursor<FDBIndexedRecord<M>>
scanIndexRecords(String indexName, IndexScanType scanType, TupleRange range, byte[] continuation, IndexOrphanBehavior orphanBehavior, ScanProperties scanProperties)
Scan the records pointed to by an index.default RecordCursor<FDBIndexedRecord<M>>
scanIndexRecords(String indexName, IndexScanType scanType, TupleRange range, byte[] continuation, IndexOrphanBehavior orphanBehavior, ScanProperties scanProperties, RecordScanLimiter recordScanLimiter)
Deprecated.because theRecordScanLimiter
should be specified as part of theScanProperties
insteaddefault RecordCursor<FDBIndexedRecord<M>>
scanIndexRecords(String indexName, IndexScanType scanType, TupleRange range, byte[] continuation, ScanProperties scanProperties)
Scan the records pointed to by an index.default RecordCursor<FDBIndexedRecord<M>>
scanIndexRecords(String indexName, IndexScanType scanType, TupleRange range, byte[] continuation, ScanProperties scanProperties, RecordScanLimiter recordScanLimiter)
Deprecated.because theRecordScanLimiter
should be specified as part of theScanProperties
insteaddefault RecordCursor<FDBIndexedRecord<M>>
scanIndexRecords(String indexName, IsolationLevel isolationLevel)
Scan the records pointed to by an index.default RecordCursor<FDBIndexedRecord<M>>
scanIndexRecordsBetween(String indexName, Object low, Object high)
Scan the records pointed to by an index between two indexed values.default RecordCursor<FDBIndexedRecord<M>>
scanIndexRecordsEqual(String indexName, Object... values)
Scan the records pointed to by an index equal to indexed values.default RecordCursor<FDBStoredRecord<M>>
scanRecords(byte[] continuation, ScanProperties scanProperties)
Scan the records in the database.default RecordCursor<FDBStoredRecord<M>>
scanRecords(TupleRange range, byte[] continuation, ScanProperties scanProperties)
Scan the records in the database in a range.RecordCursor<FDBStoredRecord<M>>
scanRecords(Tuple low, Tuple high, EndpointType lowEndpoint, EndpointType highEndpoint, byte[] continuation, ScanProperties scanProperties)
Scan the records in the database in a range.default RecordCursor<RecordIndexUniquenessViolation>
scanUniquenessViolations(Index index)
Scan the list of uniqueness violations for an index for violations with a specific value.default RecordCursor<RecordIndexUniquenessViolation>
scanUniquenessViolations(Index index, byte[] continuation, ScanProperties scanProperties)
Scan the list of uniqueness violations for an index for violations with a specific value.default RecordCursor<RecordIndexUniquenessViolation>
scanUniquenessViolations(Index index, int limit)
Scan the list of uniqueness violations for an index for violations with a specific value.default RecordCursor<RecordIndexUniquenessViolation>
scanUniquenessViolations(Index index, Key.Evaluated indexKey)
Scan the list of uniqueness violations for an index for violations with a specific value.default RecordCursor<RecordIndexUniquenessViolation>
scanUniquenessViolations(Index index, Key.Evaluated indexKey, byte[] continuation, ScanProperties scanProperties)
Scan the list of uniqueness violations for an index for violations with a specific value.RecordCursor<RecordIndexUniquenessViolation>
scanUniquenessViolations(Index index, TupleRange range, byte[] continuation, ScanProperties scanProperties)
Scan the list of uniqueness violations identified for an index.default RecordCursor<RecordIndexUniquenessViolation>
scanUniquenessViolations(Index index, Tuple valueKey)
Scan the list of uniqueness violations for an index for violations with a specific value.default RecordCursor<RecordIndexUniquenessViolation>
scanUniquenessViolations(Index index, Tuple valueKey, byte[] continuation, ScanProperties scanProperties)
Scan the list of uniqueness violations for an index for violations with a specific value.static Tuple
uniquenessViolationKey(Tuple valueKey, Tuple primaryKey)
Return the key portion ofentry
, which should be the key with the index value as a tuple.default FDBStoredRecord<M>
updateRecord(M record)
Save the given record and throw an exception if the record does not already exist in the database.default CompletableFuture<FDBStoredRecord<M>>
updateRecordAsync(M record)
Save the given record and throw an exception if the record does not already exist in the database.-
Methods inherited from interface com.apple.foundationdb.record.RecordMetaDataProvider
getRecordMetaData
-
-
-
-
Method Detail
-
getUntypedRecordStore
FDBRecordStore getUntypedRecordStore()
Get the untyped record store associated with this possibly typed store.- Returns:
- an untyped record store
-
getTypedRecordStore
default <N extends Message> FDBTypedRecordStore<N> getTypedRecordStore(@Nonnull RecordSerializer<N> serializer)
Get a typed record store using the given typed serializer.- Type Parameters:
N
- the type for the new record store- Parameters:
serializer
- typed serializer to use- Returns:
- a new typed record store
-
getContext
@Nonnull FDBRecordContext getContext()
Get the record context (transaction) to use for the record store.- Returns:
- context the record context / transaction to use
-
getTimer
@Nullable default FDBStoreTimer getTimer()
-
getSubspaceProvider
@Nullable SubspaceProvider getSubspaceProvider()
Get the subspace provider.- Returns:
- the subspace provider
-
getSerializer
@Nonnull RecordSerializer<M> getSerializer()
Get the serializer used to convert records into byte arrays.- Returns:
- the serializer to use
-
saveRecordAsync
@Nonnull default CompletableFuture<FDBStoredRecord<M>> saveRecordAsync(@Nonnull M record)
Async version ofsaveRecord(Message)
.- Parameters:
record
- the record to save- Returns:
- a future that completes with the stored record form of the saved record
-
saveRecordAsync
@Nonnull default CompletableFuture<FDBStoredRecord<M>> saveRecordAsync(@Nonnull M record, @Nonnull FDBRecordStoreBase.RecordExistenceCheck existenceCheck)
Async version ofsaveRecord(Message, RecordExistenceCheck)
.- Parameters:
record
- the record to saveexistenceCheck
- when to throw an exception if a record with the same primary key does or does not already exist- Returns:
- a future that completes with the stored record form of the saved record
-
saveRecordAsync
@Nonnull default CompletableFuture<FDBStoredRecord<M>> saveRecordAsync(@Nonnull M record, @Nullable FDBRecordVersion version)
Async version ofsaveRecord(Message, FDBRecordVersion)
.- Parameters:
record
- the record to saveversion
- the associated record version- Returns:
- a future that completes with the stored record form of the saved record
-
saveRecordAsync
@Nonnull default CompletableFuture<FDBStoredRecord<M>> saveRecordAsync(@Nonnull M record, @Nullable FDBRecordVersion version, @Nonnull FDBRecordStoreBase.VersionstampSaveBehavior behavior)
Async version ofsaveRecord(Message, FDBRecordVersion, VersionstampSaveBehavior)
.- Parameters:
record
- the record to saveversion
- the associated record versionbehavior
- the save behavior w.r.t. the givenversion
- Returns:
- a future that completes with the stored record form of the saved record
-
saveRecordAsync
@Nonnull CompletableFuture<FDBStoredRecord<M>> saveRecordAsync(@Nonnull M record, @Nonnull FDBRecordStoreBase.RecordExistenceCheck existenceCheck, @Nullable FDBRecordVersion version, @Nonnull FDBRecordStoreBase.VersionstampSaveBehavior behavior)
Async version ofsaveRecord(Message, RecordExistenceCheck, FDBRecordVersion, VersionstampSaveBehavior)
.- Parameters:
record
- the record to saveexistenceCheck
- when to throw an exception if a record with the same primary key does or does not already existversion
- the associated record versionbehavior
- the save behavior w.r.t. the givenversion
- Returns:
- a future that completes with the stored record form of the saved record
-
saveRecord
@Nonnull default FDBStoredRecord<M> saveRecord(@Nonnull M record)
Save the given record.- Parameters:
record
- the record to be saved- Returns:
- wrapping object containing saved record and metadata
-
saveRecord
@Nonnull default FDBStoredRecord<M> saveRecord(@Nonnull M record, @Nonnull FDBRecordStoreBase.RecordExistenceCheck existenceCheck)
Save the given record.- Parameters:
record
- the record to be savedexistenceCheck
- when to throw an exception if a record with the same primary key does or does not already exist- Returns:
- wrapping object containing saved record and metadata
-
saveRecord
@Nonnull default FDBStoredRecord<M> saveRecord(@Nonnull M record, @Nullable FDBRecordVersion version)
Save the given record with a specific version. Ifnull
is passed forversion
, then a new version is created that will be unique for this record.- Parameters:
record
- the record to be savedversion
- the version to associate with the record when saving- Returns:
- wrapping object containing saved record and metadata
-
saveRecord
@Nonnull default FDBStoredRecord<M> saveRecord(@Nonnull M record, @Nullable FDBRecordVersion version, @Nonnull FDBRecordStoreBase.VersionstampSaveBehavior behavior)
Save the given record with a specific version. The version is handled according to the behavior value. If behavior isDEFAULT
then the method acts assaveRecord(Message, FDBRecordVersion)
. If behavior isNO_VERSION
thenversion
is ignored and no version is saved. If behavior isWITH_VERSION
then the value ofversion
is stored as given by the caller.- Parameters:
record
- the record to be savedversion
- the version to associate with the record when savingbehavior
- the save behavior w.r.t. the givenversion
- Returns:
- wrapping object containing saved record and metadata
-
saveRecord
@Nonnull default FDBStoredRecord<M> saveRecord(@Nonnull M record, @Nonnull FDBRecordStoreBase.RecordExistenceCheck existenceCheck, @Nullable FDBRecordVersion version, @Nonnull FDBRecordStoreBase.VersionstampSaveBehavior behavior)
Save the given record with a specific version. The version is handled according to the behavior value. If behavior isDEFAULT
then the method acts assaveRecord(Message, FDBRecordVersion)
. If behavior isNO_VERSION
thenversion
is ignored and no version is saved. If behavior isWITH_VERSION
then the value ofversion
is stored as given by the caller.- Parameters:
record
- the record to be savedexistenceCheck
- when to throw an exception if a record with the same primary key does or does not already existversion
- the version to associate with the record when savingbehavior
- the save behavior w.r.t. the givenversion
- Returns:
- wrapping object containing saved record and metadata
-
insertRecordAsync
@Nonnull default CompletableFuture<FDBStoredRecord<M>> insertRecordAsync(@Nonnull M record)
Save the given record and throw an exception if a record already exists with the same primary key.- Parameters:
record
- the record to be saved- Returns:
- a future that completes with the stored record form of the saved record
-
insertRecord
@Nonnull default FDBStoredRecord<M> insertRecord(@Nonnull M record)
Save the given record and throw an exception if a record already exists with the same primary key.- Parameters:
record
- the record to be saved- Returns:
- wrapping object containing saved record and metadata
-
updateRecordAsync
@Nonnull default CompletableFuture<FDBStoredRecord<M>> updateRecordAsync(@Nonnull M record)
Save the given record and throw an exception if the record does not already exist in the database.- Parameters:
record
- the record to be saved- Returns:
- a future that completes with the stored record form of the saved record
-
updateRecord
@Nonnull default FDBStoredRecord<M> updateRecord(@Nonnull M record)
Save the given record and throw an exception if the record does not already exist in the database.- Parameters:
record
- the record to be saved- Returns:
- wrapping object containing saved record and metadata
-
loadRecord
@Nullable default FDBStoredRecord<M> loadRecord(@Nonnull Tuple primaryKey)
Load the record with the given primary key.- Parameters:
primaryKey
- the primary key for the record- Returns:
- a
FDBStoredRecord
for the record ornull
.
-
loadRecord
@Nullable default FDBStoredRecord<M> loadRecord(@Nonnull Tuple primaryKey, boolean snapshot)
Load the record with the given primary key.- Parameters:
primaryKey
- the primary key for the recordsnapshot
- whether to load at snapshot isolation- Returns:
- a
FDBStoredRecord
for the record ornull
.
-
loadRecordAsync
@Nonnull default CompletableFuture<FDBStoredRecord<M>> loadRecordAsync(@Nonnull Tuple primaryKey)
Asynchronously load a record.- Parameters:
primaryKey
- the key for the record to be loaded- Returns:
- a CompletableFuture that will return a message or null if there was no record with that key
-
loadRecordAsync
@Nonnull default CompletableFuture<FDBStoredRecord<M>> loadRecordAsync(@Nonnull Tuple primaryKey, boolean snapshot)
Asynchronously load a record.- Parameters:
primaryKey
- the key for the record to be loadedsnapshot
- whether to load at snapshot isolation- Returns:
- a CompletableFuture that will return a message or null if there was no record with that key
-
loadRecordInternal
@Nonnull @API(INTERNAL) CompletableFuture<FDBStoredRecord<M>> loadRecordInternal(@Nonnull Tuple primaryKey, @Nonnull ExecuteState executeState, boolean snapshot)
-
preloadRecordAsync
@Nonnull CompletableFuture<Void> preloadRecordAsync(@Nonnull Tuple primaryKey)
Get record into FDB RYW cache. Caller needs to hold on to result until ready or else there is a chance it will get GC'ed and cancelled before then.- Parameters:
primaryKey
- the primary key for the record to retrieve- Returns:
- a future that will return
null
when the record is preloaded
-
recordExistsAsync
@Nonnull default CompletableFuture<Boolean> recordExistsAsync(@Nonnull Tuple primaryKey)
Check if a record exists in the record store with the given primary key. This performs its reads at theIsolationLevel.SERIALIZABLE
isolation level.- Parameters:
primaryKey
- the primary key of the record- Returns:
- a future that will complete to
true
if some record in record store has that primary key andfalse
otherwise - See Also:
recordExistsAsync(Tuple, IsolationLevel)
-
recordExistsAsync
@Nonnull CompletableFuture<Boolean> recordExistsAsync(@Nonnull Tuple primaryKey, @Nonnull IsolationLevel isolationLevel)
Check if a record exists in the record store with the given primary key. This is slightly more efficient than loading the record and checking if that record isnull
as it does not have to deserialize the record, though the record's contents are still read from the database and sent over the network.- Parameters:
primaryKey
- the primary key of the recordisolationLevel
- the isolation level to use when reading- Returns:
- a future that will complete to
true
if some record in record store has that primary key andfalse
otherwise
-
recordExists
default boolean recordExists(@Nonnull Tuple primaryKey)
Check if a record exists in the record store with the given primary key. This method is blocking. For the non-blocking version of this method, seerecordExistsAsync(Tuple)
.- Parameters:
primaryKey
- the primary key of the record- Returns:
true
if some record in record store has that primary key andfalse
otherwise- See Also:
recordExistsAsync(Tuple)
-
recordExists
default boolean recordExists(@Nonnull Tuple primaryKey, @Nonnull IsolationLevel isolationLevel)
Check if a record exists in the record store with the given primary key. This method is blocking. For the non-blocking version of this method, seerecordExistsAsync(Tuple, IsolationLevel)
.- Parameters:
primaryKey
- the primary key of the recordisolationLevel
- the isolation level to use when reading- Returns:
true
if some record in record store has that primary key andfalse
otherwise- See Also:
recordExistsAsync(Tuple)
-
addRecordReadConflict
void addRecordReadConflict(@Nonnull Tuple primaryKey)
Add a read conflict as if one had read the record with the given primary key. This will cause this transaction to fail (with aFDBExceptions.FDBStoreTransactionConflictException
) if a concurrent transaction modifies the record with the provided primary key. This call however does not require performing any reads against the database, so it is faster and cheaper to perform than a real read. Note also that read-only operations are not checked for conflicts, so if this method is called, but the transaction performs no mutations, the transaction will never be failed with the above exception. Note also that this does not check that a record with this primary key actually exists in the database.One use case is that this can be used to promote a read from
IsolationLevel.SNAPSHOT
toIsolationLevel.SERIALIZABLE
. For example, if one performs a query atIsolationLevel.SNAPSHOT
and then uses a subset of the records to determine a few other writes, then one can add conflicts to only the records actually used.This method should be used with care and is advised only for those users who need extra control over conflict ranges.
- Parameters:
primaryKey
- the primary key of the record to add a read conflict on- See Also:
Transaction.addReadConflictRange(byte[], byte[])
-
addRecordWriteConflict
void addRecordWriteConflict(@Nonnull Tuple primaryKey)
Add a write conflict as if one had modified the record with the given primary key. This will cause any concurrent transactions to fail (with aFDBExceptions.FDBStoreTransactionConflictException
) if they read the record with the provided primary key. This call however does not require performing any writes against the database, so it is faster and cheaper to perform than a real write. Note that this does not check if a record with this primary key actually exists in the database, and it does not update any indexes associated with the record. In this way, it is identical (in terms of conflicts) with overwriting the given record with itself, though it will not induce any disk I/O or cause any watches on the modified keys to fire.This method should be used with care and is advised only for those users who need extra control over conflict ranges.
- Parameters:
primaryKey
- the primary key of the record to add a write conflict on- See Also:
Transaction.addWriteConflictRange(byte[], byte[])
-
scanRecords
@Nonnull default RecordCursor<FDBStoredRecord<M>> scanRecords(@Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the records in the database.- Parameters:
continuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that will scan everything in the range, picking up at continuation, and honoring the given scan properties
-
scanRecords
@Nonnull default RecordCursor<FDBStoredRecord<M>> scanRecords(@Nonnull TupleRange range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the records in the database in a range.- Parameters:
range
- the range to scancontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that will scan everything in the range, picking up at continuation, and honoring the given scan properties
-
scanRecords
@Nonnull RecordCursor<FDBStoredRecord<M>> scanRecords(@Nullable Tuple low, @Nullable Tuple high, @Nonnull EndpointType lowEndpoint, @Nonnull EndpointType highEndpoint, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the records in the database in a range.- Parameters:
low
- low point of scan rangehigh
- high point of scan pointlowEndpoint
- whether low point is inclusive or exclusivehighEndpoint
- whether high point is inclusive or exclusivecontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that will scan everything in the range, picking up at continuation, and honoring the given scan properties
-
countRecords
@Nonnull default CompletableFuture<Integer> countRecords(@Nullable Tuple low, @Nullable Tuple high, @Nonnull EndpointType lowEndpoint, @Nonnull EndpointType highEndpoint)
Count the number of records in the database in a range.- Parameters:
low
- low point of scan rangehigh
- high point of scan pointlowEndpoint
- whether low point is inclusive or exclusivehighEndpoint
- whether high point is inclusive or exclusive- Returns:
- a future that will complete with the number of records in the range
-
countRecords
@Nonnull CompletableFuture<Integer> countRecords(@Nullable Tuple low, @Nullable Tuple high, @Nonnull EndpointType lowEndpoint, @Nonnull EndpointType highEndpoint, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Count the number of records in the database in a range.- Parameters:
low
- low point of scan rangehigh
- high point of scan pointlowEndpoint
- whether low point is inclusive or exclusivehighEndpoint
- whether high point is inclusive or exclusivecontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a future that will complete with the number of records in the range
-
scanIndex
@Nonnull RecordCursor<IndexEntry> scanIndex(@Nonnull Index index, @Nonnull IndexScanType scanType, @Nonnull TupleRange range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the entries in an index.- Parameters:
index
- the index to scanscanType
- the type of scan to performrange
- range to scancontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that will scan the index, picking up at continuation, and honoring the given scan properties
-
scanIndex
@API(DEPRECATED) @Deprecated @Nonnull default RecordCursor<IndexEntry> scanIndex(@Nonnull Index index, @Nonnull IndexScanType scanType, @Nonnull TupleRange range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties, @Nullable RecordScanLimiter recordScanLimiter)
Deprecated.because theRecordScanLimiter
should be specified as part of theScanProperties
insteadScan the entries in an index.- Parameters:
index
- the index to scanscanType
- the type of scan to performrange
- range to scancontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan propertiesrecordScanLimiter
- the scan limit to use- Returns:
- a cursor that will scan the index, picking up at continuation, and honoring the given scan properties
-
scanIndexRecords
@Nonnull default RecordCursor<FDBIndexedRecord<M>> scanIndexRecords(@Nonnull String indexName)
Scan the records pointed to by an index.- Parameters:
indexName
- the name of the index- Returns:
- a cursor that return records pointed to by the index
-
scanIndexRecords
@Nonnull default RecordCursor<FDBIndexedRecord<M>> scanIndexRecords(@Nonnull String indexName, IsolationLevel isolationLevel)
Scan the records pointed to by an index.- Parameters:
indexName
- the name of the indexisolationLevel
- the isolation level to use when reading- Returns:
- a cursor that return records pointed to by the index
-
scanIndexRecords
@Nonnull default RecordCursor<FDBIndexedRecord<M>> scanIndexRecords(@Nonnull String indexName, @Nonnull IndexScanType scanType, @Nonnull TupleRange range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the records pointed to by an index.- Parameters:
indexName
- the name of the indexscanType
- the type of scan to performrange
- the range of the index to scancontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that return records pointed to by the index
-
scanIndexRecords
@API(DEPRECATED) @Deprecated @Nonnull default RecordCursor<FDBIndexedRecord<M>> scanIndexRecords(@Nonnull String indexName, @Nonnull IndexScanType scanType, @Nonnull TupleRange range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties, @Nullable RecordScanLimiter recordScanLimiter)
Deprecated.because theRecordScanLimiter
should be specified as part of theScanProperties
insteadScan the records pointed to by an index.- Parameters:
indexName
- the name of the indexscanType
- the type of scan to performrange
- the range of the index to scancontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan propertiesrecordScanLimiter
- the scan limit to use- Returns:
- a cursor that return records pointed to by the index
-
scanIndexRecords
@Nonnull default RecordCursor<FDBIndexedRecord<M>> scanIndexRecords(@Nonnull String indexName, @Nonnull IndexScanType scanType, @Nonnull TupleRange range, @Nullable byte[] continuation, @Nonnull IndexOrphanBehavior orphanBehavior, @Nonnull ScanProperties scanProperties)
Scan the records pointed to by an index.- Parameters:
indexName
- the name of the indexscanType
- the type of scan to performrange
- the range of the index to scancontinuation
- any continuation from a previous scanorphanBehavior
- how the iteration process should respond in the face of entries in the index for which there is no associated recordscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that return records pointed to by the index
-
scanIndexRecords
@API(DEPRECATED) @Deprecated @Nonnull default RecordCursor<FDBIndexedRecord<M>> scanIndexRecords(@Nonnull String indexName, @Nonnull IndexScanType scanType, @Nonnull TupleRange range, @Nullable byte[] continuation, @Nonnull IndexOrphanBehavior orphanBehavior, @Nonnull ScanProperties scanProperties, @Nullable RecordScanLimiter recordScanLimiter)
Deprecated.because theRecordScanLimiter
should be specified as part of theScanProperties
insteadScan the records pointed to by an index.- Parameters:
indexName
- the name of the indexscanType
- the type of scan to performrange
- the range of the index to scancontinuation
- any continuation from a previous scanorphanBehavior
- how the iteration process should respond in the face of entries in the index for which there is no associated recordscanProperties
- skip, limit and other scan propertiesrecordScanLimiter
- the scan limit to use- Returns:
- a cursor that return records pointed to by the index
-
fetchIndexRecords
@API(DEPRECATED) @Deprecated @Nonnull default RecordCursor<FDBIndexedRecord<M>> fetchIndexRecords(@Nonnull Index index, @Nonnull RecordCursor<IndexEntry> indexCursor, @Nonnull IndexOrphanBehavior orphanBehavior)
Deprecated.Given a cursor that iterates over entries in an index, attempts to fetch the associated records for those entries.- Parameters:
index
- the definition of the index being scannedindexCursor
- a cursor iterating over entries in the indexorphanBehavior
- how the iteration process should respond in the face of entries in the index for which there is no associated record- Returns:
- a cursor returning indexed record entries
-
fetchIndexRecords
@Nonnull default RecordCursor<FDBIndexedRecord<M>> fetchIndexRecords(@Nonnull RecordCursor<IndexEntry> indexCursor, @Nonnull IndexOrphanBehavior orphanBehavior)
Given a cursor that iterates over entries in an index, attempts to fetch the associated records for those entries.- Parameters:
indexCursor
- a cursor iterating over entries in the indexorphanBehavior
- how the iteration process should respond in the face of entries in the index for which there is no associated record- Returns:
- a cursor returning indexed record entries
-
fetchIndexRecords
@API(DEPRECATED) @Deprecated @Nonnull default RecordCursor<FDBIndexedRecord<M>> fetchIndexRecords(@Nonnull Index index, @Nonnull RecordCursor<IndexEntry> indexCursor, @Nonnull IndexOrphanBehavior orphanBehavior, @Nonnull ExecuteState executeState)
Deprecated.Given a cursor that iterates over entries in an index, attempts to fetch the associated records for those entries.- Parameters:
index
- the definition of the index being scannedindexCursor
- a cursor iterating over entries in the indexorphanBehavior
- how the iteration process should respond in the face of entries in the index for which there is no associated recordexecuteState
- theExecuteState
associated with this query execution- Returns:
- a cursor returning indexed record entries
-
fetchIndexRecords
@Nonnull default RecordCursor<FDBIndexedRecord<M>> fetchIndexRecords(@Nonnull RecordCursor<IndexEntry> indexCursor, @Nonnull IndexOrphanBehavior orphanBehavior, @Nonnull ExecuteState executeState)
Given a cursor that iterates over entries in an index, attempts to fetch the associated records for those entries.- Parameters:
indexCursor
- A cursor iterating over entries in the index.orphanBehavior
- How the iteration process should respond in the face of entries in the index for which there is no associated record.executeState
- theExecuteState
associated with this query execution- Returns:
- A cursor returning indexed record entries.
-
scanIndexRecordsEqual
@Nonnull default RecordCursor<FDBIndexedRecord<M>> scanIndexRecordsEqual(@Nonnull String indexName, @Nonnull Object... values)
Scan the records pointed to by an index equal to indexed values.- Parameters:
indexName
- the name of the indexvalues
- a left-subset of values of indexed fields- Returns:
- a cursor that return records pointed to by the index
-
scanIndexRecordsBetween
@Nonnull default RecordCursor<FDBIndexedRecord<M>> scanIndexRecordsBetween(@Nonnull String indexName, @Nullable Object low, @Nullable Object high)
Scan the records pointed to by an index between two indexed values.- Parameters:
indexName
- the name of the indexlow
- the low value for the first indexed fieldhigh
- the high value for the first indexed field- Returns:
- a cursor that return records pointed to by the index
-
hasIndexEntryRecord
@API(DEPRECATED) @Deprecated @Nonnull default CompletableFuture<Boolean> hasIndexEntryRecord(@Nonnull Index index, @Nonnull IndexEntry entry, @Nonnull IsolationLevel isolationLevel)
Deprecated.usehasIndexEntryRecord(IndexEntry, IsolationLevel)
insteadDetermine if a given index entry points to a record.- Parameters:
index
- the index to checkentry
- the index entry to checkisolationLevel
- whether to use snapshot read- Returns:
- a future that completes with
true
if the given index entry still points to a record
-
hasIndexEntryRecord
@Nonnull default CompletableFuture<Boolean> hasIndexEntryRecord(@Nonnull IndexEntry entry, @Nonnull IsolationLevel isolationLevel)
Determine if a given index entry points to a record.- Parameters:
entry
- the index entry to checkisolationLevel
- whether to use snapshot read- Returns:
- a future that completes with
true
if the given index entry still points to a record
-
loadIndexEntryRecord
@API(DEPRECATED) @Deprecated @Nonnull default CompletableFuture<FDBIndexedRecord<M>> loadIndexEntryRecord(@Nonnull Index index, @Nonnull IndexEntry entry, @Nonnull IndexOrphanBehavior orphanBehavior)
Deprecated.Using the given index entry, resolve the primary key and asynchronously return the referenced record.- Parameters:
index
- the index being scannedentry
- the index entry to be resolvedorphanBehavior
- theIndexOrphanBehavior
to apply if the record is not found- Returns:
- the record referred to by the given index entry
-
loadIndexEntryRecord
@Nonnull default CompletableFuture<FDBIndexedRecord<M>> loadIndexEntryRecord(@Nonnull IndexEntry entry, @Nonnull IndexOrphanBehavior orphanBehavior)
Using the given index entry, resolve the primary key and asynchronously return the referenced record.- Parameters:
entry
- the index entry to be resolvedorphanBehavior
- theIndexOrphanBehavior
to apply if the record is not found- Returns:
- the record referred to by the given index entry
-
loadIndexEntryRecord
@API(DEPRECATED) @Deprecated @Nonnull default CompletableFuture<FDBIndexedRecord<M>> loadIndexEntryRecord(@Nonnull Index index, @Nonnull IndexEntry entry, @Nonnull IndexOrphanBehavior orphanBehavior, @Nonnull ExecuteState executeState)
Deprecated.Using the given index entry, resolve the primary key and asynchronously return the referenced record.- Parameters:
index
- the index being scannedentry
- the index entry to be resolvedorphanBehavior
- theIndexOrphanBehavior
to apply if the record is not foundexecuteState
- an execution state object to be used to enforce limits on query execution- Returns:
- the record referred to by the given index entry
-
loadIndexEntryRecord
@Nonnull default CompletableFuture<FDBIndexedRecord<M>> loadIndexEntryRecord(@Nonnull IndexEntry entry, @Nonnull IndexOrphanBehavior orphanBehavior, @Nonnull ExecuteState executeState)
Using the given index entry, resolve the primary key and asynchronously return the referenced record.- Parameters:
entry
- the index entry to be resolvedorphanBehavior
- theIndexOrphanBehavior
to apply if the record is not foundexecuteState
- an execution state object to be used to enforce limits on query execution- Returns:
- the record referred to by the given index entry
-
indexEntryPrimaryKey
@API(DEPRECATED) @Deprecated @Nonnull static Tuple indexEntryPrimaryKey(@Nonnull Index index, @Nonnull Tuple entry)
Deprecated.useIndex.getEntryPrimaryKey(Tuple)
insteadGet the primary key portion of an index entry.- Parameters:
index
- the index associated with this entryentry
- the index entry- Returns:
- the primary key extracted from the entry
-
indexEntryKey
@Nonnull static Tuple indexEntryKey(@Nonnull Index index, @Nonnull Tuple valueKey, @Nonnull Tuple primaryKey)
Return a tuple to be used as the key for an index entry for the given value and primary key.- Parameters:
index
- the index for which this will be an entryvalueKey
- the indexed value(s) for the entryprimaryKey
- the primary key for the record- Returns:
- the key to use for an index entry, the two tuples appended with redundant parts of the primary key removed
-
scanUniquenessViolations
@Nonnull default RecordCursor<RecordIndexUniquenessViolation> scanUniquenessViolations(@Nonnull Index index, @Nonnull Tuple valueKey, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the list of uniqueness violations for an index for violations with a specific value. This is similar to the version ofscanUniquenessViolations()
that takes aTupleRange
, but this version only selects violations that have the given key as the uniqueness violation key.- Parameters:
index
- the index to scan the uniqueness violations ofvalueKey
- the key (as a tuple) of the index whose violations to scancontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that will return uniqueness violations stored for the given index in the given store
-
scanUniquenessViolations
@Nonnull default RecordCursor<RecordIndexUniquenessViolation> scanUniquenessViolations(@Nonnull Index index, @Nonnull Key.Evaluated indexKey, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the list of uniqueness violations for an index for violations with a specific value. This is similar to the version ofscanUniquenessViolations()
that takes aTupleRange
, but this version only selects violations that have the given key as the uniqueness violation key.- Parameters:
index
- the index to scan the uniqueness violations ofindexKey
- the key of the index whose violations to scancontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that will return uniqueness violations stored for the given index in the given store
-
scanUniquenessViolations
@Nonnull default RecordCursor<RecordIndexUniquenessViolation> scanUniquenessViolations(@Nonnull Index index, @Nonnull Tuple valueKey)
Scan the list of uniqueness violations for an index for violations with a specific value. This is similar to the version ofscanUniquenessViolations()
that takes aTupleRange
, but this version only selects violations that have the given key as the uniqueness violation key. It does not limit the number of responses it returns.- Parameters:
index
- the index to scan the uniqueness violations ofvalueKey
- the key (as a tuple) of the index whose violations to scan- Returns:
- a cursor that will return uniqueness violations stored for the given index in the given store
-
scanUniquenessViolations
@Nonnull default RecordCursor<RecordIndexUniquenessViolation> scanUniquenessViolations(@Nonnull Index index, @Nonnull Key.Evaluated indexKey)
Scan the list of uniqueness violations for an index for violations with a specific value. This is similar to the version ofscanUniquenessViolations()
that takes aTupleRange
, but this version only selects violations that have the given key as the uniqueness violation key. It does not limit the number of responses it returns.- Parameters:
index
- the index to scan the uniqueness violations ofindexKey
- the key of the index whose violations to scan- Returns:
- a cursor that will return uniqueness violations stored for the given index in the given store
-
scanUniquenessViolations
@Nonnull default RecordCursor<RecordIndexUniquenessViolation> scanUniquenessViolations(@Nonnull Index index, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the list of uniqueness violations for an index for violations with a specific value. This is similar to the version ofscanUniquenessViolations()
that takes aTupleRange
, but this version tries to retrieve all of the violations it can subject to the limit specified.- Parameters:
index
- the index to scan the uniqueness violations ofcontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that will return uniqueness violations stored for the given index in the given store
-
scanUniquenessViolations
@Nonnull default RecordCursor<RecordIndexUniquenessViolation> scanUniquenessViolations(@Nonnull Index index, int limit)
Scan the list of uniqueness violations for an index for violations with a specific value. This is similar to the version ofscanUniquenessViolations()
that takes aTupleRange
, but this version tries to retrieve all of the violations it can subject to the limit specified.- Parameters:
index
- the index to scan the uniqueness violations oflimit
- the maximum number of uniqueness violations to report- Returns:
- a cursor that will return uniqueness violations stored for the given index in the given store
-
scanUniquenessViolations
@Nonnull default RecordCursor<RecordIndexUniquenessViolation> scanUniquenessViolations(@Nonnull Index index)
Scan the list of uniqueness violations for an index for violations with a specific value. This is similar to the version ofscanUniquenessViolations()
that takes aTupleRange
, but this version tries to retrieve all of the violations it can. It does not try to limit its results.- Parameters:
index
- the index to scan the uniqueness violations of- Returns:
- a cursor that will return uniqueness violations stored for the given index in the given store
-
scanUniquenessViolations
@Nonnull RecordCursor<RecordIndexUniquenessViolation> scanUniquenessViolations(@Nonnull Index index, @Nonnull TupleRange range, @Nullable byte[] continuation, @Nonnull ScanProperties scanProperties)
Scan the list of uniqueness violations identified for an index. It looks only for violations within the given range subject to the given limit and (possibly) will go in reverse. They will be returned in an order that is grouped by the index value keys that they have in common and will be ordered within the grouping by the primary key.Because of how the data are stored, each primary key that is part of a uniqueness violation will appear at most once for each index key that is causing a violation. The associated existing key is going to be one of the other keys, but it might not be the only one. This means that the total number of violations per index key is capped at the number of records in the store (rather than the square), but it also means that the existing key data is of limited help.
- Parameters:
index
- the index to scan the uniqueness violations ofrange
- the range of tuples to include in the scancontinuation
- any continuation from a previous scanscanProperties
- skip, limit and other scan properties- Returns:
- a cursor that will return uniqueness violations stored for the given index in the given store
-
resolveUniquenessViolation
@Nonnull default CompletableFuture<Void> resolveUniquenessViolation(@Nonnull Index index, @Nonnull Key.Evaluated indexKey, @Nullable Tuple primaryKey)
Removes all of the records that have the given value set as their index index value (are thus causing a uniqueness violation) except for the one that has the given primary key (if the key is notnull
). This is like the version ofresolveUniquenessViolation()
that takes aTuple
, but this takes the index value as aKey.Evaluated
instead.- Parameters:
index
- the index to resolve uniqueness violations forindexKey
- the value of the index that is being removedprimaryKey
- the primary key of the record that should remain (ornull
to remove all of them)- Returns:
- a future that will complete when all of the records have been removed
-
resolveUniquenessViolation
@Nonnull CompletableFuture<Void> resolveUniquenessViolation(@Nonnull Index index, @Nonnull Tuple valueKey, @Nullable Tuple primaryKey)
Removes all of the records that have the given value set as their index value (and are thus causing a uniqueness violation) except for the one that has the given primary key (if the key is notnull
). It also cleans up the set of uniqueness violations so that none of the remaining entries will be associated with the given value key.- Parameters:
index
- the index to resolve uniqueness violations forvalueKey
- the value of the index that is being removedprimaryKey
- the primary key of the record that should remain (ornull
to remove all of them)- Returns:
- a future that will complete when all of the records have been removed
-
uniquenessViolationKey
@Nonnull static Tuple uniquenessViolationKey(@Nonnull Tuple valueKey, @Nonnull Tuple primaryKey)
Return the key portion ofentry
, which should be the key with the index value as a tuple. This is used to store the index uniqueness violations when building a unique index.- Parameters:
valueKey
- the value of the index for a recordprimaryKey
- the primary key for a record- Returns:
- a tuple that is the two keys appended together
-
deleteRecordAsync
@Nonnull CompletableFuture<Boolean> deleteRecordAsync(@Nonnull Tuple primaryKey)
Async version ofdeleteRecord(com.apple.foundationdb.tuple.Tuple)
.- Parameters:
primaryKey
- the primary key of the record to delete- Returns:
- a future that completes
true
if the record was present to be deleted
-
deleteRecord
default boolean deleteRecord(@Nonnull Tuple primaryKey)
Delete the record with the given primary key.- Parameters:
primaryKey
- the primary key for the record to be deleted- Returns:
- true if something was there to delete, false if the record didn't exist
-
deleteAllRecords
void deleteAllRecords()
Delete all the data in the record store.Everything except the store header and index state information is cleared from the database. This is is an efficient operation as all data are contiguous. This means that any disabled or write-only index will remain in its disabled or write-only state after all of the data are cleared. If one also wants to reset all index states, one can call
FDBRecordStore.rebuildAllIndexes()
, which should complete quickly on an empty record store. If one wants to remove the record store entirely (including the store header and all index states), one should callFDBRecordStore.deleteStore(FDBRecordContext, KeySpacePath)
instead of this method.Note that, at the moment, this operation also has the side effect of resetting
MAX_EVER
andMIN_EVER
indexes. See: Issue #398.
-
deleteRecordsWhere
@Nonnull default void deleteRecordsWhere(@Nonnull QueryComponent component)
Delete records and associated index entries matching a query filter.Throws an exception if the operation cannot be done efficiently in a small number of contiguous range clears. In practice, this means that the query filter must constrain a prefix of all record types' primary keys and of all indexes' root expressions.
- Parameters:
component
- the query filter for records to delete efficiently
-
deleteRecordsWhere
@Nonnull default void deleteRecordsWhere(@Nonnull String recordType, @Nullable QueryComponent component)
Delete records and associated index entries matching a query filter.Throws an exception if the operation cannot be done efficiently in a small number of contiguous range clears. In practice, this means both that all record types must have a record type key prefix and that the query filter must constrain a prefix of all record types' primary keys and of all indexes' root expressions.
- Parameters:
recordType
- the type of records to deletecomponent
- the query filter for records to delete efficiently ornull
to delete all records of the given type
-
deleteRecordsWhereAsync
@Nonnull CompletableFuture<Void> deleteRecordsWhereAsync(@Nonnull QueryComponent component)
Async version ofdeleteRecordsWhereAsync(com.apple.foundationdb.record.query.expressions.QueryComponent)
.- Parameters:
component
- the query filter for records to delete efficiently- Returns:
- a future that will be complete when the delete is done
-
deleteRecordsWhereAsync
@Nonnull default CompletableFuture<Void> deleteRecordsWhereAsync(@Nonnull String recordType, @Nullable QueryComponent component)
Async version ofdeleteRecordsWhere(String, QueryComponent)
.- Parameters:
recordType
- the type of records to deletecomponent
- the query filter for records to delete efficiently ornull
to delete all records of the given type- Returns:
- a future that will be complete when the delete is done
-
getPipelineSizer
@Nonnull FDBRecordStoreBase.PipelineSizer getPipelineSizer()
Get the function for computing the number of elements to allow in the asynchronous pipeline for an operation of the given type.- Returns:
- the pipeline sizer
-
getPipelineSize
default int getPipelineSize(@Nonnull PipelineOperation pipelineOperation)
Get the number of elements to allow in the asynchronous pipeline for an operation of the given type.- Parameters:
pipelineOperation
- the operation- Returns:
- the number of elements to pipeline
-
getSnapshotRecordCount
@Nonnull default CompletableFuture<Long> getSnapshotRecordCount()
Get the number of records in the record store. There must be a suitableCOUNT
type index defined.- Returns:
- a future that will complete to the number of records in the store
-
getSnapshotRecordCount
@Nonnull CompletableFuture<Long> getSnapshotRecordCount(@Nonnull KeyExpression key, @Nonnull Key.Evaluated value)
Get the number of records in a portion of the record store determined by a group key expression. There must be a suitably groupedCOUNT
type index defined.- Parameters:
key
- the grouping key expressionvalue
- the value ofkey
to match- Returns:
- a future that will complete to the number of records
-
getSnapshotRecordCountForRecordType
@Nonnull CompletableFuture<Long> getSnapshotRecordCountForRecordType(@Nonnull String recordTypeName)
Get the number of records in the record store of the given record type. The record type must have aCOUNT
index defined for it.- Parameters:
recordTypeName
- record type for which to count records- Returns:
- a future that will complete to the number of records
-
getSnapshotRecordUpdateCount
default CompletableFuture<Long> getSnapshotRecordUpdateCount()
-
getSnapshotRecordUpdateCount
default CompletableFuture<Long> getSnapshotRecordUpdateCount(@Nonnull KeyExpression key, @Nonnull Key.Evaluated value)
-
evaluateRecordFunction
@Nonnull default <T> CompletableFuture<T> evaluateRecordFunction(@Nonnull RecordFunction<T> function, @Nonnull FDBRecord<M> record)
Evaluate aRecordFunction
against a record.- Type Parameters:
T
- the type of the result- Parameters:
function
- the function to evaluaterecord
- the record to evaluate against- Returns:
- a future that will complete with the result of evaluating the function against the record
-
evaluateRecordFunction
@Nonnull default <T> CompletableFuture<T> evaluateRecordFunction(@Nonnull EvaluationContext evaluationContext, @Nonnull RecordFunction<T> function, @Nonnull FDBRecord<M> record)
Evaluate aRecordFunction
against a record.- Type Parameters:
T
- the type of the result- Parameters:
evaluationContext
- evaluation context containing parameter bindingsfunction
- the function to evaluaterecord
- the record to evaluate against- Returns:
- a future that will complete with the result of evaluating the function against the record
-
evaluateIndexRecordFunction
@Nonnull <T> CompletableFuture<T> evaluateIndexRecordFunction(@Nonnull EvaluationContext evaluationContext, @Nonnull IndexRecordFunction<T> function, @Nonnull FDBRecord<M> record)
Evaluate aIndexRecordFunction
against a record.- Type Parameters:
T
- the type of the result- Parameters:
evaluationContext
- evaluation context containing parameter bindingsfunction
- the function to evaluaterecord
- the record to evaluate against- Returns:
- a future that will complete with the result of evaluating the function against the record
-
evaluateStoreFunction
@Nonnull default <T> CompletableFuture<T> evaluateStoreFunction(@Nonnull StoreRecordFunction<T> function, @Nonnull FDBRecord<M> record)
Evaluate aStoreRecordFunction
against a record.- Type Parameters:
T
- the type of the result- Parameters:
function
- the function to evaluaterecord
- the record to evaluate against- Returns:
- a future that will complete with the result of evaluating the function against the record
-
evaluateStoreFunction
@Nonnull <T> CompletableFuture<T> evaluateStoreFunction(@Nonnull EvaluationContext evaluationContext, @Nonnull StoreRecordFunction<T> function, @Nonnull FDBRecord<M> record)
Evaluate aStoreRecordFunction
against a record.- Type Parameters:
T
- the type of the result- Parameters:
evaluationContext
- evaluation context containing parameter bindingsfunction
- the function to evaluaterecord
- the record to evaluate against- Returns:
- a future that will complete with the result of evaluating the function against the record
-
evaluateAggregateFunction
@Nonnull default CompletableFuture<Tuple> evaluateAggregateFunction(@Nonnull EvaluationContext evaluationContext, @Nonnull List<String> recordTypeNames, @Nonnull IndexAggregateFunction aggregateFunction, @Nonnull TupleRange range, @Nonnull IsolationLevel isolationLevel)
Evaluate anIndexAggregateFunction
against a range of the store. Before callingevaluateAggregateFunction(List, IndexAggregateFunction, TupleRange, IsolationLevel)
, this overload adjusts the given range to include any prefix in the function itself.- Parameters:
evaluationContext
- evaluation context containing parameter bindingsrecordTypeNames
- record types for which to find a matching indexaggregateFunction
- the function to evaluaterange
- the range of records (group) for which to evaluateisolationLevel
- whether to use snapshot reads- Returns:
- a future that will complete with the result of evaluating the aggregate
-
evaluateAggregateFunction
@Nonnull default CompletableFuture<Tuple> evaluateAggregateFunction(@Nonnull List<String> recordTypeNames, @Nonnull IndexAggregateFunction aggregateFunction, @Nonnull Key.Evaluated value, @Nonnull IsolationLevel isolationLevel)
Evaluate anIndexAggregateFunction
against a group value.- Parameters:
recordTypeNames
- record types for which to find a matching indexaggregateFunction
- the function to evaluatevalue
- the value for the group key(s)isolationLevel
- whether to use snapshot reads- Returns:
- a future that will complete with the result of evaluating the aggregate
-
evaluateAggregateFunction
@Nonnull CompletableFuture<Tuple> evaluateAggregateFunction(@Nonnull List<String> recordTypeNames, @Nonnull IndexAggregateFunction aggregateFunction, @Nonnull TupleRange range, @Nonnull IsolationLevel isolationLevel)
Evaluate anIndexAggregateFunction
against a range of the store.- Parameters:
recordTypeNames
- record types for which to find a matching indexaggregateFunction
- the function to evaluaterange
- the range of records (group) for which to evaluateisolationLevel
- whether to use snapshot reads- Returns:
- a future that will complete with the result of evaluating the aggregate
-
queriedRecord
@Nonnull default FDBQueriedRecord<M> queriedRecord(@Nonnull FDBStoredRecord<M> storedRecord)
Get a query result record from a stored record. This is from a direct record scan / lookup without an associated index.- Parameters:
storedRecord
- the stored record to convert to a queried record- Returns:
- a
FDBQueriedRecord
corresponding tostoredRecord
-
queriedRecord
@Nonnull default FDBQueriedRecord<M> queriedRecord(@Nonnull FDBIndexedRecord<M> indexedRecord)
Get a query result record from an indexed record. This is from an index scan and permits access to the underlying index entry.- Parameters:
indexedRecord
- the indexed record to convert to a queried record- Returns:
- a
FDBQueriedRecord
corresponding toindexedRecord
-
coveredIndexQueriedRecord
@Nonnull default FDBQueriedRecord<M> coveredIndexQueriedRecord(@Nonnull Index index, @Nonnull IndexEntry indexEntry, @Nonnull RecordType recordType, @Nonnull M partialRecord, boolean hasPrimaryKey)
Get a query result from a covering index entry. The entireStoredRecord
is not available, and the record only has fields from the index entry. Normal indexes have a primary key in their entries, but aggregate indexes do not.- Parameters:
index
- the index from which the entry cameindexEntry
- the index entryrecordType
- the record type of the indexed recordpartialRecord
- the partially populated Protobuf recordhasPrimaryKey
- whether the index entry has a primary key- Returns:
- a
FDBQueriedRecord
corresponding toindexEntry
-
executeQuery
@Nonnull default RecordCursor<FDBQueriedRecord<M>> executeQuery(@Nonnull RecordQuery query)
Plan and execute a query.- Parameters:
query
- the query to plan and execute- Returns:
- a cursor for query results
- See Also:
RecordQueryPlan.execute(com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase<M>, com.apple.foundationdb.record.EvaluationContext, byte[], com.apple.foundationdb.record.ExecuteProperties)
-
executeQuery
@Nonnull default RecordCursor<FDBQueriedRecord<M>> executeQuery(@Nonnull RecordQuery query, @Nullable byte[] continuation, @Nonnull ExecuteProperties executeProperties)
Plan and execute a query.- Parameters:
query
- the query to plan and executecontinuation
- continuation from a previous execution of this same queryexecuteProperties
- limits on execution- Returns:
- a cursor for query results
- See Also:
RecordQueryPlan.execute(com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase<M>, com.apple.foundationdb.record.EvaluationContext, byte[], com.apple.foundationdb.record.ExecuteProperties)
-
executeQuery
@Nonnull default RecordCursor<FDBQueriedRecord<M>> executeQuery(@Nonnull RecordQueryPlan query)
Execute a query.- Parameters:
query
- the query to execute- Returns:
- a cursor for query results
- See Also:
RecordQueryPlan.execute(com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase<M>, com.apple.foundationdb.record.EvaluationContext, byte[], com.apple.foundationdb.record.ExecuteProperties)
-
executeQuery
@Nonnull default RecordCursor<FDBQueriedRecord<M>> executeQuery(@Nonnull RecordQueryPlan query, @Nullable byte[] continuation, @Nonnull ExecuteProperties executeProperties)
Execute a query.- Parameters:
query
- the query to executecontinuation
- continuation from a previous execution of this same planexecuteProperties
- limits on execution- Returns:
- a cursor for query results
- See Also:
RecordQueryPlan.execute(com.apple.foundationdb.record.provider.foundationdb.FDBRecordStoreBase<M>, com.apple.foundationdb.record.EvaluationContext, byte[], com.apple.foundationdb.record.ExecuteProperties)
-
planQuery
@Nonnull RecordQueryPlan planQuery(@Nonnull RecordQuery query)
Plan a query.- Parameters:
query
- the query to plan- Returns:
- a query plan
- See Also:
RecordQueryPlanner.plan(com.apple.foundationdb.record.query.RecordQuery)
-
-