Docs Menu

Get Started

On this page

  • Prerequisites
  • Create a Federated Database Instance
  • Install Client Software
  • Connect to Your Federated Database Instance
  • Run SQL Queries

The support for SQL queries is available as a Preview feature. This feature and the corresponding documentation may change at any time during the Preview phase.

MongoDB Atlas SQL setup diagram

This page guides you through setting up a federated database instance with sample data. You can then run SQL queries against the sample data using the MongoDB JDBC Driver.

To create a federated database instance and map it to the sample data:


Select Data Federation from the left navigation panel.


If you have an existing federated database instance, instead click Create Federated Database in the top right corner of the dashboard.


You can use a sample dataset to start exploring Atlas SQL through Atlas Data Federation without configuring a data source yourself.

Configure Data Sources

To learn more about configuring different types of data sources, see Define Data Stores for a Federated Database Instance.

If you want to configure data from a Atlas cluster, you must use MongoDB version 5.0 or greater for that cluster to take advantage of Atlas SQL.


Expand the S3 store sample-data-atlas-data-lake if it isn't expanded already.

For this tutorial, configure your federated database instance as follows using the Federated Database Instance panel:


Click next to the default collection Collection0 to edit its name. For this tutorial, rename your collection Sessions.


Click next to the default name Database0 to add a collection to the database. For this tutorial, name your new collection Users.


Drag and drop the following data sources into the respective federated database instance virtual collections:

  • /mflix/sessions.json, into the Sessions collection, and
  • /mflix/users.json into the Users collection.

Your federated database instance displays a success message.

To learn more about configuring Atlas Data Federation with real data stores, see Define Data Stores for a Federated Database Instance.

Install the following client software to connect to and query your sample data with SQL.

DBeaver is a free, universal database tool. You can use it to explore your sample data in this tutorial.

Download and install DBeaver (Community Edition).

Download the latest MongoDB JDBC Driver version.


To connect with the Atlas SQL interface, you must do the following:

  • Use MongoDB JDBC driver version 2.0.0 or later.
  • Download the all.jar file, which includes necessary driver classes and dependencies.

To connect to your federated database instance from DBeaver:


If it isn't already displayed, select Data Federation from the left navigation panel.


This tutorial uses the JDBC Driver to connect. See Connect for alternative connection methods.


Atlas Data Federation provides the following information to connect to your federated database instance:

  • URL
  • Port
  • Database

You'll need this information in a later step.

  1. In DBeaver, click Database and select Driver Manager from the dropdown menu.
  2. Click New to open the Create new driver modal.
  3. In the Settings tab, enter the following information:

    Driver Name
    Class Name
  4. In the Libraries tab, click Add File and add your JDBC driver all.jar file.

    Click Find Class.

  5. Click OK. The Create new driver modal closes.
  1. In DBeaver, click Database and select New Database Connection from the dropdown menu to open the Connect to a database modal.
  2. From the list of databases, select the MongoDB database driver that you created in the previous step.


    If you don't see MongoDB, select the All category inside the modal.

    Click Next.

  3. In the Main tab, enter the following information:

    Your JDBC URL from step 5.
    The MongoDB user to connect with.
    The MongoDB user's password.
  4. In the Driver properties tab, expand User Properties. Add the following key-value properties:

    The name of your database from step 5. If you are following the tutorial, this is myFederatedVirtualDatabase.
    The MongoDB user to connect with. Not required if you entered a Username in the previous step.
    The MongoDB user's password. Not required if you entered a Password in the previous step.

In the Database Navigator, expand your MongoDB connection to verify that the sample data that the federated database instance store is mapped to is accessible.

To learn more about the different methods you can use to connect to a federated database instance, see Connect.

To run SQL queries in DBeaver:


The DBeaver Database Navigator displays your virtual databases.

  1. Right-click the virtual database you want to query.
  2. Select SQL Editor.
  3. Select Open SQL console.

    A new SQL console window opens connected to the virtual database you selected.


If the query is successful, Atlas SQL displays the results in a table view below your query.

Try running the following SQL queries against the sample data in your federated database instance.


These examples reference data that we suggest that you add in this tutorial. If you are using different data, modify these queries for your namespaces.

SELECT * FROM Sessions

Atlas SQL returns all documents from the Sessions collection.


Atlas SQL returns two documents from the Users collection.

SELECT * FROM Users WHERE name='Jon Snow'

Atlas SQL returns documents from the Users collection where the user's name is Jon Snow.

For an Atlas SQL command reference, see SQL Reference.

←  Query with SQLConnect →
Give Feedback
© 2022 MongoDB, Inc.


  • Careers
  • Investor Relations
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2022 MongoDB, Inc.