Firestore

Firestore

Cloud Firestore is a flexible, scalable database for mobile, web, and server development from Firebase and Google Cloud. Like Firebase Realtime Database, it keeps your data in sync across client apps through real-time listeners and offers offline support for mobile and web so you can build responsive apps that work regardless of network latency or Internet connectivity. Cloud Firestore also offers seamless integration with other Firebase and Google Cloud products, including Cloud Functions. Check the official page for more information.

Setup

Before starting to use any Firebase extensions, you are required to follow some initial configuration steps.

Note

The SDK version is only available for the Android, iOS and Web targets; if you're targeting other devices please follow the steps for REST API.

• Create Project (skip this if you already have a project)
• Firebase Console (enabling Firebase Firestore)
• Platform Setup (configuring SDKs or REST API)

Functions

The Firestore extension was implemented using a fluent-API (method chaining) approach and the entry point for interacting with the database is using the function FirebaseFirestore, which will return a dbReference, that can be either a <dbCollection> or a <dbDocument>.

Note

The write functions <dbReference>.Set and <dbReference>.Update can take a struct, an array or a JSON encoded string.

The following functions are given for working with the Firebase Firestore extension:

• FirebaseFirestore
• <dbReference>.Child
• <dbReference>.Delete
• <dbReference>.Listener
• <dbReference>.ListenerRemove
• <dbReference>.ListenerRemoveAll
• <dbReference>.Parent
• <dbReference>.Read
• <dbReference>.Set
• <dbReference>.Update
• <dbReference>.Query

Filter Functions

The functions given below should only be used for filtering data when querying the database using the <dbReference>.Query function given above.

• <dbReference>.EndAt
• <dbReference>.Limit
• <dbReference>.OrderBy
• <dbReference>.StartAt
• <dbReference>.Where
• <dbReference>.WhereEqual
• <dbReference>.WhereGreaterThan
• <dbReference>.WhereGreaterThanOrEqual
• <dbReference>.WhereLessThan
• <dbReference>.WhereLessThanOrEqual
• <dbReference>.WhereNotEqual

Structs

This module offers a collection of structs, which serve as custom data models for organizing and structuring data. Explore the provided structs to better understand the relationships between data elements and simplify your data manipulation tasks.

• dbReference

---

Back To Top

<dbReference>.Child

The method appends the given relative path to the current path of a dbReference.

Syntax:

<dbReference>.Child(path)

Argument	Type	Description
path	String	The relative child path.

Returns:

dbReference

Example:

var _rootPath = "database";
var _dbReference = FirebaseFirestore(_rootPath).Child("players/hero");

The code sample above will create a <dbReference> to the "database" path and afterwards appends the relative path "player/hero" to it, meaning the resulting reference (dbReference) now points to the "database/player/hero" path.

---

Back To Top

<dbReference>.Delete

This method deletes the current document reference and returns a listener identifier.

Warning

This function will only work on dbDocuments; if you pass in a dbCollection it won't be deleted.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

<dbReference>.Delete()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "FirebaseFirestore_Document_Delete"
listener	Real	The asynchronous listener ID.
path	Boolean	The path of the database reference.
status	Real	The HTTP status response code (see reference)
errorMessage	String	The readable error message

Example:

listenerId = FirebaseFirestore("myCollection/oldDoc").Delete();

In the code above we first get the reference to a database path ("myCollection/oldDoc") and then delete that entry. The function call will then return a listener ID (listenerId) that can be used inside a Social Async Event.

if (async_load[? "type"] == "FirebaseFirestore_Document_Delete")
{
    if (async_load[? "status"] == 200)
    {
        show_debug_message("Document was deleted successfully.");
    }
    else
    {
        var _errorMessage = async_load[?"errorMessage"];
    }
}

The code above matches the response against the correct event type, providing a success message if status is valid.

---

Back To Top

FirebaseFirestore

