Merge remote-tracking branch 'origin/master' into OverlayNeverNull

Author: dconeybe

firebase-annotations/src/main/java/com/google/firebase/annotations/PreviewApi.java

@@ -0,0 +1,26 @@
+// Copyright 2022 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.firebase.annotations;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Target;
+
+/**
+ * Indicates that this object (class, method, etc) is experimental and that both its signature and
+ * implementation are subject to change. An API marked with this annotation provides no guarantee of
+ * API stability or backward-compatibility.
+ */
+@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.CONSTRUCTOR})
+public @interface PreviewApi {}

firebase-firestore/CHANGELOG.md

@@ -2,13 +2,20 @@ Android changes are not released automatically. Ensure that changes are released
 by opting into a release at 
 [go/firebase-android-release](http:go/firebase-android-release) (Googlers only).
 
+# Unreleased
+- [feature] Added experimental support for indexed query execution. Indexes can
+  be enabled by invoking `FirebaseFirestore.setIndexConfiguration()` with the
+  JSON index definition exported by the Firestore CLI. Queries against the
+  cache are executed using an index once the asynchronous operation to generate
+  the index entries completes.
+
 # 24.0.2
 - [fixed] Fixed an issue of long grpc reconnection period, when App moves to
   foreground after staying in background for a while.
 - [fixed] Fixed an AppCheck issue that caused Firestore listeners to stop
   working and receive a "Permission Denied" error. This issue only occurred for
   AppCheck users that set their expiration time to under an hour.
-- [fixed] Fixed a potential problem during Firestore's shutdown that prevented 
+- [fixed] Fixed a potential problem during Firestore's shutdown that prevented
   the shutdown from proceeding if a network connection was opened right before.
 - [changed] Queries are now send to the backend before the SDK starts local 
   processing, which reduces overall Query latency.

firebase-firestore/api.txt

