Add != and notIn support

Author: Brian Chen

Firestore/CHANGELOG.md

@@ -1,4 +1,8 @@
 # Unreleased
+- [feature] Added `whereField(_:notIn:)` and `whereField(_:isNotEqualTo:)` query
+operators. `whereField(_:notIn:)` finds documents where a specified field’s
+value is not in a specified array. `whereField(_:isNotEqualTo:)` finds documents
+where a specified field's value does not equal the specified value.
 
 # v1.17.1
 - [fixed] Fix gRPC documentation warning surfaced in Xcode (#6340).

Firestore/Example/Tests/Integration/API/FIRQueryTests.mm

@@ -382,6 +382,71 @@ - (void)testCanHaveMultipleMutationsWhileOffline {
                         ]));
 }
 
+- (void)testQueriesCanUseNotEqualFilters {
+  // These documents are ordered by value in "zip" since notEquals filter is an inequality, which
+  // results in documents being sorted by value.
+  NSDictionary *testDocs = @{
+    @"a" : @{@"zip" : @(NAN)},
+    @"b" : @{@"zip" : @91102},
+    @"c" : @{@"zip" : @98101},
+    @"d" : @{@"zip" : @98103},
+    @"e" : @{@"zip" : @[ @98101 ]},
+    @"f" : @{@"zip" : @[ @98101, @98102 ]},
+    @"g" : @{@"zip" : @[ @"98101", @{@"zip" : @98101} ]},
+    @"h" : @{@"zip" : @{@"code" : @500}},
+    @"i" : @{@"zip" : [NSNull null]},
+    @"j" : @{@"code" : @500},
+  };
+  FIRCollectionReference *collection = [self collectionRefWithDocuments:testDocs];
+
+  // Search for zips not matching 98101.
+  FIRQuerySnapshot *snapshot = [self readDocumentSetForRef:[collection queryWhereField:@"zip"
+                                                                          isNotEqualTo:@98101]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[
+                          testDocs[@"a"], testDocs[@"b"], testDocs[@"d"], testDocs[@"e"],
+                          testDocs[@"f"], testDocs[@"g"], testDocs[@"h"]
+                        ]));
+
+  // With objects.
+  snapshot = [self readDocumentSetForRef:[collection queryWhereField:@"zip"
+                                                        isNotEqualTo:@{@"code" : @500}]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[
+                          testDocs[@"a"], testDocs[@"b"], testDocs[@"c"], testDocs[@"d"],
+                          testDocs[@"e"], testDocs[@"f"], testDocs[@"g"]
+                        ]));
+
+  // With null.
+  snapshot = [self readDocumentSetForRef:[collection queryWhereField:@"zip"
+                                                        isNotEqualTo:@[ [NSNull null] ]]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[
+                          testDocs[@"a"], testDocs[@"b"], testDocs[@"c"], testDocs[@"d"],
+                          testDocs[@"e"], testDocs[@"f"], testDocs[@"g"], testDocs[@"h"]
+                        ]));
+
+  // With NAN.
+  snapshot = [self readDocumentSetForRef:[collection queryWhereField:@"zip" isNotEqualTo:@(NAN)]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[
+                          testDocs[@"b"], testDocs[@"c"], testDocs[@"d"], testDocs[@"e"],
+                          testDocs[@"f"], testDocs[@"g"], testDocs[@"h"]
+                        ]));
+}
+
+- (void)testQueriesCanUseNotEqualFiltersWithDocIds {
+  NSDictionary *testDocs = @{
+    @"aa" : @{@"key" : @"aa"},
+    @"ab" : @{@"key" : @"ab"},
+    @"ba" : @{@"key" : @"ba"},
+    @"bb" : @{@"key" : @"bb"},
+  };
+  FIRCollectionReference *collection = [self collectionRefWithDocuments:testDocs];
+
+  FIRQuerySnapshot *snapshot =
+      [self readDocumentSetForRef:[collection queryWhereFieldPath:[FIRFieldPath documentID]
+                                                     isNotEqualTo:@"aa"]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot),
+                        (@[ testDocs[@"ab"], testDocs[@"ba"], testDocs[@"bb"] ]));
+}
+
 - (void)testQueriesCanUseArrayContainsFilters {
   NSDictionary *testDocs = @{
     @"a" : @{@"array" : @[ @42 ]},
@@ -441,6 +506,74 @@ - (void)testQueriesCanUseInFiltersWithDocIds {
   XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[ testDocs[@"aa"], testDocs[@"ab"] ]));
 }
 