This function is the entry point for database interactions using the Firebase Firestore extension. It returns a dbReference that can further be modified and configured using chained methods.

Note

Firebase Firestore implements a fluent-API meaning almost all functions return self allowing them to be chained and for you to build complex database interactions while keeping the code clean and easy to follow. Entries in the database are structs and are referred as < dbReference > in this documentation (they can be either a <dbDocument> or a <dbCollection> depending on the path). These, under the hood, are structs that point to a specific path in the database (they are NOT the actual entry).

Syntax:

FirebaseFirestore(path=undefined)

Argument	Type	Description
path	String	The path reference to document or collection

Returns:

dbReference

Example:

var _data = { name: "Hero", level: 99 };
var _json = json_stringify(_data);
FirebaseFirestore("playersCollection/heroDocument").Set(_json);

The code sample above will create a data structure (_data) that will be stored inside the database. This data needs to be converted to string using the json_stringify function. Afterwards it creates a <dbReference> to the path "playersCollection/heroDocument" and calls the <dbReference>.Set method on it (setting the database path to the specified value).

---

Back To Top

<dbReference>.Listener

The method listens for changes to a given document in the database. If you need to stop listening to changes you can use <dbReference>.ListenerRemove for a specific database reference or <dbReference>.ListenerRemoveAll to remove all listeners.

Warning

When you no longer need to listen to changes make sure to remove the listeners; not doing so can lead to memory leaks.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

<dbReference>.Listener()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "FirebaseFirestore_Document_Listener" or "FirebaseFirestore_Collection_Listener"
listener	Real	The asynchronous listener ID.
path	String	The path of the database reference.
status	Real	The HTTP status response code (see reference)
value	String	A JSON formatted string of either a struct (document) or array (collection)
errorMessage	String	The readable error message

Example:

listenerId = FirebaseFirestore("myCollection/newDoc").Listener();

The code above starts listening for updates on the document ("myCollection/newDoc"). If this reference gets updated, set or deleted an Async event will be triggered. The function call will return a listener ID (listenerId) that can be used inside a Social Async Event.

if (async_load[? "type"] == "FirebaseFirestore_Document_Listener")
{
    if (async_load[? "status"] == 200)
    {
        show_debug_message("Changes were made to this document");
    }
    else
    {
        var _errorMessage = async_load[? "errorMessage"];
    }
}

The code above matches the response against the correct event type and logs when changes are made to the database reference being listened to.

---

Back To Top

<dbReference>.ListenerRemove

This function removes a previously created listener (that was created using the function <dbReference>.Listener).

Tip

If you wish to remove all created listeners use the function <dbReference>.ListenerRemoveAll instead.

Syntax:

<dbReference>.ListenerRemove(listenerId)

Argument	Type	Description
listenerId	Real	The listener ID to be removed.

Returns:

N/A

Example:

listenerId = FirebaseFirestore("myCollection/myDoc").Listener();

// Some time later
FirebaseFirestore().ListenerRemove(listenerId);

The code sample above starts by creating a listener to a database reference path (using the <dbReference>.Listener function) which returns a listener ID (listenerId); at a later stage it removes that listener.

---

Back To Top

<dbReference>.ListenerRemoveAll

This function removes all previously created listeners (that were created using the function <dbReference>.Listener).

Tip

If you wish to remove a specific listener use the function <dbReference>.ListenerRemove instead.

Syntax:

<dbReference>.ListenerRemoveAll()

Returns:

N/A

Example:

listenerId1 = FirebaseFirestore("myCollection/myDoc").Listener();
listenerId2 = FirebaseFirestore("myCollection/otherDoc").Listener();
listenerId3 = FirebaseFirestore("myCollection").Listener();

// Some time later
FirebaseFirestore().ListenerRemoveAll();

The code above creates three listeners (using the <dbReference>.Listener function) and after some time it removes them all.

---

Back To Top

<dbReference>.Parent

This method goes up the hierarchy to the parent path of the current <dbReference> struct.

