Properties

firestore

read-only

unknown

The Firestore instance for the Firestore database (useful for performing transactions, etc.).

Inherited from
Query#firestore

Example

let collectionRef = firestore.collection('col');

collectionRef.add({foo: 'bar'}).then(documentReference => {
  let firestore = documentReference.firestore;
  console.log(`Root location for document is ${firestore.formattedName}`);
});

id

read-only

string

ID of the referenced collection.

Example

let collectionRef = firestore.collection('col/doc/subcollection');
console.log(`ID of the subcollection: ${collectionRef.id}`);

parent

read-only

DocumentReference

A reference to the containing Document if this is a subcollection, else null.

Example

let collectionRef = firestore.collection('col/doc/subcollection');
let documentRef = collectionRef.parent;
console.log(`Parent name: ${documentRef.path}`);

path

read-only

string

A string representing the path of the referenced collection (relative to the root of the database).

Example

let collectionRef = firestore.collection('col/doc/subcollection');
console.log(`Path of the subcollection: ${collectionRef.path}`);

Methods

add

add(data) returns Promise containing DocumentReference

Add a new document to this collection with the specified data, assigning it a document ID automatically.

Parameter

data

DocumentData

An Object containing the data for the new document.

Returns

Promise containing DocumentReference 

A Promise resolved with a DocumentReference pointing to the newly created document.

Example

let collectionRef = firestore.collection('col');
collectionRef.add({foo: 'bar'}).then(documentReference => {
  console.log(`Added document with name: ${documentReference.id}`);
});

doc

doc(documentPath) returns DocumentReference

Gets a DocumentReference instance that refers to the document at the specified path. If no path is specified, an automatically-generated unique ID will be used for the returned DocumentReference.

Parameter

documentPath

Optional

string

A slash-separated path to a document.

Returns

DocumentReference 

The DocumentReference instance.

Example

let collectionRef = firestore.collection('col');
let documentRefWithName = collectionRef.doc('doc');
let documentRefWithAutoId = collectionRef.doc();
console.log(`Reference with name: ${documentRefWithName.path}`);
console.log(`Reference with auto-id: ${documentRefWithAutoId.path}`);

endAt

endAt(...fieldValues) returns Query

Creates and returns a new Query that ends at the provided set of field values relative to the order of the query. The order of the provided values must match the order of the order by clauses of the query.

Parameter

fieldValues

The set of field values to end the query at.

Value may be repeated.

Inherited from
Query#endAt
Returns

A query with the new ending point.

Example

let query = firestore.collection('col');

query.orderBy('foo').endAt(42).get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

endBefore

endBefore(...fieldValues) returns Query

Creates and returns a new Query that ends before the set of field values relative to the order of the query. The order of the provided values must match the order of the order by clauses of the query.

Parameter

fieldValues

The set of field values to end the query before.

Value may be repeated.

Inherited from
Query#endBefore
Returns

A query with the new ending point.

Example

let query = firestore.collection('col');

query.orderBy('foo').endBefore(42).get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

get

get() returns Promise containing QuerySnapshot

Executes the query and returns the results as a QuerySnapshot.

Inherited from
Query#get
Returns

A Promise that resolves with the results of the Query.

Example

let query = firestore.collection('col').where('foo', '==', 'bar');

query.get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

limit

limit(limit) returns Query

Creates and returns a new Query that's additionally limited to only return up to the specified number of documents.

This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the limit.

Parameter

limit

The maximum number of items to return.

Inherited from
Query#limit
Returns

The created Query.

Example

let query = firestore.collection('col').where('foo', '>', 42);

query.limit(1).get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

offset

offset(offset) returns Query

Specifies the offset of the returned results.

This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the offset.

Parameter

offset

The offset to apply to the Query results

Inherited from
Query#offset
Returns

The created Query.

Example

let query = firestore.collection('col').where('foo', '>', 42);

query.limit(10).offset(20).get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

onSnapshot

onSnapshot(onNext, onError) returns function()

