Firestore

Contents on this page:

• Class Table
• Connect To A Collection
• Get A Document
• Add A Document
• Update A Document
• Delete A Document
• Issue a Query
• Debugging
• Common Errors

---

Class Table

Class	Description
Firestore	Firestore module, lets user connect to collections, issue queries and request a list of documents/collections at a specified path.
FirestoreCollection	A reference to a colleciton in Firestore, used to call functions to manage documents or nested collections.
FirestoreDocument	An object representing a fetched, updated or deleted document in Firestore.
FirestoreTask	Result of any request issued through Firestore. Processes the request, emits signals and returns a result.
FirestoreQuery	An object representing a query to Firestore, used as a parameter for the query() function.

---

Firestore

Firebase.Firestore

Functions	Description
collection(collection_path : String) -> FirestoreCollection	Create a reference to a collection inside Firestore. Returns a reference to a collection.
list(collection_path : String) -> FirestoreTask	List all contents of a collection in Firestore. Returns a FirestoreTask issuing the request.
query(firestore_query : FirestoreQuery) -> FirestoreTask	Issue a query on Firestore. Returns a FirestoreTask issuing the request.

Properties	Description
collections : Dictionary	A Dictionary containing all referenced collections.
auth : Dictionary	A Dictionary containing all auth info for the current authenticated user.

Signals	Description
listed_documents(documents : Array)	Emitted when the list() request is processed successfully by a FirestoreTask.
result_query(result : Array)	Emitted when the query() request is processed successfully by a FirestoreTask.
error(error : Dictionary)	Emitted when a query() or list() request is not processed successfully by a FirestoreTask.

***

FirestoreCollection

Firebase.Firestore.collection()

Functions	Description
add(document_id : String, fields : Dictionary) -> FirestoreTask	Add a Document to a Collection. If document_id is left to "" the id will be randomically given by Firebase.
update(document_id : String, fields : Dictionary) -> FirestoreTask	Update a specified Document to a Collection. If document_id is left to "" the id will be randomically given by Firebase, creating a new Document. If the document with the given document_id does not exist, it will be created.
get(document_id : String) -> FirestoreTask	Get a specific Document.
delete(document_id : String) -> FirestoreTask	Delete a specific Document.

Properties	Description
config : Dictionary	Configuration settings for this plugin.
auth : Dictionary	Authentication dictionary to issue requests as a logged user.
collection_name : String	The referenced collection's name

Signals	Description
add_document(document_added : FirestoreDocument)	Emitted when the add() request is processed by a FirestoreTask.
update_document(document_updated : FirestoreDocument)	Emitted when the update() request is processed by a FirestoreTask.
get_document(document_got : FirestoreDocument)	Emitted when the get() request is processed by a FirestoreTask.
delete_document()	Emitted when the delete() request is processed by a FirestoreTask.
error(code, status, message)	Emitted when a request has not processed correctly by a FirestoreTask.

---

FirestoreDocument

FirestoreDocument.new() or from a signal

Functions	Description
static dict2fields(dictionary : Dictionary) -> Dictionary	Parse a GDScript Dictionary to a Firebase dictionary of fields.
static fields2dict(fields : Dictionary) -> Dictionary	Parse a Firebase dictionary of fields to a GDScript Dictionary.
_to_string() -> String	Automatically called on print(document) to print a formatted document.

Properties	Description
doc_name : String	The document name.
doc_fields : Dictionary	The document fields, as a GDScript Dictionary.
create_at : String	Timestamp of creation date.

Signals	Description

***

FirestoreTask

returned by a Firestore request

Functions	Description

Properties	Description
data : Variant	Contains the result of a processed Task.
action : int	Contains the action the task is processing or has processed.

