DocumentDB for VS Code

User Manual — Back to User Manual

Interactive Shell

The Interactive Shell is a REPL (Read-Eval-Print Loop) terminal embedded in VS Code. It gives you a command-line experience for DocumentDB and MongoDB API databases, fully integrated with the extension’s connection management. Type a command, see the result, type the next one.

Unlike the Query Playground, which is file-based and suited for multi-statement scripts, the Interactive Shell is designed for quick, ad-hoc exploration: checking what databases exist, browsing collections, running one-off queries, and iterating on results.

Table of Contents

Getting Started

There are several ways to open an Interactive Shell session:

  1. From the tree view: Right-click a cluster, database, or collection node in the Connections, Discovery, or Azure views, then select Open Interactive Shell.
  2. From the inline button: Click the terminal icon (rightmost icon) next to a database or collection node in the tree view.
  3. From the Collection View: Use the Open in Shell toolbar button to export your current find query into a new shell session.
  4. From the Query Playground: Use a CodeLens link to launch a shell for the same connection.

Inline action buttons on a collection node: Open Collection View, New Query Playground, Open Interactive Shell

The three inline icons next to each collection node are (from left to right): Open Collection View, New Query Playground, and Open Interactive Shell.

When the shell opens, it displays a compact logo followed by the saved connection name, host, identity when available, authentication method, and active database. The prompt shows your current database name:

╭────╮
│ >_ │ DocumentDB Shell
╰────╯
Connected to: Local development (mycluster.example.com)
Identity: admin | Authentication: Username and Password (SCRAM) | Database: myDatabase
Type "help" for available commands.

myDatabase>

Shell Commands

The following built-in commands are available at the prompt:

Command Description
show dbs List all databases on the server
show collections List all collections in the current database
use <database> Switch to a different database (updates the prompt and tab name)
it Iterate to the next batch of results from the last cursor
help Show available commands and usage information
exit / quit Close the shell session
cls / clear Clear the terminal screen

Running Queries

Type any DocumentDB API query at the prompt and press Enter:

myDatabase> db.users.find({ status: "active" })

You can use the full query language, including:

Results are displayed as formatted JSON directly in the terminal, with optional ANSI color coding for readability.

Persistent Variables

Unlike the Query Playground (where each block runs in a fresh context by default), the Interactive Shell maintains state across commands within a session:

myDatabase> const threshold = 25
myDatabase> db.users.find({ age: { $gt: threshold } })

Variables, functions, and other JavaScript state persist until you close the shell session. This makes it easy to build up complex queries incrementally.

Autocompletion and Ghost Text

The shell provides two forms of input assistance:

Interactive Shell showing tab completion for collection methods and ghost text suggesting a field name

In this example, the shell suggests find(), findOne(), and other methods after typing db.restaurants.find (top). It also suggests the field name reviews as ghost text after the user typed re in a query (bottom). Field suggestions come from schema information gathered locally as you browse and query your data.

Tab Completion

Press Tab to trigger completion suggestions based on your current input:

Context What Tab Suggests
Empty prompt Shell commands: show, use, db, help, exit, it, …
After show dbs, collections
After use Available database names
After db. Collection names in the current database
After db.collection. Collection methods: find(), aggregate(), insertOne(), …

When there are multiple matches, the shell inserts the common prefix and displays all options in a multi-column list (similar to bash/zsh). Continue typing to narrow the list; Tab cycling is not currently supported. Collection names are loaded in the background after connecting and after use <database>, so they are normally ready for the first completion request.

Ghost Text (Inline Suggestions)

As you type, the shell may display a dim, inline suggestion showing what it thinks you’re about to type. For example:

The shell also suggests closing brackets automatically. When your input has unclosed brackets, parentheses, or braces, the ghost text shows the exact sequence needed to close them. For example:

Press Right Arrow to accept an insertable suggestion. Tab checks completion candidates first and accepts the visible suggestion only when no completion candidate applies. Keep typing to ignore either kind of suggestion.

Syntax Highlighting

The shell colorizes your input in real time as you type:

Color Applied To
Cyan JavaScript keywords, BSON constructors
Green Strings
Yellow Numbers, $-prefixed operators, escape sequences
Magenta Shell commands (show, use, it, etc.)
Gray Comments
Red Regex literals (and unterminated string errors)

Syntax highlighting can be disabled via the documentDB.shell.display.colorSupport setting for accessibility (screen readers) or piped output.

Cursor Iteration

When a query returns more documents than the batch size (default: 50), the shell displays the first batch and shows a hint:

myDatabase> db.users.find({})
[
  { "_id": ObjectId("..."), "name": "Alice", ... },
  ...
]
Type "it" for more

Type it and press Enter to fetch the next batch. You can keep typing it until all results are exhausted.

The batch size is controlled by the documentDB.batchSize setting.

Cancelling Operations

If a query is taking too long, press Ctrl+C to cancel it immediately. The shell terminates the running operation and creates a fresh execution context, so you can continue working without restarting the session.

Multi-line Input

The shell detects incomplete expressions automatically. If you type an opening brace or bracket without closing it, the shell waits for more input instead of trying to execute:

myDatabase> db.orders.aggregate([
...   { $group: { _id: "$status", count: { $sum: 1 } } },
...   { $sort: { count: -1 } }
... ])

When pasting multi-line text, the shell can handle it in several ways, controlled by the documentDB.shell.multiLinePasteBehavior setting:

Option Behavior
ask (default) Prompts you to choose how to process the pasted text
alwaysAsk Always shows the prompt, even if VS Code’s own paste warning is enabled
executeAsOne Joins pasted lines into a single expression and executes
runLineByLine Runs each pasted line independently

After query results that reference a known collection, the shell shows two clickable action links on the same line:

↗ Collection View [myDatabase.users]  ↗ Query Playground [myDatabase.users]

The Interactive Shell is connected to the other query surfaces in the extension:

For more details on the Query Playground, see the Query Playground documentation.

Settings

The following settings control shell behavior:

Setting Default Description
documentDB.shell.initTimeout 60 Maximum time (in seconds) to wait for the shell to connect during initialization
documentDB.shell.display.colorSupport true Enable ANSI color support for syntax highlighting and formatted output. Disable for screen readers or piped output
documentDB.shell.display.autocompletion true Tab completion, the candidate list, and the dim inline suggestions at the cursor
documentDB.shell.display.inlineHints true The informational hints marked with 🛈, which are never inserted into your input
documentDB.shell.multiLinePasteBehavior ask Controls how multi-line text is handled when pasted into the shell
documentDB.batchSize 50 Number of documents to display per cursor iteration (shared with Query Playground)

Run help in the shell for clickable shortcuts to the color, inline-hint, and autocompletion settings. Each shortcut also prints the full setting ID for manual access.

Tips and Best Practices

Related: Query Playground How It Works Behind the Scenes
This site is open source. Improve this page.