Firebase Cloud Firestore Skill

This skill defines how to correctly use Cloud Firestore in Flutter applications.

When to Use

Use this skill when:

• Setting up and configuring Cloud Firestore in a Flutter project.
• Designing document and collection structure.
• Performing read, write, or real-time listener operations.
• Optimizing for scale and avoiding hotspots.
• Applying Firestore security rules.

1. Database Selection

Choose Cloud Firestore when your app needs:

• Rich, hierarchical data models with subcollections.
• Complex queries: chaining filters, combining filtering and sorting on a property.
• Transactions that atomically read and write data from any part of the database.
• High availability (typical uptime 99.999%) or critical-level reliability.
• Scalability.

Use Realtime Database instead for simple data models requiring simple lookups and extremely low-latency synchronization (typical response times under 10ms).

2. Setup and Configuration

flutter pub add cloud_firestore

import 'package:cloud_firestore/cloud_firestore.dart';

final db = FirebaseFirestore.instance; // after Firebase.initializeApp()

Location:

• Select the database location closest to your users and compute resources.
• Use multi-region locations for critical apps (maximum availability and durability).
• Use regional locations for lower costs and lower write latency for latency-sensitive apps.

iOS/macOS: Consider pre-compiled frameworks to improve build times:

pod 'FirebaseFirestore',
  :git => 'https://github.com/invertase/firestore-ios-sdk-frameworks.git',
  :tag => 'IOS_SDK_VERSION'

3. Document Structure

• Avoid document IDs . and .. (special meaning in Firestore paths).
• Avoid forward slashes (/) in document IDs (path separators).
• Do not use monotonically increasing document IDs (e.g., Customer1, Customer2) — causes write hotspots.
• Use Firestore's automatic document IDs when possible:

db.collection("users").add(user).then((DocumentReference doc) =>
    print('DocumentSnapshot added with ID: ${doc.id}'));

• Avoid these characters in field names (require extra escaping): . [ ] * `
• Use subcollections within documents to organize complex, hierarchical data rather than deeply nested objects.

4. Indexing

• Set collection-level index exemptions to reduce write latency and storage costs.
• Disable Descending & Array indexing for fields that don't need them.
• Exempt string fields with long values that aren't used for querying.
• Exempt fields with sequential values (e.g., timestamps) from indexing if not used in queries — avoids the 500 writes/second index limit.
• Add single-field exemptions for TTL fields.
• Exempt large array or map fields not used in queries — avoids the 40,000 index entries per document limit.
• Firestore queries are indexed by default; query performance is proportional to the result set size, not the dataset size.

5. Read and Write Operations

• Always use asynchronous calls to minimize latency impact:

await db.collection("users").get().then((event) {
  for (var doc in event.docs) {
    print("${doc.id} => ${doc.data()}");
  }
});

• Do not use offsets for pagination — use cursors instead to avoid retrieving and being billed for skipped documents.
• Implement transaction retries when accessing Firestore directly through REST or RPC APIs.
• For writing a large number of documents, use a bulk writer instead of the atomic batch writer.
• Execute independent operations (e.g., a document lookup and a query) in parallel, not sequentially.
• Firestore queries are shallow: they only return documents in a specific collection or collection group, not subcollection data.
• Be aware of write rate limits: ~1 write per second per document.

6. Designing for Scale

• Avoid high read or write rates to lexicographically close documents (hotspotting).
• Avoid creating new documents with monotonically increasing fields (like timestamps) at a very high rate.
• Avoid deleting documents in a collection at a high rate.
• Gradually increase traffic when writing to the database at a high rate.
• Avoid queries that skip over recently deleted data — use start_at to find the correct start point.
• Distribute writes across different document paths to avoid contention.
• Firestore scales automatically to ~1 million concurrent connections and 10,000 writes/second.

7. Real-time Updates

• Limit the number of simultaneous real-time listeners.
• Detach listeners when they are no longer needed:

final subscription = db.collection("users")
    .snapshots()
    .listen((event) {
      // Handle the data
    });

// When no longer needed:
subscription.cancel();

• Use compound queries to filter data server-side rather than filtering on the client.
• For large collections, use queries to limit the data being listened to — never listen to an entire large collection.
• For presence functionality (online/offline status), implement custom presence solutions as described in Firebase documentation.

8. Security

• Always use Firebase Security Rules to protect Firestore data.
• Validate user input before submitting to Firestore to prevent injection attacks.
• Use transactions for operations that require atomic updates to multiple documents.
• Implement proper error handling for all Firestore operations.
• Never store sensitive information in Firestore without proper access controls.
• Security rules do not cascade unless you use a wildcard.
• If a query's results might contain data the user doesn't have access to, the entire query fails.

References

• Cloud Firestore Flutter documentation
• Cloud Firestore best practices
• Cloud Firestore security rules