User Guide Getting Started Help Center Documentation Community Training
MongoDB Using Mongo Connector for BI (MongoBI) on MongoDB Atlas

Looker can access MongoDB using Mongo Connector for BI using two options:


Your Mongo Atlas must use an M10+ cluster. For Looker to use a MongoDB database running on MongoDB Atlas, you must use the Mongo Connector for BI (MongoBI). Enabling the BI Connector for Atlas requires that Mongo Atlas use a M10+ cluster.

You must also create a user account that has read permissions for the desired database.

Configuring Looker to Use a Custom JDBC

Looker uses Mongo’s authentication plugin, so you must update Mongo’s driver to the custom JDBC by doing the following steps:

  1. Create the directory ~/looker/custom_jdbc_drivers/mongobi/
  2. Download these two JAR files into the ~/looker/custom_jdbc_drivers/mongobi/ directory:
  3. In the ~/looker/ directory, create a custom_jdbc_config.yml file (if it does not already exist):

vim ~/looker/custom_jdbc_config.yml

  1. Add the following to the custom_jdbc_config.yml file to tell Looker to use the new driver:

- name: mongobi dir_name: mongobi module_path: com.mysql.jdbc.Driver override_jdbc_url_subprotocol: mysql

  1. Only if you are on Looker 6.2 or below, add the following maria15x entry to the custom_jdbc_config.yml file. (Do not add this entry if you are on Looker 6.4 or above.)

- name: maria15x dir_name: mongobi module_path: com.mysql.jdbc.Driver override_jdbc_url_subprotocol: mysql

When you upgrade to Looker 6.4 or above, you must delete the maria15x entry as part of your upgrade.

  1. In the ~/looker/ directory, create a lookerstart.cfg file (if it does not already exist):

vim ~/looker/lookerstart.cfg

  1. In the lookerstart.cfg file, add --use-custom-jdbc-config to the end of the list of LOOKERARGS environment variables. Leave all other arguments in the list, if there are any. In this example, there are existing arguments --no-ssl and --port 8080, so we will add --use-custom-jdbc-config to the end, inside the quotes:

LOOKERARGS="‐‐no-ssl ‐‐port 8080 ‐‐use-custom-jdbc-config"

  1. Restart Looker:

./looker restart

Configuring the Mongo Connector for BI

Before creating a connection in Looker, your MongoDB or Atlas administrator needs to set up the Mongo Connector for BI using the following steps, which are explained below:

Adding the Looker Server to the Atlas Whitelist

Atlas only allows client connections from entries in the project’s whitelist. Add Looker’s IP address to the Atlas project’s whitelist:

  1. Get Looker’s IP address.
  2. Follow the Atlas Whitelist Setup instructions to add Looker’s IP address to the Atlas whitelist.

Enabling the Mongo Connector for BI

Enable the Mongo Connector for BI:

  1. Verify that you are on a M10+ cluster.
  2. 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.

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 Mongo 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 account Looker will use to connect.

Connecting Looker to Mongo

Configure a database connection via the Looker interface. From the Admin section, select Connections then New Connection. 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

Looker’s ability to provide some features depends on whether the database dialect can support them.

In the current Looker release, MongoDB supports the following Looker features:

MongoBI connections do not support:

In addition, Looker treats all timestamps accessed from MongoBI as being in the coordinated universal time (UTC) time zone.

Next Steps

After completing the database configuration, you can connect to the database from Looker using these directions.

Additional Parameter for Mongo Version 3.6 or Below

If you are running Mongo version 3.6 or below on Atlas, when you set up your database connection, you must include the Additional Params value enabledTLSProtocols=TLSv1.2 to avoid a communications link failure for the database connection: