Azure Cosmos DB for VS Code

Connect to Azure Cosmos DB for NoSQL from VS Code to explore accounts, manage databases and containers, edit items, and run queries without leaving your editor. Work with Azure accounts, connection strings, or the local Azure Cosmos DB Emulator.

Install from the Visual Studio Marketplace | Read the documentation | Report an issue

Get Started

1. Install the extension from the Visual Studio Marketplace or search for Azure Cosmos DB in the VS Code Extensions view.

2. Open the Azure view in the Activity Bar and choose how to connect:

   • Sign in to Azure to browse Cosmos DB accounts across your subscriptions.
   • Select New Connection… to attach an account with a connection string.
   • Select New Emulator Connection under Local Emulators to use a local development instance.

3. Expand an account, database, and container. Use the context menu to create or open items, import documents, or launch the Query Editor.

4. Run a query such as SELECT * FROM c, then inspect the results as a table, JSON, or tree. Query metrics and index recommendations help you tune the request.

Don't have an account? Create an Azure account or use the Azure Cosmos DB Emulator for local development.

Features

Azure Cosmos DB Explorer

The Azure Cosmos DB Explorer helps you find, view, and manage your Azure Cosmos DB databases.

• Discover Database Accounts: Scan your Azure subscriptions for available database accounts and browse their resources.

• Open in Azure Portal: Open an account directly in the Azure portal for service-level configuration.

• Manage Resources: View, create, and delete databases, containers, stored procedures, triggers, and documents.

• Edit Documents and Scripts: Open documents and stored procedures in the editor, then save changes to the service.

• Filter and Sort: Narrow large resource trees and choose the order that best fits your workflow.

• Workspace Connections: Attach database accounts with connection strings, including accounts that are not discoverable through your current Azure subscriptions.

Account Overview Dashboard

The Account Overview Dashboard gives you an at-a-glance view of a Cosmos DB account: inventory, provisioned vs. normalized RU consumption, partition health, active alerts, and recommendations. Open Account Overview → Overview from an account node in the Explorer.

The dashboard has three tabs: Monitoring, Databases and Containers, and Advisories. The Account Overview submenu also provides shortcuts to each monitoring metric and to Advisories. Metric shortcuts select the corresponding card and focus its chart in the existing Monitoring tab, preserving the time range and database scope; they do not open separate dashboards.

Expand Account details for View Cost, View JSON, and Additional account properties. View Cost opens Azure Portal Cost Analysis scoped to the account in its Azure cloud. View JSON retrieves the account resource from Azure Resource Manager and opens formatted JSON in VS Code without requesting keys or connection strings. The action bar reuses the existing database/container creation wizards and account deletion confirmation. Add container uses the database selected in the header; with All databases, it first asks you to choose a database within this account, including empty databases. These creation/deletion actions require the corresponding Azure write permissions. Try Data Modeler opens the modeler for this account; it requires AI features enabled and available GitHub Copilot models.

While Add database or Add container runs its native VS Code wizard, Overview is dimmed and unavailable to mouse and keyboard interaction. Cancel in the wizard to return without changes. After successful creation, Overview unlocks once inventory refresh finishes. Failures appear in a Fluent error message bar and are announced assertively to screen readers without moving focus.

Overview loads on opening and does not auto-refresh, including when you return to the editor. Refresh reloads every section, including inventory metrics, the selected container's partition telemetry, alerts and advisories. Changing a filter reloads only the data that depends on it. The header shows the local date and time when the displayed metric charts were generated, to the left of the filters; this is not the freshness timestamp for every section or the latest Azure metric sample.

The Refresh button shows a spinner for an explicit Refresh or a metric time/database-scope change, not for the initial load. Its label stays Refresh, with no separate updating text. Refresh and the header's database/time-range selectors are unavailable while data requests finish, including initial loading, so another filter change cannot overlap the current load. They become available again after completion or failure, retaining the selected values. Each section retains its own loading state. User-requested updates are announced to screen readers.

Sections read Azure resource metadata, Monitor metrics/alerts, Advisor recommendations and configured diagnostic logs. When a source is unavailable, its section shows an explicit state rather than treating missing data as zero:

• No data — no usable result is available for the selected window/source; this does not establish that the account is healthy.
• Not supported — the section doesn't apply to this account's API (for example, inventory metrics are only available for NoSQL (Core) API accounts).
• Access required — your Azure role doesn't grant permission to read the underlying data.

Required Azure roles

Data is fetched with your Azure credentials. The table lists typical read roles; equivalent custom permissions and assignment scope also determine access. A permission failure is shown for the affected source while independent sections remain usable.

Tier-2 derived advisories (cross-partition query fan-out, shard-key misalignment, uncontrolled ingestion, and shared-throughput starvation) additionally read the account's resource-specific CDB* diagnostic-log tables. They require diagnostic-log collection and effective query access, such as Log Analytics Reader. Missing log evidence leaves successful independent findings visible and reports the gap as Partial coverage. See the guide's log setup and permissions.

Derived advisory explanations, suggested actions and threshold references highlight numeric evidence and its units on a subtle theme-aware background. Their underlying strings remain readable plain text: paired backticks mark a highlighted phrase (for example, `400 RU/s`), not HTML or general Markdown. Translations retain those delimiters around the complete value and unit in the translated word order. Literal backticks and backslashes in resource names or query text are escaped before interpolation. Highlights remain ordinary inline text for screen readers, without extra announcements or keyboard stops.

Learn more about assigning roles in Azure role-based access control.

