[MS] Inspecting Local Data with Azure Cosmos DB Shell - devamazonaws.blogspot.com

Explore local data from the terminal, with the emulator as your development environment. Azure Cosmos DB Shell gives me a direct way to work with my data from the terminal. I can navigate databases and containers, query documents, and read a specific item without opening the portal or adding temporary application code. That is useful while I am getting an application ready to ship. A value looks wrong, a document is missing, or I want to check one partition. Instead of guessing what was stored, I can inspect it. The Azure Cosmos DB Linux Emulator provides the local environment for this walkthrough. In the previous post in this series, we used it to make local development and CI repeatable. This installment adds the shell so we can inspect that local data directly before deployment. I am reusing FleetCharge's dispatch records as the example data. The focus is the shell: connect, navigate, inspect, query, and point-read. We are troubleshooting during development, not investigating a production incident. [video width="1920" height="1080" mp4="https://devblogs.microsoft.com/cosmosdb/wp-content/uploads/sites/52/2026/10/cosmos-shell-walkthrough-captioned.mp4"][/video]

Open Azure Cosmos DB Shell

Shell is the inspection tool for this walkthrough, but it is not required to run FleetCharge or its CI tests. Choose one of these installation methods.

Install as a .NET global tool

The official installation guide includes a .NET global-tool option. This method requires the .NET SDK 10.0 or later. Install the tool and check its version:

dotnet tool install --global CosmosDBShell --prerelease
cosmosdbshell --version

If you already installed the global tool for the previous post, skip the install command and check its version. Start the shell with:

cosmosdbshell

Download a self-contained binary

Alternatively, get a self-contained binary from the official releases. This option includes its runtime, so no separate .NET installation is needed. For this Windows x64 walkthrough, I used the 1.1.280-preview Windows x64 ZIP. Extract it and open PowerShell in the extracted directory containing CosmosDBShell.exe. Check the version and start the shell:

.\CosmosDBShell.exe --version
.\CosmosDBShell.exe

For other platforms or a source build, follow the shell's installation guidance and choose the matching release asset. The source-build path requires the .NET SDK; it is not an extra step in the ZIP-based path above. The examples below use commands verified with Shell 1.1.280-preview. The print <item-id> <partition-key> command reads one item; the application and its data model have not changed.

Give the shell a local data source

The emulator lets me try these operations locally, without connecting to a live Azure account. The FleetCharge sample provides the same seed records as the previous post. If you followed that walkthrough, reuse your checkout: no application code, fixture, schema, or CI workflow changes are required. We are adding an inspection tool, not building a new application. For the walkthrough, I need:

• Azure Cosmos DB Shell, opened as described above.
• A FleetCharge checkout with Python 3.12 and uv, as described in its README.
• Docker running Linux containers on a supported x86-64 Windows or Linux host.

The previous post used Git Bash; I am using PowerShell for the host commands below. That changes the terminal syntax, not the application. Commands inside Cosmos DB Shell are in separate text blocks; they are not PowerShell commands.

Start an emulator that stays available for inspection

FleetCharge's managed demo and CI commands start their own emulators with dynamically assigned ports. They clean up their resources when they finish. That is useful for tests, but I do not want my inspection environment to disappear halfway through this walkthrough. As in the previous post, I use the sample's direct-startup approach. If your own directly started emulator is still running, reuse it: skip docker run below and continue with the readiness check. If you chose different ports, use those ports consistently for readiness, seeding, and the shell connection. Otherwise, start the emulator in one PowerShell terminal:

$image = "mcr.microsoft.com/cosmosdb/linux/azure-cosmos-emulator:vnext-latest"
docker run --rm --name fleetcharge-shell-local `
    -p 127.0.0.1:8081:8081 -p 127.0.0.1:8080:8080 `
    $image --protocol http

Leave that terminal running. The emulator's standard ports are exposed unchanged: 8081 for the database endpoint and 8080 for readiness. Both are bound to loopback. If either port or the container name is already in use, check what owns it before continuing. Do not stop or reuse an unrelated container. In a second PowerShell terminal, opened at the FleetCharge repository root, check readiness:

Invoke-RestMethod -Uri http://127.0.0.1:8080/ready

