From ddc4b42fd041df747e27a311aa853b084ef50435 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Wed, 30 Aug 2023 14:50:43 -0400 Subject: [PATCH 01/11] persistent_cache_index_manager.ts: remove @internal annotations --- .../src/api/persistent_cache_index_manager.ts | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/packages/firestore/src/api/persistent_cache_index_manager.ts b/packages/firestore/src/api/persistent_cache_index_manager.ts index 4a6d11c2b3a..f125406ee5b 100644 --- a/packages/firestore/src/api/persistent_cache_index_manager.ts +++ b/packages/firestore/src/api/persistent_cache_index_manager.ts @@ -30,9 +30,6 @@ import { ensureFirestoreConfigured, Firestore } from './database'; * 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'; @@ -47,9 +44,6 @@ export class PersistentCacheIndexManager { * * @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 @@ -76,9 +70,6 @@ export function getPersistentCacheIndexManager( * 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 @@ -90,9 +81,6 @@ export function enablePersistentCacheIndexAutoCreation( * 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 @@ -105,9 +93,6 @@ export function disablePersistentCacheIndexAutoCreation( * * Please note this function will also deletes indexes generated by * `setIndexConfiguration()`, which is deprecated. - * - * TODO(CSI) Remove @internal to make the API publicly available. - * @internal */ export function deleteAllPersistentCacheIndexes( indexManager: PersistentCacheIndexManager From 3f3c3eba68499c01b3c76c47563e4776b312a2d3 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Wed, 30 Aug 2023 14:54:38 -0400 Subject: [PATCH 02/11] yarn changeset --- .changeset/hip-cougars-float.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/hip-cougars-float.md diff --git a/.changeset/hip-cougars-float.md b/.changeset/hip-cougars-float.md new file mode 100644 index 00000000000..6021fe28578 --- /dev/null +++ b/.changeset/hip-cougars-float.md @@ -0,0 +1,5 @@ +--- +'@firebase/firestore': minor +--- + +Add `enablePersistentCacheIndexAutoCreation()` function to enable automatic creation of local cache query indexes, which can improve performance of local query execution. From 1b6c95b26250d118023665298cc6a8f7ef461217 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Wed, 30 Aug 2023 15:00:11 -0400 Subject: [PATCH 03/11] index_configuration.ts: mark manual index creation apis as "deprecated" --- .../firestore/src/api/index_configuration.ts | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/packages/firestore/src/api/index_configuration.ts b/packages/firestore/src/api/index_configuration.ts index 94754636176..7185a85ab99 100644 --- a/packages/firestore/src/api/index_configuration.ts +++ b/packages/firestore/src/api/index_configuration.ts @@ -36,6 +36,11 @@ export { /** * A single field element in an index configuration. + * + * @deprecated Instead of creating cache indexes manually, consider using + * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * create cache indexes for queries running locally. + * * @beta */ export interface IndexField { @@ -61,6 +66,11 @@ export interface IndexField { /** * The SDK definition of a Firestore index. + * + * @deprecated Instead of creating cache indexes manually, consider using + * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * create cache indexes for queries running locally. + * * @beta */ export interface Index { @@ -77,6 +87,11 @@ export interface Index { * * See {@link https://firebase.google.com/docs/reference/firestore/indexes/#json_format | JSON Format} * for a description of the format of the index definition. + * + * @deprecated Instead of creating cache indexes manually, consider using + * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * create cache indexes for queries running locally. + * * @beta */ export interface IndexConfiguration { @@ -104,6 +119,11 @@ export interface IndexConfiguration { * @throws FirestoreError if the JSON format is invalid. * @returns A `Promise` that resolves once all indices are successfully * configured. + * + * @deprecated Instead of creating cache indexes manually, consider using + * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * create cache indexes for queries running locally. + * * @beta */ export function setIndexConfiguration( @@ -135,6 +155,11 @@ export function setIndexConfiguration( * @throws FirestoreError if the JSON format is invalid. * @returns A `Promise` that resolves once all indices are successfully * configured. + * + * @deprecated Instead of creating cache indexes manually, consider using + * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * create cache indexes for queries running locally. + * * @beta */ export function setIndexConfiguration( From b75239fc588ba2923fff71f4e5ef3e459b1ad6b9 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Wed, 30 Aug 2023 15:06:29 -0400 Subject: [PATCH 04/11] persistent_cache_index_manager.ts: add docs for PersistentCacheIndexManager.type --- packages/firestore/src/api/persistent_cache_index_manager.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/packages/firestore/src/api/persistent_cache_index_manager.ts b/packages/firestore/src/api/persistent_cache_index_manager.ts index f125406ee5b..f837276b290 100644 --- a/packages/firestore/src/api/persistent_cache_index_manager.ts +++ b/packages/firestore/src/api/persistent_cache_index_manager.ts @@ -32,6 +32,7 @@ import { ensureFirestoreConfigured, Firestore } from './database'; * To use, call `getPersistentCacheIndexManager()` to get an instance. */ export class PersistentCacheIndexManager { + /** A type string to uniquely identify instances of this class. */ readonly type: 'PersistentCacheIndexManager' = 'PersistentCacheIndexManager'; /** @hideconstructor */ From e1b22218bd46041f2a2999959a1439ad925c48b9 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Wed, 30 Aug 2023 15:09:39 -0400 Subject: [PATCH 05/11] firestore.api.md updated --- common/api-review/firestore.api.md | 27 ++++++++++++++++++++++----- 1 file changed, 22 insertions(+), 5 deletions(-) diff --git a/common/api-review/firestore.api.md b/common/api-review/firestore.api.md index ada53f25a59..6086a0975f7 100644 --- a/common/api-review/firestore.api.md +++ b/common/api-review/firestore.api.md @@ -101,6 +101,9 @@ export function connectFirestoreEmulator(firestore: Firestore, host: string, por mockUserToken?: EmulatorMockTokenOptions | string; }): void; +// @public +export function deleteAllPersistentCacheIndexes(indexManager: PersistentCacheIndexManager): void; + // @public export function deleteDoc(reference: DocumentReference): Promise; @@ -110,6 +113,9 @@ export function deleteField(): FieldValue; // @public export function disableNetwork(firestore: Firestore): Promise; +// @public +export function disablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void; + // @public export function doc(firestore: Firestore, path: string, ...pathSegments: string[]): DocumentReference; @@ -172,6 +178,9 @@ export function enableMultiTabIndexedDbPersistence(firestore: Firestore): Promis // @public export function enableNetwork(firestore: Firestore): Promise; +// @public +export function enablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void; + // @public export function endAt(snapshot: DocumentSnapshot): QueryEndAtConstraint; @@ -286,10 +295,13 @@ export function getFirestore(): Firestore; // @beta export function getFirestore(app: FirebaseApp, databaseId: string): Firestore; +// @public +export function getPersistentCacheIndexManager(firestore: Firestore): PersistentCacheIndexManager | null; + // @public export function increment(n: number): FieldValue; -// @beta +// @beta @deprecated export interface Index { // (undocumented) [key: string]: unknown; @@ -297,14 +309,14 @@ export interface Index { readonly fields?: IndexField[]; } -// @beta +// @beta @deprecated export interface IndexConfiguration { // (undocumented) [key: string]: unknown; readonly indexes?: Index[]; } -// @beta +// @beta @deprecated export interface IndexField { // (undocumented) [key: string]: unknown; @@ -457,6 +469,11 @@ export interface PersistenceSettings { forceOwnership?: boolean; } +// @public +export class PersistentCacheIndexManager { + readonly type: 'PersistentCacheIndexManager'; +} + // @public export interface PersistentCacheSettings { cacheSizeBytes?: number; @@ -596,10 +613,10 @@ export function setDoc(reference // @public export function setDoc(reference: DocumentReference, data: PartialWithFieldValue, options: SetOptions): Promise; -// @beta +// @beta @deprecated export function setIndexConfiguration(firestore: Firestore, configuration: IndexConfiguration): Promise; -// @beta +// @beta @deprecated export function setIndexConfiguration(firestore: Firestore, json: string): Promise; // @public From fd9572a405a45f1135c082bc230b777fd22f319d Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Wed, 30 Aug 2023 15:14:41 -0400 Subject: [PATCH 06/11] yarn docgen devsite --- docs-devsite/firestore_.index.md | 5 + docs-devsite/firestore_.indexconfiguration.md | 5 + docs-devsite/firestore_.indexfield.md | 5 + docs-devsite/firestore_.md | 102 ++++++++++++++++++ .../firestore_.persistentcacheindexmanager.md | 37 +++++++ 5 files changed, 154 insertions(+) create mode 100644 docs-devsite/firestore_.persistentcacheindexmanager.md diff --git a/docs-devsite/firestore_.index.md b/docs-devsite/firestore_.index.md index 3ea216d6798..62cffe39092 100644 --- a/docs-devsite/firestore_.index.md +++ b/docs-devsite/firestore_.index.md @@ -13,6 +13,11 @@ https://github.com/firebase/firebase-js-sdk > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > +> Warning: This API is now obsolete. +> +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> + The SDK definition of a Firestore index. Signature: diff --git a/docs-devsite/firestore_.indexconfiguration.md b/docs-devsite/firestore_.indexconfiguration.md index 8a0592e7ed6..d5a58b5733a 100644 --- a/docs-devsite/firestore_.indexconfiguration.md +++ b/docs-devsite/firestore_.indexconfiguration.md @@ -13,6 +13,11 @@ https://github.com/firebase/firebase-js-sdk > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > +> Warning: This API is now obsolete. +> +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> + A list of Firestore indexes to speed up local query execution. See [JSON Format](https://firebase.google.com/docs/reference/firestore/indexes/#json_format) for a description of the format of the index definition. diff --git a/docs-devsite/firestore_.indexfield.md b/docs-devsite/firestore_.indexfield.md index 278e2f63ce8..98867832708 100644 --- a/docs-devsite/firestore_.indexfield.md +++ b/docs-devsite/firestore_.indexfield.md @@ -13,6 +13,11 @@ https://github.com/firebase/firebase-js-sdk > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > +> Warning: This API is now obsolete. +> +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> + A single field element in an index configuration. Signature: diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md index 0d1398c8f70..e3cf31d42ff 100644 --- a/docs-devsite/firestore_.md +++ b/docs-devsite/firestore_.md @@ -29,6 +29,7 @@ https://github.com/firebase/firebase-js-sdk | [enableIndexedDbPersistence(firestore, persistenceSettings)](./firestore_.md#enableindexeddbpersistence) | Attempts to enable persistent storage, if possible.Must be called before any other functions (other than [initializeFirestore()](./firestore_.md#initializefirestore), [getFirestore()](./firestore_.md#getfirestore) or [clearIndexedDbPersistence()](./firestore_.md#clearindexeddbpersistence).If this fails, enableIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab. \* unimplemented: The browser is incompatible with the offline persistence implementation.Persistence cannot be used in a Node.js environment. | | [enableMultiTabIndexedDbPersistence(firestore)](./firestore_.md#enablemultitabindexeddbpersistence) | Attempts to enable multi-tab persistent storage, if possible. If enabled across all tabs, all operations share access to local persistence, including shared execution of queries and latency-compensated local document updates across all connected instances.If this fails, enableMultiTabIndexedDbPersistence() will reject the promise it returns. Note that even after this failure, the [Firestore](./firestore_.firestore.md#firestore_class) instance will remain usable, however offline persistence will be disabled.There are several reasons why this can fail, which can be identified by the code on the error.\* failed-precondition: The app is already open in another browser tab and multi-tab is not enabled. \* unimplemented: The browser is incompatible with the offline persistence implementation. | | [enableNetwork(firestore)](./firestore_.md#enablenetwork) | Re-enables use of the network for this [Firestore](./firestore_.firestore.md#firestore_class) instance after a prior call to [disableNetwork()](./firestore_.md#disablenetwork). | +| [getPersistentCacheIndexManager(firestore)](./firestore_.md#getpersistentcacheindexmanager) | Returns the PersistentCache Index Manager used by the given Firestore object. The PersistentCacheIndexManager instance, or null if local persistent storage is not in use. | | [loadBundle(firestore, bundleData)](./firestore_.md#loadbundle) | Loads a Firestore bundle into the local cache. | | [namedQuery(firestore, name)](./firestore_.md#namedquery) | Reads a Firestore [Query](./firestore_.query.md#query_class) from local cache, identified by the given name.The named queries are packaged into bundles on the server side (along with resulting documents), and loaded to local cache using loadBundle. Once in local cache, use this method to extract a [Query](./firestore_.query.md#query_class) by name. | | [onSnapshotsInSync(firestore, observer)](./firestore_.md#onsnapshotsinsync) | Attaches a listener for a snapshots-in-sync event. The snapshots-in-sync event indicates that all listeners affected by a given change have fired, even if a single server-generated change affects multiple listeners.NOTE: The snapshots-in-sync event only indicates that listeners are in sync with each other, but does not relate to whether those snapshots are in sync with the server. Use SnapshotMetadata in the individual listeners to determine if a snapshot is from the cache or the server. | @@ -59,6 +60,10 @@ https://github.com/firebase/firebase-js-sdk | [endBefore(fieldValues)](./firestore_.md#endbefore) | Creates a [QueryEndAtConstraint](./firestore_.queryendatconstraint.md#queryendatconstraint_class) that modifies the result set to end before the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | | [startAfter(fieldValues)](./firestore_.md#startafter) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start after the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | | [startAt(fieldValues)](./firestore_.md#startat) | Creates a [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) that modifies the result set to start at the provided fields relative to the order of the query. The order of the field values must match the order of the order by clauses of the query. | +| function(indexManager...) | +| [deleteAllPersistentCacheIndexes(indexManager)](./firestore_.md#deleteallpersistentcacheindexes) | Removes all persistent cache indexes.Please note this function will also deletes indexes generated by setIndexConfiguration(), which is deprecated. | +| [disablePersistentCacheIndexAutoCreation(indexManager)](./firestore_.md#disablepersistentcacheindexautocreation) | Stops creating persistent cache indexes automatically for local query execution. The indexes which have been created by calling enablePersistentCacheIndexAutoCreation() still take effect. | +| [enablePersistentCacheIndexAutoCreation(indexManager)](./firestore_.md#enablepersistentcacheindexautocreation) | 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. | | function(left...) | | [aggregateQuerySnapshotEqual(left, right)](./firestore_.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | | [queryEqual(left, right)](./firestore_.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | @@ -130,6 +135,7 @@ https://github.com/firebase/firebase-js-sdk | [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | | [GeoPoint](./firestore_.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | | [LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) | Represents the task of loading a Firestore bundle. It provides progress of bundle loading, as well as task completion and error events.The API is compatible with Promise<LoadBundleTaskProgress>. | +| [PersistentCacheIndexManager](./firestore_.persistentcacheindexmanager.md#persistentcacheindexmanager_class) | A PersistentCacheIndexManager which you can config persistent cache indexes used for local query execution.To use, call getPersistentCacheIndexManager() to get an instance. | | [Query](./firestore_.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | | [QueryCompositeFilterConstraint](./firestore_.querycompositefilterconstraint.md#querycompositefilterconstraint_class) | A QueryCompositeFilterConstraint is used to narrow the set of documents returned by a Firestore query by performing the logical OR or AND of multiple [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class)s or [QueryCompositeFilterConstraint](./firestore_.querycompositefilterconstraint.md#querycompositefilterconstraint_class)s. QueryCompositeFilterConstraints are created by invoking [or()](./firestore_.md#or) or [and()](./firestore_.md#and) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryCompositeFilterConstraint. | | [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), [endBefore()](./firestore_.md#endbefore), [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | @@ -526,6 +532,28 @@ Promise<void> A `Promise` that is resolved once the network has been enabled. +## getPersistentCacheIndexManager() + +Returns the PersistentCache Index Manager used by the given `Firestore` object. + + The `PersistentCacheIndexManager` instance, or `null` if local persistent storage is not in use. + +Signature: + +```typescript +export declare function getPersistentCacheIndexManager(firestore: Firestore): PersistentCacheIndexManager | null; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| firestore | [Firestore](./firestore_.firestore.md#firestore_class) | | + +Returns: + +[PersistentCacheIndexManager](./firestore_.persistentcacheindexmanager.md#persistentcacheindexmanager_class) \| null + ## loadBundle() Loads a Firestore bundle into the local cache. @@ -659,6 +687,11 @@ If the transaction completed successfully or was explicitly aborted (the `update > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > +> Warning: This API is now obsolete. +> +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> + Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. @@ -693,6 +726,11 @@ FirestoreError if the JSON format is invalid. > This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment. > +> Warning: This API is now obsolete. +> +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> + Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. The index entries themselves are created asynchronously. You can continue to use queries that require indexing even if the indices are not yet available. Query execution will automatically start using the index once the index entries have been written. @@ -1090,6 +1128,70 @@ export declare function startAt(...fieldValues: unknown[]): QueryStartAtConstrai A [QueryStartAtConstraint](./firestore_.querystartatconstraint.md#querystartatconstraint_class) to pass to `query()`. +## deleteAllPersistentCacheIndexes() + +Removes all persistent cache indexes. + +Please note this function will also deletes indexes generated by `setIndexConfiguration()`, which is deprecated. + +Signature: + +```typescript +export declare function deleteAllPersistentCacheIndexes(indexManager: PersistentCacheIndexManager): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| indexManager | [PersistentCacheIndexManager](./firestore_.persistentcacheindexmanager.md#persistentcacheindexmanager_class) | | + +Returns: + +void + +## disablePersistentCacheIndexAutoCreation() + +Stops creating persistent cache indexes automatically for local query execution. The indexes which have been created by calling `enablePersistentCacheIndexAutoCreation()` still take effect. + +Signature: + +```typescript +export declare function disablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| indexManager | [PersistentCacheIndexManager](./firestore_.persistentcacheindexmanager.md#persistentcacheindexmanager_class) | | + +Returns: + +void + +## enablePersistentCacheIndexAutoCreation() + +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. + +Signature: + +```typescript +export declare function enablePersistentCacheIndexAutoCreation(indexManager: PersistentCacheIndexManager): void; +``` + +### Parameters + +| Parameter | Type | Description | +| --- | --- | --- | +| indexManager | [PersistentCacheIndexManager](./firestore_.persistentcacheindexmanager.md#persistentcacheindexmanager_class) | | + +Returns: + +void + ## aggregateQuerySnapshotEqual() Compares two `AggregateQuerySnapshot` instances for equality. diff --git a/docs-devsite/firestore_.persistentcacheindexmanager.md b/docs-devsite/firestore_.persistentcacheindexmanager.md new file mode 100644 index 00000000000..34029877376 --- /dev/null +++ b/docs-devsite/firestore_.persistentcacheindexmanager.md @@ -0,0 +1,37 @@ +Project: /docs/reference/js/_project.yaml +Book: /docs/reference/_book.yaml +page_type: reference + +{% comment %} +DO NOT EDIT THIS FILE! +This is generated by the JS SDK team, and any local changes will be +overwritten. Changes should be made in the source code at +https://github.com/firebase/firebase-js-sdk +{% endcomment %} + +# PersistentCacheIndexManager class +A `PersistentCacheIndexManager` which you can config persistent cache indexes used for local query execution. + +To use, call `getPersistentCacheIndexManager()` to get an instance. + +Signature: + +```typescript +export declare class PersistentCacheIndexManager +``` + +## Properties + +| Property | Modifiers | Type | Description | +| --- | --- | --- | --- | +| [type](./firestore_.persistentcacheindexmanager.md#persistentcacheindexmanagertype) | | 'PersistentCacheIndexManager' | A type string to uniquely identify instances of this class. | + +## PersistentCacheIndexManager.type + +A type string to uniquely identify instances of this class. + +Signature: + +```typescript +readonly type: 'PersistentCacheIndexManager'; +``` From aca631f68c676e77e7d21bf3386676522c4168d3 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Wed, 30 Aug 2023 15:39:36 -0400 Subject: [PATCH 07/11] add firebase to changeset --- .changeset/hip-cougars-float.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.changeset/hip-cougars-float.md b/.changeset/hip-cougars-float.md index 6021fe28578..bf77817994b 100644 --- a/.changeset/hip-cougars-float.md +++ b/.changeset/hip-cougars-float.md @@ -1,5 +1,6 @@ --- '@firebase/firestore': minor +'firebase': minor --- Add `enablePersistentCacheIndexAutoCreation()` function to enable automatic creation of local cache query indexes, which can improve performance of local query execution. From a9371f9fe55e4a698a5769d5106e85a871a576d1 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 1 Sep 2023 16:06:40 -0400 Subject: [PATCH 08/11] 'to let SDK decide' -> 'to let the SDK decide' --- packages/firestore/src/api/index_configuration.ts | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/firestore/src/api/index_configuration.ts b/packages/firestore/src/api/index_configuration.ts index 7185a85ab99..d482738280b 100644 --- a/packages/firestore/src/api/index_configuration.ts +++ b/packages/firestore/src/api/index_configuration.ts @@ -38,7 +38,7 @@ export { * A single field element in an index configuration. * * @deprecated Instead of creating cache indexes manually, consider using - * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to * create cache indexes for queries running locally. * * @beta @@ -68,7 +68,7 @@ export interface IndexField { * The SDK definition of a Firestore index. * * @deprecated Instead of creating cache indexes manually, consider using - * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to * create cache indexes for queries running locally. * * @beta @@ -89,7 +89,7 @@ export interface Index { * for a description of the format of the index definition. * * @deprecated Instead of creating cache indexes manually, consider using - * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to * create cache indexes for queries running locally. * * @beta @@ -121,7 +121,7 @@ export interface IndexConfiguration { * configured. * * @deprecated Instead of creating cache indexes manually, consider using - * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to * create cache indexes for queries running locally. * * @beta @@ -157,7 +157,7 @@ export function setIndexConfiguration( * configured. * * @deprecated Instead of creating cache indexes manually, consider using - * `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to + * `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to * create cache indexes for queries running locally. * * @beta From 5473c4a8d143ae7ce7c7bb6ed2ea431b37ba5090 Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 1 Sep 2023 16:09:34 -0400 Subject: [PATCH 09/11] 'Enables SDK to create' -> 'Enables the SDK to create' and 'when SDK believes' -> 'when the SDK believes' and 'can help improves performance' -> 'can help improve performance' --- packages/firestore/src/api/persistent_cache_index_manager.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/firestore/src/api/persistent_cache_index_manager.ts b/packages/firestore/src/api/persistent_cache_index_manager.ts index f837276b290..48b9c6e8d83 100644 --- a/packages/firestore/src/api/persistent_cache_index_manager.ts +++ b/packages/firestore/src/api/persistent_cache_index_manager.ts @@ -67,8 +67,9 @@ export function getPersistentCacheIndexManager( } /** - * Enables SDK to create persistent cache indexes automatically for local query - * execution when SDK believes cache indexes can help improves performance. + * Enables the SDK to create persistent cache indexes automatically for local + * query execution when the SDK believes cache indexes can help improve + * performance. * * This feature is disabled by default. */ From 8f62cd8e5736283dff0e3995d2bd96eb27fd505d Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Fri, 1 Sep 2023 16:12:38 -0400 Subject: [PATCH 10/11] 'which you can config' -> 'for configuring' --- packages/firestore/src/api/persistent_cache_index_manager.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/firestore/src/api/persistent_cache_index_manager.ts b/packages/firestore/src/api/persistent_cache_index_manager.ts index 48b9c6e8d83..0e7f4d17614 100644 --- a/packages/firestore/src/api/persistent_cache_index_manager.ts +++ b/packages/firestore/src/api/persistent_cache_index_manager.ts @@ -26,8 +26,8 @@ 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. + * A `PersistentCacheIndexManager` for configuring persistent cache indexes used + * for local query execution. * * To use, call `getPersistentCacheIndexManager()` to get an instance. */ From 73bfb9b7eb88d287f4ac0254c9e75a7c29b4266b Mon Sep 17 00:00:00 2001 From: Denver Coneybeare Date: Tue, 5 Sep 2023 13:58:42 -0400 Subject: [PATCH 11/11] yarn docgen devsite --- docs-devsite/firestore_.index.md | 2 +- docs-devsite/firestore_.indexconfiguration.md | 2 +- docs-devsite/firestore_.indexfield.md | 2 +- docs-devsite/firestore_.md | 10 +++++----- docs-devsite/firestore_.persistentcacheindexmanager.md | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/docs-devsite/firestore_.index.md b/docs-devsite/firestore_.index.md index 62cffe39092..02a9b95f23c 100644 --- a/docs-devsite/firestore_.index.md +++ b/docs-devsite/firestore_.index.md @@ -15,7 +15,7 @@ https://github.com/firebase/firebase-js-sdk > Warning: This API is now obsolete. > -> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to create cache indexes for queries running locally. > The SDK definition of a Firestore index. diff --git a/docs-devsite/firestore_.indexconfiguration.md b/docs-devsite/firestore_.indexconfiguration.md index d5a58b5733a..4bf7e4278fb 100644 --- a/docs-devsite/firestore_.indexconfiguration.md +++ b/docs-devsite/firestore_.indexconfiguration.md @@ -15,7 +15,7 @@ https://github.com/firebase/firebase-js-sdk > Warning: This API is now obsolete. > -> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to create cache indexes for queries running locally. > A list of Firestore indexes to speed up local query execution. diff --git a/docs-devsite/firestore_.indexfield.md b/docs-devsite/firestore_.indexfield.md index 98867832708..e05fae75804 100644 --- a/docs-devsite/firestore_.indexfield.md +++ b/docs-devsite/firestore_.indexfield.md @@ -15,7 +15,7 @@ https://github.com/firebase/firebase-js-sdk > Warning: This API is now obsolete. > -> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to create cache indexes for queries running locally. > A single field element in an index configuration. diff --git a/docs-devsite/firestore_.md b/docs-devsite/firestore_.md index e3cf31d42ff..6fdd2abdd05 100644 --- a/docs-devsite/firestore_.md +++ b/docs-devsite/firestore_.md @@ -63,7 +63,7 @@ https://github.com/firebase/firebase-js-sdk | function(indexManager...) | | [deleteAllPersistentCacheIndexes(indexManager)](./firestore_.md#deleteallpersistentcacheindexes) | Removes all persistent cache indexes.Please note this function will also deletes indexes generated by setIndexConfiguration(), which is deprecated. | | [disablePersistentCacheIndexAutoCreation(indexManager)](./firestore_.md#disablepersistentcacheindexautocreation) | Stops creating persistent cache indexes automatically for local query execution. The indexes which have been created by calling enablePersistentCacheIndexAutoCreation() still take effect. | -| [enablePersistentCacheIndexAutoCreation(indexManager)](./firestore_.md#enablepersistentcacheindexautocreation) | 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. | +| [enablePersistentCacheIndexAutoCreation(indexManager)](./firestore_.md#enablepersistentcacheindexautocreation) | Enables the SDK to create persistent cache indexes automatically for local query execution when the SDK believes cache indexes can help improve performance.This feature is disabled by default. | | function(left...) | | [aggregateQuerySnapshotEqual(left, right)](./firestore_.md#aggregatequerysnapshotequal) | Compares two AggregateQuerySnapshot instances for equality.Two AggregateQuerySnapshot instances are considered "equal" if they have underlying queries that compare equal, and the same data. | | [queryEqual(left, right)](./firestore_.md#queryequal) | Returns true if the provided queries point to the same collection and apply the same constraints. | @@ -135,7 +135,7 @@ https://github.com/firebase/firebase-js-sdk | [FirestoreError](./firestore_.firestoreerror.md#firestoreerror_class) | An error returned by a Firestore operation. | | [GeoPoint](./firestore_.geopoint.md#geopoint_class) | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.Latitude values are in the range of \[-90, 90\]. Longitude values are in the range of \[-180, 180\]. | | [LoadBundleTask](./firestore_.loadbundletask.md#loadbundletask_class) | Represents the task of loading a Firestore bundle. It provides progress of bundle loading, as well as task completion and error events.The API is compatible with Promise<LoadBundleTaskProgress>. | -| [PersistentCacheIndexManager](./firestore_.persistentcacheindexmanager.md#persistentcacheindexmanager_class) | A PersistentCacheIndexManager which you can config persistent cache indexes used for local query execution.To use, call getPersistentCacheIndexManager() to get an instance. | +| [PersistentCacheIndexManager](./firestore_.persistentcacheindexmanager.md#persistentcacheindexmanager_class) | A PersistentCacheIndexManager for configuring persistent cache indexes used for local query execution.To use, call getPersistentCacheIndexManager() to get an instance. | | [Query](./firestore_.query.md#query_class) | A Query refers to a query which you can read or listen to. You can also construct refined Query objects by adding filters and ordering. | | [QueryCompositeFilterConstraint](./firestore_.querycompositefilterconstraint.md#querycompositefilterconstraint_class) | A QueryCompositeFilterConstraint is used to narrow the set of documents returned by a Firestore query by performing the logical OR or AND of multiple [QueryFieldFilterConstraint](./firestore_.queryfieldfilterconstraint.md#queryfieldfilterconstraint_class)s or [QueryCompositeFilterConstraint](./firestore_.querycompositefilterconstraint.md#querycompositefilterconstraint_class)s. QueryCompositeFilterConstraints are created by invoking [or()](./firestore_.md#or) or [and()](./firestore_.md#and) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains the QueryCompositeFilterConstraint. | | [QueryConstraint](./firestore_.queryconstraint.md#queryconstraint_class) | A QueryConstraint is used to narrow the set of documents returned by a Firestore query. QueryConstraints are created by invoking [where()](./firestore_.md#where), [orderBy()](./firestore_.md#orderby), [startAt()](./firestore_.md#startat), [startAfter()](./firestore_.md#startafter), [endBefore()](./firestore_.md#endbefore), [endAt()](./firestore_.md#endat), [limit()](./firestore_.md#limit), [limitToLast()](./firestore_.md#limittolast) and can then be passed to [query()](./firestore_.md#query) to create a new query instance that also contains this QueryConstraint. | @@ -689,7 +689,7 @@ If the transaction completed successfully or was explicitly aborted (the `update > Warning: This API is now obsolete. > -> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to create cache indexes for queries running locally. > Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. @@ -728,7 +728,7 @@ FirestoreError if the JSON format is invalid. > Warning: This API is now obsolete. > -> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let SDK decide whether to create cache indexes for queries running locally. +> Instead of creating cache indexes manually, consider using `enablePersistentCacheIndexAutoCreation()` to let the SDK decide whether to create cache indexes for queries running locally. > Configures indexing for local query execution. Any previous index configuration is overridden. The `Promise` resolves once the index configuration has been persisted. @@ -1172,7 +1172,7 @@ void ## enablePersistentCacheIndexAutoCreation() -Enables SDK to create persistent cache indexes automatically for local query execution when SDK believes cache indexes can help improves performance. +Enables the SDK to create persistent cache indexes automatically for local query execution when the SDK believes cache indexes can help improve performance. This feature is disabled by default. diff --git a/docs-devsite/firestore_.persistentcacheindexmanager.md b/docs-devsite/firestore_.persistentcacheindexmanager.md index 34029877376..080702fb50f 100644 --- a/docs-devsite/firestore_.persistentcacheindexmanager.md +++ b/docs-devsite/firestore_.persistentcacheindexmanager.md @@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk {% endcomment %} # PersistentCacheIndexManager class -A `PersistentCacheIndexManager` which you can config persistent cache indexes used for local query execution. +A `PersistentCacheIndexManager` for configuring persistent cache indexes used for local query execution. To use, call `getPersistentCacheIndexManager()` to get an instance.