Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.
MongoDB data source for Grafana
The MongoDB data source plugin allows you to visualize data from MongoDB in Grafana.
Requirements
This plugin has the following requirements:
- A MongoDB instance with at least one user
- One of the following account types:
- Grafana Cloud: Pro customers, Advanced customers, or Pro trial users with the Enterprise plugin add-on enabled
- Grafana Enterprise: Customers with an activated license and a user with Grafana server or organization administration permissions
- The Enterprise plugin add-on enabled
Known limitations
- Only
find
andaggregate
read commands are supported - For diagnostics commands that are currently supported refer to Diagnostics
- Regex flags
g
ands
are not supported
Install the plugin
To install the data source, refer to Installation.
Configure the data source in Grafana
Add a data source by filling in the following fields:
Field Name | Description |
---|---|
Name | A name for this particular MongoDB data source. |
Connection String | Connection string for your MongoDB instance. |
Authentication | Credentials Enter your user name and password. CA Certificate Enter your CA certificate and decide whether to skip TLS cert validation. Client Certificate Enter your server name, client certificate, and client key. |
Configure the data source with provisioning
Data sources can be configured with Grafana’s provisioning system. You can read more about how it works and all the settings you can set for data sources at Provisioning Grafana.
apiVersion: 1
datasources:
- name: MongoDB
type: grafana-mongodb-datasource
access: proxy
basicAuth: false
editable: true
enabled: true
jsonData:
connection: Connection string
user: user name
secureJsonData:
password: password
Query the data source
The query editor supports the same syntax as the MongoDB Shell, with some limitations:
- You can only run one command or query in each query.
- Only
find
andaggregate
read commands are supported. ISODate
is the only supported object constructor.
Additional syntax
The editor extends the MongoDB Shell syntax by means of database selection, where you can use a database name instead of db
. For example, sample_mflix.movies.find()
. You can still use db
to refer to the default database in your connection string.
It also extends it by means of aggregate sorting. Sorting typically happens within the aggregate pipeline. The extended syntax is allowed on aggregate
similarly to find
. For example, sample_mflix.movies.aggregate({}).sort({"time": 1})
.
Note: MongoDB does not perform the sort with this syntax. The sort happens after the results are queried from the collection.
Edge cases
Collections with a dot
For collections containing a dot you can use the following syntax
my_db.getCollection("my.collection").find({})
Shortcuts
Press Ctrl + Space to show code completion, which is displayed after entering a .
after a database, collection, query method, or aggregation method name.
Cmd + S runs the query.
Query as time series
Make a time series query by aliasing a date field to time
.
Note: You can coerce non-date fields into date fields and alias them to
time
to use them to make a time series query.
The following example converts the int
field year
to a date that is projected as time
using the MongoDB $dateFromParts pipeline operator:
sample_mflix.movies.aggregate([
{"$match": { "year": {"$gt" : 2000} }},
{"$group": { "_id": "$year", "count": { "$sum": 1 }}},
{"$project": { "_id": 0, "count": 1, "time": { "$dateFromParts": {"year": "$_id", "month": 2}}}}
]
).sort({"time": 1})
If you want to group your time series by Metric, project a field called __metric
.
The following example displays the count of movies over time by movie rating using __metric
:
sample_mflix.movies.aggregate([
{"$match": { "year": {"$gt" : 2000}}},
{"$group": { "_id": {"year":"$year", "rated":"$rated"}, "count": { "$sum": 1 } }},
{"$project": { "_id": 0, "time": { "$dateFromParts": {"year": "$_id.year", "month": 2}}, "__metric": "$_id.rated", "count": 1}}
]
).sort({"time": 1})
Diagnostics
For information about diagnostics commands, refer to Diagnostic Commands.
This plugin supports the following diagnostic commands:
stats
serverStatus
replSetGetStatus
getLog
connPoolStats
connectionStatus
buildInfo
dbStats
hostInfo
lockInfo
Macros
To simplify syntax and to allow for dynamic times, you can write queries that contain macros.
- $__timeFrom
- Will be replaced by the start of the currently active time selection converted to
time
data type. - $__timeTo
- Will be replaced by the end of the currently active time selection converted to
time
data type.
Templates and variables
To add a new MongoDB query variable, refer to Add and manage variables. Use your MongoDB data source as your data source.
Here is an example of a query that gets all movie titles after 1980:
sample_mflix.movies.aggregate([
{"$match": {year: {"$gt": 1980}}},
{"$project": {"_id": 0, "movie_title": "$title"}}
])
MongoDB supports compound variables, where one variable is used as multiple variables to perform complex multi-key filters.
- Name your compound variable by starting each individual name with an underscore (
_
), such as_var1_var2
. Do not use spaces. - Query for the compound variable by making the alias use the same individual names separated by a hyphen (
-
), such asval1-val2
. - Call your variable by using normal variable syntax. For example,
$_var1
or$_var2
.
Filtering results on both movie name and year
- Create a variable and name it
_movie_year
. - Select MongoDB as the data source.
- Get an array of items with one movie-year property by setting the query as follows:
sample_mflix.movies.aggregate([
{"$match": {year: {"$gt": 1980}}},
{"$project": {"_id": 0, "movie_year": {"$concat": ["$title", " - ", {"$toString":"$year"}]}}}
])
// [{"movie-year": "Ted - 2016"}, {"movie-year": "The Terminator - 1985"}]
- Within your query, reference
$_movie
and$_year
as separate template variables:
sample_mflix.movies.find({"title":"$_movie", year: $_year})
- Use the variable in your MongoDB queries by using Variable syntax.
For more information about variables, refer to Templates and variables.
Using Ad-Hoc Filters
In addition to the standard “ad-hoc filter” type variable of any name, a second helper variable must be created. It should be a “constant” type with the name mongo_adhoc_query
and a value compatible with the query editor. The query result will be used to populate the UI’s selectable filters. You may choose to hide this variable from view as it serves no further purpose.
A query of:
sample_mflix.movies.aggregate([ {"$group": { "_id": "$year"}}, {"$project": { "year": "$_id", "_id": 0 }} ] )
…and a value selected, would look like:
Other supported functionalities with example queries
ObjectId
type support
sample_mflix.movies.find({"_id": ObjectId("573a1390f29313caabcd4803")})
sample_mflix.movies.find({"_id": {$in : [ObjectID("573a1391f29313caabcd6f98"), ObjectID("573a1392f29313caabcd9dee"), ObjectID("573a1392f29313caabcd9ca6")] }})
Regex search support
- With double quotes:
sample_mflix.movies.find({"title": {$regex: "ace", $options: "$i"} })
- With single quotes:
sample_mflix.movies.find({"title": {$regex: 'ace', $options: "$i"} })
- With pattern
sample_mflix.movies.find({"title": /ace/i })
$__timeFrom/$__timeTo
macros support
sample_mflix.movies.find({"tomatoes.dvd": { $gt: $__timeFrom}}).limit(10)
sample_mflix.movies.find({ $and: [{ "tomatoes.dvd": { $gte: $__timeFrom }}, { "tomatoes.dvd": { $lt: $__timeTo }}]})
ISODate
type support
sample_mflix.movies.find({"tomatoes.dvd": { $gte: ISODate("2013-03-01") }})
Get the most out of the plugin
- Add Annotations.
- Configure and use Templates and variables.
- Add Transformations.
- Set up alerting; refer to Alerts overview.
Related resources from Grafana Labs


