DittoSDK.DittoCollection Class Reference

A reference to a collection in a DittoStore. More...

Public Member Functions
DittoPendingCursorOperation	Find (string query)
	Creates a cursor for the documents in this collection that match the provided query.
DittoPendingCursorOperation	Find (string query, Dictionary< string, object > queryArgs)
	Creates a cursor for the documents in this collection that match the provided query, with any placeholders replaced by the relevant provided query arguments.
DittoPendingCursorOperation	FindAll ()
	Creates a cursor for all of the documents in this collection.
DittoPendingIdSpecificOperation	FindById (DittoDocumentId id)
	Creates an accessor for a single document by its unique identifier.
DittoPendingIdSpecificOperation	FindById (object id)
	Creates a pending operation for a single document based on its unique identifier.
DittoDocumentId	Upsert (Dictionary< string, object > data, DittoWriteStrategy writeStrategy=DittoWriteStrategy.Merge)
	Inserts a new document into the collection and returns its identifier. If the document already exists, the behavior is determined by the given writeStrategy.
unsafe DittoAttachment	NewAttachment (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)
	Trigger an attachment to be downloaded locally to the device and observe its progress as it does so.

Properties
string	Name [get]
	Gets the name of the collection.

Detailed Description

A reference to a collection in a DittoStore.

This is the entrypoint for inserting documents into a collection, as well querying a collection.

Member Function Documentation

FetchAttachment()

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

inline

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 attachment's fetch attempt as it tries to download it. Assuming it succeeds in downloading the attachment it will call the onFetchEvent lambda with a completed event object, which will hold a reference to the attachment.

Parameters

token	The DittoAttachmentToken relevant to the attachment that you wish to download and observe.
onFetchEvent	A lambda that will be called when the attachment fetch attempt has a new event to deliver.

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.

Find() [1/2]

DittoPendingCursorOperation DittoSDK.DittoCollection.Find ( string query )

inline

Creates a cursor for the documents in this collection that match the provided query.

Parameters

query

A ditto query string.

Returns

A cursor for the query.

Find() [2/2]

DittoPendingCursorOperation DittoSDK.DittoCollection.Find ( string query, Dictionary< string, object > queryArgs )

inline

Creates a cursor for the documents in this collection that match the provided query, with any placeholders replaced by the relevant provided query arguments.

This is the recommended method to use when performing queries on a collection if you have any dynamic data included in the query string. It allows you to provide a query string with placeholders, in the form of $args.my_arg_name, along with an accompanying dictionary of arguments, in the form of { "my_arg_name": "some value" }, and the placeholders will be appropriately replaced by the matching provided arguments from the dictionary. This includes handling things like wrapping strings in quotation marks and arrays in square brackets, for example.

Parameters

query	A ditto query string.
queryArgs	The arguments to use to replace placeholders in the provided query.

Returns

A cursor for the query.

FindAll()

DittoPendingCursorOperation DittoSDK.DittoCollection.FindAll ( )

inline

Creates a cursor for all of the documents in this collection.

Returns

A cursor for all documents in the collection.

FindById() [1/2]

DittoPendingIdSpecificOperation DittoSDK.DittoCollection.FindById ( DittoDocumentId id )

inline

Creates an accessor for a single document by its unique identifier.

Parameters

id	The id of the document in this collection.

Returns

A cursor for a single document.

FindById() [2/2]

DittoPendingIdSpecificOperation DittoSDK.DittoCollection.FindById ( object id )

inline

Creates a pending operation for a single document based on its unique identifier.

Parameters

id	The id of the document in this collection.

Returns

A cursor for a single document.

NewAttachment()

unsafe DittoAttachment DittoSDK.DittoCollection.NewAttachment ( 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 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 NewAttachment functionality to insert an attachment into a document.

var attachment = coll.NewAttachment("/path/to/my/file.pdf", metadata);

var docId = coll.Upsert(new Dictionary<string, object> { { "other", "string" }, { "attachment", attachment } });

Parameters

path	The path to the file that you want to create an attachment with.
metadata	Metadata relating to the attachment.

Returns

A DittoAttachment object, which can be used to insert the attachment into a document.

Upsert()

DittoDocumentId DittoSDK.DittoCollection.Upsert ( Dictionary< string, object > data, DittoWriteStrategy writeStrategy = DittoWriteStrategy::Merge )

inline

Inserts a new document into the collection and returns its identifier. If the document already exists, the behavior is determined by the given writeStrategy.

This method will update an existing document if you provide an _id value and a document with that identifier exists in the collection.

Below is a snippet to show how you can use the Upsert functionality to update a document.

var docId = coll.Upsert(new Dictionary<string, object> { { "_id", new DittoDocumentId("customId") }, { "some", "string" }, });

Parameters

data	The document content.
writeStrategy	Specifies the desired strategy for inserting a document. The default value is DittoWriteStrategy.Merge.

Returns

The unique DittoDocumentId or null if the document could not be inserted.