Method FindPassagesAsync

Namespace: MailFathom.Application.Retrieval

Assembly: MailFathom.Application.dll

FindPassagesAsync(MailboxScope, EmailKnowledgeQuery, CancellationToken)

Finds the passages relevant to one query within one scope.

Task<EmailKnowledgeLookup> FindPassagesAsync(MailboxScope scope, EmailKnowledgeQuery query, CancellationToken cancellationToken)

Parameters

scope MailboxScope: The accounts and folders the passages may be drawn from, decided by the caller.
query EmailKnowledgeQuery: What to look for and how to narrow it, all of which a model may have written.
cancellationToken CancellationToken: Propagates caller cancellation.

Returns

Task<EmailKnowledgeLookup>: The passages, most relevant first, bounded in number and in the size of each, beside what the lookup considered to produce them.

Remarks

A query that finds nothing produces an empty list, which is not a failure: a run whose retrieval found nothing still has an answer to give. A query the search use case refuses is a different thing and travels out as the refusal that use case raises, because the caller here owns a tool loop and can therefore hand the model the reason and let it write the lookup again. Absorbing it into an empty list would tell a model that a mailbox holds nothing when what it holds is an unusable filter.

The counts travel with the passages rather than being logged where they arise, because what an operator and an audit both ask about is a run, and a run makes several lookups. Only a caller that owns the run can add them up, so an implementation reports its own and adds nothing up itself.

Exceptions

ArgumentNullException: Thrown when scope or query is null.
MailboxQueryFilterInvalidException: Thrown when the query carries no usable text, or a filter carries a value or a length the query does not accept.