Azure Cosmos DB Shell: How to Query Your Database Directly From the Portal

Working with Azure Cosmos DB usually means moving between the Azure portal, Data Explorer, command-line tools, and application code.

That workflow is changing with Azure Cosmos DB Shell.

The shell provides a command-line style experience for working with Azure Cosmos DB for NoSQL. It supports navigation across databases and containers, querying documents, creating and updating data, and other database operations. Microsoft also provides the shell through a VS Code extension, a .NET global tool, and self-contained binaries.

For developers, the interesting part is not simply that another query tool exists. The shell brings a familiar terminal workflow closer to Cosmos DB, while the Azure portal's Data Explorer continues to provide an in-browser way to create and query data.

This article looks at how the Cosmos DB Shell works, how to query data, when it is useful, and what developers should consider before using it against production data.

What Is Azure Cosmos DB Shell?

Azure Cosmos DB Shell is a command-line interface for Azure Cosmos DB for NoSQL.

Instead of navigating through several portal screens, you can work with databases and containers using commands such as:

ls
cd mydb
cd users
pwd

Once you are inside a container, you can execute a Cosmos DB query:

query "SELECT * FROM c"

The shell supports database and container navigation, data manipulation, JSON processing, command piping, and connection management.

A simplified workflow looks like this:

Developer
    |
    v
Cosmos DB Shell
    |
    +-- Database
    |
    +-- Container
    |
    +-- Query
    |
    +-- Documents
    |
    v
Azure Cosmos DB

This is especially useful for developers who are already comfortable with command-line tools.

How Is It Different From Data Explorer?

Azure Cosmos DB already has Data Explorer in the Azure portal.

Data Explorer lets you browse databases and containers, create items, and execute SQL queries directly from the browser.

The shell provides a different workflow.

Capability	Azure Portal Data Explorer	Cosmos DB Shell
Browser-based	Yes	No
Terminal workflow	No	Yes
Browse databases	Yes	Yes
Browse containers	Yes	Yes
Run NoSQL queries	Yes	Yes
Create documents	Yes	Yes
Update documents	Yes	Yes
Delete documents	Yes	Yes
Pipe output	Limited	Yes
JSON processing with `jq`	No	Yes
Automation-friendly	Moderate	High
Works naturally with scripts	Limited	Yes

The choice is mostly about workflow.

If you are already inside the Azure portal and investigating one container, Data Explorer is convenient.

If you are working from a terminal, script, CI environment, or developer workstation, the shell can be more natural.

Installing Cosmos DB Shell

Microsoft currently provides multiple installation options.

The supported approaches include:

VS Code extension
.NET global tool
Self-contained binary

The VS Code extension is listed as the recommended option in Microsoft's current installation documentation.

After installation, verify the shell:

cosmosdbshell --version

You should receive the installed shell version.

You can then start the interactive shell:

cosmosdbshell

The shell uses the CS > prompt for interactive commands.

Connecting to Azure Cosmos DB

The shell supports different authentication approaches.

For example, an endpoint can be supplied with Microsoft Entra ID or other supported credential mechanisms.

A simplified connection example is:

cosmosdbshell --connect https://myaccount.documents.azure.com:443/

When connecting with an endpoint without additional credential arguments, the shell can use the default Azure credential chain. The shell also supports Microsoft Entra ID and managed identity connection options, as well as account-key based connection strings.

For development environments, Microsoft Entra authentication is generally preferable to placing long-lived account keys in scripts.

A production-oriented approach looks like:

Developer / Automation Identity
          |
          v
Microsoft Entra Authentication
          |
          v
Azure Cosmos DB

This keeps authentication separate from the query itself.

Navigating Databases and Containers

After connecting, the first useful command is:

ls

This lists databases available in the current location.

For example:

CS > ls

customers
orders
products

Move into a database:

cd customers

Then list its containers:

ls

You can move into a container:

cd users

Check your current location:

pwd

You might see:

/mydb/users

This navigation model is intentionally similar to working with directories in a terminal.

That makes the shell easy to understand if you already use commands such as cd, ls, and pwd.

Running Your First Query

Once you are inside a container, you can execute a Cosmos DB query.

For example:

query "SELECT * FROM c"

This retrieves documents from the current container.

A safer query for a large container is:

query "SELECT TOP 10 * FROM c"

You can also select specific fields:

query "SELECT c.id, c.name, c.email FROM c"

The Cosmos DB query language uses SQL-like syntax while working with JSON documents. It supports familiar clauses such as SELECT, FROM, WHERE, ORDER BY, and GROUP BY.

Filtering Documents

Suppose your documents look like this:

