Firestore
This page describes how to connect your application to your Firestore database and use queries to manage its content.
Connect to Firestore

To add a Firestore datasource, click the (+) sign in the Explorer tab next to Datasources. On the next screen, select the Firestore button. Your datasource is created and you are taken to a screen to configure its settings.
The Firestore plugin requires three pieces of information which are available from your project's settings page in the Firebase Console. To find the settings, navigate to your Firebase project's dashboard and click the Gear icon next to Project Overview.
- Project ID: Find this value under the General tab in your project settings.
- Database URL: Build this value from your Project ID:
https://<project-id>.firebaseio.com
- Service Account Credentials: Under the Service Accounts tab in your project settings, click Generate new private key. Open the downloaded file and copy-paste its entire contents into the Service Account Credentials field in your Appsmith datasource configuration.
Click the Test button in Appsmith to check that your configuration is valid, and Save the datasource when you're done.
Create queries
You can write queries to fetch or write data to Firestore by selecting the + New Query button on the Firestore datasource page, or by clicking (+) next to Queries/JS in the Explorer tab and selecting your Firestore datasource. You'll be brought to a new query screen where you can write queries.

Fetch documents
There are two commands available for fetching your data:
- List Documents: Fetch all documents in a given collection. Allows filtering results by additional parameters.
- Get Document: Fetch a single document by its path.
Record data is returned according to the format:
{
"date_of_birth": "1989-06-07",
"_ref": {
"path": "users/2",
"id": "2"
},
"name": "Amal",
"email": "amal@example.com"
}
Parameter | Description |
---|---|
Where | Defines conditions that documents' column values must meet to appear in your results. |
Order By | Sorts query results by a column value. Expects an array containing a single string which is the column's name. Sorts by the given column in ascending order by default, or you can add a "-" prefix to sort in descending order. (["name] / ["-name"] ). |
Start After | Sets a starting pagination cursor for searching documents. Expects an object that is a whole document result. |
End Before | Sets an ending pagination cursor for searching documents. Expects an object that is a whole document result. |
Limit Documents | Sets a limit for how many documents may be returned by the query. |
Server-side Pagination
To set up server-side pagination for your List Documents query called ListUsers
and a table called UsersTable
:
- In the properties for your
ListUsers
query, set Start After to:{{ ListUsers.data[ ListUsers.data.length - 1 ] }}
- Set End Before to:
{{ ListUsers.data[0] }}
- Set Limit Documents to:
{{ UsersTable.pageSize }}
- In the
UsersTable
's properties on the canvas, set Table Data to:{{ ListUsers.data }}
- Turn on the table's Server side pagination property and set its onPageChange property to execute your
ListUsers
query.
When you click the page buttons in the table's header, the pages should now cycle through your dataset.
Example
Fetch all documents from a Firestore collection
users
, 10 at a time, and put them into a table widgetUsersTable
.
Setup: create a Table widget called UsersTable
to display your data. Create a query called ListUsers
based on your Firestore datasource.
- Select the List command for your query, and enter
users
in the Collection field. - In the properties for your
ListUsers
query, set Start After to{{ ListUsers.data[ ListUsers.data.length - 1 ] }}
. - Set End After to
{{ ListUsers.data[0] }}
. - Set Limit Documents to
{{ UsersTable.pageSize }}
. - On the canvas in the
UsersTable
's properties, set Table Data to{{ ListUsers.data }}
. - Turn on the table's Server side pagination property and set its onPageChange property to execute your
ListUsers
query.
Your table should populate with data once your query is run.
Create a document
Use the Create Document command to create a new document in a specified collection and path. Alternatively, use the Add Document to Collection command to create a new document in a given collection, allowing Firestore to auto-generate the document's path.
After filling in the desired collection/path, enter your document data in the Body field of the query:
{
"name": "Nick",
"email": "nick@example.com",
"date_of_birth": "1995-11-11"
}
Parameter | Description |
---|---|
Timestamp Path (optional) | When filled, adds a timestamp value in the created document under the key name you provide. Expects an array with a single string value (["timestamp"] ). |
Example
Create a new document in the
users
collection with values forname
,date_of_birth
.
Setup:
Create a query
CreateUser
based on your Firestore datasource, and set it to use the Add Document to Collection command.Set the Collection/Document Path field to
users
.To gather data for the new record, create a JSON Form on the canvas called
NewUserForm
. Add Source Data to the JSON Form to create input fields:{
name: "",
email: "",
date_of_birth: ""
}In JSON Form's Submit button properties, configure the onClick event to execute your query:
// Submit button's onClick event
{{ CreateUser.run() }}Once these form fields are filled out, you can add their values to your query in the Body field like below:
// in the Body field of your query
{{
{
"name": NewUserForm.formData.name,
"email": NewUserForm.formData.email,
"date_of_birth": NewUserForm.formData.date_of_birth
}
}}
When the Submit button is clicked, your query is executed and the new record is inserted into your Firestore collection.
Update a document
Use the Update Document command to modify an existing document.
Provide the target's Collection/Document Path, and enter your document data in the Body field of the query.
When using Update Document, you only need to provide the fields that have been changed. If you use Upsert Document, your query completely replaces whatever record exists at the given path, so be sure to provide all necessary fields including those that have not changed.
{
"name": "Nicholas",
"email": "nicholas@example.com"
}
Parameter | Description |
---|---|
Delete Key Path | When filled, deletes the key/value pair with the name that you provide. For example, passing ["name"] will delete the name property in the document. |
Timestamp Path | When filled, adds a timestamp value in the created document under the key name you provide. Expects an array with a single string value (["timestamp"] ). |
Example
Update the
name
andusers
collection.
Setup: create a Table widget called UsersTable
to display your data. Use a List Documents query to display your collection of documents in the table.
Create a query
UpdateUser
based on your Firestore datasource, and set it to use the Update Document command.Set the Collection/Document Path field to the
_ref.path
property of the record you're updating:{{ UsersTable.selectedRow._ref.path }}
To gather data for the new record, create a JSON Form on the canvas called
UpdateUserForm
. Add Source Data to the JSON Form to create input fields. Reference the existing row in the Table widget to have the form fields pre-filled:{{
{
name: UserTable.selectedRow.name,
email: UserTable.selectedRow.email,
date_of_birth: UserTable.selectedRow.date_of_birth
}
}}In JSON Form's Submit button properties, configure the onClick event to execute your query:
// Submit button's onClick event
{{ UpdateUser.run(() => ListUsers.run(), () => {}) }}- The onSuccess callback is used above to refresh your table data after the operation is complete.
Once these form fields are filled out, you can add their values to your query in the Body field like below:
// in the Body field of your query
{{
{
"name": UpdateUserForm.formData.name,
"email": UpdateUserForm.formData.email,
"date_of_birth": UpdateUserForm.formData.date_of_birth
}
}}
When the Submit button is clicked, your query is executed and the new values are updated on the document.
Deleting a document
Use the Delete Document command to delete an existing document by its collection/path.
Example
Delete a document from the
users
collection.
Setup: create a Table widget called UsersTable
to display your data. Use a List Documents query to display your collection of documents in the table.
Create a query
DeleteUser
based on your Firestore datasource, and set it to use the Delete Document command.Set the Collection/Document Path field to the
_ref.path
property of the record you're deleting:{{ UsersTable.selectedRow._ref.path }}
Add a button to the canvas and update its Label to
Delete
. Configure the onClick event to execute your query:// Delete button's onClick event
{{ DeleteUser.run(() => ListUsers.run(), () => {}) }}- The onSuccess callback is used above to refresh your table data after the operation is complete.
When the Submit button is clicked, your query is executed and the document is deleted.
Commands
Below are the commands available for use with Firestore:
Command | Description |
---|---|
List Documents | Fetch documents in a given collection. Allows filtering results by additional parameters. |
Create Document | Add a new document at a specified path. |
Update Document | Make changes an existing document. |
Delete Document | Delete an existing document. |
Get Document | Fetch a single document by its collection/path. |
Upsert Document | Replaces an existing document or creates a new document at the specified path. |
Add Document to Collection | Add a new document to a collection with a path generated by Firestore. |