Google Cloud Firestore Python Client

Warnings

• breaking Version 2.0.0 introduced significant interface changes due to a next-gen code generator. Method calls shifted from positional/keyword parameters to a single `request` parameter. Code using `google.cloud.firestore_v1.gapic` namespaces will likely be incompatible. Python 3.6+ became a hard requirement.
  Fix: Review the 2.0.0 migration guide in the official documentation. The library may ship `fixup_firestore_v1_keywords.py` and `fixup_firestore_admin_v1_keywords.py` scripts to assist with code modification.
• gotcha The Firestore client can hang indefinitely on authentication errors, especially when local `gcloud CLI` authentication tokens expire. This can manifest as scripts freezing without clear error messages.
  Fix: Ensure that Application Default Credentials are valid and up-to-date. For local development, run `gcloud auth application-default login` regularly. For production, ensure service account permissions and key validity.
• gotcha Queries involving multiple fields or specific operators (like `array-contains-any`, `in`) often require a composite index to be created in the Firestore console. Failing to do so results in a `FailedPrecondition: 400 The query requires an index` error at runtime.
  Fix: When encountering index errors, follow the link provided in the error message to the Firebase/Google Cloud console to create the necessary composite index. Plan for index creation during development for complex queries.
• gotcha Confusing `google-cloud-firestore` with `firebase-admin`. While `firebase-admin` internally uses `google-cloud-firestore` for its Firestore interactions, they serve different purposes. `google-cloud-firestore` is the lower-level client for general GCP projects, while `firebase-admin` is tailored for Firebase-specific services and authentication, particularly for server-side code in a Firebase project.
  Fix: Choose the appropriate library based on your project's needs: `google-cloud-firestore` for direct Google Cloud integration, `firebase-admin` for projects heavily leveraging Firebase services (Authentication, Realtime Database, etc.).
• deprecated Support for older Python versions is progressively dropped. As of `firebase-admin` v7.0.0, Python 3.7 and 3.8 were dropped, and 3.9 was deprecated. `google-cloud-firestore` itself requires Python >= 3.7.
  Fix: Ensure your Python environment is running Python 3.7 or higher. For new projects, consider Python 3.10+ for better forward compatibility.

Install

• pip install --upgrade google-cloud-firestore Install latest version

Imports

• firestore.Client

  from google.cloud import firestore
  db = firestore.Client()

  Use `google.cloud.firestore` for direct Google Cloud Firestore API access. `firebase_admin.firestore` is part of the Firebase Admin SDK, which has different use cases and authentication flows, though it internally uses `google-cloud-firestore`.

Quickstart

This quickstart demonstrates how to initialize the Firestore client, add a new document to a collection, retrieve a single document, and perform a basic query for documents. It assumes 'Application Default Credentials' are set up (e.g., via `gcloud auth application-default login` or by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path).

import os
from google.cloud import firestore

# Ensure GOOGLE_APPLICATION_CREDENTIALS environment variable is set
# e.g., export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service_account_key.json"
# Or set programmatically (less secure for production):
# from google.oauth2 import service_account
# credentials = service_account.Credentials.from_service_account_file('path/to/your/service_account_key.json')
# db = firestore.Client(credentials=credentials)

def quickstart_firestore():
    # Initialize Firestore DB client. It automatically uses Application Default Credentials.
    # Make sure you have created a Firestore database in your GCP project first.
    db = firestore.Client()

    # Add a new document to a collection 'users'
    doc_ref = db.collection('users').document('alovelace')
    doc_ref.set({
        'first': 'Ada',
        'last': 'Lovelace',
        'born': 1815
    })
    print(f"Added document: {doc_ref.id}")

    # Read a single document
    doc = doc_ref.get()
    if doc.exists:
        print(f"Document data: {doc.to_dict()}")
    else:
        print("No such document!")

    # Query for documents
    users_ref = db.collection('users')
    docs = users_ref.where('born', '<', 1900).stream()
    print("Users born before 1900:")
    for doc in docs:
        print(f"{doc.id} => {doc.to_dict()}")

if __name__ == '__main__':
    # Placeholder for environment variable setup for local testing
    # In production environments (e.g., GCE, Cloud Functions), credentials are often auto-discovered.
    if not os.environ.get('GOOGLE_APPLICATION_CREDENTIALS'):
        print("WARNING: GOOGLE_APPLICATION_CREDENTIALS environment variable not set. "
              "Using default credentials if available, or client might fail.")
    quickstart_firestore()