Skip to content

JAVA-6236 add builder API for facet without operator and clean up search api from beta Reason.SERVER #2006

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
strogiyotec wants to merge 4 commits into
base: main
Choose a base branch
from
Open

JAVA-6236 add builder API for facet without operator and clean up search api from beta Reason.SERVER #2006

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6d9c7d4
JAVA-6236 add builder API for facet without operator
Jun 23, 2026
e0b3905
Merge branch 'main' into JAVA-6236
strogiyotec Jul 6, 2026
4a8a080
address Valentin's comments
Jul 16, 2026
6ad2537
Merge branch 'main' into JAVA-6236
strogiyotec Jul 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion driver-core/src/main/com/mongodb/client/model/search/DateSearchFacet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
* @since 4.7
*/
@Sealed
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
public interface DateSearchFacet extends SearchFacet {
/**
* Creates a new {@link DateSearchFacet} with the default bucket specified.
Expand Down
2 changes: 1 addition & 1 deletion driver-core/src/main/com/mongodb/client/model/search/FacetSearchCollector.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,6 @@
* @since 4.7
*/
@Sealed
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
public interface FacetSearchCollector extends SearchCollector {
}
2 changes: 1 addition & 1 deletion driver-core/src/main/com/mongodb/client/model/search/LowerBoundSearchCount.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
* @since 4.7
*/
@Sealed
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
public interface LowerBoundSearchCount extends SearchCount {
/**
* Creates a new {@link LowerBoundSearchCount} that instructs to count documents up to the {@code threshold} exactly,
Expand Down
2 changes: 1 addition & 1 deletion driver-core/src/main/com/mongodb/client/model/search/NumberSearchFacet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
* @since 4.7
*/
@Sealed
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
public interface NumberSearchFacet extends SearchFacet {
/**
* Creates a new {@link NumberSearchFacet} with the default bucket specified.
Expand Down
20 changes: 17 additions & 3 deletions driver-core/src/main/com/mongodb/client/model/search/SearchCollector.java
View file
Open in desktop

@stIncMale stIncMale Jul 8, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I forgot to say that we should also update the Scala API, more specifically, org.mongodb.scala.model.search.SearchCollector. Kotlin APIs do not have their own SearchCollector.

@strogiyotec strogiyotec Jul 16, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

addressed it here

Original file line number Diff line number Diff line change
Expand Up @@ -38,22 +38,36 @@
@Beta(Reason.CLIENT)
public interface SearchCollector extends Bson {
/**
* 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.
* Returns a {@link SearchCollector} that groups the results of a search based on the specified operator
* by values or ranges in the specified faceted fields, and returns the count for each of those groups.
*
* @param operator The search operator to use.
* @param facets The non-empty facet definitions.
* @return The requested {@link SearchCollector}.
* @mongodb.atlas.manual atlas-search/facet/ facet collector
*/
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
static FacetSearchCollector facet(final SearchOperator operator, final Iterable<? extends SearchFacet> facets) {
notNull("operator", operator);
notNull("facets", facets);
return new SearchConstructibleBsonElement("facet", new Document("operator", operator)
.append("facets", combineToBson(facets)));
}

/**
* Returns a {@link SearchCollector} that groups all the input documents
* by values or ranges in the specified faceted fields, and returns the count for each of those groups.
*
* @param facets The non-empty facet definitions.
* @return The requested {@link SearchCollector}.
* @mongodb.atlas.manual atlas-search/facet/ facet collector
*/
@Beta(Reason.CLIENT)
static FacetSearchCollector facet(final Iterable<? extends SearchFacet> facets) {
notNull("facets", facets);
return new SearchConstructibleBsonElement("facet", new Document("facets", combineToBson(facets)));
}

/**
* Creates a {@link SearchCollector} from a {@link Bson} in situations when there is no builder method that better satisfies your needs.
* This method cannot be used to validate the syntax.
Expand Down
2 changes: 1 addition & 1 deletion driver-core/src/main/com/mongodb/client/model/search/SearchCount.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@
* @since 4.7
*/
@Sealed
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
public interface SearchCount extends Bson {
/**
* Returns a {@link SearchCount} that instructs to count documents exactly.
Expand Down
2 changes: 1 addition & 1 deletion driver-core/src/main/com/mongodb/client/model/search/SearchFacet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,7 @@
* @since 4.7
*/
@Sealed
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
public interface SearchFacet extends Bson {
/**
* Returns a {@link SearchFacet} that allows narrowing down search results based on the most frequent
Expand Down
4 changes: 2 additions & 2 deletions driver-core/src/main/com/mongodb/client/model/search/SearchOptions.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ public interface SearchOptions extends Bson {
* @param option The counting option.
* @return A new {@link SearchOptions}.
*/
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
SearchOptions count(SearchCount option);

/**
Expand All @@ -64,7 +64,7 @@ public interface SearchOptions extends Bson {
* @return A new {@link SearchOptions}.
* @mongodb.atlas.manual atlas-search/return-stored-source/ Return stored source fields
*/
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
SearchOptions returnStoredSource(boolean returnStoredSource);

/**
Expand Down
2 changes: 1 addition & 1 deletion driver-core/src/main/com/mongodb/client/model/search/StringSearchFacet.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@
* @since 4.7
*/
@Sealed
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
public interface StringSearchFacet extends SearchFacet {
/**
* Creates a new {@link StringSearchFacet} that explicitly limits the number of facet categories.
Expand Down
2 changes: 1 addition & 1 deletion driver-core/src/main/com/mongodb/client/model/search/TotalSearchCount.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,6 @@
* @since 4.7
*/
@Sealed
@Beta({Reason.CLIENT, Reason.SERVER})
@Beta(Reason.CLIENT)
public interface TotalSearchCount extends SearchCount {
}
45 changes: 45 additions & 0 deletions driver-core/src/test/unit/com/mongodb/client/model/search/SearchCollectorTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,27 @@ void facet() {
);
}

@Test
void facetWithoutOperator() {
assertAll(
() -> assertThrows(CodecConfigurationException.class, () ->
// facet names must be unique; `BsonCodec` wraps our `IllegalStateException` into `CodecConfigurationException`
SearchCollector.facet(
asList(
stringFacet("duplicateFacetName", fieldPath("stringFieldName")),
numberFacet("duplicateFacetName", fieldPath("numberFieldName"), asList(10, 20, 30))))
// we have to render into `BsonDocument` in order to trigger the lazy check
.toBsonDocument()
),
() -> assertEquals(
documentWithoutOperator()
.toBsonDocument(),
searchCollectorWithoutOperator()
.toBsonDocument()
)
);
}

private static SearchCollector docExamplePredefined() {
return SearchCollector.facet(
exists(
Expand Down Expand Up @@ -89,4 +110,28 @@ private static Document docExampleCustom() {
fieldPath("numberFieldName"),
asList(10, 20, 30))))));
}

private static SearchCollector searchCollectorWithoutOperator() {
return SearchCollector.facet(
asList(
stringFacet(
"stringFacetName",
fieldPath("stringFieldName")),
numberFacet(
"numberFacetName",
fieldPath("numberFieldName"),
asList(10, 20, 30))));
}

private static Document documentWithoutOperator() {
return new Document("facet",
new Document("facets", combineToBson(asList(
stringFacet(
"stringFacetName",
fieldPath("stringFieldName")),
numberFacet(
"numberFacetName",
fieldPath("numberFieldName"),
asList(10, 20, 30))))));
}
}
18 changes: 15 additions & 3 deletions driver-scala/src/main/scala/org/mongodb/scala/model/search/SearchCollector.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,18 +34,30 @@ import scala.collection.JavaConverters._
object SearchCollector {

/**
* Returns a `SearchCollector` that groups results by values or ranges in the specified faceted fields and returns the count
* for each of those groups.
* Returns a `SearchCollector` that groups the results of a search based on the specified operator
* by values or ranges in the specified faceted fields, and returns the count for each of those groups.
*
* @param operator The search operator to use.
* @param facets The non-empty facet definitions.
* @return The requested `SearchCollector`.
* @see [[https://www.mongodb.com/docs/atlas/atlas-search/facet/ facet collector]]
*/
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
def facet(operator: SearchOperator, facets: Iterable[_ <: SearchFacet]): FacetSearchCollector =
JSearchCollector.facet(operator, facets.asJava)

/**
* Returns a `SearchCollector` that groups all the input documents
* by values or ranges in the specified faceted fields, and returns the count for each of those groups.
*
* @param facets The non-empty facet definitions.
* @return The requested `SearchCollector`.
* @see [[https://www.mongodb.com/docs/atlas/atlas-search/facet/ facet collector]]
*/
@Beta(Array(Reason.CLIENT))
def facet(facets: Iterable[_ <: SearchFacet]): FacetSearchCollector =
JSearchCollector.facet(facets.asJava)

/**
* Creates a `SearchCollector` from a `Bson` in situations when there is no builder method that better satisfies your needs.
* This method cannot be used to validate the syntax.
Expand Down
2 changes: 1 addition & 1 deletion driver-scala/src/main/scala/org/mongodb/scala/model/search/SearchCount.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import org.mongodb.scala.model.Projections
* @see [[https://www.mongodb.com/docs/atlas/atlas-search/counting/ Counting]]
* @since 4.7
*/
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
object SearchCount {

/**
Expand Down
2 changes: 1 addition & 1 deletion driver-scala/src/main/scala/org/mongodb/scala/model/search/SearchFacet.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ import collection.JavaConverters._
* @see [[https://www.mongodb.com/docs/atlas/atlas-search/facet/#facet-definition Facet definition]]
* @since 4.7
*/
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
object SearchFacet {

/**
Expand Down
16 changes: 8 additions & 8 deletions driver-scala/src/main/scala/org/mongodb/scala/model/search/package.scala
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -269,7 +269,7 @@ package object search {
* @see `SearchCollector.facet(SearchOperator, Iterable)`
*/
@Sealed
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
type FacetSearchCollector = com.mongodb.client.model.search.FacetSearchCollector

/**
Expand Down Expand Up @@ -360,21 +360,21 @@ package object search {
* @see [[https://www.mongodb.com/docs/atlas/atlas-search/counting/ Counting]]
*/
@Sealed
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
type SearchCount = com.mongodb.client.model.search.SearchCount

/**
* @see `SearchCount.total()`
*/
@Sealed
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
type TotalSearchCount = com.mongodb.client.model.search.TotalSearchCount

/**
* @see `SearchCount.lowerBound()`
*/
@Sealed
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
type LowerBoundSearchCount = com.mongodb.client.model.search.LowerBoundSearchCount

/**
Expand All @@ -383,28 +383,28 @@ package object search {
* @see [[https://www.mongodb.com/docs/atlas/atlas-search/facet/#facet-definition Facet definition]]
*/
@Sealed
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
type SearchFacet = com.mongodb.client.model.search.SearchFacet

/**
* @see `SearchFacet.stringFacet(String, FieldSearchPath)`
*/
@Sealed
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
type StringSearchFacet = com.mongodb.client.model.search.StringSearchFacet

/**
* @see `SearchFacet.numberFacet(String, FieldSearchPath, Iterable)`
*/
@Sealed
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
type NumberSearchFacet = com.mongodb.client.model.search.NumberSearchFacet

/**
* @see `SearchFacet.dateFacet(String, FieldSearchPath, Iterable)`
*/
@Sealed
@Beta(Array(Reason.CLIENT, Reason.SERVER))
@Beta(Array(Reason.CLIENT))
type DateSearchFacet = com.mongodb.client.model.search.DateSearchFacet

/**
Expand Down