On this page
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.
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.
A MongoDB database user with which to connect.
Create a Federated Database Instance
To create a federated database instance and map it to the sample data:
Under Data Sources, select AWS S3.
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.
Add sample data to your federated database instance.
Expand the S3 store
sample-data-atlas-data-lake if it isn't
For this tutorial, configure your federated database instance as follows using the Federated Database Instance panel:
To learn more about configuring Atlas Data Federation with real data stores, see Define Data Stores for a Federated Database Instance.
Install Client Software
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).
Install JDBC Driver
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.
all.jarfile, which includes necessary driver classes and dependencies.
Connect to Your Federated Database Instance
To connect to your federated database instance from DBeaver:
Select JDBC Driver.
This tutorial uses the JDBC Driver to connect. See Connect for alternative connection methods.
Connect from DBeaver.
Add a new driver.
In DBeaver, click Database and select Driver Manager from the dropdown menu.
Click New to open the Create new driver modal.
In the Settings tab, enter the following information:Driver Name
In the Libraries tab, click Add File and add your JDBC driver
Click Find Class.
Click OK. The Create new driver modal closes.
Create a database connection.
In DBeaver, click Database and select New Database Connection from the dropdown menu to open the Connect to a database modal.
From the list of databases, select the
MongoDBdatabase driver that you created in the previous step.
If you don't see
MongoDB, select the All category inside the modal.
In the Main tab, enter the following information:JDBC URLYour connection string from step 5.UsernameThe MongoDB user to connect with.PasswordThe MongoDB user's password.
In the Driver properties tab, expand User Properties. Add the following key-value properties:databaseThe name of your virtual database.userThe MongoDB user to connect with. Not required if you entered a
Usernamein the previous step.passwordThe MongoDB user's password. Not required if you entered a
Passwordin the previous step.
If you created your first virtual database during this tutorial, your database's name is
Database0. Otherwise, find your virtual database's name in your Atlas SQL federated database instance interface under the Data Federation tab.
To learn more about the different methods you can use to connect to a federated database instance, see Connect.
Run SQL Queries
To run SQL queries in DBeaver:
Example SQL Queries
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
SELECT * FROM Users LIMIT 2
Atlas SQL returns two documents from the
SELECT * FROM Users WHERE name='Jon Snow'
Atlas SQL returns documents from the
Users collection where the user's
For an Atlas SQL command reference, see SQL Reference.