Skip to main content

arcadedb_protocol/
stream.rs

1//! Streaming query options — the
2//! [`ArcadeDbClient::stream_query_with_options`](crate::ArcadeDbClient::stream_query_with_options)
3//! builder.
4//!
5//! The wire's `StreamQueryRequest` carries execution knobs the pre-0.3 API
6//! left at defaults: server `batch_size`, the
7//! [`RetrievalMode`] (CURSOR / MATERIALIZE_ALL / PAGED), and projection
8//! settings. [`StreamOptions`] surfaces them; the existing
9//! `stream_query`/`stream_query_with_values` keep their signatures and run
10//! with server defaults.
11
12use crate::proto::com::arcadedb::grpc::ProjectionSettings;
13
14// Canonical import path for the wire enum:
15// `arcadedb_protocol::stream::RetrievalMode`.
16pub use crate::proto::com::arcadedb::grpc::stream_query_request::RetrievalMode;
17
18/// Execution options for the server-streaming query RPC. Default is
19/// server-side defaults (batch sizing, CURSOR retrieval, full records).
20///
21/// ```no_run
22/// # async fn demo(client: &arcadedb_protocol::ArcadeDbClient) -> arcadedb_protocol::Result<()> {
23/// use arcadedb_protocol::{Params, stream::{RetrievalMode, StreamOptions}};
24/// use std::ops::ControlFlow;
25///
26/// let summary = client
27///     .stream_query_with_options(
28///         "mydb",
29///         "SELECT FROM item",
30///         Params::default(),
31///         StreamOptions::new()
32///             .batch_size(50_000)
33///             .retrieval_mode(RetrievalMode::Paged),
34///         |_batch| ControlFlow::Continue(()),
35///     )
36///     .await?;
37/// println!("{} rows in {} batches", summary.rows, summary.batches);
38/// # Ok(())
39/// # }
40/// ```
41#[derive(Clone, Debug, Default)]
42pub struct StreamOptions {
43    /// Server-side batch size; `0` = server default.
44    pub(crate) batch_size: i32,
45    pub(crate) retrieval_mode: Option<RetrievalMode>,
46    pub(crate) projection: Option<ProjectionSettings>,
47}
48
49impl StreamOptions {
50    /// Server defaults (equivalent to the plain `stream_query` methods).
51    pub fn new() -> Self {
52        Self::default()
53    }
54
55    /// Records per streamed batch: larger batches amortize per-batch
56    /// overhead, smaller batches keep memory flat.
57    pub fn batch_size(mut self, size: u32) -> Self {
58        self.batch_size = size as i32;
59        self
60    }
61
62    /// Wire retrieval mode:
63    /// - `Cursor` (server default) — run once, stream while iterating.
64    /// - `MaterializeAll` — server loads the full result, then emits batches.
65    /// - `Paged` — server re-issues `LIMIT/SKIP` per batch (consistent
66    ///   snapshots of moving data, at the cost of re-execution).
67    pub fn retrieval_mode(mut self, mode: RetrievalMode) -> Self {
68        self.retrieval_mode = Some(mode);
69        self
70    }
71
72    /// Server-side projection settings (field selection — the proto's
73    /// `ProjectionSettings`), when the query's shape should be narrowed
74    /// without rewriting the SQL text.
75    pub fn projection(mut self, settings: ProjectionSettings) -> Self {
76        self.projection = Some(settings);
77        self
78    }
79}