Method ReadRankedCandidatesAsync

Namespace

MailFathom.Application.Emails.Search

Assembly

MailFathom.Application.dll

ReadRankedCandidatesAsync(MailboxEmailSelection, EmailSearchQueryText, int, CancellationToken)

Ranks the emails matching a query, among those the structured filters select.

Task<IReadOnlyList<RankedEmailCandidate>> ReadRankedCandidatesAsync(MailboxEmailSelection selection, EmailSearchQueryText queryText, int limit, CancellationToken cancellationToken)

Parameters

selection MailboxEmailSelection

Which emails are eligible before the text is considered.

queryText EmailSearchQueryText

The validated free text to match against the index.

limit int

The greatest number of ranked candidates to return, at least one.

cancellationToken CancellationToken

Propagates caller cancellation.

Returns

Task<IReadOnlyList<RankedEmailCandidate>>

At most limit candidates, most relevant first, empty when nothing matched.

Remarks

The order is deterministic. Full-text rank alone produces ties — several messages carrying one uncommon word score identically — so an implementation orders by rank descending and then by EmailTimelinePosition in its newest-first direction, which is total. Two identical requests over an unchanged index therefore return the same sequence.

Matching nothing is an empty result rather than a failure. A search that reported the difference between "no such mail" and "no such folder" would answer questions about accounts and folders the caller was never told about.

Exceptions

ArgumentNullException

Thrown when selection or queryText is null.

ArgumentOutOfRangeException

Thrown when limit is below one.