ditto::Store Class Reference

Provides access to Collections and a transaction API. More...

Public Member Functions
std::set< std::shared_ptr< AttachmentFetcher > >	get_attachment_fetchers () const
	Returns a copy of all currently active attachment fetchers.
Collection	collection (std::string name) const
	Returns a Collection with the provided name.
std::vector< std::unique_ptr< WriteTransactionResult > >	write (std::function< void(WriteTransaction &)> fn) const
	Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.
PendingCollectionsOperation	collections () const
	Returns an object that lets you fetch or observe the collections in the store.
DiskUsage	get_disk_usage () const
	Provides access to the Store's disk usage.
QueryResult	execute (std::string query, nlohmann::json query_args=nullptr)
	Executes a DQL query and returns matching items as a query result.
std::shared_ptr< StoreObserver >	register_observer (std::string query, StoreObservationHandler change_handler)
	Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.
std::shared_ptr< StoreObserver >	register_observer (std::string query, nlohmann::json query_args, StoreObservationHandler change_handler)
	Installs and returns a change observer for a query, configuring Ditto to call the provided in change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.
std::shared_ptr< StoreObserver >	register_observer (std::string query, StoreObservationHandlerWithNextSignal change_handler)
	Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.
std::shared_ptr< StoreObserver >	register_observer (std::string query, nlohmann::json query_args, StoreObservationHandlerWithNextSignal change_handler)
	Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.
Attachment	new_attachment (std::string path, std::map< std::string, std::string > metadata=std::map< std::string, std::string >()) const
	Creates a new attachment, which can then be inserted into a document.
std::shared_ptr< AttachmentFetcher >	fetch_attachment (std::shared_ptr< AttachmentToken > token, AttachmentFetcherEventHandler event_handler) const
	Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.
std::shared_ptr< AttachmentFetcher >	fetch_attachment (std::unordered_map< std::string, any > map, AttachmentFetcherEventHandler event_handler) const
	Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.
TransactionCompletionAction	transaction (const TransactionOptions &options, const std::function< TransactionCompletionAction(Transaction &)> &fn)
	Executes multiple DQL queries within a single atomic transaction.
TransactionCompletionAction	transaction (const std::function< TransactionCompletionAction(Transaction &)> &fn)
	Convenience function, same as transaction(TransactionOptions, std::function<TransactionCompletionAction(Transaction &)>) but with default options.
void	execute_transaction (const TransactionOptions &options, const std::function< void(Transaction &)> &fn)
	Convenience function, same as transaction(TransactionOptions, std::function<TransactionCompletionAction(Transaction &)>) but with a void-returning lambda.
void	execute_transaction (const std::function< void(Transaction &)> &fn)
	Convenience function, same as transaction(std::function<TransactionCompletionAction(Transaction &)>) but with a void-returning lambda.
template<typename T>
T	transaction_returning (const TransactionOptions &options, const std::function< T(Transaction &)> &fn)
	Convenience method, same as transaction(TransactionOptions, std::function<TransactionCompletionAction(Transaction &)>), but propagates the return value of the lambda rather than the completion action.
