dittolive_ditto/dql/
mod.rs

1//! Use DQL [`Query`]s to [subscribe to], [observe], and [edit] documents.
2//!
3//! # Example: Write and Read with DQL
4//!
5//! Let's look at how to execute an immediate query on the data in the `Store`
6//! using [`ditto.store().execute(...)`]:
7//!
8//! ```
9//! use dittolive_ditto::prelude::*;
10//! use dittolive_ditto::dql::QueryResult;
11//! # async fn example(ditto: &Ditto) -> anyhow::Result<()> {
12//!
13//! // Insert a document into a collection
14//! let insert_result: QueryResult = ditto
15//!     .store()
16//!     .execute_v2((
17//!          "INSERT INTO cars DOCUMENTS (:newCar)",
18//!          serde_json::json!({
19//!              "newCar": {
20//!                  "make": "ford",
21//!                  "color": "blue"
22//!              }
23//!          })
24//!     ))
25//!     .await?;
26//!
27//! // Select all documents from a collection
28//! let select_result: QueryResult = ditto.store().execute("SELECT * FROM cars", None).await?;
29//!
30//! // Extract documents as `serde_json::Value`s
31//! let documents: Vec<serde_json::Value> = select_result
32//!     .iter()
33//!     .flat_map(|item| item.deserialize_value().ok())
34//!     .collect();
35//!
36//! # Ok(())
37//! # }
38//! ```
39//!
40//! # Example: Observe document updates with DQL
41//!
42//! If instead we want to be notified when documents are changed, we can use
43//! [`ditto.store().register_observer(...)`] to receive callbacks for documents
44//! matching a given DQL query.
45//!
46//! ```
47//! use dittolive_ditto::{
48//!     dql::{QueryResult, QueryResultItem},
49//!     prelude::*,
50//! };
51//! # fn example(ditto: &Ditto) -> anyhow::Result<()> {
52//!
53//! let _observer = ditto.store().register_observer(
54//!     "SELECT * FROM cars",
55//!     None, // No query arguments
56//!     |query_result: QueryResult| {
57//!         let changed_documents = query_result
58//!             .iter()
59//!             .flat_map(|item: QueryResultItem| {
60//!                 item.deserialize_value::<serde_json::Value>().ok()
61//!             })
62//!             .collect::<Vec<_>>();
63//!
64//!         for doc in &changed_documents {
65//!             println!("Observed change to document: {doc}");
66//!         }
67//!     },
68//! )?;
69//! # Ok(())
70//! # }
71//! ```
72//!
73//! [subscribe to]: crate::sync::Sync::register_subscription
74//! [observe]: crate::store::Store::register_observer
75//! [edit]: crate::store::Store::execute
76//! [`ditto.store().execute(...)`]: crate::store::Store::execute
77//! [`ditto.store().register_observer(...)`]: crate::store::Store::register_observer
78
79/// Query
80pub(crate) mod query;
81#[allow(deprecated)]
82pub use query::{Query, QueryArguments};
83
84pub(crate) mod query_v2;
85pub use query_v2::{IntoQuery, QueryV2};
86
87/// Dql Result
88pub(crate) mod query_result;
89pub use query_result::{QueryResult, QueryResultItem};
90
91/// Differ
92pub(crate) mod differ;
93pub use differ::{Diff, DiffMove, Differ};
94
95// TODO(v5): Remove re-exports from deprecated location
96#[doc(hidden)]
97#[deprecated(note = "Use `dittolive_ditto::store::ChangeHandler` instead")]
98pub use crate::store::ChangeHandler;
99#[doc(hidden)]
100#[deprecated(note = "Use `dittolive_ditto::store::ChangeHandlerWithSignalNext` instead")]
101pub use crate::store::ChangeHandlerWithSignalNext;
102#[doc(hidden)]
103#[deprecated(note = "Use `dittolive_ditto::store::SignalNext` instead")]
104pub use crate::store::SignalNext;
105#[doc(hidden)]
106#[deprecated(note = "Use `dittolive_ditto::store::StoreObserver` instead")]
107pub use crate::store::StoreObserver;
108// NOTE(nimo): Ensure that even though this is deprecated, it's available
109/// ```
110/// use dittolive_ditto::{dql::SyncSubscription as _, store::dql::SyncSubscription as _};
111/// ```
112#[doc(hidden)]
113#[deprecated(note = "Use `sync::SyncSubscription` instead")]
114pub use crate::sync::SyncSubscription;
dittolive_ditto/dql/mod.rs

dittolive_ditto/dql/
mod.rs
