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}