Wait for HTTP 200 with ready: true before seeding. If the emulator is still starting, check again rather than continuing after an error. Then install the locked dependencies, preserve any existing local settings, and explicitly select the endpoint and database for this session. These environment variables override the checkout's existing .env settings, keeping the seed script and shell on the same endpoint without changing application code:

uv sync --locked
if (-not (Test-Path .env)) {
    Copy-Item .env.example .env
}
$env:COSMOS_ENDPOINT = "http://127.0.0.1:8081"
$env:COSMOS_DATABASE = "fleetchargetest-demo"
uv run --locked python -m scripts.seed_cosmos

The seed command provisions the containers and writes the sample documents. Run it only against your own local demonstration environment: rerunning it upserts the fixture records and can replace changes you made to those records. The shell can now inspect those records directly. Neither FleetCharge's API nor Ollama needs to be running for this walkthrough.

Connect to the emulator

Inside Cosmos DB Shell:

connect http://127.0.0.1:8081/

The shell recognizes this loopback emulator endpoint and selects the well-known emulator key and Gateway mode. Optionally, to display the current connection information, run connect without an argument. This is an inspection step, not a second connection:

connect

The connection information should show http://127.0.0.1:8081/ and Gateway. This is the database endpoint, not the readiness URL. Now I can start exploring:

ls

Figure 1. Confirm the local endpoint, then list the databases without leaving the terminal.

Find the FleetCharge database

At the account level, ls lists databases. The seed command created one named fleetchargetest-demo. Move into it, check the current path, and list its containers:

cd fleetchargetest-demo
pwd
ls

For this example, I want dispatchUpdates, the container holding the current pickup-bay information for each depot:

cd dispatchUpdates
pwd

The current path is now:

/fleetchargetest-demo/dispatchUpdates

I can also navigate directly using the full path:

cd /fleetchargetest-demo/dispatchUpdates

Figure 2. Navigate from the account to FleetCharge's dispatch data like moving through a filesystem.

Look at the data

Now that I am inside the container, I can inspect the items stored there. To return up to 10:

ls -m 10

That is a limit, not a request for the 10 newest items. This command does not establish a chronological order. For this tiny seeded container, I can also remove the limit:

ls -m 0

On a fresh seed, there are two dispatch documents:

Depot	Item ID	Update reference	Pickup bay
SEA-01	current-dispatch	dispatch-001	BAY-2
PDX-02	current-dispatch	dispatch-099	BAY-99

Unlimited listing is convenient for two local sample documents, not a default I would carry over to a large container. Start with a limit or a narrower query. This is useful while developing because I can see what is actually in Cosmos DB, rather than what I expected the application to write. No portal. No temporary endpoint. No debug code.

Figure 3. Inspect the stored documents directly in the shell, with the emulator supplying the local data.

Query the container

Listing documents is useful, but most of the time I am looking for something specific. Start with a basic query against this small container:

query "SELECT * FROM c"

Now narrow the results to one depot:

query "SELECT * FROM c WHERE c.depotId = 'SEA-01'"

On a fresh seed, that returns the Seattle dispatch document. Or return only the fields I care about:

query "SELECT c.id, c.depotId, c.updateId, c.pickupBay FROM c"

That last query projects four fields from both depots; it does not include the Seattle filter. The smaller result is easier to scan without the system metadata included by SELECT *. These are literal, interactive queries against known sample data. Application code should continue using parameterized queries for values supplied at runtime, as FleetCharge already does.

Figure 4. Narrow the view to a single depot using the same query language the application uses.

Point-read a specific item

Sometimes I already know exactly which document I want. The dispatchUpdates container uses /depotId as its partition key. For Seattle, the item ID is current-dispatch and the partition-key value is SEA-01:

print current-dispatch SEA-01

The business fields in the result are shown below. This is an excerpt; the actual point-read output also includes Cosmos DB system metadata.

{
  "id": "current-dispatch",
  "type": "dispatchUpdate",
  "depotId": "SEA-01",
  "updateId": "dispatch-001",
  "pickupBay": "BAY-2"
}

For Portland:

print current-dispatch PDX-02

The corresponding excerpt is:

{
  "id": "current-dispatch",
  "type": "dispatchUpdate",
  "depotId": "PDX-02",
  "updateId": "dispatch-099",
  "pickupBay": "BAY-99"
}

