Skip to main content

MongoDB

This page gives information to connect Appsmith to a MongoDB database and to read and write data in your applications.

Build a MongoDB Panel

Connect MongoDB​

caution

If you are a self-hosted user, you must whitelist the IP address of the Appsmith deployment 18.223.74.85 and 3.131.104.27 on your database instance or VPC before connecting to a database. See How to whitelist IP addresses on MongoDB Atlas for more details.

Connection parameters​

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

Configure MongoDB using Connection String URI
Connect MongoDB using Connection String URI
Use Mongo Connection String URI

Options:
  • Yes: Connect to MongoDB database using the Connection String URI format
  • No: Connect to MongoDB database by configuring multiple parameter fields.
Connection String URI
A MongoDB connection string URI (Uniform Resource Identifier) is a standardized way to specify the location and other details of a MongoDB database. This field is visible only if you select Yes in the Use Mongo Connection String URI list. See Connection String URI Format for details on how to specify the MongoDB connection string.

Example:
mongodb+srv://mockdb-admin:****@mockdb.kce5o.mongodb.net/movies?retryWrites=true&w=majority&authSource=admin

The following section lists the parameters to connect MongoDB by configuring multiple parameter fields instead of the Connection String URI format.

Connect MongoDB using multiple parameter fields
Connect MongoDB using multiple parameter fields
Connection Mode
Specifies the mode in which the Appsmith application can interact with the database. This field and the subsequent fields are visible only if you select No in the Use Mongo Connection String URI list.

Options:
  • Read Only: This mode permits only read-only operations by default.
  • Read/Write: This mode permits both read-write operations by default.
Connection Type
Specifies whether to connect to a MongoDB instance or replica set deployment.

Options:
  • Direct Connection: Enables you to connect to a single MongoDB instance
  • Replicate Set: Enables you to connect to a group of connected instances that store the same set of data. This configuration provides data redundancy and high data availability. To connect to a replica set deployment, you must specify each instance's hostname and port numbers.
Host Address
Specifies the server's IP address or domain name where MongoDB is running. If you want to connect to a local MongoDB database, see Connect Local Database for directions on configuring the connection parameters.

Port
The port number on which MongoDB listens for incoming connections. Appsmith connects to port 27017 by default if you don't specify one.

Default Database Name
Specifies the default authentication database to use when authenticating a user. In MongoDB, when a user is authenticated, the authentication process checks the user's credentials against a specific database. By default, this database is admin, but you can specify a different database by using the Default Database Name parameter.

Database Name
Specifies the database name associated with the user's credentials. If Database Name is unspecified, it defaults to the name specified in the Default Database Name field. If Default Database Name is unspecified, then Database Name defaults to admin.

Authentication Type
Specifies the authentication mechanism that MongoDB uses to authenticate the connection.

Options:
  • SCRAM-SHA-1: Provides secure password storage through the use of a salted hash function. See SCRAM-SHA-1 for details.
  • SCRAM-SHA-256: Uses the SHA-256 hashing algorithm for password storage. See SCRAM-SHA-256 for details.
  • MONGODB-CR: Uses a challenge-response protocol to authenticate users based on a combination of a password and a random challenge string. See MONGODB-CR for details.
info

You cannot specify MONGODB-CR as the authentication mechanism when connecting to MongoDB 4.0+ deployments.

Username
Provide the username required for authenticating connection requests to the database.

Password
Provide the password required for authenticating connection requests for the given username to the database.

SSL Mode
SSL can be used to secure the connection between the client and the server by encrypting all data that is transmitted between them.

Options:
  • Default: Depends on Connection Type field. If using the Replica set option, this is Enabled. If using the Direct Connection, this is Disabled.
  • Enabled: Initiates the connection with TLS/SSL. Rejects the connection if SSL is not available.
  • Disabled: Initiates the connection without TLS/SSL. Disallows all administrative requests over HTTPS. It uses a plain unencrypted connection.

Query MongoDB​

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 MongoDB queries.

Create MongoDB queries
Create MongoDB queries
info

See Query and Write Operation Commands for the MongoDB database commands.

Find Documents​

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

Collection
The name of the target collection from which you want to retrieve documents.

Query
Specifies the criteria that match the documents you want to retrieve.

Example:
{ 
  rating: { $gte: 4 },
  cuisine: {{cuisineList.selectedOptionValue}}
}
In the above example, the query filters documents from a restaurant collection where the rating field is greater than 4 and the cuisine matches the one selected in the Select widget cusineList.

Sort
Specifies the order in which the documents should be returned.

Example:
{ name: 1 }
In the above example, the query sorts the results by the name field in ascending order.

Projection
Specifies which fields to include in the returned documents.

Example:
{ name: 1, rating: 1, address: 1 }
In the above example, the query only returns the name, rating, and address fields in the matching documents.