Signals	Description
task_finished(result : Variant)	Emitted when a Task has been processed. Returns the result of the request as a parameter. This is a lower level of signal communication between FirestoreTasks, Firestore and your application.
listed_documents(documents : Array)	Emitted when the list() request is processed successfully.
result_query(result : Array)	Emitted when the query() request is processed successfully.
error(error : Dictionary)	Emitted when a query() or list() request is not processed successfully.
add_document(document_added : FirestoreDocument)	Emitted when the add() request is processed.
update_document(document_updated : FirestoreDocument)	Emitted when the update() request is processed.
get_document(document_got : FirestoreDocument)	Emitted when the get() request is processed.
delete_document()	Emitted when the delete() request is processed.
error(code, status, message)	Emitted when a request has not processed correctly.

---

FirestoreQuery

FirestoreQuery.new()

Properties	Description
doc_name : String	The document name.
doc_fields : Dictionary	The document fields, as a GDScript Dictionary.
create_at : String	Timestamp of creation date.

Functions	Description
select(fields : Variant)	A SELECT query on a Collection, fields can be an Arrat/PoolStringArray of fields, or just a String for a single field.
from(collection_id : String, all_descendants : bool = true)	A FROM query to a single Collection.
from_many(collections : Array)	A FROM query on multiple Collections. collections must be an Array of Arrays of type [collection_id:String, all_descendants:bool].
where(field : String, operator : FirestoreQuery.OPERATOR, value : Variant, chain : int = -1)	A WHERE query to match fields' values with Operators. operator must be a FirestoreQuery.Operator element. chain can be OPERATOR.AND or OPERATOR.OR to chain multiple where() in sequence. The last one in a chain (or if a single one) must have chain = -1 (automatically injected).
order_by(field : String, direction : int = DIRECTION.ASCENDING)	A ORDER BY query on a Collection. Direction must be of type FirestoreQuery.DIRECTION.
order_by_fields(order_field_list : Array)	A ORDER BY query on a Collection based on multiple fields. order_field_list must be an Array of Arrays with structure [field : String, order : DIRECTION].
start_at(value : Variant, before : bool)	A START AT query on a Collection. value can be of any type, define if you want to list values before or not the specified one.
end_at(value : Variant, before : bool)	A END AT query on a Collection. value can be of any type, define if you want to list values before or not the specified one.
offset(offset : int)	A OFFSET query on a Collection to define the amount of results to be skipped.
limit(limit : int)	A LIMIT query on a Collection to define the amount of results to be returned.

Back

---

Connect To A Collection

Note you need to be authenticated for this to work

Firebase.Firestore.collection('COLLECTION_NAME')

The following will return a collection from Firestore called firestore_collection. This collection can be called on later when adding or getting documents from it.

var firestore_collection : FirestoreCollection = Firebase.Firestore.collection('COLLECTION_NAME')

Back

---

Get A Document

Note you need to be authenticated and connected to a collection for this to work

.get(documentId : String) -> FirestoreTask

Note: Unlike collections (which is just a reference) this function won't return directly a real document, but will request the specified document which will be returned with a signal.
The following methods will let you return a document from Firestore with the DOCUMENT_ID that is specified to an object called firestore_document of type FirestoreDocument:

1. Call the .get() function and than yield for the collection to return it with a signal

var collection : FirestoreCollection = Firebase.Firestore.collection(COLLECTION_ID)
collection.get(DOCUMENT_ID)
var document : FirestoreDocument = yield(collection, "get_document")

- or -

var collection : FirestoreCollection = Firebase.Firestore.collection(COLLECTION_ID)
var document_task : FirestoreTask = collection.get(DOCUMENT_ID)
var document : FirestoreDocument = yield(document_task, "get_document")

2. Connect a signal to the collection and get the document separately

var collection : FirestoreCollection = Firebase.Firestore.collection(COLLECTION_ID)
collection.connect("get_document",self,"_on_get_document")
collection.get(DOCUMENT_ID)

[...]

func _on_get_document(document : FirestoreDocument) -> void:
	pass

The following will parse the data into a human readable format with automatic parsing, from Firebase format to Dictionary.

