How to Use array-contains in Firestore Queries

Use the array-contains operator in Firestore queries to find documents where a specified array field includes a given value. This operator filters documents that have the value inside the array field you specify.

Syntax

The array-contains operator is used in Firestore queries to filter documents where an array field contains a specific value.

• collection('yourCollection'): Selects the collection to query.
• where('arrayField', 'array-contains', value): Filters documents where arrayField includes value.
• get(): Retrieves the matching documents.

javascript

db.collection('yourCollection').where('arrayField', 'array-contains', value).get()

Example

This example shows how to query a Firestore collection named users to find all users whose hobbies array includes the value 'reading'.

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 findUsersWithHobby() {
  const q = query(collection(db, 'users'), where('hobbies', 'array-contains', 'reading'));
  const querySnapshot = await getDocs(q);
  querySnapshot.forEach((doc) => {
    console.log(doc.id, '=>', doc.data());
  });
}

findUsersWithHobby();

Output

user123 => { name: 'Alice', hobbies: ['reading', 'swimming'] }
user456 => { name: 'Bob', hobbies: ['reading', 'cycling'] }

Common Pitfalls

Common mistakes when using array-contains include:

• Using array-contains on fields that are not arrays causes no matches.
• Trying to match multiple values with array-contains (it only supports one value at a time).
• Confusing array-contains with in or array-contains-any which have different behaviors.

javascript

/* Wrong: Trying to match multiple values with array-contains */
db.collection('users').where('hobbies', 'array-contains', ['reading', 'swimming']).get();

/* Right: Use array-contains-any for multiple values */
db.collection('users').where('hobbies', 'array-contains-any', ['reading', 'swimming']).get();

Quick Reference

Operator	Description	Example Usage
array-contains	Matches documents where the array field contains a specific value	where('tags', 'array-contains', 'news')
array-contains-any	Matches documents where the array field contains any of the specified values	where('tags', 'array-contains-any', ['news', 'sports'])
in	Matches documents where the field matches any value in a list (not for arrays)	where('status', 'in', ['active', 'pending'])

Key Takeaways

Use array-contains to find documents where an array field includes a single specific value.

array-contains only supports one value; use array-contains-any for multiple values.

Ensure the field you query with array-contains is an array type in your documents.

Do not confuse array-contains with in or array-contains-any operators.

Always test your queries to confirm they return the expected documents.