DittoSDK.DittoStore Class Reference

A class encompassing functionality relating to the embedded storage. This is not a class you instantiate directly. Instead you access DittoStore objects using Ditto.Store. More...

Inheritance diagram for DittoSDK.DittoStore:

Public Member Functions
DittoPendingCollectionsOperation	Collections ()
	Returns an object that lets you fetch or observe the collections in the store.
DittoCollection	Collection (string collectionName)
	A method to reference a DittoCollection.
unsafe List< DittoWriteTransactionResult >	Write (Action< DittoWriteTransaction > handler)
	Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections.
Task< DittoQueryResult >	ExecuteAsync (string query, Dictionary< string, object > arguments=default)
	Executes a DQL query and returns matching items as a query result.
DittoStoreObserver	RegisterObserver (string query, Action< DittoQueryResult > storeObservationHandler)
DittoStoreObserver	RegisterObserver (string query, Action< DittoQueryResult, Action > storeObservationHandlerWithSignalNext)
DittoStoreObserver	RegisterObserver (string query, Func< DittoQueryResult, Task > storeObservationHandlerTask)
DittoStoreObserver	RegisterObserver (string query, Dictionary< string, object > arguments, Func< DittoQueryResult, Task > storeObservationHandlerTask)
DittoStoreObserver	RegisterObserver (string query, Dictionary< string, object > arguments, Action< DittoQueryResult > storeObservationHandler)
DittoStoreObserver	RegisterObserver (string query, Dictionary< string, object > arguments, Action< DittoQueryResult, Action > storeObservationHandlerWithSignalNext)
	Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local passed in query must be a SELECT query, otherwise a store error with queryNotSupported reason is thrown.
async Task< T >	TransactionAsync< T > (Func< DittoTransaction, Task< T > > scope, string hint=null, bool isReadOnly=false)
	Convenience method, same as TransactionAsync(Func<DittoTransaction, Task<DittoTransactionCompletionAction>>, string, bool), but propagates the return value of the scope rather than the completion action.
async Task	TransactionAsync (Func< DittoTransaction, Task > scope, string hint=null, bool isReadOnly=false)
	Convenience method, same as TransactionAsync<T>/>, but intended for transaction scopes that do not return a value.
async Task< DittoTransactionCompletionAction >	TransactionAsync (Func< DittoTransaction, Task< DittoTransactionCompletionAction > > scope, string hint=null, bool isReadOnly=false)
	Executes multiple DQL queries within a single atomic transaction.
Task< DittoAttachment >	NewAttachmentAsync (string path, Dictionary< string, string > metadata=null)
	Creates a new attachment, which can then be inserted into a document.
DittoAttachmentFetcher	FetchAttachment (DittoAttachmentToken token, Action< DittoAttachmentFetchEvent > onFetchEvent)
	Fetch the attachment corresponding to the provided attachment token.
DittoAttachmentFetcher	FetchAttachment (Dictionary< string, object > token, Action< DittoAttachmentFetchEvent > onFetchEvent)
	Fetch the attachment corresponding to the provided attachment token. Expects a dictionary representation of the token as returned in a DittoQueryResultItem.

Properties
IReadOnlyCollection< DittoStoreObserver >	Observers [get]
	Gets all currently active store observers.
IReadOnlyCollection< DittoAttachmentFetcher >	AttachmentFetchers [get]
	Gets all currently active attachment fetchers.
unsafe List< string >	CollectionNames [get]
	Gets the names of all collections known about on this device.
DittoDiskUsage	DiskUsage [get]
	Gets a reference to the store disk usage.
DittoCollection	this[string collectionName] [get]
	Retrieve a DittoCollection. var collection = ditto.store["cars"]; .

Detailed Description

A class encompassing functionality relating to the embedded storage. This is not a class you instantiate directly. Instead you access DittoStore objects using Ditto.Store.

Member Function Documentation

Collection()

DittoCollection DittoSDK.DittoStore.Collection ( string collectionName )

inline

A method to reference a DittoCollection.

Parameters

collectionName

The name of the collection.

Returns

A reference to the DittoCollection.

Collections()

DittoPendingCollectionsOperation DittoSDK.DittoStore.Collections ( )

inline

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

Returns

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

ExecuteAsync()

Task< DittoQueryResult > DittoSDK.DittoStore.ExecuteAsync ( string query, Dictionary< string, object > arguments = default )

inline

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

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

Implicitly creates a one-off transaction behind the scenes to execute the query. Refer to IDittoQueryExecuting.ExecuteAsync(string, Dictionary<string, object>) for a detailed description.

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: new Dictionary<string, object> { { "mileage", 123 } }

Returns

