flusso_query/handles/
mod.rs

1//! Field handles. Each handle carries a field path **and a scope** `S`, and
2//! exposes only the operators its mapping type supports; every operator builds a
3//! [`Query`]`<S>`.
4//!
5//! Root fields and flattened object / to-one-join sub-fields are scope
6//! [`Root`](crate::Root); a `nested` array's element handles carry the element type as their
7//! scope, so their queries must be lifted with [`Nested::any`]/[`Nested::all`]
8//! before joining a parent query. (The derive picks the right scope; hand-written
9//! handles default to `Root`.)
10//!
11//! The handles are grouped by field family:
12//!
13//! - `string` — [`Keyword`], [`Text`], and the cross-field [`multi_match`].
14//! - `scalar` — [`Bool`], [`Number`], [`Date`] (exact/range value fields).
15//! - `map` — [`TextMap`]/[`KeywordMap`] dynamic-key objects and [`MapSearch`].
16//! - `nested` — [`Nested`] arrays and their [`NestedProjection`].
17//! - `object` — [`Object`] sub-documents and the opaque [`Binary`]/[`Json`] fields.
18//! - `geo` — [`Geo`] points and [`GeoPoint`].
19//! - `sort` — [`Sort`]/[`SortOrder`].
20//!
21//! This module holds the pieces they share: the leaf-query builders and the
22//! [`trait@FlussoValue`] type-kind machinery.
23
24use serde_json::{Map, Value};
25
26use crate::query::Query;
27
28mod compound;
29mod extra;
30mod geo;
31mod map;
32mod nested;
33mod object;
34mod params;
35mod scalar;
36mod sort;
37mod string;
38
39pub use compound::{
40    BoostingQuery, ConstantScoreQuery, DisMaxQuery, FunctionScoreQuery, boosting, constant_score,
41    dis_max, function_score,
42};
43pub use extra::{
44    CombinedFieldsQuery, DistanceFeatureQuery, IdsQuery, MoreLikeThisQuery, QueryStringQuery,
45    RankFeatureQuery, ScriptQuery, ScriptScoreQuery, SimpleQueryStringQuery, combined_fields,
46    distance_feature, ids, more_like_this, query_string, rank_feature, script, script_score,
47    simple_query_string,
48};
49pub use geo::{Distance, DistanceUnit, Geo, GeoDistanceQuery, GeoPoint};
50pub use map::{DateMap, KeywordMap, MapSearch, NumberMap, TextMap};
51pub use nested::{Nested, NestedProjection, NestedQuery};
52pub use object::{Binary, Json, Object};
53pub use params::{
54    BoostMode, DistanceType, Fuzziness, MinimumShouldMatch, MultiMatchType, NestedScoreMode,
55    NumericType, Operator, RangeRelation, ScoreMode, ScriptSortType, ValidationMethod,
56    ZeroTermsQuery,
57};
58pub use scalar::{Bool, Date, EqQuery, Number, RangeQuery, TermsQuery};
59pub use sort::{Sort, SortMode, SortOrder};
60pub use string::{
61    FuzzyQuery, Keyword, MatchQuery, MultiMatchQuery, NoSubfields, PrefixQuery, RegexpQuery,
62    TermQuery, Text, WildcardQuery, WithSubfields, multi_match,
63};
64
65/// `{ "<wrapper>": { "<path>": <value> } }`.
66fn single<S>(wrapper: &str, path: &str, value: Value) -> Query<S> {
67    let mut inner = Map::new();
68    inner.insert(path.to_string(), value);
69    wrap(wrapper, inner)
70}
71
72/// `{ "<wrapper>": { <body> } }`.
73fn wrap<S>(wrapper: &str, body: Map<String, Value>) -> Query<S> {
74    let mut outer = Map::new();
75    outer.insert(wrapper.to_string(), Value::Object(body));
76    Query::leaf(Value::Object(outer))
77}
78
79/// The universal leaf-query modifiers every builder carries: `boost` (a
80/// relevance multiplier) and `name` (`_name`, surfaced in a hit's
81/// `matched_queries`). Builders embed one and call [`Common::write`] when
82/// rendering.
83#[derive(Debug, Clone, Default)]
84pub(crate) struct Common {
85    boost: Option<f32>,
86    name: Option<String>,
87}
88
89impl Common {
90    pub(crate) fn set_boost(&mut self, boost: f32) {
91        self.boost = Some(boost);
92    }
93
94    pub(crate) fn set_name(&mut self, name: String) {
95        self.name = Some(name);
96    }
97
98    /// Whether neither modifier is set (so a builder may render the shorthand).
99    pub(crate) fn is_empty(&self) -> bool {
100        self.boost.is_none() && self.name.is_none()
101    }
102
103    /// Write `boost` / `_name` into an option map, if set.
104    pub(crate) fn write(&self, map: &mut Map<String, Value>) {
105        if let Some(boost) = self.boost {
106            map.insert("boost".to_string(), Value::from(boost));
107        }
108        if let Some(name) = &self.name {
109            map.insert("_name".to_string(), Value::String(name.clone()));
110        }
111    }
112}
113
114/// Emit the universal `boost` / `name` setters on a builder whose [`Common`]
115/// lives in `self.$field`. Keeps the two methods identical across every builder.
116macro_rules! common_opts {
117    ($field:ident) => {
118        /// Multiply this clause's relevance score by `boost`.
119        #[must_use]
120        pub fn boost(mut self, boost: f32) -> Self {
121            self.$field.set_boost(boost);
122            self
123        }
124
125        /// Tag this clause with `_name`, surfaced in a hit's `matched_queries`.
126        #[must_use]
127        pub fn name(mut self, name: impl Into<String>) -> Self {
128            self.$field.set_name(name.into());
129            self
130        }
131    };
132}
133pub(crate) use common_opts;
134
135/// Render `{ wrapper: { path: <value> } }` (the DSL shorthand) when `opts` is
136/// empty, else `{ wrapper: { path: { <key>: <value>, ...opts } } }`. The shared
137/// shape for the value-bearing leaf queries (`term`/`prefix`/`wildcard`/… with
138/// `key = "value"`; `match`/`match_phrase`/… with `key = "query"`).
139fn keyed_value_query<S>(
140    wrapper: &str,
141    path: &str,
142    key: &str,
143    value: Value,
144    mut opts: Map<String, Value>,
145) -> Query<S> {
146    if opts.is_empty() {
147        single(wrapper, path, value)
148    } else {
149        opts.insert(key.to_string(), value);
150        single(wrapper, path, Value::Object(opts))
151    }
152}
153
154/// `{ "exists": { "field": "<path>" } }`.
155fn exists_q<S>(path: &str) -> Query<S> {
156    let mut inner = Map::new();
157    inner.insert("field".to_string(), Value::String(path.to_string()));
158    let mut outer = Map::new();
159    outer.insert("exists".to_string(), Value::Object(inner));
160    Query::leaf(Value::Object(outer))
161}
162
163/// `{ "match_all": {} }`.
164pub(crate) fn match_all_value() -> Value {
165    let mut outer = Map::new();
166    outer.insert("match_all".to_string(), Value::Object(Map::new()));
167    Value::Object(outer)
168}
169
170/// Field-category markers for [`trait@FlussoValue`]. Zero-size and uninhabited — they
171/// exist only as the `K` type parameter, so one type can be a valid value for
172/// several kinds (e.g. `String` is a [`kind::Keyword`], [`kind::Text`], and
173/// [`kind::Date`] value).
174pub mod kind {
175    /// A `keyword` field — an exact string.
176    #[derive(Debug)]
177    pub enum Keyword {}
178    /// A `text` field — an analyzed string.
179    #[derive(Debug)]
180    pub enum Text {}
181    /// A `boolean` field.
182    #[derive(Debug)]
183    pub enum Bool {}
184    /// A `byte` field (`i8`).
185    #[derive(Debug)]
186    pub enum Byte {}
187    /// A `short` field (`i16`).
188    #[derive(Debug)]
189    pub enum Short {}
190    /// An `integer` field (`i32`).
191    #[derive(Debug)]
192    pub enum Integer {}
193    /// A `long` field (`i64`).
194    #[derive(Debug)]
195    pub enum Long {}
196    /// A `float` / `half_float` field (`f32`).
197    #[derive(Debug)]
198    pub enum Float {}
199    /// A `double` field (`f64`).
200    #[derive(Debug)]
201    pub enum Double {}
202    /// A `decimal` / `scaled_float` field (`rust_decimal::Decimal`).
203    #[derive(Debug)]
204    pub enum Decimal {}
205    /// A `date`/`timestamp` field — an ISO-8601 string.
206    #[derive(Debug)]
207    pub enum Date {}
208}
209
210/// A Rust type usable where a field of kind `K` is expected: as the field type
211/// in a `#[derive(FlussoDocument)]` struct, and as a query value — for
212/// [`kind::Keyword`] on [`Keyword::eq`]/[`Keyword::any_of`], and for
213/// [`kind::Date`] on [`Date::eq`]/[`Date::gte`]/… (`String`/`&str`, or the
214/// `chrono` date types behind the `chrono` feature).
215///
216/// Built-in leaf types are pre-implemented (`String`/`&str` for keyword, the
217/// numeric primitives for number, …). Custom enums and newtype wrappers opt in
218/// with `#[derive(FlussoValue)]` (e.g. a `Pro`/`Enterprise`/`Free` tier enum →
219/// `Account::tier().eq(AccountTier::Pro)`, matched against its serde string).
220/// `FlussoDocument` emits a deferred bound on this trait for any non-primitive
221/// field type, so a document only compiles when the type genuinely fits.
222#[diagnostic::on_unimplemented(
223    message = "`{Self}` is not a valid value for a `{K}` field",
224    label = "unsupported field type",
225    note = "use a built-in leaf type, or add `#[derive(FlussoValue)]` (with the matching kind) to `{Self}`"
226)]
227pub trait FlussoValue<K>: serde::Serialize {}
228
229impl FlussoValue<kind::Keyword> for String {}
230impl FlussoValue<kind::Keyword> for &str {}
231#[cfg(feature = "uuid")]
232impl FlussoValue<kind::Keyword> for uuid::Uuid {}
233#[cfg(feature = "uuid")]
234impl FlussoValue<kind::Keyword> for &uuid::Uuid {}
235
236impl FlussoValue<kind::Text> for String {}
237impl FlussoValue<kind::Text> for &str {}
238
239impl FlussoValue<kind::Bool> for bool {}
240
241// A numeric type is a valid value for a numeric kind iff it widens into that
242// kind's Rust leaf **without loss** — so `Order::age().eq(5)` works on an `i64`
243// field, an `f64` field rejects an `i64` (precision), and an integer field
244// rejects a float. (`i32`→`f64` and any int→`Decimal` are lossless, so bare
245// literals work on `double`/`decimal`; `byte`/`short` need a typed literal.)
246macro_rules! number_values {
247    ($kind:path: $($ty:ty),+ $(,)?) => { $(impl FlussoValue<$kind> for $ty {})+ };
248}
249number_values!(kind::Byte: i8);
250number_values!(kind::Short: i8, i16);
251number_values!(kind::Integer: i8, i16, i32);
252number_values!(kind::Long: i8, i16, i32, i64);
253number_values!(kind::Float: i8, i16, f32);
254number_values!(kind::Double: i8, i16, i32, f32, f64);
255number_values!(kind::Decimal: i8, i16, i32, i64);
256#[cfg(feature = "decimal")]
257impl FlussoValue<kind::Decimal> for crate::Decimal {}
258
259impl FlussoValue<kind::Date> for String {}
260impl FlussoValue<kind::Date> for &str {}
261#[cfg(feature = "chrono")]
262impl FlussoValue<kind::Date> for chrono::NaiveDate {}
263#[cfg(feature = "chrono")]
264impl FlussoValue<kind::Date> for chrono::NaiveDateTime {}
265#[cfg(feature = "chrono")]
266impl FlussoValue<kind::Date> for chrono::DateTime<chrono::Utc> {}
267
268/// A Rust type usable as the **document type** of a `map` field of value kind
269/// `K`: a dynamic-key object whose values are all of kind `K`.
270///
271/// The canonical map type — `HashMap<String, V>` where `V` is a `K` value — is
272/// pre-implemented via a blanket impl, so `HashMap<String, String>` is a valid
273/// `text`/`keyword` map and `HashMap<String, i64>` a valid `long` map with no
274/// extra code. A whole-map newtype wrapper (`struct Translations(HashMap<…>)`)
275/// opts in with `#[derive(FlussoMap)]`. `FlussoDocument` emits a deferred bound
276/// on this trait for a `map` field, so the document only compiles when its type
277/// genuinely fits the declared value kind.
278#[diagnostic::on_unimplemented(
279    message = "`{Self}` is not a valid map for a `{K}` field",
280    label = "unsupported map type",
281    note = "use `HashMap<String, V>` with a `{K}` value type, or add `#[derive(FlussoMap)]` (with the matching kind) to `{Self}`"
282)]
283pub trait FlussoMap<K> {}
284
285impl<K, V: FlussoValue<K>> FlussoMap<K> for std::collections::HashMap<String, V> {}
flusso_query/handles/mod.rs

flusso_query/handles/
mod.rs