print(firestore_document)

Back

---

Add A Document

Note you need to be authenticated and connected to a collection for this to work

.add(documentId : String, fields : Dictionary = {}) -> FirestoreTask

The following will add a new document into Firestore by first creating the object, and then adding it.

var add_task : FirestoreTask = firestore_collection.add("DOCUMENT_ID", {'name': 'Document Name', 'active': 'true'})
var document : FirestoreDocument = yield(add_task, "task_finished")

- or -

var document : FirestoreDocument = yield(add_task, "add_document")

- or -

var document : FirestoreDocument = yield(Firebase.Firestore, "add_document")

Internally, the FirestoreCollection instance will call the dict2fields() , used to convert the dictionary of fields into the correct format for Firestore to use.

Note: if "DOCUMENT_ID" is left as an empty String like "" Firebase will assign to this document a random name. This name will be returned through FirestoreCollection signals.

Back

---

Update A Document

Note you need to be authenticated and connected to a collection for this to work

.update(documentId : String, fields : Dictionary = {}) -> FirestoreTask

The following will update document in Firestore.

var up_task : FirestoreTask = firestore_collection.update("DOCUMENT_ID", {'name': 'Document Name', 'active': 'true'})
var document : FirestoreDocument = yield(up_task, "task_finished")

- or -

var document : FirestoreDocument = yield(up_task, "update_document")

- or -

var document : FirestoreDocument = yield(Firebase.Firestore, "update_document")

Internally, the FirestoreCollection instance will call the dict2fields() , used to convert the dictionary of fields into the correct format for Firestore to use.

Back

---

Delete A Document

Note you need to be authenticated and connected to a collection for this to work

.delete(documentId : String) -> FirestoreTask

The following will delete a new document in Firestore.

var del_task : FirestoreTask = firestore_collection.delete("DOCUMENT_ID")
var document : FirestoreDocument = yield(del_task, "task_finished")

Back

---

Issue a Query

Note you need to be authenticated for this to work

Firebase.Firestore.query(FirestoreQuery.new()) -> FirestoreTask

The following query some documents from a collection based on the value of a field.

# create a query
var query : FirestoreQuery = FirestoreQuery.new()

# FROM a collection
query.from("user_list")	

# WHERE points > 20
query.where("points", FirestoreQuery.OPERATOR.GREATER_THAN, 20)

# ORDER BY points, from the user with the best score to the latest
query.order_by("points", FirestoreQuery.DIRECTION.DESCENDING)

# LIMIT to the first 10 users
query.limit(10)

# Issue the query
var query_task : FirestoreTask = Firebase.Firestore.query(query)

# Yield on the request to get a result
var result : Array = yield(query_task, "task_finished")

Note: each FirestoreQuery function will always return itself, so queries component can be concatenated to create single-line queries

# Do all the previous, but in one line
var query : FirestoreQuery = FirestoreQuery.new().from("user_list").where("points", FirestoreQuery.OPERATOR.GREATER_THAN, 20).order_by("points", FirestoreQuery.DIRECTION.DESCENDING).limit(10)

var result : Array = yield(Firestore.Firebase.query(query), "result_query")

Back

---

Debugging

Note you need to be authenticated and connected to a collection for this to work

There are some signals that can be connected to for the purpose of debugging

• Signal ("add_document", document )
• Signal ("get_document", document )
• Signal ("update_document", document )
• Signal ("delete_document")
• Signal ("error",bod.error.code,bod.error.status,bod.error.message)

These signals need to be connected to from the collection

firestore_collection.connect("add_document", self, "on_document_add")
firestore_collection.connect("get_document", self, "on_document_get")
firestore_collection.connect("update_document", self, "on_document_update")
firestore_collection.connect("delete_document", self, "on_document_delete")
firestore_collection.connect("error", self, "on_document_error")

Back

---

Common Errors

Unauthorized

This occurs when you are trying to do something with a collection but have not logged in

Back