Syntax:

<dbReference>.Parent()

Returns:

dbReference

Example:

var _dbPath = "database/player/hero";
var _dbReference = FirebaseFirestore(_dbPath).Parent();

The code above creates a <dbReference> to the "database/player/hero" path and afterwards goes up to the parent path meaning the resulting reference (_dbReference) now points to the "database/player" path.

---

Back To Top

<dbReference>.Read

This method reads the current database reference and returns a listener identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

<dbReference>.Read()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "FirebaseFirestore_Document_Read" or "FirebaseFirestore_Collection_Read"
listener	Real	The asynchronous listener ID.
path	String	The path of the database reference.
status	Real	The HTTP status response code (see reference)
value	String	A JSON formatted string of either a struct (document) or array (collection)
errorMessage	String	The readable error message

Example:

listenerId = FirebaseFirestore("myCollection/myDoc").Read();

The code above first gets the reference to a database document ("myCollection/oldDoc") and then reads that entry. The function call will then return a listener ID (listenerId) that can be used inside a Social Async Event.

if (async_load[? "type"] == "FirebaseFirestore_Document_Read")
{
    if (async_load[? "status"] == 200)
    {
        show_debug_message("Document data is: " + async_load[? "value"]);
    }
    else
    {
        var _errorMessage = async_load[?"errorMessage"];
    }
}

The code above matches the response against the correct event type, providing the document data if the task succeeded.

---

Back To Top

<dbReference>.Set

This method creates or overwrites a document on the database. If <dbReference> is a collection then a document will be automatically created with an auto-generated name. If you wish to update an existing document instead of replacing it use <dbReference>.Update instead. This function returns a listener identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

<dbReference>.Set(json)

Argument	Type	Description
json	String or Struct or Array	A struct, array or JSON formatted string to fill the document with.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "FirebaseFirestore_Document_Set" or "FirebaseFirestore_Collection_Add"
listener	Real	The asynchronous listener ID.
path	String	The path of the database reference.
status	Real	The HTTP status response code (see reference)
errorMessage	String	The readable error message

Example:

var _data = { name: "Hero", level: 100 };
var _json = json_stringify(_data);
listenerId = FirebaseFirestore("myCollection/newDoc").Set(_json);
// OR:
// listenerId = FirebaseFirestore("myCollection/newDoc").Set(_data);

The code above creates a JSON formatted string of a struct using the json_stringify function (or directly from the struct as shown in the comments) and then sets the database document ("myCollection/newDoc") to the new string. The function call will then return a listener ID (listenerId) that can be used inside a Social Async Event.

if (async_load[? "type"] == "FirebaseFirestore_Document_Set")
{
    if (async_load[? "status"] == 200)
    {
        show_debug_message("Set() function call succeeded!");
    }
    else
    {
        var _errorMessage = async_load[? "errorMessage"];
    }
}

The code above matches the response against the correct event type and logs the success of the task.

---

Back To Top

<dbReference>.Update

This method updates the given document on the database, without deleting any omitted keys. This function returns a listener identifier.

Note

This function will only work on dbDocuments; if you pass in a dbCollection it won't be updated.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

<dbReference>.Update(json)

Argument	Type	Description
json	String or Struct or Array	A struct, array or JSON formatted string to fill the document with.

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "FirebaseFirestore_Document_Update"
listener	Real	The asynchronous listener ID.
path	String	The path of the database reference.
status	Real	The HTTP status response code (see reference)
errorMessage	String	The readable error message

Example:

var _data = { level: 200 };
var _json = json_stringify(_data);
listenerId = FirebaseFirestore("myCollection/newDoc").Update(_json);
// OR:
// listenerId = FirebaseFirestore("myCollection/newDoc").Update(_data);

The code above creates a JSON formatted string of a struct using the json_stringify function (or directly from the struct as shown in the comments) and then updates the document ("myCollection/newDoc") with the new key/value pairs (omitted keys will not be deleted). The function call will then return a listener ID (listenerId) that can be used inside a Social Async Event.

