JAVA-6236 add builder API for facet without operator#2006
Conversation
|
Assigned |
| * @return The requested {@link SearchCollector}. | ||
| * @mongodb.atlas.manual atlas-search/facet/ facet collector | ||
| */ | ||
| @Beta({Reason.CLIENT, Reason.SERVER}) |
There was a problem hiding this comment.
Looks like the server had GA of the search functionality in 2020 (see https://www.mongodb.com/docs/atlas/search-changelog/#9-june-2020-release), and there is no information on when specific parts of MQL came out of preview. The DOCSP team said they do not document availability of search operators by DB version.
Since the only information we have, is that currently the collector is not documented as being in preview, we are to interpret it as it not being in preview, despite us not knowing when GA happened. I suspect, the same applies to all the operators, but this has to be checked. We should remove Reason.SERVER here and everywhere in driver-core/src/main/com/mongodb/client/model/search, except for VectorSearchQuery, TextVectorSearchQuery, which are still in preview.
We do not have to do that in this PR, but then, we should do that in the same driver release this PR goes into. Because otherwise it will be very weird to see one of the following:
- The old
SearchCollector.facetmethod marked as beta because ofReason.SERVER, while the new one not marked the same way. - The new
SearchCollector.facetmethod marked as beta because ofReason.SERVERdespite the facet collector is not beta anymore.
| /** | ||
| * Returns a {@link SearchCollector} that groups results by values or ranges in the specified faceted fields and returns the count | ||
| * for each of those groups, faceting over the entire collection. | ||
| * <p> | ||
| * Unlike {@link #facet(SearchOperator, Iterable)}, this method omits the search operator, so the facets are computed | ||
| * across all documents in the collection.</p> |
There was a problem hiding this comment.
I see two issues with the current wording:
- The second sentence (the one after
<p>) duplicates part of the first sentence. - The "over the entire collection" / "across all documents in the collection" phrases are not future-proof.
- The pipeline stages that search collectors are used in (
$search/$searchMeta), just like all other pipeline stages, act on the input documents (see https://www.mongodb.com/docs/manual/core/aggregation-pipeline/, https://mongodb.github.io/mongo-java-driver/5.8/apidocs/driver-core/com/mongodb/client/model/Aggregates.html). Generally speaking, those documents don't have to come from or be present in any collection (https://www.mongodb.com/docs/manual/reference/operator/aggregation/documents/ is an example). Even if they come from a collection, they may not the all the documents from that collection. Granted, currently$search/$searchMeta"must be the first stage of any pipeline" and "fields must be covered by a MongoDB Search index", meaning that currently, the aforementioned wordings are correct. However, if any of those requirements ever changes, they will stop being correct. - I think, the wording should not implicitly rely on any of the two aforementioned current requirements, and should talk about all the input documents instead of talking about all documents in the collection.
- The pipeline stages that search collectors are used in (
I propose us to change the wording for both the existing and the new facet methods as per stIncMale@d086d43.
2 participants
JAVA-6236 add builder API for facet without operator
Existing API marks
operatoras mandatory but latestfacetAPI makes it optionalhttps://www.mongodb.com/docs/search/query/operators-collectors/facet/