Firestore Python API: Quickstart Reference Guide

August 13, 2019

Dependencies

pip install firebase-admin

or

pip install google-cloud-firestore

Documentation

firebase-admin

google-cloud-firestore

Initialization with Credential

via firebase-admin

import firebase_admin
from firebase_admin import credentials
from firebase_admin import firestore

PROJECT_ID = ...

cred = credentials.Certificate('firebase-adminsdk.json')
# cred = credentials.ApplicationDefault()
default_app = firebase_admin.initialize_app(cred, {
  'projectId': PROJECT_ID,
})

firestore_client = firestore.client()

via google-cloud-firestore

from google.cloud import firestore

# firestore_client = firestore.Client()
firestore_client = firestore.Client.from_service_account_json('firestore.json')

Document Reference

Auto generate document id

doc_ref = firestore_client.collection('user').document()

Specifiy document id

doc_ref = firestore_client.collection('user').document('desmond')

NOTE: Firestore Document Id Constraints.

Nested collection

user_ref = firestore_client.collection('user').document('desmond')
claim_ref = user_ref.collection('claim').document()

Create

doc_ref = firestore_client.collection('user').document('desmond')
data = {
    'name': Desmond,
    'age': 40
}
doc_ref.set(data)

Update

doc_ref = firestore_client.collection('user').document('desmond')
data = {
    'friends': ['Jack', 'Mei Ru']
}
doc_ref.update(data)

NOTE: Firestore partial update

Delete fields

data = {
    'friends': firestore.DELETE_FIELD
}
doc_ref.update(data)

Delete

doc_ref = firestore_client.collection('user').document('desmond')
doc_ref.delete()

NOTE: Deleting a document does not delete its subcollections!

Get

doc_ref = firestore_client.collection('user').document('desmond')
doc = doc_ref.get()

if doc.exists:
    print(doc.id, doc.get('name'), doc.to_dict())

NOTE: Get Multiple Documents

Query

user_ref = firestore_client.collection('user')
query = user_ref \
    .where('country', '==', 'Malaysia') \
    .where('age', '>=', 21)
docs = query.stream()

for doc in docs:
    print(doc.id, doc.get('name'), doc.to_dict())

NOTE: Firestore query limitation

Get total row/record count

row_count = len(list(docs))

Get 1st result

doc = next(docs, None)
if doc:
    print(doc.id, doc.get('name'), doc.to_dict())

Order

query = user_ref.where('country', '==', 'Malaysia').order_by('age')
query = user_ref.where('country', '==', 'Malaysia').order_by('age', direction=firestore.Query.DESCENDING)

Batch

batch = firestore_client.batch()

number_ref = firestore_client.collection('number')

for i in range(10):
    data = {
        'sequence': i
    }
    number_ref = collection_ref.document()
    batch.set(number_ref, data)

batch.commit()

Transaction

transaction = firestore_client.transaction()

user_ref = firestore_client.collection('user').document('desmond')

@firestore.transactional
def update_user_transaction(transaction, user_ref):
    doc = user_ref.get(transaction=transaction)
    transaction.update(user_ref, {
        'name_uppercase': doc.get('name').upper()
        })


update_user_transaction(transaction, user_ref)

Increment

from google.cloud.firestore_v1 import Increment

user_ref = firestore_client.collection('user').document('desmond')
user_ref.update({'like_count': Increment(1)})

DateTime and Server Timestamp

import datetime
from google.cloud.firestore_v1 import SERVER_TIMESTAMP

user_ref = firestore_client.collection('user').document('desmond')
user_ref.set({
    'created': SERVER_TIMESTAMP,
    'local_created': datetime.datetime.now(),
    'name': 'Desmond'
    })

NOTE: Transaction failures

This work is licensed under a
Creative Commons Attribution-NonCommercial 4.0 International License.