Query
The Query object configures what and how to search. At minimum, provide search text and a max results count.
Constructor
var query = new Query("search text", maxResults);Full Configuration
var query = new Query("search text", maxResults)
{
Mode = SearchMode.EditDistance, // default: EditDistance (or Bm25f)
Match = {
Tolerance = Tolerance.TwoEdits, // default: the fields' own (Field.Tolerance)
Rungs = Rungs.Fewest, // default: the first rung with hits
CursorAt = null, // default: the last word is being typed
},
Candidates = {
CandidatesPerRow = 4, // default: 4 candidates per row asked for
MaxCandidates = null, // default: null, the rows × 4, at least MinCandidates, at most 5 000
MinCandidates = 100, // default: 100, the fewest candidates
Fallback = true, // default: the most words when none holds every word
Rest = false, // default: the counted records alone, no related ones below
},
Ranking = {
Rerank = true, // default: true, the reranker orders the candidates
Share = 0.2f, // default: 0.2, the reranker's share of the score
FieldBoosts = new Dictionary<string, float> { ["title"] = 2.0f },
Boosts = boostArray, // default: none; a list that is not empty is on
},
EnableFacets = false, // default: false
SortBy = engine.GetField("rating"), // default: null
SortAscending = false, // default: false
Filter = filter, // default: null
TimeOutLimitMilliseconds = 1000 // default: 1000, max: 10000
};The three parts are never null; set them whole or member by member.
Search modes
Two choices make a search. Query.Mode is how the documents are fetched, Ranking.Rerank
whether the reranker orders them. Over HTTP they are mode and ranking.rerank.
| Mode | Which documents | Reranked (Rerank = true, the default) | Not reranked |
|---|---|---|---|
EditDistance (the default) | Every document holding each query word exactly or within one or two edits (the word being typed also as the start of a longer word), counted. With Candidates.Rest, BM25F's best of the others after them | Exact matches first, then one edit, then two, then the rest; the reranker's order within each group | The same groups, in BM25F order within each. Search as you type with a count, without the cost of reranking |
Bm25f | The best by BM25F over every field searched, words and the patterns inside them. No word count | The best up to the candidate bound (the rows times CandidatesPerRow, at least 100, at most 5 000, or MaxCandidates), reranked and cut to the rows; facets are counted over those candidates | By BM25F alone: the rows asked for, the bound does not apply; facets over those rows |
On 5.0 the reranker was called Coverage and switched with Query.EnableCoverage: EnableCoverage = false is Mode = SearchMode.Bm25f with Ranking.Rerank = false.
var query = new Query("kylling", 20) { Mode = SearchMode.EditDistance, Ranking = { Rerank = false } };
var result = engine.Search(query);
// result.ToleranceCounts: how many documents hold every word exactly, within one edit, within twoProperties
| Property | Type | Default | Description |
|---|---|---|---|
Text | string | "" | Search text |
MaxNumberOfRecordsToReturn | int | — | Maximum results to return |
Mode | SearchMode | EditDistance | How the search fetches its documents: EditDistance or Bm25f. Whether they are reranked is Ranking.Rerank. See Search modes |
Match | MatchSetup | defaults | What counts as a hit: Tolerance, Rungs, OneEditFrom, TwoEditsFrom, ThreeEditsFrom, CursorAt, TypingPrefixFrom, TypingPrefixOneEditFrom, JoinedWords. See Match |
Candidates | CandidateSetup | defaults | |
Ranking | RankingSetup | defaults | The order: Rerank, Share, TypingShift, LongFieldFrom, LongFieldWeightFloor, WholeQueryFloor, FieldWeights, FieldBoosts, Boosts, Buries. See Ranking |
EnableMatchReport | bool | false | Return Result.MatchReport, in any mode, reranked or not: how each query word was met in each returned record (whole, as a prefix or a suffix, joined, run together, within one or two edits, or not at all) and in which field, and per field how many words were met each way. The returned records are read through the reranker once more after the search, so it costs in proportion to how many are returned, and nothing when off |
EnableFacets | bool | false | Return facet counts in the result. Also required for an empty Text: without it the empty query is refused, returning an empty Result with a Reason — see Empty search |
SortBy | Field? | null | Secondary sort field. Score is always the primary key |
SortAscending | bool | false | Sort direction when SortBy is set |
FacetSelections | Dictionary<string, string[]> | empty | Values ticked on facets, by Facetable field: the list holds every selection (OR within a field, AND between), each selected field's facet is counted without its own selection, the others with them all |
FacetRanges | Dictionary<string, Filter> | empty | A range on a facet, by field: a filter on that field alone, Facetable and Filterable. Narrows the list; the field's facet and FacetStats are counted without it |
CollapseBy | string[] | empty | One record per value of these fields: a record whose values are a record's higher in the ranking is left out, nothing moves, Offset counts the records kept. Count and the facets count records. The fields need a role and may not be arrays |
Counts | Dictionary<string, Filter> | empty | Named counts: for each name, how many of the records Result.Count counts the filter lets through, in Result.Counts. Over the same set as the count and the facets, so no search of its own: a page's sections counted beside one search |
Filter | Filter? | null | Boolean filter applied before scoring |
TimeOutLimitMilliseconds | int | 1000 | Abort scoring after this many milliseconds. Max: 10000 |
Match
| Property | Type | Default | Description |
|---|---|---|---|
Tolerance | Tolerance | TwoEdits | The most edits a word may differ by: Exact, OneEdit, TwoEdits, ThreeEdits. Caps each field's own Field.Tolerance, never raises it; three edits need both at ThreeEdits |
Rungs | Rungs | Fewest | Fewest counts the first rung with hits (exactly, else one edit, else two); All every rung up to the tolerance, the nearer first |
OneEditFrom, TwoEditsFrom, ThreeEditsFrom | int | 3, 6, 9 | The shortest word given one edit, two, and three. 0 is never. Edits reach words of 64 characters at most; a longer word is met as typed only |
CursorAt | int? | null | Where the cursor is in Text. The word it is in is the one being typed, met by its start too; without it, the last word when no space follows it |
TypingPrefixFrom, TypingPrefixOneEditFrom | int | 2, 6 | The word being typed as the start of a longer word from this many letters, and that start within one edit. 0 is never |
JoinedWords | bool | true | Words written together or apart count as the word |
Candidates
| Property | Type | Default | Description |
|---|---|---|---|
CandidatesPerRow | int | 4 | The candidates the search takes per row asked for: the bound is the rows times this, at least MinCandidates (100) and at most 5 000, never fewer than the rows. Read where there are candidates to rank: EditDistance, and Bm25f reranked |
MaxCandidates | int? | null | The bound itself, outright: in place of the rows times CandidatesPerRow, and past the floor of 100 and the roof of 5 000. The documents holding every query word on the first rung with hits are all taken when they fit; when they are more, the best of them: Result.Count is then above Result.Ranked, and Result.ToleranceCounts has the count by rung |
NoFallbackForNumbersFrom | int | 0 | A query that is one number of at least this many digits (an ISBN, an EAN; a final X allowed) and that no record holds answers empty, Count 0, rather than with records sharing some of its digits. 0 is off. The field holding the numbers must be matched by its words |
MinCandidates | int | 100 | The fewest candidates, when the rows times CandidatesPerRow are fewer: a search for a few rows still ranks this many. Taken between 1 and 5 000; MaxCandidates sets the bound past it |
IndexTerms | IndexTerms | Both | Which terms pattern recognition scores with: Both, Words or Patterns |
Fallback | bool | true | When no document holds every query word: the documents holding the most of the words, then pattern matches ( Result.IsFallback). false gives an empty list |
FillWithMostWords | bool | false | When too few documents hold every query word to fill the rows: below them, not counted, the documents holding the most of the words, those lacking one word first ( Result.Fill.MostWords). Gains most in a product search with few hits; noise below the one record a title search wants. |
FillReach | int | 0 | How many typo levels past the counted one fill a short page, below the counted documents and not counted ( Result.Fill.NextRungs): 0 no fill, 1 the next level ("chili" counted, "chilli" below it; worth it in a product search with few hits), 2 up to two typos. |
Rest | bool | false | In EditDistance, pattern recognition's best documents that were not counted come below the counted ones, up to the bound: documents holding the query's words only in part, or only by pattern. They are counted (Result.ToleranceCounts.Rest) and the facets count them, so count, facets and list agree. None is taken on overflow. For a shop that wants the counted, exact-first list but related documents below the hits rather than an empty tail. Not read in Bm25f |
Ranking
| Property | Type | Default | Description |
|---|---|---|---|
Rerank | bool | true | Whether the reranker orders the candidates, in either mode. Off, Bm25f is pattern recognition alone and EditDistance orders within each group by pattern recognition. The settings below are Coverage's, read only when on |
Share | float | 0.2 | The reranker's share of the blended score; the rest is pattern recognition's |
TypingShift | float | 0.5 | How far the share moves towards the reranker alone while the last word is being typed |
LongFieldFrom, LongFieldWeightFloor | int, float | 200, 0 | From this length, in characters, a record's field counts less in the reranker: its weight is multiplied by this length over the field's own to the power 0.18 (735 characters count 0.79, 2 000 count 0.66), never below the floor. 0 is never |
WholeQueryFloor | bool | true | The whole query found in a field sets a floor under the score |
FieldWeights | Dictionary<string, float> | empty | Per field, its weight in the reranker in this search ( Field.RerankWeight otherwise). A name that is not a searchable field, or a weight below 0, is refused with a Reason; engine.ValidateRanking(ranking) asks first |
FieldBoosts | Dictionary<string, float> | empty | Per-query multipliers on each field's Weight. Keys must be searchable fields — an unknown or non-searchable key makes Search return an empty Result. Applies in both scoring modes |
Boosts | Boost[] | empty | Score boosts applied to matching documents. A list that is not empty is on |
Buries | Bury[] | empty | Score buries, taking matching documents down — see Buries |
Per-Query Field Boosts
Ranking.FieldBoosts lets you adjust how much each field counts for one search, without reconfiguring or rebuilding the index.
// title and description are both searched in the field configuration.
var query = new Query("noise cancelling", 10)
{
Ranking = {
FieldBoosts = new Dictionary<string, float>
{
["title"] = 3.0f, // 3 × title's Weight
["description"] = 0.5f // half of description's Weight
}
}
};- A boost multiplies the field's
Weight; it does not replace it. A field withWeight = 2.0fand a boost of3.0fcounts 6×. Fields you leave out keep theirWeight(a boost of 1.0). In BM25F terms the boost is folded into the pseudo term-frequency asboost × weight × tf. - Every key must be a searched field. An unknown key, or a field no longer searched, makes
Searchreturn an emptyResultwith itsReasonnaming the field. CheckReasonbefore showing "no matches". Turning a field's matching off does not remove it from boosts your code still sends. - In BM25PerField a boost acts inside its field's own index. Each field is scored on its own there and the scores are merged by
Weight, so a boost raises the field's term frequency before that field's saturation rather than multiplying its merge weight. Until 6.0 the per-field mode ignored field boosts altogether.
Constructors
Query()For serializer.
Query(string queryText, int maxNumberOfRecordsToReturn)Constructor for the class Query, having default parameters for most of the fields. This query uses the Coverage function, and times out after 1000 ms. To adjust more parameters, set them directly on the instance after creation.
stringqueryTextintmaxNumberOfRecordsToReturn
QueryFitResult()For the serializer.
Properties
| Name | Type | Access | Description |
|---|---|---|---|
Match | MatchSetup | get/set | MatchSetupWhat counts as a hit: the tolerance, the word being typed, the rungs counted
(). Never null. |
Candidates | CandidateSetup | get/set | CandidateSetupWho comes in: the bound on the candidates, the fallback ().
Never null. |
Ranking | RankingSetup | get/set | RankingSetupThe order inside the rungs' bands: the blend, field weights and boosts, boosts and buries
(). Never null. |
DocumentsBoosted | int | get | Returns the number of documents that may be boosted in the search. |
DocumentsBuried | int | get | Returns the number of documents that may be buried in the search. |
Mode | SearchMode | get/set | How the search fetches its documents:, the default,
or. Whether they are reranked is. In 5.x the choice was made byand a null. |
EnableMatchReport | bool | get/set | MatchReportReturns: how each query word was met in each returned
record, and in which field, in any mode, reranked or not. Off by default; when on, the
returned records are read through the reranker's word matching a second time after the
search, which costs in proportion to how many are returned. EnableCoverageReport until
6.0, EnableRerankReport in its previews. |
EnableFacets | bool | get/set | Activates calculations of facet histograms in the search results. |
FacetFields | string[] | get/set | EnableFacetsWith, the facetable fields to count, by name; empty, the
default, counts every facetable field. Naming the ones a page shows saves counting the
rest. A name that is not a facetable field refuses the search. Never null. |
FacetValueLimit | int | get/set | With, the most values returned per field, the commonest first;
0, the default, returns them all. The counting is the same either way, andis of every value counted. |
Offset | int | get/set | How many of the ranked records to pass over before the first returned: 0, the default,
returns from the best; 20 with 10 rows returns the 21st to the 30th. Only ranked records
can be returned, so a page pastis empty althoughmay be larger. |
FacetSelections | Dictionary<string, string[]> | get/set | FilterThe values ticked on facets, by Facetable field: the list holds the records with one of a
field's values (OR within a field, AND between fields, and AND with),
while each field's facet is counted without its own selection, so its other values keep
their counts and can be ticked too; the facets of fields without one are counted with them
all. A value is folded as the facet folds it. Read from the facets' own index, so the
field need not be Filterable. A field that is not Facetable refuses the search; an empty
list selects nothing. Empty, the default: no selection. Never null. |
FacetRanges | Dictionary<string, Filter> | get/set | A range on a facet, by field: a filter (a range filter expression, say) on that field alone, which must be Facetable and
Filterable. As: the list holds the records it lets
through, and the field's facet is counted without it, so a slider's other positions keep
their counts andits whole span. A filter on another field
refuses the search. Empty, the default: none. Never null. |
CollapseBy | string[] | get/set | One record per value: the fields named, by name, and a record whose values of them are a
record's higher in the ranked list is left out, its place taken by the next with values
not seen. The order is the ranking's; nothing moves. A record holding none of the fields,
or null in them, stands alone.counts the records kept, so no page repeats a value; a
list with too few values within the candidate bound is shorter than the rows.and the facets are of the records, as without; withthe records kept are sorted, and an empty search keeps the first of
each value in its sort order. A field that does not exist, is an array or has no role
(searched, filterable, facetable, sortable) refuses the search. Empty, the default: every record. Never
null. |
Counts | Dictionary<string, Filter> | get/set | Named counts: for each name, how many of the documentscounts
the filter lets through, in. Over the same set as the count
and the facets, so it costs no search of its own and lists no rows: a page's sections
counted beside one search's list. Empty, the default, counts nothing more. Never null. |
Filter | Filter | get/set | Is used to pass a filter to the search query. |
LogPrefix | string | get/set | If the instance of the search engine has had a logger injected into its constructor,
every search will be logged. The log prefix is then first added to the log text,
and can be used by the client to add statistical information, for example for use in dashboards. |
MaxNumberOfRecordsToReturn | int | get/set | Defines the maximum number of documents to be returned. |
MeasureFit | bool | get/set | Also measures how well the results explain the text:then returns a(ExplainedShare, UnexplainedShare and the
words on either side), for telling a search from a question. Off by default; a search
that is refused or not served returns a plaineither way. |
SerializedQueryKey | string | get | Serialized key for caching empty search results.
Format: F:{filterKey}|B:{boostFilter1};{strength1},{boostFilter2};{strength2}|Y:{buries}|S:{sortField};{asc}|M:{maxRecords}|E:{enableFacets}|V:{facetField1},{facetField2}|C:{collapseField1},{collapseField2}|L:{selections}|R:{ranges}|N:{nameLength}:{name}={filterKey},... |
SortAscending | bool | get/set | Only applicable if SortBy != null. |
SortBy | Field | get/set | Use this in order to setup sorting of the results. |
Text | string | get/set | Refers to the text (input) to be searched for. |
TimeOutLimitMilliseconds | int | get/set | Sets maximum waiting time in case of overloaded CPU. We recommend 1000 ms. Cannot be more than 10000 ms. |
ExplainedShare | float | get/set | The share of the query's weight (the sum of its words' IDF) that the best explaining
result explains, 0 to 1. Near 1: the results hold what was typed, a search. 0 when no
result explains anything, or when no word of the query weighs anything. |
UnexplainedShare | float | get/set | ExplainedShareThe share of the query's weight carried by informative words that result does not
explain, 0 to 1: words rarer than the catalogue's median word, or words the index does
not hold at all (weighed as the rarest). Common words left unexplained count in neither
share, so the two need not sum to 1. High, with a low: the
text asks for something the catalogue does not hold. |
ExplainedWords | string[] | get/set | The query's words the result explains, in the query's order: what the
results actually matched. |
UnexplainedWords | string[] | get/set | The informative words of the query no result explained, in the query's
order. |
SearchModeenum
How a search fetches its documents (); whether they are reranked is, in either. In 5.x two switches chose it,and a null.
| Name | Value |
|---|---|
Bm25f | 0 |
EditDistance | 1 |
IndexTermsenum
Which of the index's terms a search scores BM25F with (). A field matched by its words holds them as terms, one matched by pattern its pieces too; a search may use either kind alone, read from the query: its words, or the pieces it is cut into. A term that is a word in one document and a piece of a longer word in another ("tor" and "motor") is one term; withonly the documents holding it as a word are scored, read from the field of each posting as the word lookup reads it.
| Name | Value |
|---|---|
Both | 0 |
Words | 1 |
Patterns | 2 |