Struct dittolive_ditto::store::Store

pub struct Store { /* private fields */ }

Store provides access to Collections and a write transaction API.

Implementations

impl Store

pub fn collection( &self, collection_name: &str ) -> Result<Collection, DittoError>

Returns a Collection with the provided name. 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_”

pub fn collections(&self) -> PendingCollectionsOperation<'_>

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

pub fn with_batched_write<F>( &self, f: F ) -> Result<Vec<WriteTransactionResult>, DittoError>

where for<'batch> F: FnOnce(ScopedStore<'batch>) -> Action<'batch>,

Allows you to group multiple operations together that affect multiple documents, potentially across multiple collections, without auto-committing on each operation.

At the end of the batch of operations, either batch.commit_changes or batch.revert_changes must be called.

Example

ditto.store().with_batched_write(|batch| {
    let mut foo_coll = batch.collection("foo");
    foo_coll.find...().remove();
    let mut bar_coll = batch.collection("bar");
    // Expensive multi-mutation op:
    for _ in 0 .. 10_000 {
        let doc = ...;
        bar_coll.insert(doc, None, false);
    }
    // At this point, we must say whether we commit or revert
    // these changes:
    batch.commit_changes()
})

pub fn collection_names(&self) -> Result<Vec<String>, DittoError>

Returns a list of the names of collections in the local store.

pub fn queries_hash( &self, live_queries: &[LiveQuery] ) -> Result<u64, DittoError>

Returns a hash representing the current version of the given queries. When a document matching such queries gets mutated, the hash will change as well.

Please note that the hash depends on how queries are constructed, so you should make sure to always compare hashes generated with the same set of queries.

pub fn queries_hash_mnemonic( &self, live_queries: &[LiveQuery] ) -> Result<String, DittoError>

Returns a sequence of English words representing the current version of the given queries. When a document matching such queries gets mutated, the words will change as well.

Please note that the resulting sequence of words depends on how queries are constructed, so you should make sure to always compare hashes generated with the same set of queries.

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

Start all live query webhooks.

pub fn start_live_query_webhook_by_id( &self, doc_id: DocumentId ) -> Result<(), DittoError>

Start a live query webhooks by its id.

pub fn register_live_query_webhook( &self, collection_name: &str, query: &str, url: &str ) -> Result<DocumentId, DittoError>

Register a new live query webhook

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

Generate a new API secret for live query webhook

pub fn timeseries(&self, ts_name: &str) -> Result<TimeSeries, DittoError>

Returns a TimeSeries with the provided name.

pub fn disk_usage(&self) -> &DiskUsage

Return a DiskUsage to monitor the disk usage of the Store.

pub fn register_observer<Q, F>( &self, query: Q, query_args: Option<QueryArguments>, on_change: F ) -> Result<Arc<StoreObserver>, DittoError>

where Q: TryInto<Query, Error = DittoError>, F: ChangeHandler,

Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local store change such that the result of the matching query changes. The passed in query must be a SELECT query, otherwise an error will be returned.

Example

use dittolive_ditto::prelude::*;

let store = ditto.store();
let _observer = store.register_observer(
    "SELECT * FROM cars WHERE color = 'blue'",
    None,
    move |query_result| {
        for item in query_result.iter() {
            // ... handle each item
        }
    },
)?;

You’ll need to keep the returned StoreObserver accessible to be able to cancel the observation. Otherwise it will remain active until the owning Ditto object goes out of scope.

pub fn register_observer_with_signal_next<Q, F>( &self, query: Q, query_args: Option<QueryArguments>, on_change: F ) -> Result<Arc<StoreObserver>, DittoError>

where Q: TryInto<Query, Error = DittoError>, F: ChangeHandlerWithSignalNext,

Installs and returns a store observer for a query, configuring Ditto to trigger the passed in change handler whenever documents in the local store change such that the result of the matching query changes. The passed in query must be a SELECT query, otherwise an error will be returned.

Here, a function is passed as an additional argument to the change handler. This allows the change handler to control how frequently it is called. See register_observer for a convenience method that automatically signals the next invocation.

Example

use dittolive_ditto::prelude::*;

let store = ditto.store();
let _observer = store.register_observer_with_signal_next(
    "SELECT * FROM cars WHERE color = 'blue'",
    None,
    move |query_result, signal_next| {
        for item in query_result.iter() {
            // ... handle each item
        }

        // Call `signal_next` when you're ready for the next callback
        signal_next();
    },
)?;

The first invocation of the change handler will always happen after this method has returned.

You’ll need to keep the returned StoreObserver accessible to be able to cancel the observation. Otherwise it will remain active until the owning Ditto object goes out of scope.

pub fn observers(&self) -> impl '_ + Deref<Target = SetArc<StoreObserver>>

Gets temporary access to the set of currently registered observers.

A (read) lock is held until the return value is dropped: this means that neither Self::register_observer() nor StoreObserver::cancel() can make progress until this read lock is released.

pub async fn execute<Q>( &self, query: Q, query_args: Option<QueryArguments> ) -> Result<QueryResult, DittoError>

where Q: TryInto<Query, Error = DittoError>,

Executes the given query in the local store and returns the result.

Use placeholders to incorporate values from the optional query_args parameter into the query. The keys of the QueryArguments object must match the placeholders used within the query. You can not use placeholders in the FROM clause.

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

Limitations:

• Supports SELECT * FROM <collection name> with optional WHERE <expression>
• No transactions

pub async fn new_attachment( &self, filepath: &(impl ?Sized + AsRef<Path>), user_data: HashMap<String, String> ) -> Result<DittoAttachment, DittoError>

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 custom user data about the attachment, which will be replicated to other peers alongside the file attachment.

pub async fn new_attachment_from_bytes( &self, bytes: &(impl ?Sized + AsRef<[u8]>), user_data: HashMap<String, String> ) -> Result<DittoAttachment, DittoError>

Creates a new attachment from in-memory data

Refer to new_attachment for additional information.

pub fn fetch_attachment( &self, attachment_token: impl DittoAttachmentTokenLike, on_fetch_event: impl 'static + Send + Sync + Fn(DittoAttachmentFetchEvent) ) -> Result<DittoAttachmentFetcher<'static, V2>, DittoError>

Fetches the attachment corresponding to the provided attachment token.

• attachment_token: can be either a DittoAttachmentToken, or a &BTreeMap<CborValue, CborValue>, that is, the output of a QueryResultItem::value() once casted .as_object().

• on_fetch_event: A closure that will be called when the status of the request to fetch the attachment has changed. If the attachment is already available then this will be called almost immediately with a completed status value.

The returned DittoAttachmentFetcher is a handle which is safe to discard, unless you wish to be able to .cancel() the fetching operation. When not explicitly cancelled, the fetching operation will remain active until it either completes, the attachment is deleted, or the owning Ditto object is dropped.

pub fn attachment_fetchers(&self) -> Vec<DittoAttachmentFetcher<'static, V2>>

Gets a copy of the set of currently registered attachment fetchers.

A (read) lock is held during the copy: this contends with Self::fetch_attachment() and with DittoAttachmentFetcher::cancel().

Trait Implementations

impl Clone for Store

fn clone(&self) -> Store

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.