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.