Firestore: enable/disablePersistentCacheIndexAutoCreation() added, but hidden for now (firebase#7542)

Author: dconeybe

.changeset/cool-games-care.md

@@ -0,0 +1,6 @@
+---
+'@firebase/firestore': patch
+'firebase': patch
+---
+
+Implemented internal logic to auto-create client-side indexes

packages/firestore/src/api.ts

@@ -202,6 +202,13 @@ export {
   setIndexConfiguration
 } from './api/index_configuration';
 
+export {
+  PersistentCacheIndexManager,
+  getPersistentCacheIndexManager,
+  enablePersistentCacheIndexAutoCreation,
+  disablePersistentCacheIndexAutoCreation
+} from './api/persistent_cache_index_manager';
+
 /**
  * Internal exports
  */

packages/firestore/src/api/persistent_cache_index_manager.ts

@@ -0,0 +1,140 @@
+/**
+ * @license
+ * Copyright 2023 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.
+ */
+
+import {
+  firestoreClientSetPersistentCacheIndexAutoCreationEnabled,
+  FirestoreClient
+} from '../core/firestore_client';
+import { cast } from '../util/input_validation';
+import { logDebug, logWarn } from '../util/log';
+
+import { ensureFirestoreConfigured, Firestore } from './database';
+
+/**
+ * A `PersistentCacheIndexManager` which you can config persistent cache indexes
+ * used for local query execution.
+ *
+ * To use, call `getPersistentCacheIndexManager()` to get an instance.
+ *
+ * TODO(CSI) Remove @internal to make the API publicly available.
+ * @internal
+ */
+export class PersistentCacheIndexManager {
+  readonly type: 'PersistentCacheIndexManager' = 'PersistentCacheIndexManager';
+
+  /** @hideconstructor */
+  constructor(readonly _client: FirestoreClient) {}
+}
+
+/**
+ * Returns the PersistentCache Index Manager used by the given `Firestore`
+ * object.
+ *
+ * @return The `PersistentCacheIndexManager` instance, or `null` if local
+ * persistent storage is not in use.
+ *
+ * TODO(CSI) Remove @internal to make the API publicly available.
+ * @internal
+ */
+export function getPersistentCacheIndexManager(
+  firestore: Firestore
+): PersistentCacheIndexManager | null {
+  firestore = cast(firestore, Firestore);
+
+  const cachedInstance = persistentCacheIndexManagerByFirestore.get(firestore);
+  if (cachedInstance) {
+    return cachedInstance;
+  }
+
+  const client = ensureFirestoreConfigured(firestore);
+  if (client._uninitializedComponentsProvider?._offlineKind !== 'persistent') {
+    return null;
+  }
+
+  const instance = new PersistentCacheIndexManager(client);
+  persistentCacheIndexManagerByFirestore.set(firestore, instance);
+  return instance;
+}
+
+/**
+ * Enables SDK to create persistent cache indexes automatically for local query
+ * execution when SDK believes cache indexes can help improves performance.
+ *
+ * This feature is disabled by default.
+ *
+ * TODO(CSI) Remove @internal to make the API publicly available.
+ * @internal
+ */
+export function enablePersistentCacheIndexAutoCreation(
+  indexManager: PersistentCacheIndexManager
+): void {
+  setPersistentCacheIndexAutoCreationEnabled(indexManager, true);
+}
+
+/**
+ * Stops creating persistent cache indexes automatically for local query
+ * execution. The indexes which have been created by calling
+ * `enablePersistentCacheIndexAutoCreation()` still take effect.
+ *
+ * TODO(CSI) Remove @internal to make the API publicly available.
+ * @internal
+ */
+export function disablePersistentCacheIndexAutoCreation(
+  indexManager: PersistentCacheIndexManager
+): void {
+  setPersistentCacheIndexAutoCreationEnabled(indexManager, false);
+}
+
+function setPersistentCacheIndexAutoCreationEnabled(
+  indexManager: PersistentCacheIndexManager,
+  isEnabled: boolean
+): void {
+  indexManager._client.verifyNotTerminated();
+
+  const promise = firestoreClientSetPersistentCacheIndexAutoCreationEnabled(
+    indexManager._client,
+    isEnabled
+  );
+
+  promise
+    .then(_ =>
+      logDebug(
+        `setting persistent cache index auto creation ` +
+          `isEnabled=${isEnabled} succeeded`
+      )
+    )
+    .catch(error =>
+      logWarn(
+        `setting persistent cache index auto creation ` +
+          `isEnabled=${isEnabled} failed`,
+        error
+      )
+    );
+}
+
+/**
+ * Maps `Firestore` instances to their corresponding
+ * `PersistentCacheIndexManager` instances.
+ *
+ * Use a `WeakMap` so that the mapping will be automatically dropped when the
+ * `Firestore` instance is garbage collected. This emulates a private member
+ * as described in https://goo.gle/454yvug.
+ */
+const persistentCacheIndexManagerByFirestore = new WeakMap<
+  Firestore,
+  PersistentCacheIndexManager
+>();

packages/firestore/src/core/firestore_client.ts

@@ -29,7 +29,8 @@ import {
   localStoreExecuteQuery,
   localStoreGetNamedQuery,
   localStoreHandleUserChange,
-  localStoreReadDocument
+  localStoreReadDocument,
+  localStoreSetIndexAutoCreationEnabled
 } from '../local/local_store_impl';
 import { Persistence } from '../local/persistence';
 import { Document } from '../model/document';
@@ -828,3 +829,15 @@ export function firestoreClientSetIndexConfiguration(
     );
   });
 }
