elastiql 0.5.0

An opinionated Elasticsearch query language for Rust.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344

//! [Search request] types.
//!
//! [Search request]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html

use serde::{Deserialize, Serialize};
use serde_json::json;

#[cfg(feature = "graphql")]
use crate::search::{query::CompoundQueryInput, SortInput};
use crate::{
    scalars::SortedValue,
    search::{query::CompoundQuery, Sort},
};

/// The [request body] for an Elasticsearch search request.
///
/// [request body]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html
#[cfg(feature = "graphql")]
#[cfg_attr(feature = "builder", derive(typed_builder::TypedBuilder))]
#[derive(async_graphql::InputObject, Serialize, Clone, Debug)]
#[cfg_attr(feature = "builder", builder(field_defaults(setter(into))))]
pub struct RequestInput {
    /// The query to perform in this search request.
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "CompoundQueryInput::is_empty")]
    pub query: CompoundQueryInput,

    /// Sorts the results.
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub sort: Vec<SortInput>,

    /// The number of results to return.
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub size: Option<u64>,

    /// The maximum number of documents to collect for each shard, upon reaching
    /// which the query execution will terminate early.
    ///
    /// Defaults to `0`, which does not terminate query execution early.
    #[graphql(default)]
    #[cfg_attr(feature = "builder", builder(default))]
    pub terminate_after: u64,

    /// The live cursor from which to search after to fascilitate [pagination].
    ///
    /// [pagination]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-search-after
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(rename = "search_after", skip_serializing_if = "Vec::is_empty")]
    pub after: Vec<SortedValue>,

    /// Whether or not to include the document version in the search results.
    #[cfg_attr(feature = "builder", builder(default))]
    pub version: bool,

    /// Whether or not to include the [sequence number & primary term] in the
    /// search results.
    ///
    /// [sequence number & primary term]: https://www.elastic.co/guide/en/elasticsearch/reference/current/optimistic-concurrency-control.html
    #[cfg_attr(feature = "builder", builder(default))]
    pub seq_no_primary_term: bool,

    // TODO: could also be a bool...
    /// The lower bound for the number of hits to track
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub track_total_hits: Option<u64>,

    // TODO: figure out a way to not use this for queries that don't support it like `count`
    /// The [highlighted] snippets of the part(s) of the field(s) matching the
    /// search query.
    ///
    /// [highlighted]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-highlighting.html
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub highlight: Option<HighlightOptionsInput>,
}

#[cfg(feature = "graphql")]
impl RequestInput {
    /// Get a mutable reference to the [`CompoundQueryInput`].
    #[inline]
    pub fn query_mut(&mut self) -> &mut CompoundQueryInput {
        &mut self.query
    }
}

/// The [request body] for an Elasticsearch search request.
///
/// [request body]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html
#[cfg_attr(feature = "graphql", derive(async_graphql::SimpleObject))]
#[cfg_attr(feature = "builder", derive(typed_builder::TypedBuilder))]
#[derive(Serialize, Clone, Debug)]
#[cfg_attr(feature = "builder", builder(field_defaults(setter(into))))]
pub struct Request {
    /// The query to perform in this search request.
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "CompoundQuery::is_empty")]
    pub query: CompoundQuery,

    /// Sorts the results.
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Vec::is_empty")]
    pub sort: Vec<Sort>,

    /// The number of results to return.
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub size: Option<u64>,

    /// The maximum number of documents to collect for each shard, upon reaching
    /// which the query execution will terminate early.
    ///
    /// Defaults to `0`, which does not terminate query execution early.
    #[cfg_attr(feature = "builder", builder(default))]
    pub terminate_after: u64,

    /// The live cursor from which to search after to fascilitate [pagination].
    ///
    /// [pagination]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-body.html#request-body-search-search-after
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(rename = "search_after", skip_serializing_if = "Vec::is_empty")]
    pub after: Vec<SortedValue>,

    /// Whether or not to include the document version in the search results.
    #[cfg_attr(feature = "builder", builder(default))]
    pub version: bool,

    /// Whether or not to include the [sequence number & primary term] in the
    /// search results.
    ///
    /// [sequence number & primary term]: https://www.elastic.co/guide/en/elasticsearch/reference/current/optimistic-concurrency-control.html
    #[cfg_attr(feature = "builder", builder(default))]
    pub seq_no_primary_term: bool,

    // TODO: could also be a bool...
    /// The lower bound for the number of hits to track
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub track_total_hits: Option<u64>,

    // TODO: figure out a way to not use this for queries that don't support it like `count`
    /// The [highlighted] snippets of the part(s) of the field(s) matching the
    /// search query.
    ///
    /// [highlighted]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-highlighting.html
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Option::is_none")]
    pub highlight: Option<HighlightOptions>,
}