A DittoSDK.DittoQueryResult containing a DittoSDK.DittoQueryResultItem for each match.

Exceptions

DittoStoreException

Can throw a DittoStoreException. For more granular exception handling, check its subtypes: DittoQueryArgumentsInvalidException - If the query string is not a valid DQL. DittoQueryInvalidException - If the arguments dictionary is invalid (contains unsupported types). DittoQueryException - Error during query execution.

Implements DittoSDK.IDittoQueryExecuting.

FetchAttachment() [1/2]

DittoAttachmentFetcher DittoSDK.DittoStore.FetchAttachment ( Dictionary< string, object > token, Action< DittoAttachmentFetchEvent > onFetchEvent )

inline

Fetch the attachment corresponding to the provided attachment token. Expects a dictionary representation of the token as returned in a DittoQueryResultItem.

Parameters

token	Dictionary representation of the token for the attachment that you want to fetch.
onFetchEvent	An action that will be called when there is an update relating to the attachment fetch attempt. If the attachment is already available then this will be called almost immediately with a completed fetch event value.

Returns

A DittoAttachmentFetcher object, which must be kept alive for the fetch request to proceed and for you to be notified about the attachment fetch attempt's events. If the attachment fetcher could not be created then null will be returned. This can happen if, for example, an invalid attachment token was provided.

FetchAttachment() [2/2]

DittoAttachmentFetcher DittoSDK.DittoStore.FetchAttachment ( DittoAttachmentToken token, Action< DittoAttachmentFetchEvent > onFetchEvent )

inline

Fetch the attachment corresponding to the provided attachment token.

Parameters

token	The token for the attachment that you want to fetch.
onFetchEvent	An action that will be called when there is an update relating to the attachment fetch attempt. If the attachment is already available then this will be called almost immediately with a completed fetch event value.

Returns

A DittoAttachmentFetcher instance that can be used to cancel the attachment fetch.

Exceptions

DittoAttachmentNotFoundException	Attachment could not be found.
DittoAttachmentTokenInvalidException	The provided token is invalid.
DittoFailedToFetchAttachmentException	Error encountered trying to fetch the attachment.

NewAttachmentAsync()

Task< DittoAttachment > DittoSDK.DittoStore.NewAttachmentAsync ( string path, Dictionary< string, string > metadata = null )

inline

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

The file residing at the provided path will be copied into Ditto's store. The <see cref="DittoAttachment"/> 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 <see cref="NewAttachmentAsync"/> functionality to insert an attachment into a document.

var attachment = await store.NewAttachmentAsync("/path/to/my/file.zip");
if (attachment != null)
{
    var document = new Dictionary<string, object>
    {
        { &quot;some&quot;, &quot;string&quot; },
        { &quot;myAttachment&quot;, attachment }
    };
    await Ditto.Store.ExecuteAsync(
        query: &quot;INSERT INTO COLLECTION myCollection (myAttachment ATTACHMENT) DOCUMENTS (:document1)&quot;,
        arguments: new Dictionary<string, object>
        {
            { &quot;document1&quot;, document }
        }
    );
}

Parameters

path	Path to the file on disk that will be used as the attachment.
metadata	Optional metadata relating to the attachment.

Returns

A <see cref="DittoAttachment"/> object, which can be used to insert the attachment into a document.

Exceptions

DittoAttachmentFileNotFoundException	File not found at the provided path.
DittoAttachmentFilePermissionDeniedException	Permission denied error.
DittoFailedToCreateAttachmentException	Error encountered trying to create the attachment.

RegisterObserver() [1/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Action< DittoQueryResult > storeObservationHandler )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Action<DittoQueryResult, Action>)

RegisterObserver() [2/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Action< DittoQueryResult, Action > storeObservationHandlerWithSignalNext )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Action<DittoQueryResult, Action>)

RegisterObserver() [3/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Dictionary< string, object > arguments, Action< DittoQueryResult > storeObservationHandler )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Action<DittoQueryResult, Action>)

Parameters

storeObservationHandler

A simplified callback containing the DittoQueryResult, where signalNext is automatically called when the handler finishes.

RegisterObserver() [4/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Dictionary< string, object > arguments, Action< DittoQueryResult, Action > storeObservationHandlerWithSignalNext )

inline

Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local passed in query must be a SELECT query, otherwise a store error with queryNotSupported reason is thrown.

Returns

An active DittoStoreObserver for the passed in query and arguments. You'll have to keep it to be able to cancel the observation, i.e. remove it from the store again. Otherwise it will remain active until Ditto goes out of scope.

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: new Dictionary<string, object>() { { "mileage" , 123 } }
storeObservationHandlerWithSignalNext	A callback that is invoked whenever an active store observer receives a new result. The first parameter is the query result, while the second is an Action, signalNext, that should be called when the handler is ready to receive new data.