template<typename T>
T	transaction_returning (const std::function< T(Transaction &)> &fn)
	Convenience method, same as transaction(std::function<TransactionCompletionAction(Transaction &)>, but propagates the return value of the lambda rather than the completion action.

Public Attributes
std::set< std::shared_ptr< StoreObserver > >	observers
	Returns a copy of all currently active store observers.

Detailed Description

Provides access to Collections and a transaction API.

Executes multiple DQL queries within a single atomic transaction.

This ensures that either all statements are executed successfully, or none are executed at all, providing strong consistency guarantees. Certain mesh configurations may impose limitations on these guarantees. For more details, refer to the Ditto documentation.

Transactions are initiated as read-write transactions by default, and only a single read-write transaction is being executed at any given time. Any other read-write transaction started concurrently will wait until the current transaction has been committed or rolled back.

Therefore, it is crucial to make sure a transaction finishes as early as possible so other read-write transactions aren't blocked for a long time.

A transaction can also be configured to be read-only using the read_only option. Multiple read-only transactions can be executed concurrently. However, executing a mutating DQL statement in a read-only transaction will throw an error.

If errors occur in an execute() call within a transaction block and the error is caught and handled within the block, the transaction will continue to run and not be rolled back. When an error is thrown at any point inside the transaction block or while committing the transaction, the transaction is implicitly rolled back and the error is propagated up to the caller.

When a Ditto instance is closed or destroyed, it will drive all pending transactions to completion before being shut down.

Member Function Documentation

collection()

Collection ditto::Store::collection

(

std::string

name

)

const

Returns a Collection with the provided name.

Parameters

[in]

name

the name of the collection. A name is valid if: its length is less than 100 it does not contain the char '\0' it is not prefixed with "$TS_" it is not empty

Returns

a Collection.

Exceptions

if	name is not a valid Collection name.

collections()

PendingCollectionsOperation ditto::Store::collections

(

)

const

Returns an object that lets you fetch or observe the collections in the store.

Returns

a PendingCollectionsOperation object that you can use to fetch or observe the collections in the store

execute()

QueryResult ditto::Store::execute	(	std::string	query,
		nlohmann::json	query_args = nullptr )

Executes a DQL query and returns matching items as a query result.

This method only returns results from the local store without waiting for any SyncSubscriptions to have caught up with the latest changes. Only use this method if your program must proceed with immediate results. Use a StoreObserver to receive updates to query results as soon as they have been synced to this peer.

Parameters

query	a string containing a valid query expressed in DQL.
query_args	a dictionnary of values keyed by the placeholder name without the leading :.

execute_transaction() [1/2]

void ditto::Store::execute_transaction

(

const std::function< void(Transaction &)> &

fn

)

Convenience function, same as transaction(std::function<TransactionCompletionAction(Transaction &)>) but with a void-returning lambda.

The transaction is committed implicitly upon return or rolled back if an error is thrown.

execute_transaction() [2/2]

void ditto::Store::execute_transaction	(	const TransactionOptions &	options,
		const std::function< void(Transaction &)> &	fn )

Convenience function, same as transaction(TransactionOptions, std::function<TransactionCompletionAction(Transaction &)>) but with a void-returning lambda.

The transaction is committed implicitly upon return or rolled back if an exception is thrown.

fetch_attachment() [1/2]

std::shared_ptr< AttachmentFetcher > ditto::Store::fetch_attachment	(	std::shared_ptr< AttachmentToken >	token,
		AttachmentFetcherEventHandler	event_handler ) const

Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report changes to the status of the fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the event_handler lambda with a completed event object, which will hold a reference to the attachment.

Parameters

[in]	token	the AttachmentToken relevant to the attachment that you wish to download and observe.
[in]	event_handler	a lambda that will be called when there is an update relating to the attachment fetch attempt.

Returns

an AttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment's fetch attempt events.

Exceptions

`AttachmentNotFoundError`	if an attachment based on the provided token could not be found.
`AttachmentTokenInvalidError`	if the provided token is invalid.
`FailedToFetchAttachmentError`	if the fetch attempt failed for some other reason.

Note

this mutates the object, but in a synchronized, thread-safe fashion.

fetch_attachment() [2/2]

std::shared_ptr< AttachmentFetcher > ditto::Store::fetch_attachment	(	std::unordered_map< std::string, any >	map,
		AttachmentFetcherEventHandler	event_handler ) const

Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

When you encounter a document that contains an attachment the attachment will not automatically be downloaded along with the document. You trigger an attachment to be downloaded locally to a device by calling this method. It will report changes to the status of the fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the event_handler lambda with a completed event object, which will hold a reference to the attachment.

Parameters

[in]	map	a map representation of the AttachmentToken relevant to the attachment that you wish to download and observe.
[in]	event_handler	a lambda that will be called when there is an update relating to the attachment fetch attempt.

Returns

an AttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment's fetch attempt events.

Exceptions

`AttachmentNotFoundError`	if an attachment based on the provided token could not be found.
`AttachmentTokenInvalidError`	if the provided token is invalid.
`FailedToFetchAttachmentError`	if the fetch attempt failed for some other reason.

Note

this mutates the object, but in a synchronized, thread-safe fashion.

get_disk_usage()

DiskUsage ditto::Store::get_disk_usage

(

)

const

Provides access to the Store's disk usage.

Returns

a DiskUsage object.

new_attachment()

Attachment ditto::Store::new_attachment	(	std::string	path,
		std::map< std::string, std::string >	metadata = std::map<std::string, std::string>() ) const

Creates a new attachment, which can then be inserted into a document.

The file residing at the provided path will be copied into the Ditto's store. The Attachment object that is returned is what you can then use to insert an attachment into a document.

You can provide metadata about the attachment, which will be replicated to other peers alongside the file attachment.

Below is a snippet to show how you can use the new_attachment functionality to insert an attachment into a document.

auto attachment = ditto.get_store().new_attachment("/path/to/my/file.pdf");
auto docID = collection.insert(json{{"attachment", attachment}, {"other",
"string"}});

Parameters

[in]	path	the path to the file that you want to create an attachment with.
[in]	metadata	metadata relating to the attachment.

Returns

an Attachment object, which can be used to insert the attachment into a document.

Exceptions

`AttachmentFileNotFoundError`	if the file at the provided path does not exist.
`AttachmentFilePermissionDeniedError`	if the file at the provided path cannot be read.
`FailedToCreateAttachmentError`	if the attachment could not be created for some other reason.

register_observer() [1/4]

std::shared_ptr< StoreObserver > ditto::Store::register_observer	(	std::string	query,
		nlohmann::json	query_args,
		StoreObservationHandler	change_handler )

Installs and returns a change observer for a query, configuring Ditto to call the provided in change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.

Use a Differ to calculate a diff between subsequent query results delivered to the change handler.

Parameters

query	a string containing a valid query expressed in DQL.
arguments	a dictionary of values keyed by the placeholder name without the leading :. Example: {{"mileage", 123}}.

Returns

An active StoreObserver for the provided query and arguments. You'll have to keep it in scope to keep receiving changes.

Exceptions

`DittoError`

if the query is not a valid DQL query or if the query fails.

register_observer() [2/4]

std::shared_ptr< StoreObserver > ditto::Store::register_observer	(	std::string	query,
		nlohmann::json	query_args,
		StoreObservationHandlerWithNextSignal	change_handler )

Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.

Use a Differ to calculate a diff between subsequent query results delivered to the change handler.

Parameters

query	a string containing a valid query expressed in DQL.
query_args	a dictionary of values keyed by the placeholder name without the leading :. Example: {{"mileage", 123}}.

Returns

: An active StoreObserver for the provided query and arguments. You'll have to keep it in scope to receive changes.

register_observer() [3/4]

std::shared_ptr< StoreObserver > ditto::Store::register_observer	(	std::string	query,
		StoreObservationHandler	change_handler )

Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.

Use a Differ to calculate a diff between subsequent query results delivered to the change handler.

Parameters

query

a string containing a valid query expressed in DQL.

Returns

An active StoreObserver for the provided query. You'll have to keep it in scope to receive changes.

Exceptions

ref `DittoError` if the query is not a valid DQL query.

register_observer() [4/4]

std::shared_ptr< StoreObserver > ditto::Store::register_observer	(	std::string	query,
		StoreObservationHandlerWithNextSignal	change_handler )

Installs and returns a change observer for a query, configuring Ditto to call the provided change handler whenever documents in the local store change such that the result of the matching query changes. The provided query must be a SELECT query.

Use a Differ to calculate a diff between subsequent query results delivered to the change handler.

Parameters

query

a string containing a valid query expressed in DQL.

Returns

An active StoreObserver for the provided query. You'll have to keep it in scope to keep receiving changes.

transaction()

TransactionCompletionAction ditto::Store::transaction	(	const TransactionOptions &	options,
		const std::function< TransactionCompletionAction(Transaction &)> &	fn )

Executes multiple DQL queries within a single atomic transaction.

This ensures that either all statements are executed successfully, or none are executed at all, providing strong consistency guarantees. Certain mesh configurations may impose limitations on these guarantees. For more details, refer to the Ditto documentation.

Transactions are initiated as read-write transactions by default, and only a single read-write transaction is being executed at any given time. Any other read-write transaction started concurrently will wait until the current transaction has been committed or rolled back.

Therefore, it is crucial to make sure a transaction finishes as early as possible so other read-write transactions aren't blocked for a long time.

A transaction can also be configured to be read-only using the read_only option. Multiple read-only transactions can be executed concurrently. However, executing a mutating DQL statement in a read-only transaction will throw an error.

If errors occur in an execute() call within a transaction block and the error is caught and handled within the block, the transaction will continue to run and not be rolled back. When an error is thrown at any point inside the transaction block or while committing the transaction, the transaction is implicitly rolled back and the error is propagated up to the caller.

When a Ditto instance is closed or destroyed, it will drive all pending transactions to completion before being shut down.

Warning

Calling ditto.get_store().execute() or creating a nested transaction within a transaction block may lead to a deadlock.

For a complete guide on transactions, please refer to the Ditto documentation.

Parameters

options	a `TransactionOptions` object specifying configuration
fn	a lambda that provides access to a `Transaction` object that can be used to execute DQL queries.

Returns

a `TransactionCompletionAction` that was taken

Exceptions

`TransactionReadOnlyError`	if the transaction is read-only but a mutating query was executed
`DittoError`	if a DittoError is thrown within the lambda or upon attempt to commit the transaction
exception	if any exception is thrown within the fn lambda

See also

Transaction

transaction_returning() [1/2]

template<typename T>

T ditto::Store::transaction_returning ( const std::function< T(Transaction &)> & fn )

inline

Convenience method, same as transaction(std::function<TransactionCompletionAction(Transaction &)>, but propagates the return value of the lambda rather than the completion action.

The transaction is committed implicitly upon return or rolled back if an exception is thrown.

Template Parameters

T	The return type of the lambda.

transaction_returning() [2/2]

template<typename T>

T ditto::Store::transaction_returning ( const TransactionOptions & options, const std::function< T(Transaction &)> & fn )

inline

Convenience method, same as transaction(TransactionOptions, std::function<TransactionCompletionAction(Transaction &)>), but propagates the return value of the lambda rather than the completion action.

The transaction is committed implicitly upon return or rolled back if an exception is thrown.

Template Parameters

T	The return type of the lambda.

write()

std::vector< std::unique_ptr< WriteTransactionResult > > ditto::Store::write

(

std::function< void(WriteTransaction &)>

fn

)

const

Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.

Parameters

fn	a lambda that provides access to a write transaction object that can be used to perform operations on the store.

Returns

a list of WriteTransactionResults. There is a result for each operation performed as part of the write transaction.