Global - Documentation

Members

SERVICE

Span names for instrumented operations.

(constant) gapicConfig

Client JSON configuration object, loaded from src/v1/firestore_admin_client_config.json. This file defines retry strategy and timeouts for all API methods in this library.

(constant) gapicConfig

Client JSON configuration object, loaded from src/v1/firestore_client_config.json. This file defines retry strategy and timeouts for all API methods in this library.

(constant) gapicConfig

Client JSON configuration object, loaded from src/v1beta1/firestore_client_config.json. This file defines retry strategy and timeouts for all API methods in this library.

Methods

setLogFunction(logger)

Sets or disables the log function for all active Firestore instances.

Parameters:

Name	Type	Description
`logger`		A log function that takes a message (such as `console.log`) or `null` to turn off logging.

Type Definitions

BulkWriterError

An error thrown when a BulkWriter operation fails.

The error used by BulkWriter~shouldRetryCallback set in BulkWriter#onWriteError.

Properties:

Name	Type	Description
`code`	GrpcStatus	The status code of the error.
`message`	string	The error message of the error.
`documentRef`	DocumentReference	The document reference the operation was performed on.
`operationType`	'create' \| 'set' \| 'update' \| 'delete'	The type of operation performed.
`failedAttempts`	number	How many times this operation has been attempted unsuccessfully.

BulkWriterOptions

An options object to configure throttling on BulkWriter.

Whether to disable or configure throttling. By default, throttling is enabled. throttling can be set to either a boolean or a config object. Setting it to true will use default values. You can override the defaults by setting it to false to disable throttling, or by setting the config values to enable throttling with the provided values.

Properties:

Name	Type	Description
`throttling`	boolean \| Object	Whether to disable or enable throttling. Throttling is enabled by default, if the field is set to `true` or if any custom throttling options are provided. `{ initialOpsPerSecond: number }` sets the initial maximum number of operations per second allowed by the throttler. If `initialOpsPerSecond` is not set, the default is 500 operations per second. `{ maxOpsPerSecond: number }` sets the maximum number of operations per second allowed by the throttler. If `maxOpsPerSecond` is not set, no maximum is enforced.

DocumentData

Document data (e.g. for use with set()) consisting of fields mapped to values.

FirestoreDataConverter

Converter used by withConverter() to transform user objects of type AppModelType into Firestore data of type DbModelType.

Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore.

Properties:

Name	Type	Description
`toFirestore`	function	Called by the Firestore SDK to convert a custom model object of type `AppModelType` into a plain Javascript object (suitable for writing directly to the Firestore database).
`fromFirestore`	function	Called by the Firestore SDK to convert Firestore data into an object of type `AppModelType`.

Example

```
class Post {
  constructor(readonly title: string, readonly author: string) {}

  toString(): string {
    return this.title + ', by ' + this.author;
  }
}

const postConverter = {
  toFirestore(post: Post): FirebaseFirestore.DocumentData {
    return {title: post.title, author: post.author};
  },
  fromFirestore(
    snapshot: FirebaseFirestore.QueryDocumentSnapshot
  ): Post {
    const data = snapshot.data();
    return new Post(data.title, data.author);
  }
};

const postSnap = await Firestore()
  .collection('posts')
  .withConverter(postConverter)
  .doc().get();
const post = postSnap.data();
if (post !== undefined) {
  post.title; // string
  post.toString(); // Should be defined
  post.someNonExistentProperty; // TS error
}

```

GrpcStatus

Status codes returned by GRPC operations.

See:

https://github.com/grpc/grpc/blob/master/doc/statuscodes.md

Precondition

An options object that configures conditional behavior of update() and delete() calls in DocumentReference, WriteBatch, BulkWriter, and Transaction. Using Preconditions, these calls can be restricted to only apply to documents that match the specified conditions.

Properties:

Name	Type	Description
`lastUpdateTime`	Timestamp	The update time to enforce. If set, enforces that the document was last updated at lastUpdateTime. Fails the operation if the document was last updated at a different time.
`exists`	boolean	If set, enforces that the target document must or must not exist.

Example

```
const documentRef = firestore.doc('coll/doc');

documentRef.get().then(snapshot => {
  const updateTime = snapshot.updateTime;

  console.log(`Deleting document at update time: ${updateTime.toDate()}`);
  return documentRef.delete({ lastUpdateTime: updateTime });
});

```

ReadOptions

An options object that can be used to configure the behavior of getAll() calls. By providing a fieldMask, these calls can be configured to only return a subset of fields.

Properties:

Name	Type	Description
`fieldMask`	Array.<(string\|FieldPath)>	Specifies the set of fields to return and reduces the amount of data transmitted by the backend. Adding a field mask does not filter results. Documents do not need to contain values for all the fields in the mask to be part of the result set.

SetOptions

An options object that configures the behavior of set() calls in DocumentReference, WriteBatch, and Transaction. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions object with { merge : true }.

Properties:

Name	Type	Description
`merge`	boolean	Changes the behavior of a set() call to only replace the values specified in its data argument. Fields omitted from the set() call remain untouched.
`mergeFields`	Array.<(string\|FieldPath)>	Changes the behavior of set() calls to only replace the specified field paths. Any field path that is not specified is ignored and remains untouched. It is an error to pass a SetOptions object to a set() call that is missing a value for any of the fields specified here.

UpdateData

Update data (for use with update) that contains paths mapped to values. Fields that contain dots reference nested fields within the document.

You can update a top-level field in your document by using the field name as a key (e.g. foo). The provided value completely replaces the contents for this field.

You can also update a nested field directly by using its field path as a key (e.g. foo.bar). This nested field update replaces the contents at bar but does not modify other data under foo.

Example

```
const documentRef = firestore.doc('coll/doc');
documentRef.set({a1: {a2: 'val'}, b1: {b2: 'val'}, c1: {c2: 'val'}});
documentRef.update({
 b1: {b3: 'val'},
 'c1.c3': 'val',
});
// Value is {a1: {a2: 'val'}, b1: {b3: 'val'}, c1: {c2: 'val', c3: 'val'}}

```

documentSnapshotCallback(snapshot)

onSnapshot() callback that receives a DocumentSnapshot.

Parameters:

Name	Type	Description
`snapshot`	DocumentSnapshot	A document snapshot.

errorCallback(err)

onSnapshot() callback that receives an error.

Parameters:

Name	Type	Description
`err`	Error	An error from a listen.

querySnapshotCallback(snapshot)

onSnapshot() callback that receives a QuerySnapshot.

Parameters:

Name	Type	Description
`snapshot`	QuerySnapshot	A query snapshot.