if (async_load[? "type"] == "FirebaseFirestore_Document_Update")
{
    if (async_load[? "status"] == 200)
    {
        show_debug_message(".Update() function call succeeded!");
    }
    else
    {
        var _errorMessage = async_load[? "errorMessage"];
    }
}

The code above matches the response against the correct event type and logs the success of the task.

---

Back To Top

<dbReference>.EndAt

This method is a filter that should be used when performing a <dbReference>.Query that is ordered by a specific field. The filter assures that the queried documents stop at a specific value (relative to the field specified in <dbReference>.OrderBy).

Syntax:

<dbReference>.EndAt(value)

Argument	Type	Description
value	Real or String	The value to stop the query at.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").OrderBy("Points", "ASCENDING").EndAt(99).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" ordered by the "Points" field in an ascending order (using the <dbReference>.OrderBy function) ending the query results when the "Points" reach the value 99.

---

Back To Top

<dbReference>.Limit

This method is a filter that should be used when performing a <dbReference>.Query that will limit the number of queried documents.

Syntax:

<dbReference>.Limit(value)

Argument	Type	Description
value	Real	The maximum number of documents to return.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").OrderBy("Points", "ASCENDING").Limit(10).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" ordered by the "Points" field in an ascending order (using the <dbReference>.OrderBy function) and returns the first 10 elements.

---

Back To Top

<dbReference>.OrderBy

This method is a filter that should be used when performing a <dbReference>.Query that will return documents ordered by a specific field.

Note

This function does not ensure that the data you receive from your query will be sorted, however any other filter functions being called after this will see the data sorted in the correct order. For example, if you call this function to sort a collection in an ascending order and then call .Limit(5), you will get the first 5 items from that sorted list however those 5 items may not get to you in the same order.

Syntax:

<dbReference>.OrderBy(path, direction)

Argument	Type	Description
path	String	The path to the field to be used for sorting/ordering
direction	String	The direction to order by "ASCENDING" or "DESCENDING"

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").OrderBy("Points", "ASCENDING").Limit(10).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" ordered by the "Points" field in an ascending order and returns the first 10 elements (using the <dbReference>.Limit function).

---

Back To Top

<dbReference>.Query

This method executes a query and returns a listener identifier.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

<dbReference>.Query()

Returns:

Real

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "FirebaseFirestore_Collection_Query"
listener	Real	The asynchronous listener ID.
path	String	The path of the database reference.
status	Real	The HTTP status response code (see reference)
value	String	A JSON formatted string of an array
errorMessage	String	The readable error message

Example:

listenerId = FirebaseFirestore("myCollection").OrderBy("Points", "ASCENDING").Limit(10).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" ordered by the "Points" field in an ascending order and returns the first 10 elements (using the <dbReference>.Limit function). The function call will then return a listener ID (listenerId) that can be used inside a Social Async Event.

if (async_load[? "type"] == "FirebaseFirestore_Collection_Query")
{
    if (async_load[? "status"] == 200)
    {
        show_debug_message(async_load[? "value"]);
    }
    else
    {
        var _errorMessage = async_load[? "errorMessage"];
    }
}

The code above matches the response against the correct event type and logs the results of the performed query.

---

Back To Top

<dbReference>.StartAt

This method is a filter that should be used when performing a <dbReference>.Query that is ordered by a specific field. The filter assures that the queried documents start at a specific value (relative to the field specified in <dbReference>.OrderBy).

Syntax:

<dbReference>.StartAt(value)

Argument	Type	Description
value	Real or String	The value to start the query at.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").OrderBy("Points", "ASCENDING").StartAt(10).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" ordered by the "Points" field in an ascending order (using the <dbReference>.OrderBy function) starting the query results when the "Points" fields is higher then 10.

---

Back To Top

<dbReference>.Where

