Array-contains queries in Firebase - Step-by-Step Execution

Process Flow - Array-contains queries

Start Query

↓

Specify Collection

↓

Add array-contains filter

↓

Send Query to Firestore

↓

Firestore scans documents

↓

Check if array field contains value

Yes No↓

Include doc

↓

Return matching docs

↓

End

The query starts by specifying a collection, adds an array-contains filter, sends it to Firestore, which scans documents and returns those whose array field contains the specified value.

Execution Sample

Firebase

db.collection('users').where('tags', 'array-contains', 'admin').get()

Query Firestore for documents in 'users' collection where 'tags' array contains 'admin'.

Process Table

Step	Action	Query Condition	Document Checked	Array Field Value	Contains Value?	Include in Result
1	Start query	tags array-contains 'admin'	-	-	-	-
2	Check doc1	tags array-contains 'admin'	doc1	['user', 'admin']	Yes	Yes
3	Check doc2	tags array-contains 'admin'	doc2	['user', 'editor']	No	No
4	Check doc3	tags array-contains 'admin'	doc3	['admin', 'moderator']	Yes	Yes
5	Check doc4	tags array-contains 'admin'	doc4	[]	No	No
6	Return results	tags array-contains 'admin'	doc1, doc3	-	-	doc1, doc3

💡 All documents checked; only those with 'admin' in 'tags' array included in results.

Status Tracker

Variable	Start	After Step 2	After Step 3	After Step 4	After Step 5	Final
MatchingDocs	[]	['doc1']	['doc1']	['doc1', 'doc3']	['doc1', 'doc3']	['doc1', 'doc3']

Key Moments - 2 Insights

Why does doc2 not appear in the results even though it has a 'tags' array?

Because the 'tags' array in doc2 does not contain the value 'admin'. The query only includes documents where the array contains the exact value specified, as shown in execution_table rows 3 and 4.

What happens if the array field is empty or missing in a document?

Documents with empty or missing arrays do not match the 'array-contains' condition, so they are excluded. This is shown in execution_table row 5 where doc4 has an empty array and is not included.

Visual Quiz - 3 Questions

Look at the execution table, which documents are included in the query result?

A doc1 and doc3

B doc2 and doc4

C doc1, doc2, doc3

D doc4 only

💡 Hint

Check the 'Include in Result' column in the execution_table rows 2, 3, 4, and 5.

At which step does the query determine that doc2 does not match the condition?

A Step 2

B Step 3

C Step 4

D Step 5

💡 Hint

Look at the 'Document Checked' and 'Contains Value?' columns in execution_table row 3.

If the query was changed to 'array-contains' value 'user', which document would be included at step 3?

A doc1 only

B doc2 only

C doc1 and doc2

D doc3 only

💡 Hint

Refer to the 'Array Field Value' column and imagine checking for 'user' instead of 'admin'.

Concept Snapshot

Firestore array-contains query syntax:
collection.where('arrayField', 'array-contains', value).get()
Returns documents where the arrayField includes the exact value.
Does not match if array is empty or value missing.
Efficient for filtering documents by array membership.

Full Transcript

This visual execution trace shows how a Firestore array-contains query works. The query starts by specifying the collection and the array-contains filter. Firestore then checks each document's array field to see if it contains the specified value. Documents with the value are included in the results; others are excluded. For example, documents with 'tags' arrays containing 'admin' are returned, while those without are not. Empty or missing arrays do not match. The variable tracker shows how the list of matching documents grows as each document is checked. Key moments clarify why some documents are excluded. The quiz tests understanding of which documents match and when decisions happen during execution.

Practice

1.

What does the array-contains query operator do in Firebase Firestore?

easy

A. Finds documents where an array field includes a specific value

B. Finds documents where a string field contains a substring

C. Finds documents where a number field is greater than a value

D. Finds documents where a field is missing

Solution

1. Step 1: Understand the purpose of array-contains

   This operator is designed to check if an array field in a document contains a specific value.

2. Step 2: Compare with other query types

   Other options describe different query operators, but only array-contains matches arrays including a value.

3. Final Answer:

   Finds documents where an array field includes a specific value -> Option A

4. Quick Check:

   array-contains = finds value in array [OK]