{
  "id": "1001",
  "name": "Rahul",
  "status": "active",
  "department": "engineering"
}

You can filter active users:

query "SELECT * FROM c WHERE c.status = 'active'"

You can filter by multiple conditions:

query "SELECT c.id, c.name FROM c WHERE c.status = 'active' AND c.department = 'engineering'"

For a production container with a large amount of data, avoid starting with:

SELECT * FROM c

unless you actually need every document.

Instead, select only what you need.

SELECT c.id, c.name, c.status
FROM c
WHERE c.status = 'active'

This reduces unnecessary data returned to the client.

Querying Nested JSON

Cosmos DB documents can contain nested objects.

For example:

{
  "id": "1001",
  "name": "Rahul",
  "address": {
    "city": "Delhi",
    "country": "India"
  }
}

You can query the nested property directly:

query "SELECT c.id, c.name, c.address.city FROM c"

The query language supports property access for hierarchical JSON structures.

This is one of the areas where Cosmos DB differs from a traditional relational table. You are querying a document structure rather than a fixed collection of columns.

Using the Partition Key

Partitioning is one of the most important considerations when querying Cosmos DB.

Suppose your container uses a partition key that allows a query to target a specific partition.

You can provide a partition key value to the shell:

query "SELECT * FROM c WHERE c.id = 'user1'" --partition-key user1

The shell supports a --partition-key option for targeted queries.

This can be useful when you know the partition key for the data you need.

The broader principle is simple:

Good Query
    |
    +-- Correct Filter
    +-- Appropriate Projection
    +-- Known Partition Key
    |
    v
Less Unnecessary Work

Do not assume that adding a filter automatically makes every query inexpensive. Understand how the container is partitioned and how your query is executed.

Limiting Query Results

For troubleshooting or exploration, limit the number of documents returned.

For example:

query "SELECT TOP 20 * FROM c"

The shell also supports a maximum-item option:

query "SELECT * FROM c" --max-items 20

The command reference also documents continuation tokens for paginated results.

This matters when a container contains thousands or millions of documents.

Instead of testing with:

SELECT * FROM c

start with:

SELECT TOP 10 * FROM c

Then expand the query when you know it behaves correctly.

Aggregation Queries

The shell is not limited to retrieving individual documents.

You can run aggregate queries such as:

query "SELECT c.status, COUNT(*) AS count FROM c GROUP BY c.status"

For example, the result might tell you:

active      842
inactive    173
pending      29

This can be useful for quick operational checks.

You can also use expressions and projections to return exactly the structure you need.

SELECT VALUE {
    "status": c.status,
    "customerId": c.customerId
}
FROM c
WHERE c.status = "active"

The Cosmos DB query language supports projections that can shape the JSON returned from the query.

Working With Documents

The shell also supports data manipulation.

Create a document:

create item {"id":"user3","name":"Charlie","status":"active"}

Retrieve a document:

get user3

Update a document:

update {"id":"user3","name":"Charlie","status":"inactive"}

Delete a document:

rm user3

These operations make the shell more than a query-only utility. It can be used for development and controlled operational tasks as well.

Processing Results With jq

One particularly useful feature is command piping.

Suppose you run:

query "SELECT * FROM c"

You can pipe the JSON output into jq.

For example:

query "SELECT * FROM c" | jq '.[] | {id, name}'

You can filter the returned data:

query "SELECT * FROM c" | jq '.[] | select(.status == "active")'

Or extract a single property:

query "SELECT * FROM c" | jq '.[] | .name'

This opens up scripting possibilities that are difficult to reproduce comfortably in a browser interface.

A Practical Developer Workflow

Consider a developer investigating a production issue.

The problem report says that some customers are stuck in a pending state.

Instead of opening several portal pages, the developer could work through a sequence such as:

cd customerdb
cd customers

Then:

query "SELECT TOP 20 c.id, c.status, c.updatedAt FROM c WHERE c.status = 'pending'"

If the result needs additional filtering:

query "SELECT c.id, c.status, c.updatedAt FROM c WHERE c.status = 'pending' AND c.region = 'eu'"

Then process the response:

query "SELECT c.id, c.status, c.updatedAt FROM c WHERE c.status = 'pending'" | jq '.[] | {id, updatedAt}'

This is a much more repeatable workflow than manually copying data from a portal screen.

Using the Shell in Scripts

The command-line model also makes automation possible.

For example, a script could execute a query and save the result:

query "SELECT c.id, c.status FROM c WHERE c.status = 'failed'" > failed-items.json

The output can then be processed by another command or application.

A broader workflow could look like:

Scheduled Job
     |
     v
Cosmos DB Shell
     |
     v
Query
     |
     v
