Sending MongoDB BI Connector data to HullUpdated 13/02/2020


Although we do not support native MongoDB integration, there is an advanced feature in MongoDB which, when available on higher plans, allows to query the database using our generic SQL importer connector.

The required feature is called BI Connector and more information can be found in the official documentation.

IMPORTANT: BI Connector is an advanced feature not available in basic MongoDB package: - it's only available for MongoDB server version 3.2 and greater. - when using official MongoDB hosted service - Atlas it's available starting from M10 pricing tier. And the BI Connector is an extra paid addon. - when using On Premise instance MongoDB BI Connector is available on enterprise plan. - following guide is based on a M10 Atlas instance example

First, make sure that BI Connector feature is available and enabled for your MongoDB instance. Once again, this setup won't work with all MongoDB instances, only those where BI Connector is available.

mongo bi connector enable

When enabled you can get your credentials which will be required in further steps of the guide.

mongo bi connector connect

mongo bi connector credentials

Then, head to your Hull Dashboard and install a SQL Importer connector.

mongo bi install sql importer

When installed go to the settings pane where most of the setup happens. Start with selecting mysql as the type of database, then copy paste the hostname, port and username exactly as they are provided in the MongoDB cluster connect modal. Additionally you need to provide database name you want to query and extra connection string in the field below to enable SSL connection - ssl=true. Finally, type in your user password.

mongo bi connector settings

By default connector allows to import Users data, if you want to get Events or Accounts data, define it using "Import Type" field in the section below.

When everything is ready click "Save changes" and go back to the overview screen to click "Query Editor".

mongo bi connector query editor

Here you can write your SQL language query to fetch data from MongoDB instance and pull them as Users, Events or Accounts into your Hull organization.

In this guide we are using the data sample provided by MongoDB Atlas service and try to get data from sample_analytics database, collection customers.

This is the most basic query we can write:

SELECT email, name, birthdate FROM customers

Once the query is written you can hit "Preview" button to get the sample of results.

mongo bi connector preview

IMPORTANT: There are two important caveats when writing those queries: - this query builder is not meant as generic SQL query tool, every time the query needs to return one of required columns for a particular entity (e.g. email for users). See connector documentation for details. - Hull cannot process attribute names with $ or .. The latter can happen when querying BI Connector, in such case rename the column name using SQL as keyword.

Once you are happy with the previewed query save it with the "Save" button and you can either perform full fetch using the "Import" button or let the connector start fetching data on interval specified in the settings of the connector.

In any case the data will be imported eventually as Hull Users and their profile will looke like this:

mongo bi connector profile