Query

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.

Source:

Members

(readonly) firestore :Firestore

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

Source:
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(…fieldValuesOrDocumentSnapshot) → {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.

Parameters:
Name Type Attributes Description
fieldValuesOrDocumentSnapshot * | DocumentSnapshot <repeatable>

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.
Source:
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(…fieldValuesOrDocumentSnapshot) → {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.

Parameters:
Name Type Attributes Description
fieldValuesOrDocumentSnapshot * | DocumentSnapshot <repeatable>

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.
Source:
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() → {Promise.<QuerySnapshot>}

Executes the query and returns the results as a QuerySnapshot.

Source:
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(other) → {boolean}

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

Parameters:
Name Type Description
other *

The value to compare against.
Source:

limit(limit) → {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.

Parameters:
Name Type Description
limit number

The maximum number of items to return.
Source:
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) → {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.

Parameters:
Name Type Description
offset number

The offset to apply to the Query results
Source:
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(onNext, onErroropt) → {function}

Attaches a listener for QuerySnapshot events.

Parameters:
Name Type Attributes Description
onNext querySnapshotCallback

A callback to be called every time a new QuerySnapshot is available.
onError errorCallback <optional>

A callback to be called if the listen fails or is cancelled. No further callbacks will occur.
Source:
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(fieldPath, directionStropt) → {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.

Parameters:
Name Type Attributes Description
fieldPath string | FieldPath

The field to sort by.
directionStr string <optional>

Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending.
Source:
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(…fieldPaths) → {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.

Parameters:
Name Type Attributes Description
fieldPaths string | FieldPath <repeatable>

The field paths to return.
Source:
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(…fieldValuesOrDocumentSnapshot) → {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.

Parameters:
Name Type Attributes Description
fieldValuesOrDocumentSnapshot * | DocumentSnapshot <repeatable>

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.
Source:
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(…fieldValuesOrDocumentSnapshot) → {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.

Parameters:
Name Type Attributes Description
fieldValuesOrDocumentSnapshot * | DocumentSnapshot <repeatable>

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.
Source:
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.<QueryDocumentSnapshot>}

Executes the query and streams the results as QueryDocumentSnapshots.

Source:
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(fieldPath, opStr, value) → {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.

Parameters:
Name Type Description
fieldPath string | FieldPath

The name of a property value to compare.
opStr string

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.
Source:
Example
let collectionRef = firestore.collection('col');

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

Query

new Query(_firestore, _queryOptions)

Parameters:
Name Type Description
_firestore

The Firestore Database client.
_queryOptions

Options that define the query.
Source:

Members

(readonly) firestore :Firestore

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

Source:
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(…fieldValuesOrDocumentSnapshot) → {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.

Parameters:
Name Type Attributes Description
fieldValuesOrDocumentSnapshot * | DocumentSnapshot <repeatable>

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.
Source:
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(…fieldValuesOrDocumentSnapshot) → {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.

Parameters:
Name Type Attributes Description
fieldValuesOrDocumentSnapshot * | DocumentSnapshot <repeatable>

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.
Source:
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() → {Promise.<QuerySnapshot>}

Executes the query and returns the results as a QuerySnapshot.

Source:
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(other) → {boolean}

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

Parameters:
Name Type Description
other *

The value to compare against.
Source:

limit(limit) → {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.

Parameters:
Name Type Description
limit number

The maximum number of items to return.
Source:
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) → {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.

Parameters:
Name Type Description
offset number

The offset to apply to the Query results
Source:
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(onNext, onErroropt) → {function}

Attaches a listener for QuerySnapshot events.

Parameters:
Name Type Attributes Description
onNext querySnapshotCallback

A callback to be called every time a new QuerySnapshot is available.
onError errorCallback <optional>

A callback to be called if the listen fails or is cancelled. No further callbacks will occur.
Source:
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(fieldPath, directionStropt) → {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.

Parameters:
Name Type Attributes Description
fieldPath string | FieldPath

The field to sort by.
directionStr string <optional>

Optional direction to sort by ('asc' or 'desc'). If not specified, order will be ascending.
Source:
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(…fieldPaths) → {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.

Parameters:
Name Type Attributes Description
fieldPaths string | FieldPath <repeatable>

The field paths to return.
Source:
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(…fieldValuesOrDocumentSnapshot) → {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.

Parameters:
Name Type Attributes Description
fieldValuesOrDocumentSnapshot * | DocumentSnapshot <repeatable>

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.
Source:
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(…fieldValuesOrDocumentSnapshot) → {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.

Parameters:
Name Type Attributes Description
fieldValuesOrDocumentSnapshot * | DocumentSnapshot <repeatable>

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.
Source:
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.<QueryDocumentSnapshot>}

Executes the query and streams the results as QueryDocumentSnapshots.

Source:
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(fieldPath, opStr, value) → {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.

Parameters:
Name Type Description
fieldPath string | FieldPath

The name of a property value to compare.
opStr string

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.
Source:
Example
let collectionRef = firestore.collection('col');

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