Looker requires at least MongoDB version 4.0+ and MongoDB Connector for BI version 2.6.0+ (where the
type_conversion_mode
session variable was introduced).
Looker can access MongoDB using the MongoDB Connector for BI using two options:
- Using the MongoDB Connector for BI in MongoDB Atlas.
- Using a MongoDB Connector for BI installed on the same server as the MongoDB database.
MongoDB Atlas
Your MongoDB Atlas must use an M10+ cluster. For Looker to use a MongoDB database running on MongoDB Atlas, you must use the MongoDB Connector for BI (MongoBI). Enabling the BI Connector for Atlas requires that MongoDB Atlas use a M10+ cluster.
You must also create a user account that has read permissions for the desired database.
Configuring the MongoDB Connector for BI
Before creating a connection in Looker, your MongoDB or Atlas administrator needs to set up the MongoDB Connector for BI using the following steps, which are explained on this page:
- Add the Looker server to the Atlas IP access list
- Enable the MongoDB Connector for BI
- Allow use of regular derived tables (recommended)
Adding the Looker server to the Atlas IP access list
Atlas only allows client connections from entries in the project’s IP access list. Add Looker’s IP address to the Atlas project’s IP access list:
- Get Looker’s IP address.
- Follow the Atlas IP access list setup instructions to add Looker’s IP address to the Atlas IP access list.
Enabling the MongoDB Connector for BI
Enable the MongoDB Connector for BI:
- Verify that you are on a M10+ cluster.
- In Atlas, open the Connect page for the cluster. Make a note of the hostname, port, and user. You’ll need to use that information when configuring the connection in Looker.
MongoDB on the same server
Before creating a connection in Looker, your MongoDB administrator should set up MongoDB and the Mongo Connector for BI using the following steps, which are explained on this page:
- Installing the Mongo Connector for BI
- Encrypting network traffic
- Setting up the Looker user and permissions
- Allowing use of regular derived tables (recommended)
Installing the Mongo Connector for BI
> Install the MongoDB Connector for BI on the same server as the MongoDB database, as explained on the Install BI Connector On Premises MongoDB documentation page.
Encrypting network traffic
The MongoDB Connector for BI requires using SSL encryption between MongoDB’s server and the Looker application. Follow the SSL setup instructions on the Configure SSL for BI Connector MongoDB documentation page.
Setting up the Looker user and permissions
In the MongoDB shell, enter the use
command to switch to the database that Looker will connect to. Then, create a user for Looker with db.createUser()
with the role readWrite
:
Installing the MongoBI JDBC driver files
For both MongoDB Connector for BI options, Looker requires configuring JDBC driver files by doing the following steps:
Download these two JAR files:
Follow the steps on the Unpackaged JDBC drivers documentation page using the following values:
driver symbol: mongobi
driver entry:
- name: mongobi
dir_name: mongobi
module_path: com.mysql.jdbc.Driver
override_jdbc_url_subprotocol: mysql
If you are on Looker 6.2 or earlier:
- name: maria15x
dir_name: mongobi
module_path: com.mysql.jdbc.Driver
override_jdbc_url_subprotocol: mysql
For the step to put the driver in your dialect’s directory, the paths to these files will look like this:looker/custom_jdbc_drivers/mongobi/mongosql-auth-1.0.0-rc0.jar
looker/custom_jdbc_drivers/mongobi/mysql-connector-java-5.1.47.jar
Allowing use of regular derived tables (recommended)
Derived tables are important tools in Looker that enable you to expand the sophistication of your analyses. They can also play a valuable role in enhancing query performance. At a high level, Looker’s derived table functionality provides a way to create new tables that don’t already exist in your database.
The MongoDB Connector for BI supports temporary regular derived tables but does not yet support persistent derived tables.
Since regular derived tables are temporary, they do not need to be stored. Thus, you don’t need to create a schema for them. However, you need to grant the dbOwner
role to looker_tmp
schema, even if that schema does not exist.
Follow the Modify MongoDB Users section on this MongoDB documentation page to add the dbOwner
role on looker_tmp
for the user Looker will use to connect.
Adding the connection
Configure a database connection via the Looker interface. From the Admin section, select Connections, and then select New Connection. Fill out the connection details (see the Connecting Looker to your database documentation page for more information).
Click on Test These Settings to verify the connection is successful. The Testing database connectivity documentation page has troubleshooting information.
Using SQL functions and operators with MongoDB Connector for BI
When developing using a MongoDB Connector for BI connection, you can use the SQL functions and operators listed on this MongoDB documentation page.
Feature support
For Looker to support some features, your database dialect must also support them.
In Looker 22.6, MongoDB supports the following Looker features:
In addition:
- MongoDB does not support millisecond and microsecond timeframes for dimension groups.
- MongoDB does not support millisecond, millisecondX, and microsecond types for dimensions.
- Looker treats all timestamps accessed from MongoBI as being in the coordinated universal time (UTC) time zone.
Next steps
After you have completed the database configuration, connect to the database from Looker.