@google-cloud/firestore 0.14.1 » Class: Query

Query

class

Constructor

Query

new Query()

A Query refers to a query which you can read or stream from. You can also construct refined Query objects by adding filters and ordering.

Property

firestore

read-only

Firestore

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

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}`);
});

Methods

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	(repeatable any type or DocumentSnapshot) 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.

Returns

Query 

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	(repeatable any type or DocumentSnapshot) 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.

Returns

Query 

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.

Returns

Promise containing QuerySnapshot 

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}`);
  });
});

isEqual

isEqual(other) returns boolean

Returns true if this Query is equal to the provided value.

Parameter
other	any type The value to compare against.

Returns

boolean 

true if this Query is equal to the provided value.

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	number The maximum number of items to return.

Returns

Query 

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	number The offset to apply to the Query results

Returns

Query 

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	querySnapshotCallback A callback to be called every time a new QuerySnapshot is available.
onError	Optional errorCallback A callback to be called if the listen fails or is cancelled. No further callbacks will occur.

Returns

function() 

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	(string or FieldPath) The field to sort by.
directionStr	Optional string Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending.

Returns

Query 

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	(string or FieldPath) The field paths to return. Value may be repeated.

Returns

Query 

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	(repeatable any type or DocumentSnapshot) 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.

Returns

Query 

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	(repeatable any type or DocumentSnapshot) 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.

Returns

Query 

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.

Returns

Stream containing QueryDocumentSnapshot 

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	(string or FieldPath) The name of a property value to compare.
opStr	string A comparison operation in the form of a string (e.g., "<").
value	any type The value to which to compare the field for inclusion in a query.

Returns

Query 

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}`);
  });
});