diff options
author | Paul Masurel <paul.masurel@gmail.com> | 2016-10-30 10:06:51 +0900 |
---|---|---|
committer | Paul Masurel <paul.masurel@gmail.com> | 2016-10-30 10:06:51 +0900 |
commit | 8b5f7af688fe442c7f30447473034aafbc242361 (patch) | |
tree | 187855e630f3e96ea737828ecf53d2a08c63e0d0 /src/query | |
parent | 767fa94d182a4df8097540b81e8a1730f0fefdca (diff) |
issue/50 Added documentation for the query object.
Diffstat (limited to 'src/query')
-rw-r--r-- | src/query/query.rs | 50 |
1 files changed, 44 insertions, 6 deletions
diff --git a/src/query/query.rs b/src/query/query.rs index 0e27c13..3b15f30 100644 --- a/src/query/query.rs +++ b/src/query/query.rs @@ -8,17 +8,55 @@ use std::fmt; use std::any::Any; -/// Queries represent the query of the user, and are in charge -/// of the logic defining the set of documents that should be -/// sent to the collector, as well as the way to score the -/// documents. +/// Query trait are in charge of defining : +/// +/// - a set of documents +/// - a way to score these documents +/// +/// When performing a [search](#method.search), these documents will then +/// be pushed to a [Collector](../collector/trait.Collector.html), +/// which will in turn be in charge of deciding what to do with them. +/// +/// Concretely, this scored docset is represented by the +/// [`Scorer`](./trait.Scorer.html) trait. +/// +/// Because our index is actually split into segments, the +/// query does not actually directly creates `DocSet` object. +/// Instead, the query creates a [`Weight`](./trait.Weight.html) +/// object for a given searcher. +/// +/// The weight object, in turn, makes it possible to create +/// a scorer for a specific [`SegmentReader`](../struct.SegmentReader.html). +/// +/// So to sum it up : +/// - a `Query` is recipe to define a set of documents as well the way to score them. +/// - a `Weight` is this recipe tied to a specific `Searcher`. It may for instance +/// hold statistics about the different term of the query. It is created by the query. +/// - a `Scorer` is a cursor over the set of matching documents, for a specific +/// [`SegmentReader`](../struct.SegmentReader.html). It is created by the [`Weight`](./trait.Weight.html). +/// +/// When implementing a new type of `Query`, it is normal to implement a +/// dedicated `Query`, `Weight` and `Scorer`. pub trait Query: fmt::Debug { + /// Used to make it possible to cast Box<Query> + /// into a specific type. This is mostly useful for unit tests. fn as_any(&self) -> &Any; + /// Create the weight associated to a query. + /// + /// See [Weight](./trait.Weight.html). fn weight(&self, searcher: &Searcher) -> Result<Box<Weight>>; - - /// Perform the search operation + + /// Search works as follows : + /// + /// First the weight object associated to the query is created. + /// + /// Then, the query loops over the segments and for each segment : + /// - setup the collector and informs it that the segment being processed has changed. + /// - creates a `Scorer` object associated for this segment + /// - iterate throw the matched documents and push them to the collector. + /// fn search( &self, searcher: &Searcher, |