Query

The Query object configures what and how to search. At minimum, provide search text and a max results count.

Constructor

csharp
var query = new Query("search text", maxResults);

Full Configuration

csharp
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.

ModeWhich documentsReranked (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.

csharp
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 two

Properties

PropertyTypeDefaultDescription
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
Who comes in: CandidatesPerRow, MaxCandidates, IndexTerms, Fallback. See Candidates
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

PropertyTypeDefaultDescription
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

PropertyTypeDefaultDescription
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

PropertyTypeDefaultDescription
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.

csharp
// 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 with Weight = 2.0f and a boost of 3.0f counts 6×. Fields you leave out keep their Weight (a boost of 1.0). In BM25F terms the boost is folded into the pseudo term-frequency as boost × weight × tf.
  • Every key must be a searched field. An unknown key, or a field no longer searched, makes Search return an empty Result with its Reason naming the field. Check Reason before 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

csharp
Query()

For serializer.

csharp
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.

  • string queryText
  • int maxNumberOfRecordsToReturn
csharp
QueryFitResult()

For the serializer.

Properties

NameTypeAccessDescription
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.

NameValue
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.

NameValue
Both
0
Words
1
Patterns
2