This method is a filter that should be used when performing a <dbReference>.Query and allows you to perform comparison operations on a field's values.

Syntax:

<dbReference>.Where(path, operation, value)

Argument	Type	Description
path	String	The path to field.
operation	String	Any one of the following operations (as strings): "==","!=","",">",">=","="
value	Real or String	The value used for the comparison.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").Where("Points", ">=", 1000).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" returning every element where the "Points" field is more than or equal to 1000.

---

Back To Top

<dbReference>.WhereEqual

This method is a filter that can be used when performing a <dbReference>.Query and selects elements where the field's path value is equal to value.

Syntax:

<dbReference>.WhereEqual(path, value)

Argument	Type	Description
path	String	The path to field.
value	Real or String	The value used for the comparison.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").WhereEqual("Points", 1000).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" returning every element where the "Points" field is equal to 1000.

---

Back To Top

<dbReference>.WhereGreaterThan

This method is a filter that can be used when performing a <dbReference>.Query and selects elements where the field's path value is greater than value.

Syntax:

<dbReference>.WhereGreaterThan(path, value)

Argument	Type	Description
path	String	The path to field.
value	Real or String	The value used for the comparison.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").WhereGreaterThan("Points", 1000).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" returning every element where the "Points" field is greater than 1000.

---

Back To Top

<dbReference>.WhereGreaterThanOrEqual

This method is a filter that can be used when performing a <dbReference>.Query and selects elements where the field's path value is greater than or equal to value.

Syntax:

<dbReference>.WhereGreaterThanOrEqual(path, value)

Argument	Type	Description
path	String	The path to field.
value	Real or String	The value used for the comparison.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").WhereGreaterThanOrEqual("Points", 1000).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" returning every element where the "Points" field is greater than or equal to 1000.

---

Back To Top

<dbReference>.WhereLessThan

This method is a filter that can be used when performing a <dbReference>.Query and selects elements where the field's path value is less than value.

Syntax:

<dbReference>.WhereLessThan(path, value)

Argument	Type	Description
path	String	The path to field.
value	Real or String	The value used for the comparison.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").WhereLessThan("Points", 1000).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" returning every element where the "Points" field is less than 1000.

---

Back To Top

<dbReference>.WhereLessThanOrEqual

This method is a filter that can be used when performing a <dbReference>.Query and selects elements where the field's path value is less than or equal to value.

Syntax:

<dbReference>.WhereLessThanOrEqual(path, value)

Argument	Type	Description
path	String	The path to field.
value	Real or String	The value used for the comparison.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").WhereLessThanOrEqual("Points", 1000).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" returning every element where the "Points" field is less than or equal to 1000.

---

Back To Top

<dbReference>.WhereNotEqual

This method is a filter that can be used when performing a <dbReference>.Query and selects elements where the field's path value is not equal to value.

Syntax:

<dbReference>.WhereNotEqual(path, value)

Argument	Type	Description
path	String	The path to field.
value	Real or String	The value used for the comparison.

Returns:

dbReference

Example:

listenerId = FirebaseFirestore("myCollection").WhereNotEqual("Points", 1000).Query();

The code above performs a query (using the <dbReference>.Query function) on the database reference "myCollection" returning every element where the "Points" field is not equal to 1000.

---

Back To Top

dbReference

This struct is used by the Firestore functions. You use methods on it to build and refine the query.

See the examples included with the various functions.

This struct is referenced by the following functions:

• <dbReference>.Child
• FirebaseFirestore
• <dbReference>.Parent
• <dbReference>.EndAt
• <dbReference>.Limit
• <dbReference>.OrderBy
• <dbReference>.StartAt
• <dbReference>.Where
• <dbReference>.WhereEqual
• <dbReference>.WhereGreaterThan
• <dbReference>.WhereGreaterThanOrEqual
• <dbReference>.WhereLessThan
• <dbReference>.WhereLessThanOrEqual
• <dbReference>.WhereNotEqual