impl Request {
    /// Get a mutable reference to the [`CompoundQuery`].
    #[inline]
    pub fn query_mut(&mut self) -> &mut CompoundQuery {
        &mut self.query
    }
}

/// The [options] for highlighting.
///
/// **TODO**: add more options...
///
/// [options]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-highlighting.html#highlighting-settings
#[cfg(feature = "graphql")]
#[cfg_attr(feature = "builder", derive(typed_builder::TypedBuilder))]
#[derive(async_graphql::InputObject, Serialize, Deserialize, Clone, Debug)]
#[cfg_attr(feature = "builder", builder(field_defaults(setter(into))))]
pub struct HighlightOptionsInput {
    /// The field names and their options to highlight.
    pub fields: crate::scalars::Map,

    /// The highligher type to use.
    #[graphql(name = "type", default)]
    #[serde(rename = "type")]
    #[cfg_attr(feature = "builder", builder(default))]
    pub ty: HighlighterType,

    /// The maximum number of fragments to return.
    #[graphql(default_with = "5")]
    #[cfg_attr(feature = "builder", builder(default = 5))]
    pub number_of_fragments: u64,

    /// The size of the highlighted fragment in characters.
    #[graphql(default_with = "100")]
    #[cfg_attr(feature = "builder", builder(default = 100))]
    pub fragment_size: u32,

    /// How far to scan for boundary characters.
    #[graphql(default_with = "20")]
    #[cfg_attr(feature = "builder", builder(default = 20))]
    pub boundary_max_scan: u32,

    // TODO: should be an enum?
    /// Set to [`styled`] to use the built-in tag schema.
    ///
    /// [`styled`]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-highlighting.html
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "builder", builder(default))]
    pub tags_schema: Option<String>,

    /// Use in conjunction with `post_tags` to define the HTML tags to use for
    /// the highlighted text. By default, highlighted text is wrapped in `<em>`
    /// and `</em>` tags.
    #[graphql(default)]
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Vec::is_empty")] // es errors without this
    pub pre_tags: Vec<String>,

    /// Use in conjunction with `pre_tags` to define the HTML tags to use for
    /// the highlighted text. By default, highlighted text is wrapped in `<em>`
    /// and `</em>` tags.
    #[graphql(default)]
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Vec::is_empty")] // es errors without this
    pub post_tags: Vec<String>,

    /// By default, only fields that contains a query match are highlighted. Set
    /// `require_field_match` to `false` to highlight all fields.
    #[graphql(default = true)]
    #[cfg_attr(feature = "builder", builder(default = true))]
    pub require_field_match: bool,
}

/// The [options] for highlighting.
///
/// **TODO**: add more options...
///
/// [options]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-highlighting.html#highlighting-settings
#[cfg_attr(feature = "graphql", derive(async_graphql::SimpleObject))]
#[cfg_attr(feature = "builder", derive(typed_builder::TypedBuilder))]
#[derive(Serialize, Deserialize, Clone, Debug)]
#[cfg_attr(feature = "builder", builder(field_defaults(setter(into))))]
pub struct HighlightOptions {
    /// The field names and their options to highlight.
    pub fields: crate::scalars::Map,

