diff --git a/.changeset/hip-cougars-float.md b/.changeset/hip-cougars-float.md new file mode 100644 index 00000000000..bf77817994b --- /dev/null +++ b/.changeset/hip-cougars-float.md @@ -0,0 +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. 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 diff --git a/docs-devsite/firestore_.index.md b/docs-devsite/firestore_.index.md index 3ea216d6798..02a9b95f23c 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 the 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..4bf7e4278fb 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 the 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..e05fae75804 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 the 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..6fdd2abdd05 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 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. | @@ -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 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. | @@ -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 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. 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 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. 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 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. + +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..080702fb50f --- /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` for configuring 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'; +``` diff --git a/packages/firestore/src/api/index_configuration.ts b/packages/firestore/src/api/index_configuration.ts index 94754636176..d482738280b 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 the 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 the 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 the 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 the 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 the SDK decide whether to + * create cache indexes for queries running locally. + * * @beta */ export function setIndexConfiguration( diff --git a/packages/firestore/src/api/persistent_cache_index_manager.ts b/packages/firestore/src/api/persistent_cache_index_manager.ts index 4a6d11c2b3a..0e7f4d17614 100644 --- a/packages/firestore/src/api/persistent_cache_index_manager.ts +++ b/packages/firestore/src/api/persistent_cache_index_manager.ts @@ -26,15 +26,13 @@ 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. - * - * TODO(CSI) Remove @internal to make the API publicly available. - * @internal */ export class PersistentCacheIndexManager { + /** A type string to uniquely identify instances of this class. */ readonly type: 'PersistentCacheIndexManager' = 'PersistentCacheIndexManager'; /** @hideconstructor */ @@ -47,9 +45,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 @@ -72,13 +67,11 @@ 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. - * - * TODO(CSI) Remove @internal to make the API publicly available. - * @internal */ export function enablePersistentCacheIndexAutoCreation( indexManager: PersistentCacheIndexManager @@ -90,9 +83,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 +95,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