Our search API in the com.mongodb.client.model.search package is still marked as @Beta (the same applies to the corresponding Scala API).

We should move it out of Beta, but before doing so, we should re-visit at least the following API design aspects:

1. Building objects (for example, search operators) based on pre-build objects.

Despite this idea having been in mind when the API was design, it wasn't fully supported:

• only optional fields can be overwritten: if I have TextSearchOperator t1, I can overwrite the fuzzy option by doing t2 = t1.fuzzy(), but can't overwrite the required path field.
• there usually is no way to unset a optional field when overwriting: if an instance of AutocompleteSearchOperator has its option score set, there is no way to unset it.

I no longer think it is a good idea to design our API with this functionality in mind, and I am open to rejecting it, which, in turn, allows us to make the API objects modifiable. Unfortunately, we have already moved VectorSearchOptions out of beta (https://github.com/mongodb/mongo-java-driver/pull/1496), so VectorSearchOptions has to stay unmodifiable. Given that, it seems surprising to make SearchOptions modifiable. However, all the SearchOperator s and SearchCollector s still can be made modifiable if we decide so.

2. Supporting MQL evolution that makes previously mutually-exclusive optional fields not mutually-exclusive anymore

This one was brought up by maxim.katcharov@mongodb.com.

For example, TextSearchOperator.fuzzy and TextSearchOperator.synonyms options are currently mutually-exclusive. To safe-guard a user from incorrectly specifying both, each method erases the effect of the other one. However, if in the future the MQL evolves such that these options stop being mutually exclusive, it is unclear how to nicely support such evolution in the API. Maybe there is a different API design that achieves everything the current API does, but also allows to nicely support the aforementioned MQL evolution.

One simple, not necessarily the optimal alternative is to rename the methods to something like fuzzyEraseConflicting. We may also look in the direction of playing with types, when TextSearchOperator.fuzzy and TextSearchOperator.synonyms return different types, such that neither of them has the conflicting method. However, at some point I tried exactly that approach (I fail to remember the situation in which I tried it), and it was decided in review that it is to be abandoned.

See comments for other potential requirements.