Bemærk
Adgang til denne side kræver godkendelse. Du kan prøve at logge på eller ændre mapper.
Adgang til denne side kræver godkendelse. Du kan prøve at ændre mapper.
Important
This feature is currently in preview and is provided without a service-level agreement. At this time, previews aren't recommended for production workloads. Certain features of this preview aren't supported or might have capability constraints. For more information, see supplemental terms of use for Microsoft Azure previews.
Azure Cosmos DB Data Modeler is a guided design experience in the Visual Studio Code extension. Describe your document structure, query patterns, write rates, and expected scale. Then, use GitHub Copilot to compare partition-key candidates for each modeled container.
The wizard starts with a workload scenario, collects inputs for each container, and presents a recommendation for review. You can optionally deploy the model to the selected account or export deployment code. Modeling and requesting recommendations don't create databases or containers.
What Data Modeler provides
Use Data Modeler to:
- Start from a workload scenario and customize its proposed containers.
- Describe a container's properties manually or infer them from a JSON file.
- Capture read patterns, peak query rates, write rates, and expected growth.
- Compare partition-key candidates, their trade-offs, query routing, and applicable guardrails.
- Resume locally saved modeling work for an account.
- Create the selected database and containers, or export Bicep, Terraform, or C# SDK deployment code.
The preview supports modeling up to 10 containers in one workload. It isn't a data migration or bulk import tool.
Prerequisites
Before you start, you need:
- Visual Studio Code and an Azure Cosmos DB extension version that includes Data Modeler (preview).
- An Azure Cosmos DB account that uses the NoSQL API, available in the extension.
- GitHub Copilot available in Visual Studio Code with access to Copilot models.
- AI features enabled:
chat.disableAIFeaturesmust be off. - Data Modeler enabled:
cosmosDB.experimental.dataModeler.enabledmust be on. - Workload information, including document structure, common queries, peak read and write rates, and growth expectations.
To deploy the model, you also need permission to create the selected database and containers in the target account. Viewing or editing a local model doesn't grant these Azure permissions.
Open Data Modeler
- Open the Command Palette.
- Run Cosmos DB: Data Modeler (preview).
- Select the Azure Cosmos DB account for your modeling work.
Alternatively, open the account's dashboard and select Try Data Modeler. This action uses the dashboard's account without asking you to select another account.
Choose a workload and containers
The landing page lists workload scenarios. Filter them by name or workload characteristics to find a starting point for your design.
On Workload, choose the scenario closest to your application. For example, select Chat & Sessions to start with modeled
ChatSession,Message, andUsercontainers.Select Start to load its proposed model.
Review the modeled containers. Rename them as needed for your application.
Use Add container to model another container, or Remove from model to remove one from the local design.
Removing a container from the model doesn't delete a container or its data in Azure. Treat the scenario's proposed properties and rates as a starting point, not as evidence about your workload.
Describe each container
Each container has Data, Queries, and Scale tabs. Complete all three before advancing to Review.
Define document structure
On Data, review the property names and types. Add or remove properties, and choose their purpose in the Role dropdown:
| Role | Modeling purpose |
|---|---|
| Unique / business key | An identifier or business key to consider when evaluating partitioning and access patterns. |
| Query filter | A property used to filter common reads. |
| Payload / other | Document content that doesn't primarily identify or filter records. |
These roles describe modeling intent. Selecting Unique / business key doesn't create a unique key constraint in Azure Cosmos DB.
To infer a schema from sample documents:
- Select Upload JSON.
- Choose a JSON file containing one object or an array of objects.
- Confirm that you want to replace this container's modeled properties with the inferred schema.
- Review and correct the inferred properties, types, document sizes, and array characteristics.
The file is used to infer the model; this action doesn't import documents into Azure Cosmos DB. Properties inside arrays, and properties with object or array values, aren't eligible scalar partition-key fields in the wizard.
Enter the total attributes, average and maximum document sizes, and array characteristics. A sample's sizes and fields might not represent your full dataset, so adjust the model to reflect expected production documents.
Describe reads and writes
On Queries, describe each important read pattern. Include its query text, the properties used as filters, and Peak QPS, measured across all users. Add more patterns by selecting Add read query.
Enter the expected inserts, updates, and deletes per second. Use representative peak rates rather than assuming the scenario defaults apply to your application.
These inputs help you compare whether common reads can target one logical partition and whether writes can create uneven load. Entering a query in the model doesn't execute it against your account.
Estimate scale and distribution
On Scale, review:
- Estimated distinct values for the partition-key candidates.
- Items per partition-key value.
- Whether writes are even, skewed, or concentrated on current-time data.
- Expected data growth per partition-key value.
- Projected logical-partition size.
The projected size uses your inputs; it isn't a measurement of an existing container. High cardinality alone doesn't prevent a frequently used value from becoming a hot partition. Validate distribution, common filters, value stability, and per-key growth together. For more information, see Partitioning in Azure Cosmos DB.
Request and review a recommendation
Select Next after completing the container inputs.
On Review, verify the model for every container and resolve validation messages.
Select Get Recommendation.
Follow the request in Copilot Chat and wait for the recommendation to appear on Result.
Select each container in the result to compare candidates and review the reasoning.
Important
The recommendation request sends your modeled schema, query text, and workload inputs to Copilot Chat. Review those inputs for sensitive information and follow your organization's AI-use policies before requesting a recommendation.
The result can include:
- A recommended partition key and its rationale.
- Candidate keys labeled Recommended, Alternative, or Avoid, with suitability scores and supporting assessments.
- Query routing under the recommended key.
- A document ID strategy.
- Hot-partition risk comparisons when supported by the available inputs.
- Absolute rules (guardrails) and any assumptions that need confirmation.
Suitability scores are design judgments, not measured RU costs, latency, or guarantees of performance. Confirm that the selected field remains stable throughout a document's lifetime, and validate the recommendation against representative data and queries before deployment.
If Copilot reports missing guidance or insufficient workload evidence, supply the requested information instead of treating an incomplete result as a valid recommendation. Editing model inputs can invalidate an earlier result; request a new recommendation after changes.
On Result, select Deploy to review deployment options, or Start Over to reset the wizard and choose another workload. Start Over clears the current modeling inputs and recommendation; it doesn't delete deployed databases or containers.
Deploy or export the model
After you review a valid recommendation:
- Select Deploy on Result.
- Verify the target account, subscription, and resource group shown on the deployment page.
- Choose New database and enter its name, or choose Existing database.
- Choose the containers to deploy and review their partition keys.
- Select the deployment method:
- Direct creates resources through the extension.
- Bicep, Terraform, and C# SDK generate code for you to review and use with the corresponding tools.
- For direct deployment, review the confirmation before proceeding. For code export, select Copy code or Download.
- After deployment, browse the target account and verify the created containers and their partition keys.
Direct deployment creates Azure resources and can incur normal Azure Cosmos DB charges. Generating or downloading code doesn't execute a deployment.
Existing containers with matching partition keys are left unchanged. A container with the same name and a different partition key causes a conflict; the wizard doesn't change its partition key, policies, or throughput. Choose another database or adjust the model rather than assuming an existing container will be replaced.
Deployment creates the database and container resources, not the uploaded JSON documents. If deployment fails after some resources are created, inspect the account before retrying. Select the existing database on retry; matching containers are left unchanged.
Resume or remove local modeling data
The extension saves modeling inputs and results locally, scoped to the account. Reopen Data Modeler for the same account. If the Start a new data model? prompt appears, select No to resume your saved inputs and recommendation. Selecting Yes replaces the saved work with an empty model. This working state isn't a backup of your Azure resources.
To remove all local modeling data:
- Open the Command Palette and run Cosmos DB: Delete All Data Modeler Data.
- Review the warning that the action closes all Data Modeler tabs and permanently removes saved modeling data for every account.
- Select Delete All to confirm, or Cancel to keep the data.
Deleting local modeling data doesn't delete deployed databases or containers.
Troubleshooting
- The command or dashboard shortcut is missing. Check the extension version,
cosmosDB.experimental.dataModeler.enabled, Copilot model availability, andchat.disableAIFeatures. If the preview isn't in your installed version, check for Switch to Pre-Release Version on the extension's details page. - JSON inference fails. Use a valid JSON object or array of objects, and review the file size and attribute-limit messages. Correct the input or use a smaller representative sample.
- A recommendation doesn't complete. Check Copilot Chat for missing guidance, missing inputs, or an interrupted request before requesting another recommendation.
- State can't load or save. Use Retry loading or Retry saving. Keep the tab open until the save succeeds.
- Deployment is unavailable or fails. Reopen the modeler from the account in the explorer, verify Azure permissions, and inspect existing database and container names before retrying.