Skip to main content

arcadedb_protocol/client/
streaming.rs

1//! Server-streaming queries — the `StreamQuery` RPC: per-batch consumption,
2//! typed row streaming, and the testable [`consume_stream`] core.
3
4use super::*;
5
6/// Consume a `StreamQuery` batch stream through `on_batch`, one batch at a
7/// time. This is the testable core of
8/// [`ArcadeDbClient::stream_query`](crate::ArcadeDbClient::stream_query):
9/// generic over any stream of proto batches, so tests drive it with fakes
10/// instead of a live server.
11///
12/// The callback's borrow of each batch ends when it returns — borrowed
13/// `RecordDecode` views must be consumed (or converted to owned) inside the
14/// call; the API, not a caller-side comment, enforces the scope. Returning
15/// [`ControlFlow::Break`] stops pulling, drops the stream (cancelling the
16/// RPC), and marks the returned summary `truncated`.
17pub async fn consume_stream<S, F>(
18    stream: S,
19    mut on_batch: F,
20) -> std::result::Result<StreamSummary, tonic::Status>
21where
22    S: Stream<Item = std::result::Result<QueryResultBatch, tonic::Status>> + Unpin,
23    F: FnMut(&QueryResultBatch) -> ControlFlow<()>,
24{
25    let mut stream = stream;
26    let mut summary = StreamSummary::default();
27    while let Some(item) = stream.next().await {
28        let batch = item?;
29        summary.batches += 1;
30        summary.rows += batch.records.len();
31        summary.running_total_emitted = batch.running_total_emitted;
32        summary.is_last_batch = batch.is_last_batch;
33        if on_batch(&batch).is_break() {
34            summary.truncated = true;
35            return Ok(summary);
36        }
37    }
38    Ok(summary)
39}
40
41impl ArcadeDbClient {
42    /// Execute a SQL query on the server-streaming RPC (`StreamQuery`),
43    /// feeding each result batch to `on_batch` as it arrives — ranking,
44    /// filtering, and discarding happen per batch while the server produces
45    /// the next one, instead of materializing the entire result set
46    /// client-side first.
47    ///
48    /// The callback contract is [`consume_stream`]'s: borrowed views are
49    /// consumed inside the call, and `ControlFlow::Break` cancels the stream
50    /// early (the summary reports `truncated`). Prefer this over
51    /// [`query`](Self::query) for large candidate sets; keep `query` for
52    /// small reads.
53    pub async fn stream_query<F>(
54        &self,
55        database: &str,
56        query: &str,
57        on_batch: F,
58    ) -> Result<StreamSummary>
59    where
60        F: FnMut(&QueryResultBatch) -> ControlFlow<()>,
61    {
62        self.stream_query_impl(
63            database,
64            query,
65            crate::encode::Params::default(),
66            crate::stream::StreamOptions::default(),
67            on_batch,
68        )
69        .await
70    }
71
72    /// [`stream_query`](Self::stream_query) with bound `:name` parameters —
73    /// same parameter-safety and plan-caching notes as
74    /// [`query_with_values`](Self::query_with_values).
75    pub async fn stream_query_with_values<F>(
76        &self,
77        database: &str,
78        query: &str,
79        parameters: impl Into<crate::encode::Params>,
80        on_batch: F,
81    ) -> Result<StreamSummary>
82    where
83        F: FnMut(&QueryResultBatch) -> ControlFlow<()>,
84    {
85        let parameters = parameters.into();
86        self.stream_query_impl(
87            database,
88            query,
89            parameters,
90            crate::stream::StreamOptions::default(),
91            on_batch,
92        )
93        .await
94    }
95
96    /// [`stream_query_with_values`](Self::stream_query_with_values) with
97    /// explicit execution knobs — the
98    /// [`StreamOptions`](crate::stream::StreamOptions) knobs
99    /// (`batch_size`, `retrieval_mode`, projections) the plain methods
100    /// leave at server defaults.
101    pub async fn stream_query_with_options<F>(
102        &self,
103        database: &str,
104        query: &str,
105        parameters: impl Into<crate::encode::Params>,
106        options: crate::stream::StreamOptions,
107        on_batch: F,
108    ) -> Result<StreamSummary>
109    where
110        F: FnMut(&QueryResultBatch) -> ControlFlow<()>,
111    {
112        self.stream_query_impl(database, query, parameters.into(), options, on_batch)
113            .await
114    }
115
116    /// Typed row streaming: each record is decoded into `T` (the
117    /// [`RecordDecode`](crate::RecordDecode) bound) and passed to `on_row`
118    /// as it arrives — the [`rows`](QueryResult::rows) contract without
119    /// buffering the result set.
120    ///
121    /// `ControlFlow::Break` stops the stream early (summary reports
122    /// `truncated`). A row that does not decode fails the whole call with
123    /// [`ArcadeDbError::Decode`] — fail-fast, matching the buffered path's
124    /// whole-query error semantics.
125    pub async fn stream_query_rows<T, F>(
126        &self,
127        database: &str,
128        query: &str,
129        parameters: impl Into<crate::encode::Params>,
130        on_row: F,
131    ) -> Result<StreamSummary>
132    where
133        T: for<'r> TryFrom<&'r GrpcRecord, Error = RecordDecodeError>,
134        F: FnMut(T) -> ControlFlow<()>,
135    {
136        self.stream_query_rows_impl(
137            database,
138            query,
139            parameters,
140            crate::stream::StreamOptions::default(),
141            on_row,
142        )
143        .await
144    }
145
146    /// [`stream_query_rows`](Self::stream_query_rows) with explicit
147    /// [`StreamOptions`](crate::stream::StreamOptions).
148    pub async fn stream_query_rows_with_options<T, F>(
149        &self,
150        database: &str,
151        query: &str,
152        parameters: impl Into<crate::encode::Params>,
153        options: crate::stream::StreamOptions,
154        on_row: F,
155    ) -> Result<StreamSummary>
156    where
157        T: for<'r> TryFrom<&'r GrpcRecord, Error = RecordDecodeError>,
158        F: FnMut(T) -> ControlFlow<()>,
159    {
160        self.stream_query_rows_impl(database, query, parameters, options, on_row)
161            .await
162    }
163
164    pub(crate) async fn stream_query_impl<F>(
165        &self,
166        database: &str,
167        query: &str,
168        parameters: crate::encode::Params,
169        options: crate::stream::StreamOptions,
170        on_batch: F,
171    ) -> Result<StreamSummary>
172    where
173        F: FnMut(&QueryResultBatch) -> ControlFlow<()>,
174    {
175        let req = tonic::Request::new(StreamQueryRequest {
176            database: database.into(),
177            query: query.into(),
178            parameters: parameters.0,
179            credentials: Some(self.auth.creds.clone()),
180            language: "sql".into(),
181            batch_size: options.batch_size,
182            retrieval_mode: options.retrieval_mode.map_or(0, |m| m as i32),
183            projection_settings: options.projection,
184            ..Default::default()
185        });
186
187        let streaming = self
188            .data
189            .clone()
190            .stream_query(self.add_auth_headers(req))
191            .await
192            .map_err(|e| map_rpc_error("stream_query", query, e))?
193            .into_inner();
194
195        let summary = consume_stream(streaming, on_batch)
196            .await
197            .map_err(|e| map_rpc_error("stream_query", query, e))?;
198
199        tracing::info!(
200            count = summary.rows,
201            batches = summary.batches,
202            truncated = summary.truncated,
203            query = %query,
204            "stream query results"
205        );
206
207        Ok(summary)
208    }
209
210    /// Typed-row streaming core: wraps [`stream_query_impl`](Self::
211    /// stream_query_impl)'s batch callback with per-row decode. Decode
212    /// failure and callback `Break` both stop the stream; the decode failure
213    /// wins as the returned error (fail-fast, never half-reported).
214    pub(crate) async fn stream_query_rows_impl<T, F>(
215        &self,
216        database: &str,
217        query: &str,
218        parameters: impl Into<crate::encode::Params>,
219        options: crate::stream::StreamOptions,
220        mut on_row: F,
221    ) -> Result<StreamSummary>
222    where
223        T: for<'r> TryFrom<&'r GrpcRecord, Error = RecordDecodeError>,
224        F: FnMut(T) -> ControlFlow<()>,
225    {
226        let mut row_error: Option<ArcadeDbError> = None;
227        let mut stopped = false;
228        let result = self
229            .stream_query_impl(database, query, parameters.into(), options, |batch| {
230                if stopped {
231                    return ControlFlow::Break(());
232                }
233                for record in &batch.records {
234                    match T::try_from(record) {
235                        Ok(row) => {
236                            if let ControlFlow::Break(()) = on_row(row) {
237                                stopped = true;
238                                return ControlFlow::Break(());
239                            }
240                        }
241                        Err(e) => {
242                            row_error = Some(ArcadeDbError::Decode {
243                                what: format!("stream row of `{query}`"),
244                                source: e,
245                            });
246                            stopped = true;
247                            return ControlFlow::Break(());
248                        }
249                    }
250                }
251                ControlFlow::Continue(())
252            })
253            .await;
254
255        if let Some(e) = row_error {
256            return Err(e);
257        }
258        result
259    }
260}