+
+export function firestoreClientSetPersistentCacheIndexAutoCreationEnabled(
+  client: FirestoreClient,
+  isEnabled: boolean
+): Promise<void> {
+  return client.asyncQueue.enqueue(async () => {
+    return localStoreSetIndexAutoCreationEnabled(
+      await getLocalStore(client),
+      isEnabled
+    );
+  });
+}

packages/firestore/src/local/index_manager.ts

@@ -41,6 +41,19 @@ export const enum IndexType {
   FULL
 }
 
+export function displayNameForIndexType(indexType: IndexType): string {
+  switch (indexType) {
+    case IndexType.NONE:
+      return 'NONE';
+    case IndexType.PARTIAL:
+      return 'PARTIAL';
+    case IndexType.FULL:
+      return 'FULL';
+    default:
+      return `[unknown IndexType: ${indexType}]`;
+  }
+}
+
 /**
  * Represents a set of indexes that are used to execute queries efficiently.
  *
@@ -92,6 +105,12 @@ export interface IndexManager {
     index: FieldIndex
   ): PersistencePromise<void>;
 
+  /** Creates a full matched field index which serves the given target. */
+  createTargetIndexes(
+    transaction: PersistenceTransaction,
+    target: Target
+  ): PersistencePromise<void>;
+
   /**
    * Returns a list of field indexes that correspond to the specified collection
    * group.

packages/firestore/src/local/indexeddb_index_manager.ts

@@ -252,6 +252,26 @@ export class IndexedDbIndexManager implements IndexManager {
       );
   }
 
+  createTargetIndexes(
+    transaction: PersistenceTransaction,
+    target: Target
+  ): PersistencePromise<void> {
+    return PersistencePromise.forEach(
+      this.getSubTargets(target),
+      (subTarget: Target) => {
+        return this.getIndexType(transaction, subTarget).next(type => {
+          if (type === IndexType.NONE || type === IndexType.PARTIAL) {
+            const targetIndexMatcher = new TargetIndexMatcher(subTarget);
+            return this.addFieldIndex(
+              transaction,
+              targetIndexMatcher.buildTargetIndex()
+            );
+          }
+        });
+      }
+    );
+  }
+
   getDocumentsMatchingTarget(
     transaction: PersistenceTransaction,
     target: Target

packages/firestore/src/local/indexeddb_remote_document_cache.ts

@@ -55,6 +55,7 @@ import {
 } from './local_serializer';
 import { PersistencePromise } from './persistence_promise';
 import { PersistenceTransaction } from './persistence_transaction';
+import { QueryContext } from './query_context';
 import { RemoteDocumentCache } from './remote_document_cache';
 import { RemoteDocumentChangeBuffer } from './remote_document_change_buffer';
 import { SimpleDbStore } from './simple_db';
@@ -279,7 +280,8 @@ class IndexedDbRemoteDocumentCacheImpl implements IndexedDbRemoteDocumentCache {
     transaction: PersistenceTransaction,
     query: Query,
     offset: IndexOffset,
-    mutatedDocs: OverlayMap
+    mutatedDocs: OverlayMap,
+    context?: QueryContext
   ): PersistencePromise<MutableDocumentMap> {
     const collection = query.path;
     const startKey = [
@@ -300,6 +302,7 @@ class IndexedDbRemoteDocumentCacheImpl implements IndexedDbRemoteDocumentCache {
     return remoteDocumentsStore(transaction)
       .loadAll(IDBKeyRange.bound(startKey, endKey, true))
       .next(dbRemoteDocs => {
+        context?.incrementDocumentReadCount(dbRemoteDocs.length);
         let results = mutableDocumentMap();
         for (const dbRemoteDoc of dbRemoteDocs) {
           const document = this.maybeDecodeDocument(

packages/firestore/src/local/local_documents_view.ts

@@ -60,6 +60,7 @@ import { MutationQueue } from './mutation_queue';
 import { OverlayedDocument } from './overlayed_document';
 import { PersistencePromise } from './persistence_promise';
 import { PersistenceTransaction } from './persistence_transaction';
+import { QueryContext } from './query_context';
 import { RemoteDocumentCache } from './remote_document_cache';
 
 /**
@@ -355,25 +356,30 @@ export class LocalDocumentsView {
    * @param transaction - The persistence transaction.
    * @param query - The query to match documents against.
    * @param offset - Read time and key to start scanning by (exclusive).
+   * @param context - A optional tracker to keep a record of important details
+   *   during database local query execution.
    */
   getDocumentsMatchingQuery(
     transaction: PersistenceTransaction,
     query: Query,
-    offset: IndexOffset
+    offset: IndexOffset,
+    context?: QueryContext
   ): PersistencePromise<DocumentMap> {
     if (isDocumentQuery(query)) {
       return this.getDocumentsMatchingDocumentQuery(transaction, query.path);
     } else if (isCollectionGroupQuery(query)) {
       return this.getDocumentsMatchingCollectionGroupQuery(
         transaction,
         query,
-        offset
+        offset,
+        context
       );
     } else {
       return this.getDocumentsMatchingCollectionQuery(
         transaction,
         query,
-        offset
+        offset,
+        context
       );
     }
   }