Hint: Remember: array-contains checks for one value inside an array [OK]

Common Mistakes:

• Confusing array-contains with substring search
• Using array-contains on non-array fields
• Thinking it works with multiple values at once

2.

Which of the following is the correct syntax to query documents where the tags array contains the value "urgent"?

const query = firestore.collection('tasks').where(____);

easy

A. "tags", "contains", "urgent"

B. "tags", "==", "urgent"

C. "tags", "array-contains-any", ["urgent"]

D. "tags", "array-contains", "urgent"

Solution

1. Step 1: Recall the correct operator for single value in array

   The operator is "array-contains" to check if an array includes a specific value.

2. Step 2: Check syntax format

   The syntax is .where("field", "array-contains", value). "tags", "array-contains", "urgent" matches this exactly.

3. Final Answer:

   "tags", "array-contains", "urgent" -> Option D

4. Quick Check:

   Correct syntax uses array-contains [OK]

Hint: Use "array-contains" for single value array queries [OK]

Common Mistakes:

• Using == instead of array-contains for arrays
• Confusing array-contains with array-contains-any
• Using non-existent operator "contains"

3.

Given the following documents in a Firestore collection projects:

[{ id: 1, members: ["alice", "bob"] }, { id: 2, members: ["carol"] }, { id: 3, members: ["bob", "dave"] }]

What will the query firestore.collection('projects').where('members', 'array-contains', 'bob').get() return?

medium

A. Documents with id 2 only

B. Documents with id 1 only

C. Documents with id 1 and 3

D. No documents

Solution

1. Step 1: Identify documents where 'members' array contains 'bob'

   Document 1 has members ["alice", "bob"] which includes "bob". Document 3 has ["bob", "dave"] which also includes "bob". Document 2 does not.

2. Step 2: Determine query result

   The query returns documents 1 and 3 because their 'members' arrays contain "bob".

3. Final Answer:

   Documents with id 1 and 3 -> Option C

4. Quick Check:

   array-contains 'bob' = docs 1 and 3 [OK]

Hint: Check which arrays include the value exactly [OK]

Common Mistakes:

• Including documents without the value
• Confusing array-contains with array-contains-any
• Assuming partial matches inside strings

4.

What is wrong with this Firestore query?

firestore.collection('orders').where('items', 'array-contains', ['apple', 'banana'])

The items field is an array of strings.

medium

A. You cannot use an array as the value with array-contains

B. The operator should be 'array-contains-any' instead

C. The field 'items' must be a string, not an array

D. The query syntax is correct

Solution

1. Step 1: Understand array-contains value type

   The 'array-contains' operator expects a single value, not an array, to check inside the array field.

2. Step 2: Identify correct usage

   Passing an array as the value causes an error. To check multiple values, 'array-contains-any' is used instead.

3. Final Answer:

   You cannot use an array as the value with array-contains -> Option A

4. Quick Check:

   array-contains needs single value, not array [OK]

Hint: array-contains accepts only one value, not arrays [OK]

Common Mistakes:

• Passing an array as the value to array-contains
• Confusing array-contains with array-contains-any
• Assuming array-contains works like 'in' operator

5.

You want to find all documents in the events collection where the attendees array contains both "john" and "jane". Which approach is correct?

hard

A. Use a single query with array-contains-any and pass both names

B. Use two queries with array-contains for each name and merge results client-side

C. Use a single query with array-contains and pass an array of both names

D. Use a query with where('attendees', '==', ['john', 'jane'])

Solution

1. Step 1: Understand limitations of array-contains and array-contains-any

   array-contains checks for one value in array; array-contains-any checks if array contains any of multiple values but not all.

2. Step 2: Find correct method to get documents containing both values

   Since Firestore does not support querying for multiple values all present in one array in a single query, you must run two queries with array-contains and combine results client-side.

3. Final Answer:

   Use two queries with array-contains for each name and merge results client-side -> Option B

4. Quick Check:

   Multiple array-contains queries combined client-side [OK]

Hint: Firestore can't query multiple array-contains in one query [OK]

Common Mistakes:

• Using array-contains-any expecting all values matched
• Passing array of values to array-contains
• Using equality check on arrays