+- (void)testQueriesCanUseNotInFilters {
+  NSDictionary *testDocs = @{
+    @"a" : @{@"zip" : @98101},
+    @"b" : @{@"zip" : @91102},
+    @"c" : @{@"zip" : @98103},
+    @"d" : @{@"zip" : @[ @98101 ]},
+    @"e" : @{@"zip" : @[ @"98101", @{@"zip" : @98101} ]},
+    @"f" : @{@"zip" : @{@"code" : @500}},
+    @"g" : @{@"zip" : @[ @98101, @98102 ]},
+    @"h" : @{@"code" : @500},
+    @"i" : @{@"zip" : [NSNull null]},
+    @"j" : @{@"zip" : @(NAN)},
+  };
+  FIRCollectionReference *collection = [self collectionRefWithDocuments:testDocs];
+
+  // Search for zips not matching 98101, 98103, and [98101, 98102].
+  FIRQuerySnapshot *snapshot = [self
+      readDocumentSetForRef:[collection queryWhereField:@"zip"
+                                                  notIn:@[ @98101, @98103, @[ @98101, @98102 ] ]]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[
+                          testDocs[@"b"], testDocs[@"d"], testDocs[@"e"], testDocs[@"f"],
+                          testDocs[@"i"], testDocs[@"j"]
+                        ]));
+
+  // With objects.
+  snapshot = [self readDocumentSetForRef:[collection queryWhereField:@"zip"
+                                                               notIn:@[ @{@"code" : @500} ]]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[
+                          testDocs[@"a"], testDocs[@"b"], testDocs[@"c"], testDocs[@"d"],
+                          testDocs[@"e"], testDocs[@"g"], testDocs[@"i"], testDocs[@"j"]
+                        ]));
+
+  // With null.
+  snapshot = [self readDocumentSetForRef:[collection queryWhereField:@"zip"
+                                                               notIn:@[ [NSNull null] ]]];
+  XCTAssertTrue(snapshot.isEmpty);
+
+  // With NAN.
+  snapshot = [self readDocumentSetForRef:[collection queryWhereField:@"zip" notIn:@[ @(NAN) ]]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[
+                          testDocs[@"a"], testDocs[@"b"], testDocs[@"c"], testDocs[@"d"],
+                          testDocs[@"e"], testDocs[@"f"], testDocs[@"g"], testDocs[@"i"]
+                        ]));
+
+  // With NAN and a number.
+  snapshot = [self readDocumentSetForRef:[collection queryWhereField:@"zip"
+                                                               notIn:@[ @(NAN), @98101 ]]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[
+                          testDocs[@"b"], testDocs[@"c"], testDocs[@"d"], testDocs[@"e"],
+                          testDocs[@"f"], testDocs[@"g"], testDocs[@"i"]
+                        ]));
+}
+
+- (void)testQueriesCanUseNotInFiltersWithDocIds {
+  NSDictionary *testDocs = @{
+    @"aa" : @{@"key" : @"aa"},
+    @"ab" : @{@"key" : @"ab"},
+    @"ba" : @{@"key" : @"ba"},
+    @"bb" : @{@"key" : @"bb"},
+  };
+  FIRCollectionReference *collection = [self collectionRefWithDocuments:testDocs];
+
+  FIRQuerySnapshot *snapshot =
+      [self readDocumentSetForRef:[collection queryWhereFieldPath:[FIRFieldPath documentID]
+                                                            notIn:@[ @"aa", @"ab" ]]];
+  XCTAssertEqualObjects(FIRQuerySnapshotGetData(snapshot), (@[ testDocs[@"ba"], testDocs[@"bb"] ]));
+}
+
 - (void)testQueriesCanUseArrayContainsAnyFilters {
   NSDictionary *testDocs = @{
     @"a" : @{@"array" : @[ @42 ]},

Firestore/Example/Tests/Integration/API/FIRValidationTests.mm

@@ -602,7 +602,7 @@ - (void)testQueryInequalityFieldMustMatchFirstOrderByField {
 
   NSString *reason =
       @"Invalid query. You have a where filter with "
-       "an inequality (lessThan, lessThanOrEqual, greaterThan, or greaterThanOrEqual) "
+       "an inequality (notEqual, lessThan, lessThanOrEqual, greaterThan, or greaterThanOrEqual) "
        "on field 'x' and so you must also use 'x' as your first queryOrderedBy field, "
        "but your first queryOrderedBy is currently on field 'y' instead.";
   FSTAssertThrows([base queryOrderedByField:@"y"], reason);
@@ -611,6 +611,7 @@ - (void)testQueryInequalityFieldMustMatchFirstOrderByField {
   FSTAssertThrows([[[coll queryOrderedByField:@"y"] queryOrderedByField:@"x"] queryWhereField:@"x"
                                                                                 isGreaterThan:@32],
                   reason);
+  FSTAssertThrows([[coll queryOrderedByField:@"y"] queryWhereField:@"x" isNotEqualTo:@32], reason);
 
   XCTAssertNoThrow([base queryWhereField:@"x" isLessThanOrEqualTo:@"cat"],
                    @"Same inequality fields work");
@@ -638,6 +639,20 @@ - (void)testQueryInequalityFieldMustMatchFirstOrderByField {
                    @"array_contains different than orderBy works.");
 }
 
+- (void)testQueriesWithMultipleNotEqualAndInequalitiesFail {
+  FIRCollectionReference *coll = [self.db collectionWithPath:@"collection"];
+
+  FSTAssertThrows([[coll queryWhereField:@"x" isNotEqualTo:@1] queryWhereField:@"x"
+                                                                  isNotEqualTo:@2],
+                  @"Invalid Query. You cannot use more than one 'notEqual' filter.");
+
+  FSTAssertThrows([[coll queryWhereField:@"x" isNotEqualTo:@1] queryWhereField:@"y"
+                                                                  isNotEqualTo:@2],
+                  @"Invalid Query. All where filters with an inequality (lessThan, "
+                   "lessThanOrEqual, greaterThan, or greaterThanOrEqual) must be on "
+                   "the same field. But you have inequality filters on 'x' and 'y'");
+}
+
 - (void)testQueriesWithMultipleArrayFiltersFail {
   FIRCollectionReference *coll = [self.db collectionWithPath:@"collection"];
   FSTAssertThrows([[coll queryWhereField:@"foo" arrayContains:@1] queryWhereField:@"foo"
@@ -655,6 +670,18 @@ - (void)testQueriesWithMultipleArrayFiltersFail {
       @"Invalid Query. You cannot use 'arrayContains' filters with 'arrayContainsAny' filters.");
 }
 
+- (void)testQueriesWithNotEqualAndNotInFiltersFail {
+  FIRCollectionReference *coll = [self.db collectionWithPath:@"collection"];
+
+  FSTAssertThrows([[coll queryWhereField:@"foo" notIn:@[ @1 ]] queryWhereField:@"foo"
+                                                                  isNotEqualTo:@2],
+                  @"Invalid Query. You cannot use 'notEqual' filters with 'notIn' filters.");
+
+  FSTAssertThrows([[coll queryWhereField:@"foo" isNotEqualTo:@2] queryWhereField:@"foo"
+                                                                           notIn:@[ @1 ]],
+                  @"Invalid Query. You cannot use 'notIn' filters with 'notEqual' filters.");
+}
+
 - (void)testQueriesWithMultipleDisjunctiveFiltersFail {
   FIRCollectionReference *coll = [self.db collectionWithPath:@"collection"];
   FSTAssertThrows([[coll queryWhereField:@"foo" in:@[ @1 ]] queryWhereField:@"foo" in:@[ @2 ]],
@@ -664,6 +691,10 @@ - (void)testQueriesWithMultipleDisjunctiveFiltersFail {
                                                                          arrayContainsAny:@[ @2 ]],
                   @"Invalid Query. You cannot use more than one 'arrayContainsAny' filter.");
 
+  FSTAssertThrows([[coll queryWhereField:@"foo" notIn:@[ @1 ]] queryWhereField:@"foo"
+                                                                         notIn:@[ @2 ]],
+                  @"Invalid Query. You cannot use more than one 'notIn' filter.");
+
   FSTAssertThrows([[coll queryWhereField:@"foo" arrayContainsAny:@[ @1 ]] queryWhereField:@"foo"
                                                                                        in:@[ @2 ]],
                   @"Invalid Query. You cannot use 'in' filters with 'arrayContainsAny' filters.");
@@ -672,18 +703,44 @@ - (void)testQueriesWithMultipleDisjunctiveFiltersFail {
                                                            arrayContainsAny:@[ @2 ]],
                   @"Invalid Query. You cannot use 'arrayContainsAny' filters with 'in' filters.");
 
+  FSTAssertThrows(
+      [[coll queryWhereField:@"foo" arrayContainsAny:@[ @1 ]] queryWhereField:@"foo" notIn:@[ @2 ]],
+      @"Invalid Query. You cannot use 'notIn' filters with 'arrayContainsAny' filters.");
+
+  FSTAssertThrows(
+      [[coll queryWhereField:@"foo" notIn:@[ @1 ]] queryWhereField:@"foo" arrayContainsAny:@[ @2 ]],
+      @"Invalid Query. You cannot use 'arrayContainsAny' filters with 'notIn' filters.");
+
+  FSTAssertThrows([[coll queryWhereField:@"foo" in:@[ @1 ]] queryWhereField:@"foo" notIn:@[ @2 ]],
+                  @"Invalid Query. You cannot use 'notIn' filters with 'in' filters.");
+
+  FSTAssertThrows([[coll queryWhereField:@"foo" notIn:@[ @1 ]] queryWhereField:@"foo" in:@[ @2 ]],
+                  @"Invalid Query. You cannot use 'in' filters with 'notIn' filters.");
+
   // This is redundant with the above tests, but makes sure our validation doesn't get confused.
   FSTAssertThrows([[[coll queryWhereField:@"foo"
                                        in:@[ @1 ]] queryWhereField:@"foo"
                                                      arrayContains:@2] queryWhereField:@"foo"
                                                                       arrayContainsAny:@[ @2 ]],
                   @"Invalid Query. You cannot use 'arrayContainsAny' filters with 'in' filters.");
 
+  FSTAssertThrows(
+      [[[coll queryWhereField:@"foo"
+                arrayContains:@1] queryWhereField:@"foo" in:@[ @2 ]] queryWhereField:@"foo"
+                                                                    arrayContainsAny:@[ @2 ]],
+      @"Invalid Query. You cannot use 'arrayContainsAny' filters with 'arrayContains' filters.");
+
+  FSTAssertThrows([[[coll queryWhereField:@"foo"
+                                    notIn:@[ @1 ]] queryWhereField:@"foo"
+                                                     arrayContains:@2] queryWhereField:@"foo"
+                                                                      arrayContainsAny:@[ @2 ]],
+                  @"Invalid Query. You cannot use 'arrayContains' filters with 'notIn' filters.");
+
   FSTAssertThrows([[[coll queryWhereField:@"foo"
                             arrayContains:@1] queryWhereField:@"foo"
                                                            in:@[ @2 ]] queryWhereField:@"foo"
-                                                                      arrayContainsAny:@[ @2 ]],
-                  @"Invalid Query. You cannot use 'arrayContainsAny' filters with 'in' filters.");
+                                                                                 notIn:@[ @2 ]],
+                  @"Invalid Query. You cannot use 'notIn' filters with 'arrayContains' filters.");
 }
 
 - (void)testQueriesCanUseInWithArrayContain {
@@ -715,6 +772,9 @@ - (void)testQueriesInAndArrayContainsAnyArrayRules {
   FSTAssertThrows([coll queryWhereField:@"foo" in:@[]],
                   @"Invalid Query. A non-empty array is required for 'in' filters.");
 
+  FSTAssertThrows([coll queryWhereField:@"foo" notIn:@[]],
+                  @"Invalid Query. A non-empty array is required for 'notIn' filters.");
+
   FSTAssertThrows([coll queryWhereField:@"foo" arrayContainsAny:@[]],
                   @"Invalid Query. A non-empty array is required for 'arrayContainsAny' filters.");
 
@@ -726,6 +786,9 @@ - (void)testQueriesInAndArrayContainsAnyArrayRules {
   FSTAssertThrows([coll queryWhereField:@"foo" arrayContainsAny:values],
                   @"Invalid Query. 'arrayContainsAny' filters support a maximum of 10 elements"
                    " in the value array.");
+  FSTAssertThrows(
+      [coll queryWhereField:@"foo" notIn:values],
+      @"Invalid Query. 'notIn' filters support a maximum of 10 elements in the value array.");
 
   NSArray *withNullValues = @[ @1, [NSNull null] ];
   FSTAssertThrows([coll queryWhereField:@"foo" in:withNullValues],

Firestore/Source/API/FIRQuery.mm

@@ -215,6 +215,16 @@ - (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path isEqualTo:(id)value {
   return [self queryWithFilterOperator:Filter::Operator::Equal path:path.internalValue value:value];
 }
 
+- (FIRQuery *)queryWhereField:(NSString *)field isNotEqualTo:(id)value {
+  return [self queryWithFilterOperator:Filter::Operator::NotEqual field:field value:value];
+}
+
+- (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path isNotEqualTo:(id)value {
+  return [self queryWithFilterOperator:Filter::Operator::NotEqual
+                                  path:path.internalValue
+                                 value:value];
+}
+
 - (FIRQuery *)queryWhereField:(NSString *)field isLessThan:(id)value {
   return [self queryWithFilterOperator:Filter::Operator::LessThan field:field value:value];
 }
@@ -285,6 +295,16 @@ - (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path in:(NSArray<id> *)values
   return [self queryWithFilterOperator:Filter::Operator::In path:path.internalValue value:values];
 }
 
+- (FIRQuery *)queryWhereField:(NSString *)field notIn:(NSArray<id> *)values {
+  return [self queryWithFilterOperator:Filter::Operator::NotIn field:field value:values];
+}
+
+- (FIRQuery *)queryWhereFieldPath:(FIRFieldPath *)path notIn:(NSArray<id> *)values {
+  return [self queryWithFilterOperator:Filter::Operator::NotIn
+                                  path:path.internalValue
+                                 value:values];
+}
+
 - (FIRQuery *)queryFilteredUsingComparisonPredicate:(NSPredicate *)predicate {
   NSComparisonPredicate *comparison = (NSComparisonPredicate *)predicate;
   if (comparison.comparisonPredicateModifier != NSDirectPredicateModifier) {
@@ -307,6 +327,8 @@ - (FIRQuery *)queryFilteredUsingComparisonPredicate:(NSPredicate *)predicate {
         return [self queryWhereField:path isGreaterThan:value];
       case NSGreaterThanOrEqualToPredicateOperatorType:
         return [self queryWhereField:path isGreaterThanOrEqualTo:value];
+      case NSNotEqualToPredicateOperatorType:
+        return [self queryWhereField:path isNotEqualTo:value];
       default:;  // Fallback below to throw assertion.
     }
   } else if ([comparison.leftExpression expressionType] == NSConstantValueExpressionType &&
@@ -324,6 +346,8 @@ - (FIRQuery *)queryFilteredUsingComparisonPredicate:(NSPredicate *)predicate {
         return [self queryWhereField:path isLessThan:value];
       case NSGreaterThanOrEqualToPredicateOperatorType:
         return [self queryWhereField:path isLessThanOrEqualTo:value];
+      case NSNotEqualToPredicateOperatorType:
+        return [self queryWhereField:path isNotEqualTo:value];
       default:;  // Fallback below to throw assertion.
     }
   } else {
@@ -483,7 +507,8 @@ - (FIRQuery *)queryWithFilterOperator:(Filter::Operator)filterOperator
                                  path:(const FieldPath &)fieldPath
                                 value:(id)value {
   FieldValue fieldValue = [self parsedQueryValue:value
-                                     allowArrays:filterOperator == Filter::Operator::In];
+                                     allowArrays:filterOperator == Filter::Operator::In ||
+                                                 filterOperator == Filter::Operator::NotIn];
   auto describer = [value] { return MakeString(NSStringFromClass([value class])); };
   return Wrap(_query.Filter(fieldPath, filterOperator, std::move(fieldValue), describer));
 }