Docs Menu

Docs HomeMongoDB Atlas

Connect from the MongoDB Shell

On this page

  • Prerequisites
  • Procedure
  • Run SQL Queries

This page describes how to connect to a federated database instance through the MongoDB Shell (mongosh).

  • A federated database instance that is mapped to one or more data stores.


    If some or all of your data comes from an Atlas cluster, you must use MongoDB version 5.0 or greater for that cluster to take advantage of Atlas SQL.


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


If you do not have the MongoDB Shell installed:


To check that your installation was successful, in your terminal, run:

mongosh --version

If the installation was successful, mongosh displays a version.

If you already have the MongoDB Shell installed:



The MongoDB Shell, or mongosh, is separate from the mongo versions in the modal dropdown menu.

If you want to ensure that you have mongosh installed, in your terminal, run:

mongosh --version

If mongosh is installed, it displays a version.


Your authentication method depends on how your Database Access is configured. To learn more about database access, see Configure Database Users.

You can choose:

  • Password (SCRAM), or

  • X.509.

Atlas Data Federation provides a connection string for your authentication method.


If you selected the Password (SCRAM) authentication method, you are prompted for a password for the connecting user.


To confirm that you are connected to your federated database instance, using mongosh, run:

show dbs

If you successfully connected to your federated database instance that is mapped to a data store, mongosh displays the names of your virtual databases.

You can run Atlas SQL queries against your federated database instance virtual collections using the MongoDB Shell.

For an Atlas SQL command reference, see SQL Reference.

Atlas SQL supports an aggregation pipeline stage syntax and a short-form syntax for constructing the SQL queries. You can use either of these syntaxes to write queries in the MongoDB Shell:

You can use the $sql aggregation pipeline stage to write Atlas SQL queries. See $sql for a list of properties you must provide to $sql.


Atlas SQL uses the dialect mongosql.

The following example uses $sql syntax to execute the Atlas SQL statement select * from Users limit 2:

db.aggregate( [ { $sql: { statement: "select * from Users limit 2", format: "jdbc", dialect: "mongosql" } } ] )

You can use a short-form syntax, db.sql, to supply an Atlas SQL statement directly.


Short-form syntax is not stable and may change in the future.

db.sql( "select * from Users limit 2" )

Try running the following Atlas SQL queries against the Get Started sample federated database instance, or modify them to read your own data.


These examples use short-form syntax.

db.sql("select * from Sessions")

Atlas SQL returns all documents from the Sessions collection.

db.sql("select * from Users limit 2")

Atlas SQL returns two documents from the Users collection.

db.sql("select * from Users where name='Jon Snow'")

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

←  Connect from TableauSchema Management →
Share Feedback
© 2023 MongoDB, Inc.


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