JSON Output
     |
     v
jq / Script
     |
     v
Report or Alert

However, do not treat this as permission to run unrestricted database commands from automation.

The identity used by the script should have only the permissions it requires.

Common Mistakes

Running SELECT * Against Large Containers

This is useful for a quick test but is a poor default for large datasets.

Prefer:

SELECT TOP 20 c.id, c.name
FROM c

Ignoring Partitioning

A query that looks simple may still have expensive execution characteristics depending on the container's partitioning strategy.

Understand the partition key before designing operational queries.

Using Production Credentials in Scripts

Avoid embedding account keys directly in source control or shared shell scripts.

Use appropriate Azure identity and secret-management mechanisms.

Updating Data Without a Verification Query

Before changing data, first verify which documents match the condition.

For example:

SELECT c.id, c.status
FROM c
WHERE c.status = "pending"

Only after confirming the target set should you perform an update.

Treating the Shell Like a Backup System

Exporting query results can be useful for diagnostics, but a manually generated JSON file should not automatically be considered a production backup strategy.

Backup requirements should be handled using appropriate Cosmos DB backup capabilities and operational procedures.

Troubleshooting

No Documents Are Returned

Start with a simple query:

query "SELECT TOP 1 * FROM c"

If that returns nothing, verify that you are in the correct database and container.

Check:

pwd

Then list available resources:

ls

Microsoft's troubleshooting guidance also recommends checking whether the container actually contains data and simplifying restrictive queries when diagnosing empty results.

Query Returns Too Much Data

Use TOP:

query "SELECT TOP 10 * FROM c"

Or project only the fields you need:

query "SELECT c.id, c.name FROM c"

Authentication Fails

Check:

The endpoint.
The identity being used.
Azure permissions.
Tenant information if applicable.
Managed identity configuration if used.
Whether the account is reachable from the current environment.

Query Works in the Portal but Not in the Shell

First verify the current database and container:

pwd

Then test a simple query:

query "SELECT TOP 1 * FROM c"

After that, move back to the more complex query.

This makes it easier to determine whether the problem is the query itself or the shell context.

Advantages

Faster Terminal-Based Investigation

Developers can inspect Cosmos DB without constantly switching between tools.

Scriptable

Shell commands can be incorporated into developer scripts and operational workflows.

Familiar Command Model

Commands such as ls, cd, and pwd make navigation easy to understand.

JSON-Friendly

The ability to pipe output into jq makes it practical to transform query results.

Useful for Development and Diagnostics

The shell provides a compact way to inspect data and test queries.

Disadvantages

Requires Command-Line Familiarity

Developers who prefer visual database tools may find Data Explorer easier.

Still Requires Cosmos DB Knowledge

The shell does not remove the need to understand partitioning, query behavior, indexing, or data modeling.

Dangerous With Write Permissions

Because the shell supports create, update, and delete operations, careless commands can modify real data.

Not a Replacement for Application Code

The shell is useful for exploration, diagnostics, and controlled operations. It should not replace properly tested application data-access logic.

Best Practices

Start with TOP when exploring data.
Select only the fields you need.
Understand the container's partition key.
Use targeted queries whenever possible.
Prefer Microsoft Entra authentication or managed identity where appropriate.
Do not store Cosmos DB account keys in source control.
Verify the target documents before changing data.
Use read-only access for investigation whenever possible.
Use jq for controlled JSON processing instead of manually copying large outputs.
Test operational scripts against a non-production account first.
Be careful with delete and update commands.
Treat shell-based exports as diagnostic data unless they are part of an approved data-management process.

When Should You Use Cosmos DB Shell?

The shell is a good fit when you need to:

Quickly test a Cosmos DB query.
Inspect documents from a terminal.
Troubleshoot application data.
Run repeatable diagnostic commands.
Process JSON output.
Experiment with queries during development.
Build controlled operational scripts.

Data Explorer is often more convenient when you need visual navigation or are already working inside the Azure portal.

A useful rule is:

Visual investigation
        |
        v
Azure Portal Data Explorer

Repeatable / scriptable workflow
        |
        v
Cosmos DB Shell

Both tools solve different parts of the same problem.

Summary

Azure Cosmos DB Shell provides a terminal-based way to work with Azure Cosmos DB for NoSQL. It supports database and container navigation, SQL-like queries, document operations, partition-key targeting, pagination, JSON processing, and command piping.

For developers who spend most of their time in terminals or VS Code, it can make Cosmos DB investigation faster and more repeatable.

The key is to use it as an engineering tool rather than a shortcut around database practices. Keep queries targeted, understand partitioning, protect credentials, verify data before changing it, and restrict production write access wherever possible.