ditto::Collection Class Reference

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

#include <Collection.hpp>

Public Member Functions
	Collection (std::shared_ptr< DittoHandleWrapper > ditto_handle_wrapper, uint64_t site_id, std::string name, private_ctor &&)
DocumentId	upsert (nlohmann::json content, WriteStrategy write_strategy=WriteStrategy::merge) const
	Inserts a new document into the collection and returns its ID. If the document already exists, the behavior is determined by the given write_strategy. More...
DocumentId	insert (nlohmann::json content, DocumentId id=DocumentId(), bool is_default=false) const DITTO_DEPRECATED
	Inserts a new document into the collection and returns the document's ID. More...
DocumentId	insert_with_strategy (nlohmann::json content, DocumentId id=DocumentId(), WriteStrategy write_strategy=WriteStrategy::overwrite) const DITTO_DEPRECATED
	Inserts a new document into the collection and returns the document's ID. More...
PendingIDSpecificOperation	find_by_id (DocumentId id) const
	Generates a PendingIDSpecificOperation with the provided document ID that can be used to find the document at a point in time or you can chain a call to observe, observe_local, or subscribe if you want to get updates about the document over time. More...
PendingCursorOperation	find_all () const
	Generates a PendingCursorOperation that can be used to find all documents in the collection at a point in time or you can chain a call to observe, observe_local, or subscribe if you want to get updates about documents in the collection over time. More...
PendingCursorOperation	find (std::string query) const
	Generates a PendingCursorOperation with the provided query that can be used to find the documents matching the query at a point in time or you can chain a call to observe, observe_local, or subscribe if you want to get updates about documents matching the query as they occur. More...
PendingCursorOperation	find (std::string query, nlohmann::json query_args) const
	Generates a PendingCursorOperation with the provided query that can be used to find the documents matching the query at a point in time or you can chain a call to observe, observe_local, or subscribe if you want to get updates about documents matching the query as they occur. More...
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. More...
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. More...

Public Attributes
std::string	name
	The name of the collection.

Detailed Description

A reference to a collection in a Store.

Member Function Documentation

fetch_attachment()

std::shared_ptr< AttachmentFetcher > ditto::Collection::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.

find() [1/2]

PendingCursorOperation ditto::Collection::find

(

std::string

query

)

const

Generates a PendingCursorOperation with the provided query that can be used to find the documents matching the query at a point in time or you can chain a call to observe, observe_local, or subscribe if you want to get updates about documents matching the query as they occur.

Parameters

[in]

query

the query to run against the collection.

Returns

a PendingCursorOperation that you can use to chain further query-related function calls.

find() [2/2]

PendingCursorOperation ditto::Collection::find	(	std::string	query,
		nlohmann::json	query_args
	)		const

Generates a PendingCursorOperation with the provided query that can be used to find the documents matching the query at a point in time or you can chain a call to observe, observe_local, or subscribe if you want to get updates about documents matching the query as they occur.

This is the recommended function 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[in]	the query to run against the collection.
query_args[in]	the arguments to use to replace placeholders in the provided query.

Returns

a PendingCursorOperation that you can use to chain further query-related function calls.

find_all()

PendingCursorOperation ditto::Collection::find_all

(

)

const

Generates a PendingCursorOperation that can be used to find all documents in the collection at a point in time or you can chain a call to observe, observe_local, or subscribe if you want to get updates about documents in the collection over time.

Returns

a PendingCursorOperation that you can use to chain further query-related function calls.

find_by_id()

PendingIDSpecificOperation ditto::Collection::find_by_id

(

DocumentId

id

)

const

Generates a PendingIDSpecificOperation with the provided document ID that can be used to find the document at a point in time or you can chain a call to observe, observe_local, or subscribe if you want to get updates about the document over time.

Parameters

[in]

id

the ID of the document.

Returns

a PendingIDSpecificOperation that you can chain function calls to either get the document immediately or get updates about it over time.

insert()

DocumentId ditto::Collection::insert	(	nlohmann::json	content,
		DocumentId	id = DocumentId(),
		bool	is_default = false
	)		const

Inserts a new document into the collection and returns the document's ID.

Parameters

[in]	content	the value to insert into the collection.
[in]	id	the ID to use for the document. If none (or a DocumentId created using the the default DocumentId constructor) is provided then Ditto will automatically assign an ID.
[in]	is_default	represents whether or not the data being inserted should be treated as default data or not. Set this to true if you want to set a default value that you expect to be overwritten by other devices in the network. The default value is false.

Returns

the ID of the inserted document.

Deprecated:

please use upsert() instead.

insert_with_strategy()

DocumentId ditto::Collection::insert_with_strategy	(	nlohmann::json	content,
		DocumentId	id = DocumentId(),
		WriteStrategy	write_strategy = WriteStrategy::overwrite
	)		const

Inserts a new document into the collection and returns the document's ID.

Parameters

[in]	content	the value to insert into the collection.
[in]	id	the ID to use for the document. If none (or a DocumentId created using the the default DocumentId constructor) is provided then Ditto will automatically assign an ID.
	write_strategy	specifies the desired strategy for inserting a document. The default value is WriteStrategy::overwrite.

Returns

the ID of the inserted document.

Deprecated:

please use upsert() instead.

new_attachment()

Attachment ditto::Collection::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 = collection.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.

upsert()

DocumentId ditto::Collection::upsert	(	nlohmann::json	content,
		WriteStrategy	write_strategy = WriteStrategy::merge
	)		const

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

Parameters

[in]	content	the value to insert into the collection. created using the the default DocumentId constructor) is provided then Ditto will automatically assign an ID.
	write_strategy	specifies the desired strategy for inserting a document. The default value is WriteStrategy::merge.

Returns

the ID of the inserted document.