You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This plugin enables you to query and visualize data from your MongoDB databases directly within Grafana. Leverage the flexibility of MongoDB's aggregation pipeline to create insightful dashboards and panels.
5
8
6
9
7
10
8
-
## Download
9
-
[Download the latest build](https://github.com/haohanyang/mongodb-datasource/actions/runs/11313289435/artifacts/2049966955)
11
+
## Features
10
12
13
+
-**Flexible Querying:** Craft precise queries using MongoDB's aggregation pipeline syntax in JSON or JavaScript.
14
+
-**Time Series & Table Data:** Visualize time-based data or display results in tabular format for various Grafana panels.
15
+
-**Secure Execution:** Execute JavaScript queries within a secure ShadowRealm sandbox to control access.
16
+
-**Legacy Plugin Compatibility:** Seamlessly migrate from the legacy plugin with support for its query syntax.
17
+
-**Up-to-date:** Use the latest Grafana Plugin SDKs and follow best practices.
11
18
12
-
## Use
13
-
### Query language
14
-
The query text should be a valid MongoDB Aggregate pipeline - an array consisting of MongoDB Aggregate operations. Your may use the Grafana's built-in variables `"$__from"` and `"$__to"` to query data based on the current panel's time range. The plugin supports JSON and JavaScript query languages. In JSON query, you need to enter the database in the UI. Here is an example of JSON query.
15
-
```json
16
-
[
17
-
{
18
-
"$match": {
19
-
"createdTime": {
20
-
"$gt": {
21
-
"$date": {
22
-
"$numberLong": "$__from"
23
-
}
24
-
},
25
-
"$lt": {
26
-
"$date": {
27
-
"$numberLong": "$__to"
28
-
}
29
-
}
30
-
}
31
-
}
32
-
}
33
-
]
34
-
```
35
-
In JavaScript query, you need to follow the format `db.<collection-name>.aggregate([<json-query>])`. As shows in the following example.
36
-
```js
37
-
db.transactions.aggregate([
38
-
{
39
-
"$match": {
40
-
"createdTime": {
41
-
"$gt": {
42
-
"$date": {
43
-
"$numberLong":"$__from"
44
-
}
45
-
},
46
-
"$lt": {
47
-
"$date": {
48
-
"$numberLong":"$__to"
49
-
}
50
-
}
51
-
}
52
-
}
53
-
}
54
-
]);
55
-
```
19
+
## Getting Started
20
+
1.**Download:** Obtain the latest plugin build from the [Release page](https://github.com/haohanyang/mongodb-datasource/releases) or [workflow artifacts](https://github.com/haohanyang/mongodb-datasource/actions?query=branch%3Amaster).
56
21
57
-
You can also use the `"$from"`, `"$to"` and `"$dateBucketCount"`(number of intervals in the time range) conventions originated from a legacy plugin.
58
-
```json
59
-
[
60
-
{
61
-
"$match": {
62
-
"createdTime": {
63
-
"$gt": "$from",
64
-
"$lt": "$to"
65
-
}
66
-
}
67
-
}
68
-
]
69
-
```
70
-
```json
71
-
{
72
-
"$bucketAuto": {
73
-
"groupBy": "$timestamp",
74
-
"buckets": "$dateBucketCount",
75
-
//
76
-
}
77
-
}
78
-
```
79
-
### Query type
80
-
#### Time series
81
-
Time series query type is suitable for time series panels. The query results should consist the following fields:
82
-
*`ts`
83
-
The timestamp
84
-
*`value`
85
-
Either integer or double. Currently all values should be of the same type.
86
-
*`name` (Optional)
87
-
Useful if you want to show time series data of different categories.
88
-
89
-
Here is an example of JSON query from [Sample AirBnB Listings Dataset](https://www.mongodb.com/docs/atlas/sample-data/sample-airbnb/). The query shows the number of created AirBnB reviews of apartment and house property type in each month during the selected time range.
22
+
2.**Install:**
23
+
- Extract the downloaded archive (`haohanyang-mongodb-datasource-<version>.zip`) into your Grafana plugins directory (`/var/lib/grafana/plugins` or similar).
24
+
- Ensure the plugin binaries (`mongodb-datasource/gpx_mongodb_datasource_*`) have execute permissions (`chmod +x`).
- Configure the plugin as a data source within Grafana, providing your MongoDB connection details.
29
+
30
+
Refer to the [example docker-compose.prod.yaml](/docker-compose.prod.yaml) file for a production-ready setup.
31
+
32
+
3. **Start Querying:**
33
+
- Select your MongoDB data sourcein a Grafana panel.
34
+
- Use the query editor to write your aggregation pipeline queries (see Query Language below).
35
+
36
+
## Query Language
37
+
38
+
### JSON (Recommended)
39
+
40
+
Provide the collection name and your MongoDB aggregation pipeline in standard JSON format.
41
+
42
+
**Example:** Retrieve 10 AirBnB listings scraped within the selected time range:
90
43
```json
91
44
[
92
45
{
93
46
"$match": {
94
-
"first_review": {
47
+
"last_scraped": {
95
48
"$gt": {
96
49
"$date": {
97
50
"$numberLong": "$__from"
@@ -102,54 +55,141 @@ Here is an example of JSON query from [Sample AirBnB Listings Dataset](https://w
102
55
"$numberLong": "$__to"
103
56
}
104
57
}
105
-
},
106
-
"property_type": {
107
-
"$in": [
108
-
"Apartment",
109
-
"House"
110
-
]
111
58
}
112
59
}
113
60
},
114
61
{
115
-
"$group": {
116
-
"_id": {
117
-
"month": {
118
-
"$dateToString": {
119
-
"format": "%Y-%m",
120
-
"date": "$first_review"
121
-
}
122
-
},
123
-
"property_type": "$property_type"
124
-
},
125
-
"value": {
126
-
"$count": {}
127
-
}
128
-
}
129
-
},
130
-
{
131
-
"$project": {
132
-
"ts": {
133
-
"$toDate": "$_id.month"
134
-
},
135
-
"name": "$_id.property_type",
136
-
"value": 1
137
-
}
62
+
"$limit": 10
138
63
}
139
64
]
140
65
```
141
-
#### table
142
-
Table type is more flexible and doesn't require the output schema. This usually fits panels that don't require timestamp.
143
66
67
+
### JavaScript (Legacy & ShadowRealm)
144
68
145
-
## Install
146
-
* Download the packaged plugin `haohanyang-mongodb-datasource-<version>.zip` from [workflow artifacts](#download) to the root directory (where `docker-compose.yaml` exists) and extract files to folder `mongodb-datasource`
69
+
- **Legacy:** Maintain compatibility with the older plugin's syntax:
70
+
```javascript
71
+
db.listingsAndReviews.aggregate([ /* Your aggregation pipeline (JSON) */ ]);
72
+
```
73
+
This gives the same result as the previous JSON query.
74
+
```js
75
+
db.listingsAndReviews.aggregate([
76
+
{
77
+
"$match": {
78
+
"last_scraped": {
79
+
"$gt": {
80
+
"$date": {
81
+
"$numberLong": "$__from"
82
+
}
83
+
},
84
+
"$lt": {
85
+
"$date": {
86
+
"$numberLong": "$__to"
87
+
}
88
+
}
89
+
}
90
+
}
91
+
},
92
+
{
93
+
"$limit": 10
94
+
}
95
+
])
96
+
```
97
+
- **ShadowRealm (Secure):** Define an `aggregate()` function that returns your pipeline. The function executes within a [ShadowRealm](https://github.com/tc39/proposal-shadowrealm) sandboxed environment.
98
+
```javascript
99
+
function aggregate() {
100
+
// ... your logic based on template variables ...
101
+
return [ /* Your aggregation pipeline */ ];
102
+
}
103
+
```
104
+
In this example, only the admin user to can view the query result.
* Create/start the docker container as descriped in the [example docker compose file](/docker-compose.prod.yaml)
125
+
### Query Types
126
+
127
+
- **Time series:** For time-based visualizations. Your query must return documents with `ts` (timestamp) and `value` fields. An optional `name` field enables grouping by category.
128
+
129
+
The following query of [Sample AirBnB Listings Dataset](https://www.mongodb.com/docs/atlas/sample-data/sample-airbnb/) shows the number of AirBnB listings in each month that have the first review in the selected time range.
130
+
```json
131
+
[
132
+
{
133
+
"$match": {
134
+
"first_review": {
135
+
"$gt": {
136
+
"$date": {
137
+
"$numberLong": "$__from"
138
+
}
139
+
},
140
+
"$lt": {
141
+
"$date": {
142
+
"$numberLong": "$__to"
143
+
}
144
+
}
145
+
}
146
+
}
147
+
},
148
+
{
149
+
"$group": {
150
+
"_id": {
151
+
"month": {
152
+
"$dateToString": {
153
+
"format": "%Y-%m",
154
+
"date": "$first_review"
155
+
}
156
+
},
157
+
"property_type": "$property_type"
158
+
},
159
+
"value": {
160
+
"$count": {}
161
+
}
162
+
}
163
+
},
164
+
{
165
+
"$project": {
166
+
"ts": {
167
+
"$toDate": "$_id.month"
168
+
},
169
+
"name": "$_id.property_type",
170
+
"value": 1
171
+
}
172
+
}
173
+
]
174
+
```
175
+
- **Table:** For more flexible data display in tables, pie charts, etc. No specific output schema is required.
0 commit comments