Struct dittolive_ditto::store::query_builder::PendingIdSpecificOperation

pub struct PendingIdSpecificOperation { /* private fields */ }

Use .find_by_id(...) to query or mutate a single Document by its ID.

This object lets you take various actions on the selected document, such as:

• .exec(): Immediately return the current state of the document from the local store.

• .observe_local(...): Register a callback to receive notifications whenever the document changes in the local store. Note that this does not automatically begin syncing this document from remote peers, use .subscribe() for that.

• .subscribe(): Create a Subscription that syncs this document from remote peers.

• .remove(): Remove the document from the collection, replacing it with a tombstone. If another peer concurrently updates this document, the update will win (“add-wins”). This removal may be synced to other peers.

• .evict(): Evicts the document from this peer’s local store. This can be used to reduce resource consumption on peers that have finished using a document. This will not cause remote peers to evict or remove this document, it only impacts the local peer’s store.

• .update(...): Update the document via a callback that receives a mutable reference to it.

• .update_doc(...): Update the document by upserting a new value to replace the document.

Implementations

impl PendingIdSpecificOperation

pub fn exec(&self) -> Result<BoxedDocument, DittoError>

Execute the find operation and return the document with the matching ID.

Example

use dittolive_ditto::prelude::*;

let pending_op = ditto
    .store()
    .collection("cars")?
    .find_by_id(&b"mustang"[..]);
let document = pending_op.exec()?;

pub fn observe_local<Handler>( &self, handler: Handler, ) -> Result<LiveQuery, DittoError>

where Handler: SingleDocumentEventHandler,

Register a callback that delivers updates when the document changes.

The callback will be called any time the selected document is changed in this peer’s local store. It will NOT cause the document to be synced with remote peers, for that use .subscribe().

Hold the returned LiveQuery for as long as you wish to continue receiving updates. Dropping the LiveQuery will cancel the callbacks.

Example

use dittolive_ditto::prelude::*;

let pending_op = ditto
    .store()
    .collection("cars")?
    .find_by_id(&b"mustang"[..]);

// Hold the LiveQuery to continue receiving callbacks
let _live_query = pending_op.observe_local(|maybe_doc, event| {
    if let Some(doc) = maybe_doc {
        println!("Doc update: {doc:?}");
    }
})?;

// Drop the LiveQuery to cancel the callbacks
drop(_live_query);

pub fn subscribe(&self) -> Subscription

Creates a Subscription that syncs this document from remote peers.

Holding the Subscription will cause Ditto to continue syncing this document from remote peers. Dropping the Subscription will cancel the sync with remote peers.

Example

use dittolive_ditto::prelude::*;

let pending_op = ditto
    .store()
    .collection("cars")?
    .find_by_id(&b"mustang"[..]);

// Hold the subscription to continue syncing
let _subscription = pending_op.subscribe();

// Drop the subscription to cancel sync
drop(_subscription);

Panics

Panics if the parent Ditto object has been closed.

pub fn remove(&self) -> Result<(), DittoError>

Removes this document from its Collection.

A document removal may sync to other peers, causing them to remove the document as well. However, a concurrent update from a remote peer will win when merging the update with the removal (“add-wins”).

Example

use dittolive_ditto::prelude::*;

let pending_op = ditto
    .store()
    .collection("cars")?
    .find_by_id(&b"mustang"[..]);
pending_op.remove()?;

pub fn evict(&self) -> Result<(), DittoError>

Evict this document from the local peer’s store.

Unlike a removal, an eviction does not create a tombstone to sync with other peers. When a document is evicted, it is simply removed from the local store to save disk space.

Example

use dittolive_ditto::prelude::*;

let pending_op = ditto
    .store()
    .collection("cars")?
    .find_by_id(&b"mustang"[..]);
pending_op.evict()?;

pub fn update<Updater>( &self, updater: Updater, ) -> Result<Vec<UpdateResult>, DittoError>

where Updater: Fn(Option<&mut BoxedDocument>),

Update the selected document by mutating it directly.

Example

use dittolive_ditto::prelude::*;

let pending_op = ditto
    .store()
    .collection("cars")?
    .find_by_id(&b"mustang"[..]);

let results = pending_op.update(|maybe_doc| {
    if let Some(doc) = maybe_doc {
        doc.set("details.make", "ford").unwrap();
    }
})?;

pub fn update_doc<T>(&self, new_value: &T) -> Result<(), DittoError>

where T: Serialize,

Replaces the matching document with the provided value.

• new_value: A new Serializable which will replace the found document

Note this actually follows “upsert” rules and will insert a document if no document is found with the given DocumentId.

Example

use dittolive_ditto::prelude::*;

let pending_op = ditto.store().collection("cars")?.find_by_id(&b"mustang"[..]);
pending_op.update_doc(&serde_json::json!({
    "make": "ford",
    "color": "red"
}))?;