feat!: remove the no-op distinct find option

anidotnet · claude · anidotnet · commit fa94cb70da57 · 2026-08-07T12:59:09.000+05:30
BREAKING CHANGE: removed `FindOptions.withDistinct()` (both overloads),
`FindOptions.distinct()` and `FindPlan.distinct`.

The flag never affected the result set. A find never returns the same
document twice, and the `or` sub-plan union in ReadOperations has always
applied DistinctStream unconditionally - so FindOptimizer wrote the flag
onto the FindPlan and nothing ever read it back. Callers passing
`FindOptions.withDistinct()` can drop it with no change in results.

`DistinctStream` itself is unchanged and still used for the `or` union.

Also adds CollectionOrDuplicateTest, which pins the set-union behaviour of
an `or` filter for the no-index, one-indexed-branch and all-indexed-branch
cases. nitrite-java was already correct here; the same test found real
duplicate defects in nitrite-rust and nitrite-flutter, and is added to keep
the three implementations honest.

Co-Authored-By: Claude Opus 5 &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,9 @@
+## Release 5.0.0 - Aug 7, 2026
+
+### Breaking Changes
+
+- Removed the `distinct` find option - `FindOptions.withDistinct()` (both overloads), `FindOptions.distinct()` and `FindPlan.distinct`. It had no effect on the result set. A find never returns the same document twice, and the `or` sub-plan union has always deduplicated unconditionally, so the flag was written by the planner and never read. Callers passing `FindOptions.withDistinct()` can drop it with no change in results.
+
 ## Release 4.5.0 - Aug 7, 2026
 
 ### New Features
diff --git a/nitrite-bom/pom.xml b/nitrite-bom/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>4.5.0</version>
+        <version>5.0.0</version>
     </parent>
 
     <artifactId>nitrite-bom</artifactId>
diff --git a/nitrite-jackson-mapper/pom.xml b/nitrite-jackson-mapper/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>4.5.0</version>
+        <version>5.0.0</version>
     </parent>
 
     <artifactId>nitrite-jackson-mapper</artifactId>
diff --git a/nitrite-mvstore-adapter/pom.xml b/nitrite-mvstore-adapter/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>4.5.0</version>
+        <version>5.0.0</version>
     </parent>
 
     <artifactId>nitrite-mvstore-adapter</artifactId>
diff --git a/nitrite-mvstore-adapter/src/test/java/org/dizitart/no2/integration/collection/CollectionFindByCompoundIndexTest.java b/nitrite-mvstore-adapter/src/test/java/org/dizitart/no2/integration/collection/CollectionFindByCompoundIndexTest.java
@@ -19,7 +19,6 @@
 
 import org.dizitart.no2.collection.Document;
 import org.dizitart.no2.collection.DocumentCursor;
-import org.dizitart.no2.collection.FindOptions;
 import org.dizitart.no2.collection.FindPlan;
 import org.dizitart.no2.common.SortOrder;
 import org.dizitart.no2.common.tuples.Pair;
@@ -83,7 +82,7 @@ public void testFindByOrFilterAndFilter() {
                     where("firstName").eq("fn3"),
                     where("lastName").eq("ln2")
                 )
-            ), FindOptions.withDistinct()
+            )
         );
 
         assertEquals(2, cursor.size());
@@ -203,22 +202,6 @@ public void testFindByOrFilter() throws ParseException {
         FindPlan findPlan = cursor.getFindPlan();
         assertEquals(3, findPlan.getSubPlans().size());
         assertEquals(3, cursor.size());
-
-        // distinct
-        cursor = collection.find(
-            or(
-                or(
-                    where("lastName").eq("ln2"),
-                    where("firstName").notEq("fn1")
-                ),
-                where("birthDay").eq(simpleDateFormat.parse("2012-07-01T16:02:48.440Z")),
-                where("firstName").notEq("fn1")
-            ), FindOptions.withDistinct()
-        );
-
-        findPlan = cursor.getFindPlan();
-        assertEquals(3, findPlan.getSubPlans().size());
-        assertEquals(3, cursor.size());
     }
 
     @Test
