CollectionReference
A CollectionReference object can be used for adding documents, getting document references, and querying for documents (using the methods inherited from Query).
- Extends
- Query
Properties
firestore
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
string
ID of the referenced collection.
Example
let collectionRef = firestore.collection('col/doc/subcollection');
console.log(`ID of the subcollection: ${collectionRef.id}`);
parent
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
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 |
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
-
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(fieldValuesOrDocumentSnapshot) 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 |
|
---|---|
fieldValuesOrDocumentSnapshot |
The snapshot of the document the query results should end at or the field values to end this query at, in order of the query's order by. |
- 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(fieldValuesOrDocumentSnapshot) 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 |
|
---|---|
fieldValuesOrDocumentSnapshot |
The snapshot of the document the query results should end before or the field values to end this query before, in order of the query's order by. |
- 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(fieldValuesOrDocumentSnapshot) 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 |
|
---|---|
fieldValuesOrDocumentSnapshot |
The snapshot of the document the query results should start after or the field values to start this query after, in order of the query's order by. |
- 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(fieldValuesOrDocumentSnapshot) 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 |
|
---|---|
fieldValuesOrDocumentSnapshot |
The snapshot of the document the query results should start at or the field values to start this query at, in order of the query's order by. |
- 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}`);
});
});