How to Use startAt and endAt in Firestore Queries

Use startAt and endAt in Firestore queries to filter documents starting or ending at specific values. These methods set query cursors to include documents from or up to the given field values or document snapshots.

Syntax

The startAt and endAt methods are used on Firestore query objects to set the starting and ending points of the query results. You can pass either field values or a document snapshot to these methods.

• startAt(value1, value2, ...): Starts the query results at the given field values or document snapshot, including that document.
• endAt(value1, value2, ...): Ends the query results at the given field values or document snapshot, including that document.

These methods are often used with orderBy to define the order and range of documents returned.

javascript

const query = firestore.collection('users')
  .orderBy('age')
  .startAt(18)
  .endAt(30);

Example

This example queries a Firestore collection named users and returns all users whose age field is between 18 and 30, inclusive.

javascript

import { getFirestore, collection, query, orderBy, startAt, endAt, getDocs } from 'firebase/firestore';

const firestore = getFirestore();
const usersRef = collection(firestore, 'users');

async function getUsersByAgeRange() {
  const q = query(usersRef, orderBy('age'), startAt(18), endAt(30));
  const querySnapshot = await getDocs(q);
  const users = [];
  querySnapshot.forEach(doc => {
    users.push({ id: doc.id, ...doc.data() });
  });
  return users;
}

getUsersByAgeRange().then(users => console.log(users));

Output

[
  { id: 'user1', name: 'Alice', age: 18 },
  { id: 'user2', name: 'Bob', age: 25 },
  { id: 'user3', name: 'Carol', age: 30 }
]

Common Pitfalls

Common mistakes when using startAt and endAt include:

• Not using orderBy on the same field(s) as the cursor values, which causes errors.
• Passing values that do not match the orderBy fields in number or type.
• Confusing startAt (inclusive) with startAfter (exclusive), leading to unexpected results.
• Using these methods without understanding that they include the boundary document or value.

Example of wrong usage:

javascript

const wrongQuery = firestore.collection('users')
  .startAt(18) // Missing orderBy on 'age'
  .endAt(30); // This will cause an error

// Correct usage:
const correctQuery = firestore.collection('users')
  .orderBy('age')
  .startAt(18)
  .endAt(30);

Quick Reference

Method	Description	Includes Boundary?
startAt(...values)	Starts query results at the given field values or document snapshot	Yes
endAt(...values)	Ends query results at the given field values or document snapshot	Yes
startAfter(...values)	Starts query results just after the given field values or document snapshot	No
endBefore(...values)	Ends query results just before the given field values or document snapshot	No

Key Takeaways

Always use orderBy on the same fields before using startAt or endAt.

startAt and endAt include the boundary values or documents in the results.

Pass the correct number and type of values matching the orderBy fields.

Use startAfter and endBefore for exclusive range boundaries.

These methods help paginate or filter query results by range efficiently.