Skip to content

Restyle Update mongodb.md #480

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
restyled-io wants to merge 2 commits into from
Closed

Restyle Update mongodb.md #480

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
eeac1ce
Update mongodb.md
kurianbenoy Aug 26, 2020
0c53bc2
Restyled by prettier-markdown
restyled-commits Aug 26, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
116 changes: 64 additions & 52 deletions src/pages/kb/data-sources/mongodb.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,61 +9,70 @@ toc: true
# Setup

To setup a MongoDB connection, you need to at least provide a **Connection
String** and a **DB Name**.
String** and a **DB Name**.

**Connection String**
**Connection String**

* The simplest: `mongodb://username:password@hostname:port/dbname`
- The simplest: `mongodb://username:password@hostname:port/dbname`

* With SSL enabled: `mongodb://username:password@hostname:port/dbname?ssl=true`
- With SSL enabled: `mongodb://username:password@hostname:port/dbname?ssl=true`

* With SSL enabled and self-signed certificates (disables certificate verification): `mongodb://username:password@hostname:port/dbname?ssl=true&ssl_cert_reqs=CERT_NONE`
- With SSL enabled and self-signed certificates (disables certificate
verification):
`mongodb://username:password@hostname:port/dbname?ssl=true&ssl_cert_reqs=CERT_NONE`