Attaches a listener for QuerySnapshot events.

Parameter

onNext

A callback to be called every time a new QuerySnapshot is available.

onError

Optional

A callback to be called if the listen fails or is cancelled. No further callbacks will occur.

Inherited from
Query#onSnapshot
Returns

An unsubscribe function that can be called to cancel the snapshot listener.

Example

let query = firestore.collection('col').where('foo', '==', 'bar');

let unsubscribe = query.onSnapshot(querySnapshot => {
  console.log(`Received query snapshot of size ${querySnapshot.size}`);
}, err => {
  console.log(`Encountered error: ${err}`);
});

// Remove this listener.
unsubscribe();

orderBy

orderBy(fieldPath, directionStr) returns Query

Creates and returns a new Query that's additionally sorted by the specified field, optionally in descending order instead of ascending.

This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the field mask.

Parameter

fieldPath

The field to sort by.

directionStr

Optional

Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending.

Inherited from
Query#orderBy
Returns

The created Query.

Example

let query = firestore.collection('col').where('foo', '>', 42);

query.orderBy('foo', 'desc').get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

select

select(...fieldPaths) returns Query

Creates and returns a new Query instance that applies a field mask to the result and returns only the specified subset of fields. You can specify a list of field paths to return, or use an empty list to only return the references of matching documents.

This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the field mask.

Parameter

fieldPaths

The field paths to return.

Value may be repeated.

Inherited from
Query#select
Returns

The created Query.

Example

let collectionRef = firestore.collection('col');
let documentRef = collectionRef.doc('doc');

return documentRef.set({x:10, y:5}).then(() => {
  return collectionRef.where('x', '>', 5).select('y').get();
}).then((res) => {
  console.log(`y is ${res.docs[0].get('y')}.`);
});

startAfter

startAfter(...fieldValues) returns Query

Creates and returns a new Query that starts after the provided set of field values relative to the order of the query. The order of the provided values must match the order of the order by clauses of the query.

Parameter

fieldValues

The set of field values to start the query after.

Value may be repeated.

Inherited from
Query#startAfter
Returns

A query with the new starting point.

Example

let query = firestore.collection('col');

query.orderBy('foo').startAfter(42).get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

startAt

startAt(...fieldValues) returns Query

Creates and returns a new Query that starts at the provided set of field values relative to the order of the query. The order of the provided values must match the order of the order by clauses of the query.

Parameter

fieldValues

The set of field values to start the query at.

Value may be repeated.

Inherited from
Query#startAt
Returns

A query with the new starting point.

Example

let query = firestore.collection('col');

query.orderBy('foo').startAt(42).get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});

stream

stream() returns Stream containing QueryDocumentSnapshot

Executes the query and streams the results as QueryDocumentSnapshots.

Inherited from
Query#stream
Returns

A stream of QueryDocumentSnapshots.

Example

let query = firestore.collection('col').where('foo', '==', 'bar');

let count = 0;

query.stream().on('data', (documentSnapshot) => {
  console.log(`Found document with name '${documentSnapshot.id}'`);
  ++count;
}).on('end', () => {
  console.log(`Total count is ${count}`);
});

where

where(fieldPath, opStr, value) returns Query

Creates and returns a new Query with the additional filter that documents must contain the specified field and that its value should satisfy the relation constraint provided.

Returns a new Query that constrains the value of a Document property.

This function returns a new (immutable) instance of the Query (rather than modify the existing instance) to impose the filter.

Parameter

fieldPath

The name of a property value to compare.

opStr

A comparison operation in the form of a string (e.g., "<").

value

The value to which to compare the field for inclusion in a query.

Inherited from
Query#where
Returns

The created Query.

Example

let collectionRef = firestore.collection('col');

collectionRef.where('foo', '==', 'bar').get().then(querySnapshot => {
  querySnapshot.forEach(documentSnapshot => {
    console.log(`Found document at ${documentSnapshot.ref.path}`);
  });
});