How to Use Compound Queries in Firestore: Simple Guide

Use Firestore's where() method multiple times on a collection reference to create a compound query that filters documents by multiple conditions. Chain these where() calls inside a query() function before calling getDocs() to retrieve matching documents.

Syntax

A compound query in Firestore uses multiple where() filters chained together inside a query() function on a collection reference. Each where() takes three arguments: the field name, a comparison operator, and the value to compare.

Example parts:

• collection('users'): selects the collection
• where('age', '>=', 18): filters documents where age is 18 or more
• where('status', '==', 'active'): filters documents with status active
• getDocs(): fetches the filtered documents

javascript

import { collection, query, where, getDocs } from 'firebase/firestore';

const usersRef = collection(db, 'users');
const q = query(usersRef, where('age', '>=', 18), where('status', '==', 'active'));
const querySnapshot = await getDocs(q);

Example

This example fetches users who are at least 18 years old and have an active status. It shows how to chain where() filters inside a query() and handle the results.

javascript

import { initializeApp } from 'firebase/app';
import { getFirestore, collection, query, where, getDocs } from 'firebase/firestore';

const firebaseConfig = {
  // your config here
};

const app = initializeApp(firebaseConfig);
const db = getFirestore(app);

async function getActiveAdultUsers() {
  const usersRef = collection(db, 'users');
  const q = query(usersRef, where('age', '>=', 18), where('status', '==', 'active'));
  const querySnapshot = await getDocs(q);
  const results = [];
  querySnapshot.forEach((doc) => {
    results.push({ id: doc.id, ...doc.data() });
  });
  return results;
}

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

Output

[
  { id: 'user1', name: 'Alice', age: 25, status: 'active' },
  { id: 'user3', name: 'Bob', age: 30, status: 'active' }
]

Common Pitfalls

Common mistakes when using compound queries include:

• Not creating a composite index in Firestore for the fields used in multiple where() filters, which causes errors.
• Using unsupported operators together, like != with == in the same query.
• Trying to filter on different fields without proper indexing.
• Chaining where() calls incorrectly by mixing query() and collection references.

javascript

/* Wrong: Mixing collection ref and where without query() */
// This is valid in the older Firestore SDK but not recommended in modular SDK
// Use query() to combine filters instead

/* Right: Use query() to combine filters */
const q = query(
  collection(db, 'users'),
  where('age', '>=', 18),
  where('status', '==', 'active')
);
getDocs(q);

Quick Reference

Tips for using compound queries in Firestore:

• Always chain multiple where() filters inside a query() call.
• Ensure Firestore indexes exist for the fields used together in filters.
• Use supported comparison operators: ==, <, <=, >, >=, array-contains, etc.
• Limit the number of filters to avoid complex queries that Firestore cannot optimize.

Key Takeaways

Chain multiple where() filters inside a query() to create compound queries in Firestore.

Firestore requires composite indexes for compound queries on multiple fields.

Use only supported operators and combinations in compound queries.

Always test queries to catch index errors and fix them in the Firebase console.

Use async/await with getDocs() to fetch query results cleanly.