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 and aggregate read commands are supported
• For diagnostics commands that are currently supported refer to Diagnostics
• Regex flags g and s 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:

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.

yaml

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 and aggregate 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 as val1-val2.
• Call your variable by using normal variable syntax. For example, $_var1 or $_var2.

Filtering results on both movie name and year

1. Create a variable and name it _movie_year.
2. Select MongoDB as the data source.
3. 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"}]

4. Within your query, reference $_movie and $_year as separate template variables:

sample_mflix.movies.find({"title":"$_movie", year: $_year})

5. 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.