diff --git a/nitrite-native-tests/pom.xml b/nitrite-native-tests/pom.xml
@@ -7,7 +7,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>4.5.0</version>
+        <version>5.0.0</version>
     </parent>
 
     <artifactId>nitrite-native-tests</artifactId>
diff --git a/nitrite-rocksdb-adapter/pom.xml b/nitrite-rocksdb-adapter/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>4.5.0</version>
+        <version>5.0.0</version>
     </parent>
 
     <artifactId>nitrite-rocksdb-adapter</artifactId>
diff --git a/nitrite-rocksdb-adapter/src/test/java/org/dizitart/no2/integration/collection/CollectionFindByCompoundIndexTest.java b/nitrite-rocksdb-adapter/src/test/java/org/dizitart/no2/integration/collection/CollectionFindByCompoundIndexTest.java
@@ -19,7 +19,6 @@
 
 import org.dizitart.no2.collection.Document;
 import org.dizitart.no2.collection.DocumentCursor;
-import org.dizitart.no2.collection.FindOptions;
 import org.dizitart.no2.collection.FindPlan;
 import org.dizitart.no2.common.SortOrder;
 import org.dizitart.no2.common.tuples.Pair;
@@ -83,7 +82,7 @@ public void testFindByOrFilterAndFilter() {
                     where("firstName").eq("fn3"),
                     where("lastName").eq("ln2")
                 )
-            ), FindOptions.withDistinct()
+            )
         );
 
         assertEquals(2, cursor.size());
@@ -203,22 +202,6 @@ public void testFindByOrFilter() throws ParseException {
         FindPlan findPlan = cursor.getFindPlan();
         assertEquals(3, findPlan.getSubPlans().size());
         assertEquals(3, cursor.size());
-
-        // distinct
-        cursor = collection.find(
-            or(
-                or(
-                    where("lastName").eq("ln2"),
-                    where("firstName").notEq("fn1")
-                ),
-                where("birthDay").eq(simpleDateFormat.parse("2012-07-01T16:02:48.440Z")),
-                where("firstName").notEq("fn1")
-            ), FindOptions.withDistinct()
-        );
-
-        findPlan = cursor.getFindPlan();
-        assertEquals(3, findPlan.getSubPlans().size());
-        assertEquals(3, cursor.size());
     }
 
     @Test
diff --git a/nitrite-spatial/pom.xml b/nitrite-spatial/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>4.5.0</version>
+        <version>5.0.0</version>
     </parent>
 
     <artifactId>nitrite-spatial</artifactId>
diff --git a/nitrite-support/pom.xml b/nitrite-support/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>4.5.0</version>
+        <version>5.0.0</version>
     </parent>
 
     <artifactId>nitrite-support</artifactId>
diff --git a/nitrite/pom.xml b/nitrite/pom.xml
@@ -4,7 +4,7 @@
     <parent>
         <groupId>org.dizitart</groupId>
         <artifactId>nitrite-java</artifactId>
-        <version>4.5.0</version>
+        <version>5.0.0</version>
     </parent>
 
     <artifactId>nitrite</artifactId>
