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
/*
* Licensed to the Apache Software Foundation (ASF) under one or more
* contributor license agreements. See the NOTICE file distributed with
* this work for additional information regarding copyright ownership.
* The ASF licenses this file to You under the Apache License, Version 2.0
* (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
use crate::core::search::collector::Collector;
use crate::core::search::score_doc::{ScoreDoc, ScoreDocLike};
use crate::core::search::top_docs::{TopDocs, TopDocsLike};
use crate::core::search::total_hits::Relation::EqualTo;
use crate::core::search::total_hits::{Relation, TotalHits};
use crate::core::util::error::lucene_error::{LuceneError, Result};
use crate::core::util::priority_queue::{Compare, PriorityQueue};
use std::sync::LazyLock;
pub static EMPTY_TOP_DOCS: LazyLock<TopDocs<ScoreDoc>> =
LazyLock::new(|| TopDocs::new(TotalHits::new(0, EqualTo), vec![]));
/// A base trait for all collectors that return a [`TopDocs`] output.
///
/// This collector supports customization by accepting a [`PriorityQueue`] during creation,
/// together with reusable state for that priority queue and a total-hit counter.
///
/// Implementations can provide any of the methods to customize behavior.
/// It is also possible to avoid the use of the priority queue entirely by passing `None` instead of a [`PriorityQueue`].
/// In that case, provide all relevant methods to avoid inconsistent behavior.
///
/// # Notes
/// - This trait defines the shared [`TopDocsCollector`] behavior.
/// - The associated [`TopDocs`] represents the search results (hits + metadata).
/// - The `total_hits` counter and the [`PriorityQueue`] are the common state shared by all implementations.
pub trait TopDocsCollector: Collector {
/// The concrete priority-queue entry. The result type is provided by `TopDocsLike`.
type Item: ScoreDocLike + Default + Into<<Self::TopDocsLike as TopDocsLike>::ScoreDocLike>;
type Cmp: Compare<Self::Item>;
type TopDocsLike: TopDocsLike;
fn pq(&self) -> &PriorityQueue<Self::Item, Self::Cmp>;
fn pq_mut(&mut self) -> &mut PriorityQueue<Self::Item, Self::Cmp>;
fn total_hits(&self) -> usize;
/// The total number of documents that matched this query.
fn get_total_hits_relation(&self) -> Relation;
/// Populates the results array with the ScoreDoc instances.
/// This can be overridden in case a different ScoreDoc type should be returned.
fn populate_results(
&mut self,
results: &mut [<Self::TopDocsLike as TopDocsLike>::ScoreDocLike],
how_many: usize,
) -> Result<()> {
let pq = self.pq_mut();
debug_assert!(how_many <= pq.size());
for i in (0..how_many).rev() {
results[i] = pq.pop_unchecked()?.into()
}
Ok(())
}
/// Returns a [`TopDocs`] instance containing the given results.
///
/// If `results` is `None`, it means there are no results to return:
/// - either because there were 0 calls to `collect()`,
/// - or because the arguments to [`TopDocsCollector::top_docs`] were invalid.
///
/// # Notes
/// Builds top docs from a score-doc slice and a starting offset.
fn new_top_docs(
&self,
results: Option<Vec<<Self::TopDocsLike as TopDocsLike>::ScoreDocLike>>,
_start: i32,
) -> Self::TopDocsLike
where
Self: Sized;
fn default_new_top_docs(
&self,
results: Option<Vec<<Self::TopDocsLike as TopDocsLike>::ScoreDocLike>>,
_start: i32,
) -> TopDocs<<Self::TopDocsLike as TopDocsLike>::ScoreDocLike>
where
Self: Sized,
{
match results {
None => Self::empty_top_docs(),
Some(res) => TopDocs::new(
TotalHits::new(self.total_hits(), self.get_total_hits_relation()),
res,
),
}
}
fn top_docs_size(&self) -> usize {
let total = self.total_hits();
let pq_size = self.pq().size();
if total < pq_size { total } else { pq_size }
}
/// Returns the top docs that were collected by this collector.
fn top_docs(&mut self) -> Result<Self::TopDocsLike>
where
Self: Sized,
{
let size = self.top_docs_size() as i32;
self.top_docs_with_start_limit(0, size)
}
/// Returns the documents in the range `[start .. pq.size())` that were collected by this collector.
///
/// If `start >= pq.size()`, an empty [`TopDocs`] is returned.
///
/// This method is convenient to call if the application always asks for the last results,
/// starting from the last "page".
///
/// **NOTE:** you cannot call this method more than once for each search execution.
/// If you need to call it more than once, passing each time a different `start`,
/// you should call [`TopDocsCollector::top_docs`] and work with the returned [`TopDocs`] object,
/// which will contain all the results this search execution collected.
fn top_docs_with_start(&mut self, start: i32) -> Result<Self::TopDocsLike>
where
Self: Sized,
{
// In case pq was populated with sentinel values, there might be less
// results than pq.size(). Therefore return all results until either
// pq.size() or totalHits.
let size = self.top_docs_size() as i32;
self.top_docs_with_start_limit(start, size)
}
/// Returns the documents in the range `[start .. start+how_many)` that were collected by this collector.
///
/// If `start >= pq.size()`, an empty [`TopDocs`] is returned.
/// If `pq.size() - start < how_many`, then only the available documents in `[start .. pq.size())` are returned.
///
/// This method is useful in cases where pagination of search results is allowed by the application,
/// and it attempts to optimize memory usage by allocating only as much space as requested by `how_many`.
///
/// **NOTE:** you cannot call this method more than once for each search execution.
/// If you need to call it more than once, passing each time a different range,
/// you should call [`TopDocsCollector::top_docs`] and work with the returned [`TopDocs`] object,
/// which will contain all the results this search execution collected.
fn top_docs_with_start_limit(
&mut self,
start: i32,
mut how_many: i32,
) -> Result<Self::TopDocsLike>
where
Self: Sized,
{
let size = self.top_docs_size() as i32;
if how_many < 0 {
return Err(LuceneError::illegal_argument(format!(
"Number of hits requested must be greater than 0 but value was {}",
how_many
)));
}
if start < 0 {
return Err(LuceneError::illegal_argument(format!(
"Expected value of starting position is between 0 and {}, got {}",
size, start
)));
}
if start >= size || how_many == 0 {
return Ok(self.new_top_docs(None, start));
}
how_many = std::cmp::min(size - start, how_many);
let result_len = how_many as usize;
let mut results = vec![Default::default(); result_len];
let discard_count = self.pq().size() as i32 - start - how_many;
let pq = self.pq_mut();
for _ in 0..discard_count {
pq.pop_unchecked()?;
}
self.populate_results(&mut results, result_len)?;
Ok(self.new_top_docs(Some(results), start))
}
/// This is used in case topDocs() is called with illegal parameters, or there simply aren't (enough) results.
fn empty_top_docs() -> TopDocs<<Self::TopDocsLike as TopDocsLike>::ScoreDocLike>
where
Self: Sized,
{
TopDocs::new(TotalHits::new(0, Relation::EqualTo), vec![])
}
}
pub struct TopDocsCollectorBase<T, C> {
/// The total number of documents that the collector encountered.
pub(crate) total_hits: usize,
/// The priority queue which holds the top documents.
/// Note that different implementations of PriorityQueue give different meaning to 'top documents'.
/// HitQueue for example aggregates the top scoring documents,
/// while other PQ implementations may hold documents sorted by other criteria.
pub(crate) pq: PriorityQueue<T, C>,
/// Whether totalHits is exact or a lower bound.
pub(crate) total_hits_relation: Relation,
}
impl<T, C> TopDocsCollectorBase<T, C> {
pub fn new(pq: PriorityQueue<T, C>) -> Self {
Self {
total_hits: 0,
pq,
total_hits_relation: Relation::EqualTo,
}
}
}