google_cloud_firestore

A Dart client library for Google Cloud Firestore.

This package provides a complete API for interacting with Google Cloud Firestore, including support for documents, collections, queries, transactions, batches, and bulk writes.

It can be used standalone or as part of the Firebase Admin SDK.

Installation

Add google_cloud_firestore to your pubspec.yaml:

dart pub add google_cloud_firestore

Usage

Initialization

Usage with Firebase Functions

When running inside Firebase Functions, the environment is automatically configured with Application Default Credentials. You can simply instantiate Firestore without any arguments.

import 'package:firebase_functions/firebase_functions.dart';
import 'package:google_cloud_firestore/google_cloud_firestore.dart';

void main(List<String> args) async {
  await fireUp(args, (firebase) {
    // Example: HTTPS callable function that reads from Firestore
    firebase.https.onCall(
      name: 'getUserData',
      (request, response) async {
        final data = request.data as Map<String, dynamic>?;
        final userId = data?['userId'] as String?;
        
        if (userId == null) {
          throw InvalidArgumentError('userId is required');
        }
        
        final firestore = firebase.adminApp.firestore();
        final snapshot = await firestore.collection('users').doc(userId).get();
        
        if (!snapshot.exists) {
          throw NotFoundError('User not found');
        }
        
        return CallableResult(snapshot.data());
      },
    );
  });
}

Usage with Firebase Admin SDK

If you are using the firebase_admin_sdk package, you can access Firestore via the FirebaseApp instance.

import 'package:firebase_admin_sdk/firebase_admin_sdk.dart';
import 'package:google_cloud_firestore/google_cloud_firestore.dart';

final app = FirebaseApp.initializeApp();
final firestore = app.firestore(); // Returns a Firestore instance from this package

Standalone Usage

You can initialize Firestore directly using Application Default Credentials or by providing a service account.

import 'dart:io';
import 'package:google_cloud_firestore/google_cloud_firestore.dart';

// Option 1: Use Application Default Credentials (ADC)
// Recommended for Google environments like Cloud Run, App Engine, etc.
final firestore = Firestore();

// Option 2: With a service account file
final firestoreWithSA = Firestore(
  settings: Settings(
    credential: Credential.fromServiceAccount(
      File('path/to/service-account.json'),
    ),
  ),
);

// Option 3: With explicit parameters
final firestoreWithParams = Firestore(
  settings: Settings(
    projectId: 'my-project',
    credential: Credential.fromServiceAccountParams(
      email: 'xxx@xxx.iam.gserviceaccount.com',
      privateKey: '-----BEGIN PRIVATE KEY-----...',
      projectId: 'my-project',
    ),
  ),
);

Basic Operations

Set / Update / Delete

final ref = firestore.collection('users').doc('user-id');

// Set a document (creates or overwrites)
await ref.set({'name': 'John Doe', 'age': 27});

// Update specific fields
await ref.update({'age': 28});

// Delete a document
await ref.delete();

Get / Query

// Get a single document
final snapshot = await firestore.collection('users').doc('user-id').get();
if (snapshot.exists) {
  print(snapshot.data());
}

// Query a collection
final querySnapshot = await firestore
    .collection('users')
    .where('age', WhereFilter.greaterThan, 18)
    .orderBy('age', descending: true)
    .get();

for (final doc in querySnapshot.docs) {
  print('${doc.id} => ${doc.data()}');
}

Get All

// Fetch multiple documents at once
final snapshots = await firestore.getAll([
  firestore.collection('users').doc('user-1'),
  firestore.collection('users').doc('user-2'),
]);

for (final snap in snapshots) {
  if (snap.exists) {
    print(snap.data());
  }
}

Transactions

Transactions allow you to read and modify documents under lock. They are committed atomically.

final balance = await firestore.runTransaction((transaction) async {
  final ref = firestore.collection('users').doc('user-id');
  final snapshot = await transaction.get(ref);
  
  final currentBalance = snapshot.exists ? snapshot.data()?['balance'] ?? 0 : 0;
  final newBalance = currentBalance + 10;
  
  transaction.update(ref, {'balance': newBalance});
  return newBalance;
});

Write Batch

Use a write batch for performing multiple writes as a single atomic operation.

final batch = firestore.batch();

batch.set(firestore.collection('users').doc('user-1'), {'name': 'Alice'});
batch.update(firestore.collection('users').doc('user-2'), {FieldPath(['age']): 30});
batch.delete(firestore.collection('users').doc('user-3'));

await batch.commit();

Bulk Writer

BulkWriter is designed for performing a large number of writes in parallel with automatic rate limiting and retries.

import 'dart:async';

final bulkWriter = firestore.bulkWriter();

for (var i = 0; i < 1000; i++) {
  unawaited(
    bulkWriter.set(
      firestore.collection('items').doc('item-$i'),
      {'index': i},
    ),
  );
}

// Wait for all writes to complete
await bulkWriter.close();

Contributing

Contributions are welcome! Please read the contributing guide to get started.

License

Apache License Version 2.0