@@ -472,7 +478,8 @@ export class LocalDocumentsView {
   private getDocumentsMatchingCollectionGroupQuery(
     transaction: PersistenceTransaction,
     query: Query,
-    offset: IndexOffset
+    offset: IndexOffset,
+    context?: QueryContext
   ): PersistencePromise<DocumentMap> {
     debugAssert(
       query.path.isEmpty(),
@@ -493,7 +500,8 @@ export class LocalDocumentsView {
           return this.getDocumentsMatchingCollectionQuery(
             transaction,
             collectionQuery,
-            offset
+            offset,
+            context
           ).next(r => {
             r.forEach((key, doc) => {
               results = results.insert(key, doc);
@@ -506,7 +514,8 @@ export class LocalDocumentsView {
   private getDocumentsMatchingCollectionQuery(
     transaction: PersistenceTransaction,
     query: Query,
-    offset: IndexOffset
+    offset: IndexOffset,
+    context?: QueryContext
   ): PersistencePromise<DocumentMap> {
     // Query the remote documents and overlay mutations.
     let overlays: OverlayMap;
@@ -518,7 +527,8 @@ export class LocalDocumentsView {
           transaction,
           query,
           offset,
-          overlays
+          overlays,
+          context
         );
       })
       .next(remoteDocuments => {