For explanations of health, charts, alerts and everyday use, read the Account Overview guide. When implementing or changing Account Overview calculations, refresh behavior, actions or diagnostics, use the implementation specification for exact rules, rationale and regression requirements.

Data Modeler

Data Modeler (Preview) helps you choose partition keys for Azure Cosmos DB for NoSQL using GitHub Copilot. The cosmosDB.experimental.dataModeler.enabled setting defaults to true. Set it to false to hide the Command Palette entry and Account Overview promotion without disabling other AI features. Changes take effect immediately; existing modeler tabs and the command to delete saved modeler data remain available. Open it with Try Data Modeler in Account Overview, from an account in Explorer, or run Data Modeling Wizard from the Command Palette. Requires available GitHub Copilot models and AI features enabled.

1. Choose a workload template or define your own schemas, queries, and scale estimates.
2. Compare single-path partition-key recommendations, query routing, and warnings. Review assumptions before deploying.
3. Deploy selected databases and containers directly, or export editable Bicep, Terraform, or C# SDK code. Deployment requires resource-creation permissions and may incur Azure charges; it does not upload documents.

Work is saved locally per account so you can resume later; saved sessions expire 30 days after their last save. To permanently clear local Data Modeler data for every account, run Cosmos DB: Delete All Data Modeler Data from the Command Palette and confirm. This closes all Data Modeler tabs and removes saved sessions, including legacy data. It does not delete deployed databases or containers, saved container schemas, or query history. See modeling details and the telemetry inventory for more.

Query Editor

The Query Editor provides a focused workspace for writing, running, and tuning Azure Cosmos DB for NoSQL queries.

• Language Support: Get syntax highlighting, completions, diagnostics, hover documentation, signature help, and formatting. Schema-aware suggestions include properties discovered in the active container.

• Query History: Automatically saves previously executed queries, allowing you to open and reuse them later.

• Run Queries: Execute queries and view results in Table, JSON, or Tree view.

• Export Results: Provides options to copy query results as JSON or CSV or to save them to a file for later use.

• Pagination: Adjust how many results are displayed at a time when working with large datasets.

• Query Insights and Index Advisor: Review execution time, request charge, response size, activity ID, and indexing recommendations.

• Edit Documents: Open, update, and save individual documents.

• Create New Documents: Write and validate documents with syntax highlighting.

Keyboard Shortcuts

The Azure Cosmos DB extension supports various keyboard shortcuts to improve your productivity when working with queries and documents.

For a complete list of keyboard shortcuts, see Keyboard Shortcuts.

AI-Powered Query Assistance (GitHub Copilot)

The extension integrates with GitHub Copilot to help you write, edit, and understand Cosmos DB NoSQL queries using natural language.

• Generate Query: Click the AI button in the Query Editor toolbar and select Generate query to describe your query in plain English. Copilot will generate a Cosmos DB NoSQL query for you.

• Explain Query: Click the AI button and select Explain query to get a plain-English explanation of the current query in the editor.

Requires the GitHub Copilot extension and an active Copilot subscription.

For more details, see the AI Chat documentation.

Migration Assistant (Preview)

The Migration Assistant uses the cosmosdb-relational-migration Skill in GitHub Copilot Chat to guide relational database and application migrations. Phase actions open or resume Chat; the assistant tracks progress and validates the artifacts in .cosmosdb-migration.

Migration projects started before the Skill was introduced can still be opened and inspected. Their existing artifacts need evidence validation before their phases can be treated as complete in the Skill workflow.

Use cosmosDB.experimental.migration.enabled to show or hide the migration feature.

Import into Azure Cosmos DB

The extension allows you to import documents into Azure Cosmos DB.

• Workspace Integration: Use the context menu of a container or JSON document file to start an import.

  

Attach to the Azure Cosmos DB Emulator

Attach the Azure Cosmos DB Emulator to work with a local instance of Azure Cosmos DB for development and testing purposes.

• Emulator Installation: Install and run the Azure Cosmos DB Emulator on your local machine.

• New Emulator Connection: Expand Cosmos DB Accounts, then Local Emulators, and select New Emulator Connection to attach the emulator to your workspace.

For local setup instructions and connection details, see Azure Cosmos DB Emulator.

Corporate proxies

Normal Cosmos DB for NoSQL connections delegate proxy handling to VS Code. See VS Code network configuration for proxy, authentication, and certificate guidance.

Emulator exception: local localhost and 127.0.0.1 emulators remain direct and retain their self-signed certificate handling. Emulator connections supply an explicit TLS agent, so http.proxySupport: "on" does not add proxy routing for them. A remotely hosted emulator requiring a proxy needs fallback or override and appropriate certificate trust.

Known Issues

[!WARNING] Support for previously included features such as MongoDB, PostgreSQL, Graph (Gremlin), Table, Cassandra, and the Grammar Language Server has been removed from this extension.

• For MongoDB support, use the DocumentDB Extension for VS Code.
• For PostgreSQL support, use the PostgreSQL Extension for VS Code.

Telemetry

Data Modeler template downloads report a downloadCode action with the template format, outcome (success, cancelled, or error), and whether the code was edited. These events use the existing Data Modeler telemetry context and do not include database names, filenames, paths, code contents, or raw error messages.

VS Code collects usage data and sends it to Microsoft to help improve our products and services. Read our privacy statement to learn more. If you don’t wish to send usage data to Microsoft, you can set the telemetry.enableTelemetry setting to false. If you want to disable feedback requests in VS Code, set telemetry.feedback.enabled to false. Learn more in our FAQ.

Data Collection. The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft’s privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=521839. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.

License

MIT