Make != and NOT_in filters public (firebase#1975)

Author: Brian Chen

firebase-firestore/CHANGELOG.md

@@ -1,4 +1,12 @@
 # Unreleased
+- [feature] Added `Query.whereNotIn()` and `Query.whereNotEqualTo()` query
+ operators. `Query.whereNotIn()` finds documents where a specified field’s
+ value is not in a specified array. `Query.whereNotEqualTo()` finds
+ documents where a specified field's value does not equal the specified value.
+ Neither query operator will match documents where the specified field is not
+ present.
+
+# 21.6.0
 - [fixed] Removed a delay that may have prevented Firestore from immediately
  reestablishing a network connection if a connectivity change occurred while
  the app was in the background.

firebase-firestore/api.txt

@@ -270,6 +270,10 @@ package com.google.firebase.firestore {
  method @NonNull public com.google.firebase.firestore.Query whereLessThan(@NonNull com.google.firebase.firestore.FieldPath, @NonNull Object);
  method @NonNull public com.google.firebase.firestore.Query whereLessThanOrEqualTo(@NonNull String, @NonNull Object);
  method @NonNull public com.google.firebase.firestore.Query whereLessThanOrEqualTo(@NonNull com.google.firebase.firestore.FieldPath, @NonNull Object);
+ method @NonNull public com.google.firebase.firestore.Query whereNotEqualTo(@NonNull String, @Nullable Object);
+ method @NonNull public com.google.firebase.firestore.Query whereNotEqualTo(@NonNull com.google.firebase.firestore.FieldPath, @Nullable Object);
+ method @NonNull public com.google.firebase.firestore.Query whereNotIn(@NonNull String, @NonNull java.util.List<?>);
+ method @NonNull public com.google.firebase.firestore.Query whereNotIn(@NonNull com.google.firebase.firestore.FieldPath, @NonNull java.util.List<?>);
  }
 
  public enum Query.Direction {

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/QueryTest.java

@@ -41,7 +41,6 @@
 import java.util.Map;
 import java.util.concurrent.Semaphore;
 import org.junit.After;
-import org.junit.Ignore;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 
@@ -486,20 +485,20 @@ public void testQueriesFireFromCacheWhenOffline() {
  listener.remove();
  }
 
- // TODO(ne-queries): Re-enable once emulator support is added to CI.
- @Ignore
  @Test
  public void testQueriesCanUseNotEqualFilters() {
- Map<String, Object> docA = map("zip", 98101L);
+ // These documents are ordered by value in "zip" since the notEquals filter is an inequality,
+ // which results in documents being sorted by value.
+ Map<String, Object> docA = map("zip", Double.NaN);
  Map<String, Object> docB = map("zip", 91102L);
- Map<String, Object> docC = map("zip", "98101");
- Map<String, Object> docD = map("zip", asList(98101L));
- Map<String, Object> docE = map("zip", asList("98101", map("zip", 98101L)));
- Map<String, Object> docF = map("zip", map("code", 500L));
- Map<String, Object> docG = map("zip", asList(98101L, 98102L));
- Map<String, Object> docH = map("code", 500L);
- Map<String, Object> docI = map("zip", null);
- Map<String, Object> docJ = map("zip", Double.NaN);
+ Map<String, Object> docC = map("zip", 98101L);
+ Map<String, Object> docD = map("zip", "98101");
+ Map<String, Object> docE = map("zip", asList(98101L));
+ Map<String, Object> docF = map("zip", asList(98101L, 98102L));
+ Map<String, Object> docG = map("zip", asList("98101", map("zip", 98101L)));
+ Map<String, Object> docH = map("zip", map("code", 500L));
+ Map<String, Object> docI = map("code", 500L);
+ Map<String, Object> docJ = map("zip", null);
 
  Map<String, Map<String, Object>> allDocs =
  map(
@@ -509,39 +508,37 @@ public void testQueriesCanUseNotEqualFilters() {
 
  // Search for zips not matching 98101.
  Map<String, Map<String, Object>> expectedDocsMap = Maps.newHashMap(allDocs);
- expectedDocsMap.remove("a");
- expectedDocsMap.remove("h");
+ expectedDocsMap.remove("c");
  expectedDocsMap.remove("i");
+ expectedDocsMap.remove("j");
 
  QuerySnapshot snapshot = waitFor(collection.whereNotEqualTo("zip", 98101L).get());
  assertEquals(Lists.newArrayList(expectedDocsMap.values()), querySnapshotToValues(snapshot));
 
  // With objects.
  expectedDocsMap = Maps.newHashMap(allDocs);
- expectedDocsMap.remove("f");
  expectedDocsMap.remove("h");
  expectedDocsMap.remove("i");
+ expectedDocsMap.remove("j");
  snapshot = waitFor(collection.whereNotEqualTo("zip", map("code", 500)).get());
  assertEquals(Lists.newArrayList(expectedDocsMap.values()), querySnapshotToValues(snapshot));
 
  // With Null.
  expectedDocsMap = Maps.newHashMap(allDocs);
- expectedDocsMap.remove("h");
  expectedDocsMap.remove("i");
+ expectedDocsMap.remove("j");
  snapshot = waitFor(collection.whereNotEqualTo("zip", null).get());
  assertEquals(Lists.newArrayList(expectedDocsMap.values()), querySnapshotToValues(snapshot));
 
  // With NaN.
  expectedDocsMap = Maps.newHashMap(allDocs);
- expectedDocsMap.remove("h");
+ expectedDocsMap.remove("a");
  expectedDocsMap.remove("i");
  expectedDocsMap.remove("j");
  snapshot = waitFor(collection.whereNotEqualTo("zip", Double.NaN).get());
  assertEquals(Lists.newArrayList(expectedDocsMap.values()), querySnapshotToValues(snapshot));
  }
 
- // TODO(ne-queries): Re-enable once emulator support is added to CI.
- @Ignore
  @Test
  public void testQueriesCanUseNotEqualFiltersWithDocIds() {
  Map<String, String> docA = map("key", "aa");
@@ -617,20 +614,20 @@ public void testQueriesCanUseInFiltersWithDocIds() {
  assertEquals(asList(docA, docB), querySnapshotToValues(docs));
  }
 
- // TODO(ne-queries): Re-enable once emulator support is added to CI.
- @Ignore
  @Test
  public void testQueriesCanUseNotInFilters() {
- Map<String, Object> docA = map("zip", 98101L);
+ // These documents are ordered by value in "zip" since the notEquals filter is an inequality,
+ // which results in documents being sorted by value.
+ Map<String, Object> docA = map("zip", Double.NaN);
  Map<String, Object> docB = map("zip", 91102L);
- Map<String, Object> docC = map("zip", 98103L);
- Map<String, Object> docD = map("zip", asList(98101L));
- Map<String, Object> docE = map("zip", asList("98101", map("zip", 98101L)));
- Map<String, Object> docF = map("zip", map("code", 500L));
- Map<String, Object> docG = map("zip", asList(98101L, 98102L));
- Map<String, Object> docH = map("code", 500L);
- Map<String, Object> docI = map("zip", null);
- Map<String, Object> docJ = map("zip", Double.NaN);
+ Map<String, Object> docC = map("zip", 98101L);
+ Map<String, Object> docD = map("zip", 98103L);
+ Map<String, Object> docE = map("zip", asList(98101L));
+ Map<String, Object> docF = map("zip", asList(98101L, 98102L));
+ Map<String, Object> docG = map("zip", asList("98101", map("zip", 98101L)));
+ Map<String, Object> docH = map("zip", map("code", 500L));
+ Map<String, Object> docI = map("code", 500L);
+ Map<String, Object> docJ = map("zip", null);
 
  Map<String, Map<String, Object>> allDocs =
  map(
@@ -640,19 +637,21 @@ public void testQueriesCanUseNotInFilters() {
 
  // Search for zips not matching 98101, 98103, or [98101, 98102].
  Map<String, Map<String, Object>> expectedDocsMap = Maps.newHashMap(allDocs);
- expectedDocsMap.remove("a");
  expectedDocsMap.remove("c");
- expectedDocsMap.remove("g");
- expectedDocsMap.remove("h");
+ expectedDocsMap.remove("d");
+ expectedDocsMap.remove("f");
+ expectedDocsMap.remove("i");
+ expectedDocsMap.remove("j");
 
  QuerySnapshot snapshot =
  waitFor(collection.whereNotIn("zip", asList(98101L, 98103L, asList(98101L, 98102L))).get());
  assertEquals(Lists.newArrayList(expectedDocsMap.values()), querySnapshotToValues(snapshot));
 
  // With objects.
  expectedDocsMap = Maps.newHashMap(allDocs);
- expectedDocsMap.remove("f");
  expectedDocsMap.remove("h");
+ expectedDocsMap.remove("i");
+ expectedDocsMap.remove("j");
  snapshot = waitFor(collection.whereNotIn("zip", asList(map("code", 500L))).get());
  assertEquals(Lists.newArrayList(expectedDocsMap.values()), querySnapshotToValues(snapshot));
 
@@ -664,22 +663,22 @@ public void testQueriesCanUseNotInFilters() {
 
  // With NaN.
  expectedDocsMap = Maps.newHashMap(allDocs);
- expectedDocsMap.remove("h");
+ expectedDocsMap.remove("a");
+ expectedDocsMap.remove("i");
  expectedDocsMap.remove("j");
  snapshot = waitFor(collection.whereNotIn("zip", asList(Double.NaN)).get());
  assertEquals(Lists.newArrayList(expectedDocsMap.values()), querySnapshotToValues(snapshot));
 
  // With NaN and a number.
  expectedDocsMap = Maps.newHashMap(allDocs);
  expectedDocsMap.remove("a");
- expectedDocsMap.remove("h");
+ expectedDocsMap.remove("c");
+ expectedDocsMap.remove("i");
  expectedDocsMap.remove("j");
  snapshot = waitFor(collection.whereNotIn("zip", asList(Float.NaN, 98101L)).get());
  assertEquals(Lists.newArrayList(expectedDocsMap.values()), querySnapshotToValues(snapshot));
  }
 
- // TODO(ne-queries): Re-enable once emulator support is added to CI.
- @Ignore
  @Test
  public void testQueriesCanUseNotInFiltersWithDocIds() {
  Map<String, String> docA = map("key", "aa");

firebase-firestore/src/androidTest/java/com/google/firebase/firestore/ValidationTest.java

@@ -414,10 +414,12 @@ public void queriesWithNullOrNaNFiltersOtherThanEqualityFail() {
  CollectionReference collection = testCollection();
  expectError(
  () -> collection.whereGreaterThan("a", null),
- "Invalid Query. Null supports only equality comparisons (via whereEqualTo()).");
+ "Invalid Query. Null only supports comparisons via "
+ + "whereEqualTo() and whereNotEqualTo().");
  expectError(
  () -> collection.whereArrayContains("a", null),
- "Invalid Query. Null supports only equality comparisons (via whereEqualTo()).");
+ "Invalid Query. Null only supports comparisons via "
+ + "whereEqualTo() and whereNotEqualTo().");
  expectError(
  () -> collection.whereArrayContainsAny("a", null),
  "Invalid Query. A non-empty array is required for 'array_contains_any' filters.");
@@ -430,10 +432,12 @@ public void queriesWithNullOrNaNFiltersOtherThanEqualityFail() {
 
  expectError(
  () -> collection.whereGreaterThan("a", Double.NaN),
- "Invalid Query. NaN supports only equality comparisons (via whereEqualTo()).");
+ "Invalid Query. NaN only supports comparisons via "
+ + "whereEqualTo() and whereNotEqualTo().");
  expectError(
  () -> collection.whereArrayContains("a", Double.NaN),
- "Invalid Query. NaN supports only equality comparisons (via whereEqualTo()).");
+ "Invalid Query. NaN only supports comparisons via "
+ + "whereEqualTo() and whereNotEqualTo().");
  }
 
  @Test
@@ -544,8 +548,9 @@ public void queryOrderByKeyBoundsMustBeStringsWithoutSlashes() {
  public void queriesWithDifferentInequalityFieldsFail() {
  expectError(
  () -> testCollection().whereGreaterThan("x", 32).whereLessThan("y", "cat"),
- "All where filters other than whereEqualTo() must be on the same field. But you "
- + "have filters on 'x' and 'y'");
+ "All where filters with an inequality (notEqualTo, notIn, lessThan, "
+ + "lessThanOrEqualTo, greaterThan, or greaterThanOrEqualTo) must be on the "
+ + "same field. But you have filters on 'x' and 'y'");
  }
 
  @Test
@@ -571,8 +576,9 @@ public void queriesWithMultipleNotEqualAndInequalitiesFail() {
 
  expectError(
  () -> testCollection().whereNotEqualTo("x", 32).whereGreaterThan("y", 33),
- "All where filters other than whereEqualTo() must be on the same field. But you "
- + "have filters on 'x' and 'y'");
+ "All where filters with an inequality (notEqualTo, notIn, lessThan, "
+ + "lessThanOrEqualTo, greaterThan, or greaterThanOrEqualTo) must be on the "
+ + "same field. But you have filters on 'x' and 'y'");
  }
 
  @Test
@@ -619,7 +625,9 @@ public void queriesWithMultipleDisjunctiveFiltersFail() {
 
  expectError(
  () -> testCollection().whereNotIn("foo", asList(1, 2)).whereNotIn("bar", asList(1, 2)),
- "Invalid Query. You cannot use more than one 'not_in' filter.");
+ "All where filters with an inequality (notEqualTo, notIn, lessThan, "
+ + "lessThanOrEqualTo, greaterThan, or greaterThanOrEqualTo) must be on the "
+ + "same field. But you have filters on 'foo' and 'bar'");
 
  expectError(
  () ->

firebase-firestore/src/main/java/com/google/firebase/firestore/Query.java

@@ -119,8 +119,7 @@ public Query whereEqualTo(@NonNull FieldPath fieldPath, @Nullable Object value)
  * @return The created {@code Query}.
  */
  @NonNull
- // TODO(ne-queries): Make method public once backend is ready.
- Query whereNotEqualTo(@NonNull String field, @Nullable Object value) {
+ public Query whereNotEqualTo(@NonNull String field, @Nullable Object value) {
  return whereHelper(FieldPath.fromDotSeparatedPath(field), Operator.NOT_EQUAL, value);
  }
 
@@ -136,8 +135,7 @@ Query whereNotEqualTo(@NonNull String field, @Nullable Object value) {
  * @return The created {@code Query}.
  */
  @NonNull
- // TODO(ne-queries): Make method public once backend is ready.
- Query whereNotEqualTo(@NonNull FieldPath fieldPath, @Nullable Object value) {
+ public Query whereNotEqualTo(@NonNull FieldPath fieldPath, @Nullable Object value) {
  return whereHelper(fieldPath, Operator.NOT_EQUAL, value);
  }
 
@@ -352,6 +350,10 @@ public Query whereIn(@NonNull FieldPath fieldPath, @NonNull List<? extends Objec
  * Creates and returns a new {@code Query} with the additional filter that documents must contain
  * the specified field and the value does not equal any of the values from the provided list.
  *
+ * <p>One special case is that {@coce whereNotIn} cannot match {@code null} values. To query for
+ * documents where a field exists and is {@code null}, use {@code whereNotEqualTo}, which can
+ * handle this special case.
+ *
  * <p>A {@code Query} can have only one {@code whereNotIn()} filter, and it cannot be combined
  * with {@code whereArrayContains()}, {@code whereArrayContainsAny()}, {@code whereIn()}, or
  * {@code whereNotEqualTo()}.
@@ -361,15 +363,18 @@ public Query whereIn(@NonNull FieldPath fieldPath, @NonNull List<? extends Objec
  * @return The created {@code Query}.
  */
  @NonNull
- // TODO(ne-queries): Make method public once backend is ready.
- Query whereNotIn(@NonNull String field, @NonNull List<? extends Object> values) {
+ public Query whereNotIn(@NonNull String field, @NonNull List<? extends Object> values) {
  return whereHelper(FieldPath.fromDotSeparatedPath(field), Operator.NOT_IN, values);
  }
 
  /**
  * Creates and returns a new {@code Query} with the additional filter that documents must contain
  * the specified field and the value does not equal any of the values from the provided list.
  *
+ * <p>One special case is that {@coce whereNotIn} cannot match {@code null} values. To query for
+ * documents where a field exists and is {@code null}, use {@code whereNotEqualTo}, which can
+ * handle this special case.
+ *
  * <p>A {@code Query} can have only one {@code whereNotIn()} filter, and it cannot be combined
  * with {@code whereArrayContains()}, {@code whereArrayContainsAny()}, {@code whereIn()}, or
  * {@code whereNotEqualTo()}.
@@ -379,8 +384,7 @@ Query whereNotIn(@NonNull String field, @NonNull List<? extends Object> values)
  * @return The created {@code Query}.
  */
  @NonNull
- // TODO(ne-queries): Make method public once backend is ready.
- Query whereNotIn(@NonNull FieldPath fieldPath, @NonNull List<? extends Object> values) {
+ public Query whereNotIn(@NonNull FieldPath fieldPath, @NonNull List<? extends Object> values) {
  return whereHelper(fieldPath, Operator.NOT_IN, values);
  }
 
@@ -569,8 +573,9 @@ private void validateNewFilter(Filter filter) {
  if (existingInequality != null && !existingInequality.equals(newInequality)) {
  throw new IllegalArgumentException(
  String.format(
- "All where filters other than whereEqualTo() must be on the same field. But you "
- + "have filters on '%s' and '%s'",
+ "All where filters with an inequality (notEqualTo, notIn, lessThan, "
+ + "lessThanOrEqualTo, greaterThan, or greaterThanOrEqualTo) must be on the "
+ + "same field. But you have filters on '%s' and '%s'",
  existingInequality.canonicalString(), newInequality.canonicalString()));
  }
  com.google.firebase.firestore.model.FieldPath firstOrderByField =

firebase-firestore/src/main/java/com/google/firebase/firestore/core/FieldFilter.java

@@ -73,17 +73,17 @@ public static FieldFilter create(FieldPath path, Operator operator, Value value)
  return new KeyFieldFilter(path, operator, value);
  }
  } else if (Values.isNullValue(value)) {
- // TODO(ne-queries): Update error message to include != operator.
  if (operator != Operator.EQUAL && operator != Operator.NOT_EQUAL) {
  throw new IllegalArgumentException(
- "Invalid Query. Null supports only equality comparisons (via whereEqualTo()).");
+ "Invalid Query. Null only supports comparisons via "
+ + "whereEqualTo() and whereNotEqualTo().");
  }
  return new FieldFilter(path, operator, value);
  } else if (Values.isNanValue(value)) {
- // TODO(ne-queries): Update error message to include != operator.
  if (operator != Operator.EQUAL && operator != Operator.NOT_EQUAL) {
  throw new IllegalArgumentException(
- "Invalid Query. NaN supports only equality comparisons (via whereEqualTo()).");
+ "Invalid Query. NaN only supports comparisons via "
+ + "whereEqualTo() and whereNotEqualTo().");
  }
  return new FieldFilter(path, operator, value);
  } else if (operator == Operator.ARRAY_CONTAINS) {
@@ -137,7 +137,8 @@ public boolean isInequality() {
  Operator.LESS_THAN_OR_EQUAL,
  Operator.GREATER_THAN,
  Operator.GREATER_THAN_OR_EQUAL,
- Operator.NOT_EQUAL)
+ Operator.NOT_EQUAL,
+ Operator.NOT_IN)
  .contains(operator);
  }
 

firebase-firestore/src/test/java/com/google/firebase/firestore/core/QueryTest.java

@@ -675,7 +675,7 @@ public void testCanonicalIdsAreStable() {
  "collection|f:ain[1,2,3]|ob:__name__asc");
  assertCanonicalId(
  baseQuery.filter(filter("a", "not-in", Arrays.asList(1, 2, 3))),
- "collection|f:anot_in[1,2,3]|ob:__name__asc");
+ "collection|f:anot_in[1,2,3]|ob:aasc__name__asc");
  assertCanonicalId(
  baseQuery.filter(filter("a", "array-contains-any", Arrays.asList(1, 2, 3))),
  "collection|f:aarray_contains_any[1,2,3]|ob:__name__asc");