Exceptions

DittoStoreException

Can throw a DittoStoreException. For more granular exception handling check the following subtypes: DittoQueryArgumentsInvalidException - If the query string is not a valid DQL. DittoQueryInvalidException - If the arguments dictionary is not valid (contains unsupported types). DittoQueryNotSupportedException - If the query is not a SELECT query.

RegisterObserver() [5/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Dictionary< string, object > arguments, Func< DittoQueryResult, Task > storeObservationHandlerTask )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Action<DittoQueryResult, Action>)

Parameters

storeObservationHandlerTask

A simplified callback containing the DittoQueryResult, to be used in an async context, where signalNext is automatically called when the handler task finishes.

RegisterObserver() [6/6]

DittoStoreObserver DittoSDK.DittoStore.RegisterObserver ( string query, Func< DittoQueryResult, Task > storeObservationHandlerTask )

inline

See also

RegisterObserver(string, Dictionary<string, object>, Func<DittoQueryResult, Task>)

TransactionAsync() [1/2]

async Task DittoSDK.DittoStore.TransactionAsync ( Func< DittoTransaction, Task > scope, string hint = null, bool isReadOnly = false )

inline

Convenience method, same as TransactionAsync<T>/>, but intended for transaction scopes that do not return a value.

The transaction is committed implicitly upon successful completion and rolled back if an exception is thrown.

Parameters

scope	A delegate that provides access to a transaction object that can be used to execute DQL queries.
hint	A hint for the transaction, which is logged. Mostly useful for debugging and testing.
isReadOnly	A flag indicating whether the transaction is read-only.

Returns

A task that completes when the transaction scope has finished and the transaction has either committed or rolled back.

Exceptions

Exception

Will rethrow any error thrown within the scope function.

TransactionAsync() [2/2]

async Task< DittoTransactionCompletionAction > DittoSDK.DittoStore.TransactionAsync ( Func< DittoTransaction, Task< DittoTransactionCompletionAction > > scope, string hint = null, bool isReadOnly = false )

inline

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 isReadOnly parameter. 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 DittoTransaction.ExecuteAsync 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 explicitly disposed or garbage collected, it will drive all pending transactions to completion before being shut down.

<warning> Calling DittoStore.ExecuteAsync or creating a nested transaction within a transaction may lead to a deadlock. </warning>

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

.

Parameters

scope	A delegate that provides access to a transaction object that can be used to execute DQL queries.
hint	A hint for the transaction, which is logged. Mostly useful for debugging and testing.
isReadOnly	A flag indicating whether the transaction is read-only.

Returns

Transaction action that was taken (DittoTransactionCompletionAction.Commit or DittoTransactionCompletionAction.Rollback).

Exceptions

DittoTransactionReadOnlyException	Thrown if the transaction is read-only but a mutating query was executed.
DittoException	May throw other DittoException errors.

Will rethrow any error thrown within the scope delegate.

See also

DittoTransaction

TransactionAsync< T >()

async Task< T > DittoSDK.DittoStore.TransactionAsync< T > ( Func< DittoTransaction, Task< T > > scope, string hint = null, bool isReadOnly = false )

inline

Convenience method, same as TransactionAsync(Func<DittoTransaction, Task<DittoTransactionCompletionAction>>, string, bool), but propagates the return value of the scope rather than the completion action.

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

Parameters

scope	A delegate that provides access to a transaction object that can be used to execute DQL queries.
hint	A hint for the transaction, which is logged. Mostly useful for debugging and testing.
isReadOnly	A flag indicating whether the transaction is read-only.

Template Parameters

T	The return type of the transaction scope.

Returns

The propagated return value of the scope.

Will rethrow any error thrown within the scope function.

Write()

unsafe List< DittoWriteTransactionResult > DittoSDK.DittoStore.Write ( Action< DittoWriteTransaction > handler )

inline

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

Parameters

handler

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

Returns

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

Property Documentation

CollectionNames

unsafe List<string> DittoSDK.DittoStore.CollectionNames

get

Gets the names of all collections known about on this device.

Note, this will return immediately what is in the store.

this[string collectionName]

DittoCollection DittoSDK.DittoStore.this[string collectionName]

get

Retrieve a DittoCollection. var collection = ditto.store["cars"]; .

Parameters

collectionName

The name of the collection.

A collection name is valid if:

• its length is less than 100
• it is not empty
• it does not contain the char '\0'
• it does not begin with "$TS_"

  Returns

  A reference to the DittoCollection.