diff --git a/nitrite/src/main/java/org/dizitart/no2/collection/FindOptions.java b/nitrite/src/main/java/org/dizitart/no2/collection/FindOptions.java
@@ -51,11 +51,6 @@ public class FindOptions {
      * */
     private Long limit;
 
-    /**
-     * Indicates if the find operation should return distinct results.
-     * */
-    private boolean distinct = false;
-
     /**
      * Specifies the {@link Collator}.
      */
@@ -109,15 +104,6 @@ public static FindOptions limitBy(long limit) {
         return findOptions;
     }
 
-    /**
-     * Indicates if the find operation should return distinct results.
-     */
-    public static FindOptions withDistinct() {
-        FindOptions findOptions = new FindOptions();
-        findOptions.distinct(true);
-        return findOptions;
-    }
-
     /**
      * Skip find options.
      *
@@ -179,15 +165,4 @@ public FindOptions thenOrderBy(String fieldName, SortOrder sortOrder) {
         }
         return this;
     }
-
-    /**
-     * Indicates if the find operation should return distinct and unique results.
-     *
-     * @param distinct the distinct
-     * @return the find options
-     */
-    public FindOptions withDistinct(boolean distinct) {
-        this.distinct = distinct;
-        return this;
-    }
 }
diff --git a/nitrite/src/main/java/org/dizitart/no2/collection/FindPlan.java b/nitrite/src/main/java/org/dizitart/no2/collection/FindPlan.java
@@ -78,11 +78,6 @@ public class FindPlan {
      * */
     private Long limit;
 
-    /**
-     * Gets the distinct flag.
-     * */
-    private boolean distinct;
-
     /**
      * Gets the {@link Collator}.
      * */
diff --git a/nitrite/src/main/java/org/dizitart/no2/collection/operation/FindOptimizer.java b/nitrite/src/main/java/org/dizitart/no2/collection/operation/FindOptimizer.java
@@ -47,7 +47,6 @@ public FindPlan optimize(Filter filter,
 
         if (findOptions != null) {
             findPlan.setCollator(findOptions.collator());
-            findPlan.setDistinct(findOptions.distinct());
         }
         return findPlan;
     }
diff --git a/nitrite/src/test/java/org/dizitart/no2/collection/FindOptionsTest.java b/nitrite/src/test/java/org/dizitart/no2/collection/FindOptionsTest.java
@@ -121,13 +121,5 @@ public void testThenOrderBy2() {
         FindOptions orderByResult = FindOptions.orderBy("Field Name", SortOrder.Ascending);
         assertSame(orderByResult, orderByResult.thenOrderBy("Field Name", SortOrder.Ascending));
     }
-
-    @Test
-    public void testDistinct() {
-        FindOptions findOptions = new FindOptions();
-        FindOptions actualDistinctResult = findOptions.withDistinct(true);
-        assertSame(findOptions, actualDistinctResult);
-        assertTrue(actualDistinctResult.distinct());
-    }
 }
 