    /// The highligher type to use.
    #[serde(rename = "type")]
    #[cfg_attr(feature = "builder", builder(default))]
    pub ty: HighlighterType,

    /// The maximum number of fragments to return.
    #[cfg_attr(feature = "builder", builder(default = 5))]
    pub number_of_fragments: u64,

    /// The size of the highlighted fragment in characters.
    #[cfg_attr(feature = "builder", builder(default = 100))]
    pub fragment_size: u32,

    /// How far to scan for boundary characters.
    #[cfg_attr(feature = "builder", builder(default = 20))]
    pub boundary_max_scan: u32,

    // TODO: should be an enum?
    /// Set to [`styled`] to use the built-in tag schema.
    ///
    /// [`styled`]: https://www.elastic.co/guide/en/elasticsearch/reference/current/search-request-highlighting.html
    #[serde(skip_serializing_if = "Option::is_none")]
    #[cfg_attr(feature = "builder", builder(default))]
    pub tags_schema: Option<String>,

    /// Use in conjunction with `post_tags` to define the HTML tags to use for
    /// the highlighted text. By default, highlighted text is wrapped in `<em>`
    /// and `</em>` tags.
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Vec::is_empty")] // es errors without this
    pub pre_tags: Vec<String>,

    /// Use in conjunction with `pre_tags` to define the HTML tags to use for
    /// the highlighted text. By default, highlighted text is wrapped in `<em>`
    /// and `</em>` tags.
    #[cfg_attr(feature = "builder", builder(default))]
    #[serde(skip_serializing_if = "Vec::is_empty")] // es errors without this
    pub post_tags: Vec<String>,

    /// By default, only fields that contains a query match are highlighted. Set
    /// `require_field_match` to `false` to highlight all fields.
    #[cfg_attr(feature = "builder", builder(default = true))]
    pub require_field_match: bool,
}

impl Default for HighlightOptions {
    #[inline]
    fn default() -> Self {
        let fields = [("*".to_string(), json!({}).into())]
            .iter()
            .cloned()
            .collect();

        HighlightOptions {
            fields,
            ty: HighlighterType::default(),
            number_of_fragments: 5,
            fragment_size: 100,
            boundary_max_scan: 20,
            tags_schema: Some("styled".to_string()),
            pre_tags: vec![],
            post_tags: vec![],
            require_field_match: true,
        }
    }
}

/// The different supported highlighter types/algorithm.
#[cfg_attr(feature = "graphql", derive(async_graphql::Enum, Eq, PartialEq, Copy))]
#[derive(Serialize, Deserialize, Clone, Debug)]
#[serde(rename_all = "lowercase")]
pub enum HighlighterType {
    /// The `unified` highlighter uses the Lucene Unified Highlighter. This
    /// highlighter breaks the text into sentences and uses the BM25 algorithm
    /// to score individual sentences as if they were documents in the corpus.
    /// It also supports accurate phrase and multi-term (fuzzy, prefix, regex)
    /// highlighting. This is the default highlighter.
    Unified,

    /// The `plain` highlighter uses the standard Lucene highlighter. It
    /// attempts to reflect the query matching logic in terms of understanding
    /// word importance and any word positioning criteria in phrase queries.
    Plain,

    /// The `fvh` highlighter uses the Lucene Fast Vector highlighter. This
    /// highlighter can be used on fields with term_vector set to
    /// `with_positions_offsets` in the mapping. The fast vector highlighter:
    ///
    /// - Can be customized with a `boundary_scanner`.
    /// - Requires setting term_vector to with_positions_offsets which increases
    ///   the size of the index
    /// - Can combine matches from multiple fields into one result. See
    ///   `matched_fields`
    /// - Can assign different weights to matches at different positions
    ///   allowing for things like phrase matches being sorted above term
    ///   matches when highlighting a Boosting Query that boosts phrase matches
    ///   over term matches
    Fvh,
}

impl Default for HighlighterType {
    #[inline]
    fn default() -> Self {
        Self::Unified
    }
}