Firestore
Firestore is a database type provided by Google Cloud with the goal of building real-time applications. The module firestore.py provides the key features for that, whether it is saving a Firestore document, connecting, or loading data.
Let's take a deeper look at the classes inside the firestore module.
FirestoreClient¶
The FirestoreClient class is designed to perform a connection with a Firestore database by setting the database name and the project name in the class instance. Below we have an implementation example of how this would look like:
from everysk.core.firestore import FirestoreClient
firestore_client = FirestoreClient(project_name='my_project', database_name='my_database')
If for some reason the project_name or the database_name are not passed as parameters to the class, we use the _DEFAULT_DATABASE variable from Google Cloud for the database_name and the EVERYSK_GOOGLE_CLOUD_PROJECT variable located inside the settings module for the database_name.
Connection¶
The connection property is used in order to return the correct connection to access Firestore. In the cases where the connection already exists we simply return it, otherwise we create a brand new connection.
Get Collection¶
A CollectionReference is an object that can be used for adding documents, retrieving document references, and querying documents.
The get_collection() method returns a CollectionReference object which refers to the collection_name inside firestore.
Document¶
A Document is used as the main storage unit in Firestore. Every document is identified by a name, the documents contain fields which are mapped to values.
The Document class can be used to perform all the different types of operations when it comes to saving, loading, and parsing documents.
In the example below we see the creation of a Document entity:
from everysk.core.firestore import Document
doc = Document()
doc
{'updated_at': None, 'firestore_id': None, 'created_at': DateTime(2024, 9, 11, 19, 47, 41, 84931, tzinfo=zoneinfo.ZoneInfo(key='UTC'))}
Now let's take a look at its different methods and properties.
Loads¶
The loads() method is designed to list all the instances of the Document class that are populated with all the firestore data according to these conditions: <, <=, ==, >=, > and in.
It accepts a field argument which indicates the field that will be used to filter, a condition argument which the filter will be made, and a value that will be used.
from everysk.core.firestore import Document
Document._config.collection_name = 'my-collection'
Document.loads(field='firestore_id', condition='==', value='my-id')
Paginated Load¶
On the other hand, the loads_paginated() method will load all documents from a specific collection using the limit argument to retrieve the data by groups, avoiding timeouts from the Google API.
As mentioned before, the limit argument is used to as a control to the number of Documents that will be retrieved. Apart from the limit argument we also have the order_by argument which is the name of the field used to sort, the fields input which is a list of strings in order to restrict the fields which will be filtered.
Loading¶
Following our thought process we arrive at the load() method, which will take the firestore_id mentioned previously and use it to retrieve all the data from Firestore that is associated with that ID.
from everysk.core.firestore import Document
doc = Document(firestore_id='id01')
doc._config.collection_name = 'my-collection'
doc.load()
Saving¶
As the name suggests, the save() method is designed with the purpose of either saving or updating a Firestore document.
from everysk.core.firestore import Document
doc = Document(firestore_id='id01')
doc._config.collection_name = 'my-collection'
doc.save()
Convert To Dictionary¶
The method to_dict() inside the Document module is used in order to convert the document object to a dictionary.
Take a look at the example below:
from everysk.core.datetime import DateTime, Date
from everysk.core.firestore import Document
doc = Document(
firestore_id='id01',
dct={'a': 1},
lst=[1,2,3],
byte=b'Text',
date=Date(2024, 11, 15),
created_at=DateTime.fromisoformat('2023-04-03T00:00:00+00:00'),
datetime=DateTime.fromisoformat('2022-01-01T10:00:00+00:00')
)
doc.to_dict()
{
'firestore_id': 'id01',
'dct': {'a': 1},
'lst': [1, 2, 3],
'byte': b'Text',
'date': '2024-11-15',
'created_at': '2023-04-03T00:00:00+00:00',
'datetime': '2022-01-01T10:00:00+00:00',
'updated_at': None
}