@@ -153,6 +153,7 @@ package com.google.firebase.firestore {
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> runBatch(@NonNull com.google.firebase.firestore.WriteBatch.Function);
     method @NonNull public <TResult> com.google.android.gms.tasks.Task<TResult> runTransaction(@NonNull com.google.firebase.firestore.Transaction.Function<TResult>);
     method public void setFirestoreSettings(@NonNull com.google.firebase.firestore.FirebaseFirestoreSettings);
+    method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> setIndexConfiguration(@NonNull String);
     method public static void setLoggingEnabled(boolean);
     method @NonNull public com.google.android.gms.tasks.Task<java.lang.Void> terminate();
     method public void useEmulator(@NonNull String, int);

firebase-firestore/firebase-firestore.gradle

@@ -123,6 +123,7 @@ googleJavaFormat {
 }
 
 dependencies {
+    implementation project(':firebase-annotations')
     implementation project(':firebase-common')
     implementation project(':protolite-well-known-types')
     implementation project(':firebase-database-collection')

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

@@ -27,6 +27,7 @@
 import com.google.android.gms.tasks.TaskCompletionSource;
 import com.google.android.gms.tasks.Tasks;
 import com.google.firebase.FirebaseApp;
+import com.google.firebase.annotations.PreviewApi;
 import com.google.firebase.appcheck.interop.InternalAppCheckTokenProvider;
 import com.google.firebase.auth.internal.InternalAuthProvider;
 import com.google.firebase.emulators.EmulatedServiceSettings;
@@ -304,8 +305,9 @@ public FirebaseApp getApp() {
    * @return A task that resolves once all indices are successfully configured.
    * @throws IllegalArgumentException if the JSON format is invalid
    */
-  @VisibleForTesting
-  Task<Void> setIndexConfiguration(String json) {
+  @PreviewApi
+  @NonNull
+  public Task<Void> setIndexConfiguration(@NonNull String json) {
     ensureClientConfigured();
     Preconditions.checkState(
         settings.isPersistenceEnabled(), "Cannot enable indexes when persistence is disabled");

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

@@ -17,7 +17,9 @@
 import static com.google.firebase.firestore.model.Values.max;
 import static com.google.firebase.firestore.model.Values.min;
 
+import android.util.Pair;
 import androidx.annotation.Nullable;
+import com.google.firebase.firestore.core.OrderBy.Direction;
 import com.google.firebase.firestore.model.DocumentKey;
 import com.google.firebase.firestore.model.FieldIndex;
 import com.google.firebase.firestore.model.FieldPath;
@@ -185,65 +187,18 @@ public Bound getLowerBound(FieldIndex fieldIndex) {
 
     // For each segment, retrieve a lower bound if there is a suitable filter or startAt.
     for (FieldIndex.Segment segment : fieldIndex.getDirectionalSegments()) {
-      Value segmentValue = null;
-      boolean segmentInclusive = true;
+      Pair<Value, Boolean> segmentBound =
+          segment.getKind().equals(FieldIndex.Segment.Kind.ASCENDING)
+              ? getAscendingBound(segment, startAt)
+              : getDescendingBound(segment, startAt);
 
-      // Process all filters to find a value for the current field segment
-      for (FieldFilter fieldFilter : getFieldFiltersForPath(segment.getFieldPath())) {
-        Value filterValue = null;
-        boolean filterInclusive = true;
-
-        switch (fieldFilter.getOperator()) {
-          case LESS_THAN:
-          case LESS_THAN_OR_EQUAL:
-            filterValue = Values.getLowerBound(fieldFilter.getValue().getValueTypeCase());
-            break;
-          case EQUAL:
-          case IN:
-          case GREATER_THAN_OR_EQUAL:
-            filterValue = fieldFilter.getValue();
-            break;
-          case GREATER_THAN:
-            filterValue = fieldFilter.getValue();
-            filterInclusive = false;
-            break;
-          case NOT_EQUAL:
-          case NOT_IN:
-            filterValue = Values.MIN_VALUE;
-            break;
-          default:
-            // Remaining filters cannot be used as lower bounds.
-        }
-
-        if (max(segmentValue, filterValue) == filterValue) {
-          segmentValue = filterValue;
-          segmentInclusive = filterInclusive;
-        }
-      }
-
-      // If there is a startAt bound, compare the values against the existing boundary to see
-      // if we can narrow the scope.
-      if (startAt != null) {
-        for (int i = 0; i < orderBys.size(); ++i) {
-          OrderBy orderBy = this.orderBys.get(i);
-          if (orderBy.getField().equals(segment.getFieldPath())) {
-            Value cursorValue = startAt.getPosition().get(i);
-            if (max(segmentValue, cursorValue) == cursorValue) {
-              segmentValue = cursorValue;
-              segmentInclusive = startAt.isInclusive();
-            }
-            break;
-          }
-        }
-      }
-
-      if (segmentValue == null) {
+      if (segmentBound.first == null) {
         // No lower bound exists
         return null;
       }
 
-      values.add(segmentValue);
-      inclusive &= segmentInclusive;
+      values.add(segmentBound.first);
+      inclusive &= segmentBound.second;
     }
 
     return new Bound(values, inclusive);
@@ -259,75 +214,159 @@ public Bound getLowerBound(FieldIndex fieldIndex) {
 
     // For each segment, retrieve an upper bound if there is a suitable filter or endAt.
     for (FieldIndex.Segment segment : fieldIndex.getDirectionalSegments()) {
-      @Nullable Value segmentValue = null;
-      boolean segmentInclusive = true;
+      Pair<Value, Boolean> segmentBound =
+          segment.getKind().equals(FieldIndex.Segment.Kind.ASCENDING)
+              ? getDescendingBound(segment, endAt)
+              : getAscendingBound(segment, endAt);
 
-      // Process all filters to find a value for the current field segment
-      for (FieldFilter fieldFilter : getFieldFiltersForPath(segment.getFieldPath())) {
-        Value filterValue = null;
-        boolean filterInclusive = true;
+      if (segmentBound.first == null) {
+        // No upper bound exists
+        return null;
+      }
 
-        switch (fieldFilter.getOperator()) {
-          case GREATER_THAN_OR_EQUAL:
-          case GREATER_THAN:
-            filterValue = Values.getUpperBound(fieldFilter.getValue().getValueTypeCase());
-            filterInclusive = false;
-            break;
-          case EQUAL:
-          case IN:
-          case LESS_THAN_OR_EQUAL:
-            filterValue = fieldFilter.getValue();
-            break;
-          case LESS_THAN:
-            filterValue = fieldFilter.getValue();
-            filterInclusive = false;
-            break;
-          case NOT_EQUAL:
-          case NOT_IN:
-            filterValue = Values.MAX_VALUE;
-            break;
-          default:
-            // Remaining filters cannot be used as upper bounds.
-        }
+      values.add(segmentBound.first);
+      inclusive &= segmentBound.second;
+    }
 
-        if (min(segmentValue, filterValue) == filterValue) {
-          segmentValue = filterValue;
-          segmentInclusive = filterInclusive;
-        }
+    return new Bound(values, inclusive);
+  }
+
+  /**
+   * Returns the value for an ascending bound of `segment`.
+   *
+   * @param segment The segment to get the value for.
+   * @param bound A bound to restrict the index range.
+   * @return a Pair with a nullable Value and a boolean indicating whether the bound is inclusive
+   */
+  private Pair<Value, Boolean> getAscendingBound(
+      FieldIndex.Segment segment, @Nullable Bound bound) {
+    Value segmentValue = null;
+    boolean segmentInclusive = true;
+
+    // Process all filters to find a value for the current field segment
+    for (FieldFilter fieldFilter : getFieldFiltersForPath(segment.getFieldPath())) {
+      Value filterValue = null;
+      boolean filterInclusive = true;
+
+      switch (fieldFilter.getOperator()) {
+        case LESS_THAN:
+        case LESS_THAN_OR_EQUAL:
+          filterValue = Values.getLowerBound(fieldFilter.getValue().getValueTypeCase());
+          break;
+        case EQUAL:
+        case IN:
+        case GREATER_THAN_OR_EQUAL:
+          filterValue = fieldFilter.getValue();
+          break;
+        case GREATER_THAN:
+          filterValue = fieldFilter.getValue();
+          filterInclusive = false;
+          break;
+        case NOT_EQUAL:
+        case NOT_IN:
+          filterValue = Values.MIN_VALUE;
+          break;
+        default:
+          // Remaining filters cannot be used as bound.
       }
 
-      // If there is an endAt bound, compare the values against the existing boundary to see
-      // if we can narrow the scope.
-      if (endAt != null) {
-        for (int i = 0; i < orderBys.size(); ++i) {
-          OrderBy orderBy = this.orderBys.get(i);
-          if (orderBy.getField().equals(segment.getFieldPath())) {
-            Value cursorValue = endAt.getPosition().get(i);
-            if (min(segmentValue, cursorValue) == cursorValue) {
-              segmentValue = cursorValue;
-              segmentInclusive = endAt.isInclusive();
-            }
-            break;
+      if (max(segmentValue, filterValue) == filterValue) {
+        segmentValue = filterValue;
+        segmentInclusive = filterInclusive;
+      }
+    }
+
+    // If there is an additional bound, compare the values against the existing range to see if we
+    // can narrow the scope.
+    if (bound != null) {
+      for (int i = 0; i < orderBys.size(); ++i) {
+        OrderBy orderBy = this.orderBys.get(i);
+        if (orderBy.getField().equals(segment.getFieldPath())) {
+          Value cursorValue = bound.getPosition().get(i);
+          if (max(segmentValue, cursorValue) == cursorValue) {
+            segmentValue = cursorValue;
+            segmentInclusive = bound.isInclusive();
           }
         }
       }
+    }
 
-      if (segmentValue == null) {
-        // No upper bound exists
-        return null;
+    return new Pair<>(segmentValue, segmentInclusive);
+  }
+
+  /**
+   * Returns the value for a descending bound of `segment`.
+   *
+   * @param segment The segment to get the value for.
+   * @param bound A bound to restrict the index range.
+   * @return a Pair with a nullable Value and a boolean indicating whether the bound is inclusive
+   */
+  private Pair<Value, Boolean> getDescendingBound(
+      FieldIndex.Segment segment, @Nullable Bound bound) {
+    Value segmentValue = null;
+    boolean segmentInclusive = true;
+
+    // Process all filters to find a value for the current field segment
+    for (FieldFilter fieldFilter : getFieldFiltersForPath(segment.getFieldPath())) {
+      Value filterValue = null;
+      boolean filterInclusive = true;
+
+      switch (fieldFilter.getOperator()) {
+        case GREATER_THAN_OR_EQUAL:
+        case GREATER_THAN:
+          filterValue = Values.getUpperBound(fieldFilter.getValue().getValueTypeCase());
+          filterInclusive = false;
+          break;
+        case EQUAL:
+        case IN:
+        case LESS_THAN_OR_EQUAL:
+          filterValue = fieldFilter.getValue();
+          break;
+        case LESS_THAN:
+          filterValue = fieldFilter.getValue();
+          filterInclusive = false;
+          break;
+        case NOT_EQUAL:
+        case NOT_IN:
+          filterValue = Values.MAX_VALUE;
+          break;
+        default:
+          // Remaining filters cannot be used as bound.
       }
 
-      values.add(segmentValue);
-      inclusive &= segmentInclusive;
+      if (min(segmentValue, filterValue) == filterValue) {
+        segmentValue = filterValue;
+        segmentInclusive = filterInclusive;
+      }
     }
 
-    return new Bound(values, inclusive);
+    // If there is an additional bound, compare the values against the existing range to see if we
+    // can narrow the scope.
+    if (bound != null) {
+      for (int i = 0; i < orderBys.size(); ++i) {
+        OrderBy orderBy = this.orderBys.get(i);
+        if (orderBy.getField().equals(segment.getFieldPath())) {
+          Value cursorValue = bound.getPosition().get(i);
+          if (min(segmentValue, cursorValue) == cursorValue) {
+            segmentValue = cursorValue;
+            segmentInclusive = bound.isInclusive();
+          }
+        }
+      }
+    }
+
+    return new Pair<>(segmentValue, segmentInclusive);
   }
 
   public List<OrderBy> getOrderBy() {
     return this.orderBys;
   }
 
+  /** Returns the order of the document key component. */
+  public Direction getKeyOrder() {
+    return this.orderBys.get(this.orderBys.size() - 1).getDirection();
+  }
+
   /** Returns a canonical string representing this target. */
   public String getCanonicalId() {
     if (memoizedCanonicalId != null) {

firebase-firestore/src/main/java/com/google/firebase/firestore/local/IndexManager.java

@@ -24,7 +24,6 @@
 import com.google.firebase.firestore.model.ResourcePath;
 import java.util.Collection;
 import java.util.List;
-import java.util.Set;
 
 /**
  * Represents a set of indexes that are used to execute queries efficiently.
@@ -95,7 +94,7 @@ public interface IndexManager {
    * Returns the documents that match the given target based on the provided index or {@code null}
    * if the query cannot be served from an index.
    */
-  Set<DocumentKey> getDocumentsMatchingTarget(Target target);
+  List<DocumentKey> getDocumentsMatchingTarget(Target target);
 
   /** Returns the next collection group to update. Returns {@code null} if no group exists. */
   @Nullable