Limit
Specifies the maximum number of documents to return. The default value is 10. If this field is not specified, the query returns 10 documents.

Example:
{{tableItems.pageSize}}
In the above example, tableItems is the name of the Table widget where you display the results from the query. The query limits the results based on the table widget's pageSize property.

Skip
This field specifies the number of documents to skip before returning results.

Example:
{{tableItems.pageOffset}}
In the above examples for the Limit and Skip fields, the queries use server-side pagination to limit the number of query results returned by the server and fetch additional results when the user moves to the next page in the Table widget. You can fork this Sample App to see how to implement server-side pagination on the Table widget.

Insert Documents​

This command inserts one or more documents and returns a document containing the status of all inserts. The following section lists all the fields for the Insert Documents command.

Collection
The name of the target collection where you want to insert the documents.

Documents
Specifies an array of one or more documents you want to insert into the collection.

Example:
[
  { 
    "_id": {{NewMovieForm.data.idInput}}, 
    "name": {{NewMovieForm.data.nameInput}}, 
    "rating": {{NewMovieForm.data.ratingSelect}}
  }
]
In the above example, the query inserts a new movie using the data entered in the Form widget.

Update Documents​

This command modifies the documents in a collection based on a specified set of filters. The following section lists all the fields available for the Update Documents command.

Collection
The name of the target collection where you want to update documents.

Query
Specifies the criteria that match the documents you want to update.

Example:
{ 
  "_id": {{tableItems.selectedRow.id}} 
}
In the above example, the query filters the record where the _id field is equal to the value in the id column of the row selected on the Table widget named tableItems.

Update
Specifies the modifications you want to make to the selected documents.

Example:
{ 
  $set: {
    "name":  {{tableItems.updatedRow.name}},
    "rating": {{tableItems.updatedRow.rating}}
  }
}
In the above example, the query updates the name and rating fields with the values updated in the table cells using inline editing.

Limit
Specifies whether to delete single or multiple documents

Options:
  • Single Document: Limits the update to one document that meets the query criteria.
  • All Matching Documents: Updates the fields in all documents that meet the query criteria.

Delete Documents​

This command removes one or more documents from the collection based on specified filters. The following section lists all the fields available for the Delete Documents command.

Collection
The name of the target collection where you want to delete documents.

Query
Specifies the criteria that match the documents to delete.

Example:
{ 
  "rating": {{selectRating.selectedOptionValue}} 
}
In the above example, the query deletes all the documents where the rating field contains the same value as the one selected in the Select widget named selectRating.

Limit
Specifies whether to delete single or multiple documents

Options:
  • Single Document: Limits the update to one document that meets the query criteria.
  • All Matching Documents: Updates the fields in all documents that meet the query criteria.

Count​

This command counts the number of documents in a collection that match a specified set of criteria. The following section lists all the fields available for the Count command.

Collection
The name of the target collection where you want to count the documents.

Query
This field specifies the criteria for selecting the documents to count.

Example:
{ 
  "release_dt": { $gte: {{releaseDate.formattedDate}} 
}
In the above example, the query counts the documents in a movies collection where the release date is greater than the date picked in the Datepicker widget releaseDate.

Distinct​

This command finds the unique or distinct values for a specified field across a single collection. The following section lists all the fields available for the Distinct command.

Collection
Specifies the name of the target collection to query for distinct values.

Query
Specifies the documents from which to retrieve the distinct values.

Example:
{ 
  "rating": {{selectRating.selectedOptionValue}} 
}
In the above example, the query retrieves distinct values from the documents where the rating field contains the same value as the one selected in the Select widget named selectRating.

Key
Specifies the name of the field for which to return distinct values.

Aggregate​

This command allows users to process data records and return computed results. The aggregation framework provides several operators to perform a variety of operations like filtering, grouping, sorting, projecting, and calculating. See Aggregation Pipeline Stages for information on the aggregation operators. The following section lists all the fields available for the Aggregate command.

Collection
Specifies the name of the target collection that serves as the input for the aggregation pipeline.

Array of Pipelines
An array of aggregation pipeline stages that process and transform the document stream as part of the aggregation pipeline.

Example:
{ 
  [
    { $project: { tags: 1 } },
    { $unwind: "$tags" },
    { $group: { _id: "$tags", count: { $sum : 1 } } }
  ] 
}
The preceding example performs an aggregate operation on the articles collection to calculate the count of each distinct element in the tags array that appears in the collection.

Limit
Specifies the maximum number of documents to return. The default value is 10. If this field isn't specified, the query returns 10 documents.

Raw​

This command allows you to write queries using the MongoDB database command syntax. See Raw Query Commands for more information.

Troubleshooting​

Mongo query failed to execute
Missing default database name

If you experience difficulties, contact the support team using the chat widget at the bottom right of this page.

See also​

Data access and binding