Firestore

This page provides information for connecting your application to your Firestore database and for using queries to manage its content.

Connection parameters

The following section is a reference guide that provides a complete description of all the parameters to connect to a Firestore database.

Database URL

The domain or network location of your database instance. This value includes your Project ID in the format https://PROJECT_ID.firebaseio.com.

Project ID

The unique identifier for your Firestore project, accessible in your Firebase project's Project Settings. For more information, see Understand Firebase projects.

Service account credentials

A string of credentials generated on Firebase that is used to authenticate your queries. You can generate these credentials from your Firebase project's Project Settings page under Service Accounts. Open the downloaded file and copy-paste its entire contents into the Service account credentials field in your Appsmith datasource configuration. For

Create queries

The following section is a reference guide that provides a complete description of all the read and write operation commands with their parameters to create Firestore queries.

List Documents

This command lists all documents from a given collection. The following section lists all the fields available for the List Documents command.

Collection Name

The name of the collection to query.

Where

Defines conditions that documents' column values must meet to appear in your results. The available comparison operators are ==, <, <=, >=, >, in, contains, and contains any.

Options:

Add condition: Adds another simple single-line expression.
Add group condition: Adds a nested expression with multiple levels of AND statements.

*Use Where conditions to create multiple levels of filtering.*

Order by

Sorts query results by a column value. Expects a JSON array containing a single string which is the column's name. By default this sorts in ascending order, or you can add a - prefix to the column name to sort in descending order. For example, ["name"] is ascending and ["-name"] is descending.

Start after

Sets a record that acts as a starting cursor for pagination. Expects an object that is a whole document, i.e. a document that was returned from a prior query. For example, you can pass the last record from the most recent execution of a query:

{{ ListQuery.data[ListQuery.data.length - 1] }}

Each time the query is run, it fetches the next set of results that come after the previous execution.

End before

Sets a record that acts as an ending cursor for pagination. Expects an object that is a whole document, i.e. a document that was returned from a prior query. For example, you can pass the first record from the most recent execution of a query:

{{ ListQuery.data[0] }}

When the query is paged backwards, it fetches the set of results that lead up to the current results.

Limit

Sets a limit for how many documents may be returned by the query.

Create Document

This command creates a new document within a given collection. Firestore automatically generates an identifier for the created document. The following section lists all the fields available for the Create Document command.

Collection Name

The name of the collection where the new document should be created.

Body

Expects a JSON object that represents the document to be created. For example:

{
    "name": {{ NameInput.text }},
    "email": {{ EmailInput.text }},
    "date_of_birth": {{ DatePicker.selectedDate }}
}

Timestamp Path

When filled, adds a timestamp key-value pair into the created document that shows when the document was created. Expects an array with a single string value, for example ["TIMESTAMP_KEY_NAME"]. The string you provide in this field is used as the key to the timestamp value in your document. You can create a timestamp key-value pair within a nested object by using . to specify the path.

For example, the value ["meta.dateCreated"] adds the following to your document:

{
  "meta": {
    "dateCreated": {
      "seconds": 1681997026,
      "nanos": 409000000
    },
  },
  // ...
}

Update Document

This command updates an existing document at a given path. The following section lists all the fields available for the Update Document command.

Collection/Document path

The path to the document to update. For example, the path Users/Admins/admin001 refers to a document admin001 in the the Admins directory of the Users Collection.

Body

Expects a JSON object that represents the new key-value pairs to update the document with. You only need to include the key-value pairs that are changing, adding all keys is not necessary. For example:

{
    "name": {{ NewNameInput.text }}
}

Delete Key Path

When filled, deletes the key located at the path specified by this field. You can delete nested keys by providing the path from the root of the object. Expects an array with a single string value, for example ["PARENT_KEY.KEY_TO_DELETE"].

Timestamp Path

When filled, adds a timestamp key-value pair into the created document that shows when the document was updated. Expects an array with a single string value, for example ["TIMESTAMP_KEY_NAME"]. The string you provide in this field is used as the key to the timestamp value in your document. You can create a timestamp key-value pair within a nested object by using . to specify the path.

For example, the value ["meta.lastModified"] adds the following to your document:

{
  "meta": {
    "lastModified": {
      "seconds": 1681997026,
      "nanos": 409000000
    },
  },
  // ...
}

Delete Document

This command deletes an existing document at a given path. The following section lists all the fields available for the Delete Document command.

Collection/Document path

The path to the document to delete. For example, the path Users/Admins/admin001 refers to a document admin001 in the the Admins directory of the Users Collection.

Get Document

This command fetches a single existing document at a given path. The following section lists all the fields available for the Get Document command.

Collection/Document path

The path to the document to fetch. For example, the path Users/Admins/admin001 refers to a document admin001 in the the Admins directory of the Users Collection.

Upsert Document

This command creates a new document or replaces an existing document at the given path. The following section lists all the fields available for the Upsert Document command.

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.

Collection/Document path

The path to the document to update. For example, the path Users/Admins/admin001 refers to a document admin001 in the the Admins directory of the Users Collection.

Body

Expects a JSON object that represents the document to be created. If a document already exists at the path given in Collection/Document path, this command completely replaces it with the content of this field. For example:

{
    "name": {{ NameInput.text }},
    "email": {{ EmailInput.text }},
    "date_of_birth": {{ DatePicker.selectedDate }}
}

Timestamp Path

For example, the value ["meta.dateCreated"] adds the following to your document:

{
  "meta": {
    "dateCreated": {
      "seconds": 1681997026,
      "nanos": 409000000
    },
  },
  // ...
}

Add document to collection

This command creates a new document within a given collection, under the identifier you provide. The following section lists all the fields available for the Add document to collection command.

Collection/Document path

The path to where the document should be created. The last part of this string becomes the document's identifier. For example, a path Users/Admins/admin001 will create a document admin001 in the Users Collection in the Admins directory.

Body

Expects a JSON object that represents the document to be created. For example:

{
    "name": {{ NameInput.text }},
    "email": {{ EmailInput.text }},
    "date_of_birth": {{ DatePicker.selectedDate }}
}

Timestamp Path

For example, the value ["meta.dateCreated"] adds the following to your document:

{
  "meta": {
    "dateCreated": {
      "seconds": 1681997026,
      "nanos": 409000000
    },
  },
  // ...
}

Troubleshooting

If you are experiencing difficulties, you can refer to the Datasource troubleshooting guide or contact the support team using the chat widget at the bottom right of this page.

Was this page helpful?

Firestore

Connection parameters​

Database URL​

Project ID​

Service account credentials​

Create queries​

List Documents​

Collection Name​

Where​

Order by​

Start after​

End before​

Limit​

Create Document​

Collection Name​

Body​

Timestamp Path​

Update Document​

Collection/Document path​

Body​

Delete Key Path​

Timestamp Path​

Delete Document​

Collection/Document path​

Get Document​

Collection/Document path​

Upsert Document​

Collection/Document path​

Body​

Timestamp Path​

Add document to collection​

Collection/Document path​

Body​

Timestamp Path​

Troubleshooting​

Connection parameters

Database URL

Project ID

Service account credentials

Create queries

List Documents

Collection Name

Where

Order by

Start after

End before

Limit

Create Document

Collection Name

Body

Timestamp Path

Update Document

Collection/Document path

Body

Delete Key Path

Timestamp Path

Delete Document

Collection/Document path

Get Document

Collection/Document path

Upsert Document

Collection/Document path

Body

Timestamp Path

Add document to collection

Collection/Document path

Body

Timestamp Path

Troubleshooting