Same item ID. Different partition key. Different document. For a point read, the item ID alone is not enough: the complete partition key is part of the address. The shell's print command performs a point read, rather than querying the container to find a matching item. For FleetCharge, that makes it straightforward to compare the current dispatch document for two depots without querying every dispatch document.

Figure 5. current-dispatch identifies a different item in each depot's partition.

Move around without starting over

The shell works much like navigating a filesystem. Move back one level and list the containers:

cd ..
ls

Or jump directly back to the dispatch container:

cd /fleetchargetest-demo/dispatchUpdates

That sounds simple, but it matters when an application has several containers. I can move through the data model without reconnecting or rebuilding each command.

Use it while getting the application ready to ship

This is the part I like about putting the emulator and the shell together. The shell makes the stored data visible while I am building and testing. The emulator supplies the repeatable local environment behind it. An application write looks unexpected. Open the shell. A local test fails because the stored document does not look right. Inspect the same document in the same test environment while it is still available. Need to check one partition without adding diagnostic code? Use a point read. The workflow stays close to the application: Build -> Run -> Inspect -> Query -> Fix -> Run again The command-line workflow also fits naturally into development containers and scripted tooling. Here it complements FleetCharge's existing CI checks; it does not replace them or add a new CI gate. The same shell commands work after an application changes the data. If I run the dispatch-feed example from the FleetCharge README, I can point-read the updated document and compare its updateId and pickupBay with what the application acknowledged. I do not need a separate inspection endpoint.

When the local result is not what I expected

What I see	What I check before changing code
The shell cannot connect.	Is Docker running, did readiness return HTTP 200, and am I connecting to port 8081, not 8080?
The database is missing.	Did I seed this endpoint? Did a managed demo or CI run use a different port or already clean up its database?
My query runs in the wrong place.	Run pwd, then cd /fleetchargetest-demo/dispatchUpdates.
A point read cannot find the item.	Check both current-dispatch and the depot's partition-key value.
Seattle shows BAY-7 instead of BAY-2.	Check updateId. Running FleetCharge's dispatch-feed example changes the seeded snapshot; that difference is expected.

These are local checks during development, not a production incident-response procedure. The emulator does not prove production authentication, authorization, performance, throughput, or resiliency. Its well-known key is not a production credential, and successful local operations do not validate Azure access. Keep this HTTP setup on loopback. FleetCharge itself accepts only loopback Cosmos endpoints and test-prefixed database names. It is intentionally not configured for deployment to a live account. Production readiness still needs the appropriate security, networking, deployment, monitoring, and workload validation.

Try it yourself

With the local emulator running and the FleetCharge fixtures seeded, open Cosmos DB Shell and try:

connect http://127.0.0.1:8081/
ls
cd fleetchargetest-demo
ls
cd dispatchUpdates
pwd
ls -m 10
query "SELECT * FROM c WHERE c.depotId = 'SEA-01'"
print current-dispatch SEA-01
print current-dispatch PDX-02

That is enough to go from a local application environment to inspecting the data behind it without writing additional application code. When finished, in the repository terminal with the same Cosmos environment variables, remove only your demo database:

uv run --locked python -m scripts.cleanup_cosmos

Then stop the emulator's docker run terminal with Ctrl+C. The --rm option removes that container when it exits. This walkthrough does not configure persistent storage, so do not treat it as a durable data store. Make the shell part of your next local test run. Download Azure Cosmos DB Shell, connect it to the emulator, and run the query and point reads above. Confirm that current-dispatch returns BAY-2 for SEA-01 and BAY-99 for PDX-02. Then inspect one document your application writes. Compare its stored values with what your tests expect, fix any mismatch, and rerun your local checks before opening your next pull request. If you have not set up local development and CI yet, start with From Local Development to CI Workflows with the Azure Cosmos DB Emulator. Then return here to add direct data inspection to that workflow.

Further reading

• FleetCharge sample and emulator workflow
• Azure Cosmos DB Shell
• Shell connection guide
• Shell command reference
• Azure Cosmos DB Linux emulator

About Azure Cosmos DB

Azure Cosmos DB is a fully managed NoSQL and vector database for modern applications, including AI. Ready to move beyond local testing? Try Azure Cosmos DB for free.

Follow us on X, YouTube and LinkedIn for product updates and developer walkthroughs.

Post Updated on October 27, 2026 at 01:31PM
Thanks for reading
from devamazonaws.blogspot.com