If needed, you can pass additional connection options in the query string. See
full details in [MongoDB's
documentation](https://docs.mongodb.com/manual/reference/connection-string
/#connection-options).
full details in
[MongoDB's documentation](https://docs.atlas.mongodb.com/reference/faq/connection-changes/index.html).

You might notice that there is a separate field for the DB Name in the data
source configuration and we also include it in the connection string. This is
usually required on shared hosts like MLab.

## MongoDB Atlas

We've had issues with users connecting to MongoDB Atlas free tier accounts because they are on a shared environment. For best results, use a connection string of the format:
We've had issues with users connecting to MongoDB Atlas free tier accounts
because they are on a shared environment. For best results, use a connection
string of the format:

`mongodb+srv://<user>:<password>@<subdomain>.mongodb.net/<database>?retryWrites=true`


## Troubleshooting

**Error: "SSL handshake failed: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed"**

This usually happens when your MongoDB server is using self signed certificates. You can either switch to a properly signed certificate or just add the `ssl_cert_reqs=CERT_NONE` option to your Connection String.


Write your MongoDB query as a JSON object. During execution, Redash will convert it into either a [`db.collection.find()`](https://docs.mongodb.com/manual/reference/method/db.collection.find/) call or a [`db.collection.aggregate()`](https://docs.mongodb.com/manual/reference/method/db.collection.aggregate/) call. Here's how your JSON object is mapped and sent to MongoDB:

| MongoDB Token | Where to write in Redash |
|--------------------------------|-------------------------------------------------------|
| `db` | On the data source setup screen |
| `collection` | Add a `collection` key in your query object |
| `query` | Add a `query` key in your query object |
| `projection` | Add a `fields` key in your query object |
| `.sort() method` | Add a `sort` key in your query object |
| `.skip() method` | Add a `skip` key in your query object |
| `.limit() method` | Add a `limit` key in your query object |
| `db.collection.count()` method | Use a `count` key with any value in your query object |

The values you use for each key are passed unmodified as as parameters to MongoDB.
**Error: "SSL handshake failed: [SSL: CERTIFICATE_VERIFY_FAILED] certificate
verify failed"**

This usually happens when your MongoDB server is using self signed certificates.
You can either switch to a properly signed certificate or just add the
`ssl_cert_reqs=CERT_NONE` option to your Connection String.

Write your MongoDB query as a JSON object. During execution, Redash will convert
it into either a
[`db.collection.find()`](https://docs.mongodb.com/manual/reference/method/db.collection.find/)
call or a
[`db.collection.aggregate()`](https://docs.mongodb.com/manual/reference/method/db.collection.aggregate/)
call. Here's how your JSON object is mapped and sent to MongoDB:

| MongoDB Token | Where to write in Redash |
| ------------------------------ | ----------------------------------------------------- |
| `db` | On the data source setup screen |
| `collection` | Add a `collection` key in your query object |
| `query` | Add a `query` key in your query object |
| `projection` | Add a `fields` key in your query object |
| `.sort() method` | Add a `sort` key in your query object |
| `.skip() method` | Add a `skip` key in your query object |
| `.limit() method` | Add a `limit` key in your query object |
| `db.collection.count()` method | Use a `count` key with any value in your query object |

The values you use for each key are passed unmodified as as parameters to
MongoDB.

# Querying

## Query Examples

### Simple Query Example


{
"collection": "my_collection",
"query": {
Expand All @@ -78,28 +87,25 @@ The values you use for each key are passed unmodified as as parameters to MongoD
"direction": -1
}]
}


An equivalent query in Javascript would be written: `db.my_collection.find({"type": 1}, {"_id": 1, "name": 2}).sort([{"name": "date","direction": -1}])`

An equivalent query in Javascript would be written:
`db.my_collection.find({"type": 1}, {"_id": 1, "name": 2}).sort([{"name": "date","direction": -1}])`

### Count Query Example



{
"collection": "my_collection",
"count": true
}


### Aggregation

Aggregation uses a syntax similar to the one used in PyMongo. However, to support the correct order of sorting, it uses a regular list for the “$sort” operation that converts into a SON (sorted dictionary) object before execution.
Aggregation uses a syntax similar to the one used in PyMongo. However, to
support the correct order of sorting, it uses a regular list for the “\$sort”
operation that converts into a SON (sorted dictionary) object before execution.

Aggregation query example:


{
"collection": "things",
"aggregate": [{
Expand All @@ -122,10 +128,11 @@ Aggregation query example:
}]
}


### MongoDB Extended JSON Support

We support [MongoDB Extended JSON](https://docs.mongodb.com/manual/reference/mongodb-extended-json/) along with our own extension - `$humanTime`:
We support
[MongoDB Extended JSON](https://docs.mongodb.com/manual/reference/mongodb-extended-json/)
along with our own extension - `$humanTime`:

{
"collection": "date_test",
Expand All @@ -138,25 +145,28 @@ We support [MongoDB Extended JSON](https://docs.mongodb.com/manual/reference/mo
},
"limit": 100
}


It accepts a human-readable string like the above (“3 years ago”, “yesterday”, etc) or timestamps.
It accepts a human-readable string like the above (“3 years ago”, “yesterday”,
etc) or timestamps.

{% callout info %}

The `$humanTime` function is also needed when using [Query Parameters]({% link _kb/user-guide/querying/query-parameters.md %}) of type Date or Date/Time with MongoDB, due to the difference between the format Redash uses and the one MongoDB expects.
The `$humanTime` function is also needed when using [Query
Parameters]({% link _kb/user-guide/querying/query-parameters.md %}) of type Date
or Date/Time with MongoDB, due to the difference between the format Redash uses
and the one MongoDB expects.

When using a Date (or Date Range) parameter, wrap it with a `$humanTime` object: `{{param}}` becomes `{"$humanTime": "{{param}} 00:00"}` (the ` 00:00` suffix is needed only with Date parameters, for Date Time parameters you should skip it).
When using a Date (or Date Range) parameter, wrap it with a `$humanTime` object:
`{{param}}` becomes `{"$humanTime": "{{param}} 00:00"}` (the `00:00` suffix is
needed only with Date parameters, for Date Time parameters you should skip it).

{% endcallout %}

### MongoDB Filtering

You can add filters to Mongo queries by projecting a column with the
'::filter' keyword added on to the end.
You can add filters to Mongo queries by projecting a column with the '::filter'
keyword added on to the end.



{
"collection": "zipcodes",
"aggregate": [{
Expand All @@ -169,7 +179,6 @@ You can add filters to Mongo queries by projecting a column with the
}
}]
}


The above example will show a 'State' column, and allow you to filter on this
column.
Expand All @@ -178,9 +187,12 @@ column.

### Sort exceeded memory limit of 104857600 bytes

> Sort exceeded memory limit of 104857600 bytes, but did not opt in to external sorting. Aborting operation. Pass allowDiskUse:true to opt in.
> Sort exceeded memory limit of 104857600 bytes, but did not opt in to external
> sorting. Aborting operation. Pass allowDiskUse:true to opt in.

In MongoDB, the in-memory sorting have a limit of 100M, to perform a large sort, you need enable `allowDiskUse` option to write data to a temporary files for sorting.
In MongoDB, the in-memory sorting have a limit of 100M, to perform a large sort,
you need enable `allowDiskUse` option to write data to a temporary files for
sorting.

To enable the `allowDiskUse` option, just add the option to your query:

Expand All @@ -189,4 +201,4 @@ To enable the `allowDiskUse` option, just add the option to your query:
...
"allowDiskUse": true
}
```
```