diff --git a/nitrite/src/test/java/org/dizitart/no2/collection/FindPlanTest.java b/nitrite/src/test/java/org/dizitart/no2/collection/FindPlanTest.java
@@ -31,7 +31,7 @@ public void testConstructor() {
         assertTrue(actualFindPlan.getBlockingSortOrder().isEmpty());
         assertEquals(
             "FindPlan(byIdFilter=null, indexScanFilter=null, collectionScanFilter=null, indexDescriptor=null,"
-                + " indexScanOrder=null, blockingSortOrder=[], skip=null, limit=null, distinct=false, " +
+                + " indexScanOrder=null, blockingSortOrder=[], skip=null, limit=null, " +
                 "collator=null, subPlans=[])",
             actualFindPlan.toString());
         assertTrue(actualFindPlan.getSubPlans().isEmpty());
diff --git a/nitrite/src/test/java/org/dizitart/no2/common/streams/SortedDocumentStreamTest.java b/nitrite/src/test/java/org/dizitart/no2/common/streams/SortedDocumentStreamTest.java
@@ -40,7 +40,7 @@ public void testConstructor() {
         List<Pair<String, SortOrder>> blockingSortOrder = findPlan.getBlockingSortOrder();
         assertTrue(blockingSortOrder instanceof java.util.ArrayList);
         assertEquals("FindPlan(byIdFilter=null, indexScanFilter=null, collectionScanFilter=null, indexDescriptor=null,"
-            + " indexScanOrder=null, blockingSortOrder=[], skip=null, limit=null, distinct=false, collator=null, " +
+            + " indexScanOrder=null, blockingSortOrder=[], skip=null, limit=null, collator=null, " +
             "subPlans=[])", findPlan.toString());
         assertTrue(blockingSortOrder.isEmpty());
         List<FindPlan> subPlans = findPlan.getSubPlans();
diff --git a/nitrite/src/test/java/org/dizitart/no2/integration/collection/CollectionFindByCompoundIndexTest.java b/nitrite/src/test/java/org/dizitart/no2/integration/collection/CollectionFindByCompoundIndexTest.java
@@ -19,7 +19,6 @@
 
 import org.dizitart.no2.collection.Document;
 import org.dizitart.no2.collection.DocumentCursor;
-import org.dizitart.no2.collection.FindOptions;
 import org.dizitart.no2.collection.FindPlan;
 import org.dizitart.no2.common.SortOrder;
 import org.dizitart.no2.common.tuples.Pair;
@@ -103,39 +102,6 @@ public void testFindByOrFilterAndFilter() {
         assertNotNull(findPlan.getSubPlans().get(0).getIndexScanFilter());
         assertNotNull(findPlan.getSubPlans().get(1).getIndexScanFilter());
 
-        assertEquals(1, cursor.toList().stream().filter(d ->
-            d.get("firstName", String.class).equals("fn2")
-                && d.get("lastName", String.class).equals("ln2")).count());
-
-        assertEquals(1, cursor.toList().stream().filter(d ->
-            d.get("firstName", String.class).equals("fn3")
-                && d.get("lastName", String.class).equals("ln2")).count());
-
-        // distinct test - should still return the same results since we're already deduplicating
-        cursor = collection.find(
-            or(
-                and(
-                    where("lastName").eq("ln2"),
-                    where("firstName").notEq("fn1")
-                ),
-                and(
-                    where("firstName").eq("fn3"),
-                    where("lastName").eq("ln2")
-                )
-            ), FindOptions.withDistinct()
-        );
-
-        assertEquals(2, cursor.size());
-
-        findPlan = cursor.getFindPlan();
-        assertNull(findPlan.getIndexScanFilter());
-        assertNull(findPlan.getCollectionScanFilter());
-        assertNotNull(findPlan.getSubPlans());
-
-        assertEquals(2, findPlan.getSubPlans().size());
-        assertNotNull(findPlan.getSubPlans().get(0).getIndexScanFilter());
-        assertNotNull(findPlan.getSubPlans().get(1).getIndexScanFilter());
-
         assertEquals(1, cursor.toList().stream().filter(d ->
             d.get("firstName", String.class).equals("fn2")
                 && d.get("lastName", String.class).equals("ln2")).count());
@@ -252,22 +218,6 @@ public void testFindByOrFilter() throws ParseException {
         FindPlan findPlan = cursor.getFindPlan();
         assertEquals(3, findPlan.getSubPlans().size());
         assertEquals(3, cursor.size());
-
-        // distinct test - should still return the same results since we're already deduplicating
-        cursor = collection.find(
-            or(
-                or(
-                    where("lastName").eq("ln2"),
-                    where("firstName").notEq("fn1")
-                ),
-                where("birthDay").eq(simpleDateFormat.parse("2012-07-01T16:02:48.440Z")),
-                where("firstName").notEq("fn1")
-            ), FindOptions.withDistinct()
-        );
-
-        findPlan = cursor.getFindPlan();
-        assertEquals(3, findPlan.getSubPlans().size());
-        assertEquals(3, cursor.size());
     }
 
     @Test
diff --git a/nitrite/src/test/java/org/dizitart/no2/integration/collection/CollectionOrDuplicateTest.java b/nitrite/src/test/java/org/dizitart/no2/integration/collection/CollectionOrDuplicateTest.java
diff --git a/pom.xml b/pom.xml
diff --git a/potassium-nitrite/pom.xml b/potassium-nitrite/pom.xml
