CosmosDB PowerShell Module

Module Build Status

| Branch | Azure Pipelines | Automated Tests | Code Quality | | ------ | --------------- | ----------------| ------------ | | main | [![ap-image-main][]][ap-site-main] | [![ts-image-main][]][ts-site-main] | [![cq-image-main][]][cq-site-main] |

Introduction

This PowerShell module provides cmdlets for accessing Cosmos DB collections via the Azure Cosmos DB REST API. It makes it easy to perform CRUD operations on Cosmos DB collections and documents and related entities while also implementing role-based access control or token-based authentication.

[!IMPORTANT] The CosmosDB PowerShell module is not intended to be a replacement for the Az.CosmosDB. Although there is some cross-over between the two modules, the CosmosDB PowerShell module is primarily intended to be used for accessing the documents within collections using RBAC and token-based authentication. This is functionality that the Az.CosmosDB module does not currently provide.

The CosmosDB PowerShell module enables management of:

• Attachments
• Collections
• Databases
• Documents
• Offers
• Permissions
• Stored Procedures
• Triggers
• User Defined Functions
• Users

The module uses the Cosmos DB (DocumentDB) Rest APIs. For more information on the Cosmos DB Rest APIs, see this link.

Table of Contents

• Introduction
• Requirements
• Recommended Knowledge
• Installation
• Getting Started
  • Working with Contexts
    • Create a Context using an Entra ID Authorization Token
      • Configuring Role-Based Access Control (RBAC) with Entra ID
      • Database Operations allowed by Role-Based Access Control
    • Create a Context specifying the Key Manually
    • Use CosmosDB Module to Retrieve Key from Azure Management Portal
    • Create a Context from Resource Authorization Tokens
    • Create a Context for a Cosmos DB in Azure US Government Cloud
    • Create a Context for a Cosmos DB in Azure China Cloud (Mooncake)
    • Create a Context for a Cosmos DB with a Custom Endpoint
    • Create a Context for a Cosmos DB Emulator
  • Working with Accounts
  • Working with Databases
  • Working with Offers
  • Working with Collections
    • Creating a Collection with a custom Indexing Policy
    • Creating a Collection with a custom Indexing Policy including Composite Indexes
    • Update an existing Collection with a new Indexing Policy
    • Creating a Collection with a custom Indexing Policy using JSON
    • Creating a Collection with a custom Unique Key Policy
    • Update an existing Collection with a new Unique Key Policy
    • Creating a Collection without a Partition Key
  • Working with Documents
    • Using a While Loop to get all Documents in a Collection
    • Working with Documents in a non-partitioned Collection
  • Using Resource Authorization Tokens
  • Working with Attachments
  • Working with Users
  • Stored Procedures
  • Working with Triggers
  • Working with User Defined Functions
  • How to Handle Exceeding Provisioned Throughput
• Compatibility and Testing
• Contributing
• Cmdlets
• Change Log
• Links

Requirements

This module requires the following:

• Windows PowerShell 5.x, PowerShell Core 6.x or PowerShell 7.x

PowerShell Module Dependencies

• Az.Accounts: 5.0.0 and newer.
• Az.Resources: 8.0.0 and newer.

These modules are required if using New-CosmosDbContext -ResourceGroupName $resourceGroup or *-CosmosDbAccount functions.

Recommended Knowledge

It is recommended that before using this module it is important to understand the fundamental concepts of Cosmos DB. This will ensure you have an optimal experience by adopting design patterns that align to Cosmos DB best practices.

Users new to Cosmos DB should familiarize themselves with the following concepts:

• Overview of Cosmos DB
• NoSQL vs. Relational Databases
• Partitioning

It is also recommended to watch this Ignite video on data modelling and partitioning in Cosmos DB.

Installation

To install the module from PowerShell Gallery, use the PowerShell Cmdlet:

Install-Module -Name CosmosDB

Getting Started

The easiest way to use this module is to first create a context object using the New-CosmosDbContext cmdlet which you can then use to pass to the other Cosmos DB cmdlets in the module.

To create the context object you will either need access to the primary or secondary keys from your Cosmos DB account or allow the CosmosDB Powershell module to retrieve the keys directly from the Azure management portal for you.

Working with Contexts

Create a Context Using an Entra ID Authorization Token

You can create a context object that can include use an Entra ID Authorization Token that will be used to authenticate requests to Cosmos DB. For more information on how to set up Role-Based Access Control (RBAC) for Cosmos DB accounts, see use data plane role-based access control with Azure Cosmos DB for NoSQL

[!IMPORTANT] This is the recommended method of authenticating to Cosmos DB for all scenarios. Other methods are included for backwards compatibility and for low risk developer scenarios. It is always recommended to use this method in production environments.

To create a context object using an Entra ID Authorization Token you will need to set the EntraIdToken parameter to the token you have retrieved from Entra ID for the identity.

[!IMPORTANT] You must have assiged appropriate roles to the account, database and/or collection for the identity. See Create a Data Plane Role Assignment section for an example of doing this with PowerShell.

# Get an OAuth2 resource token from Entra ID for the Cosmos DB account.
# This will use the currently logged in user to authenticate to Entra ID to
# get the token. There are many other ways of doing this.
$entraIdOAuthToken = Get-CosmosDbEntraIdToken -Endpoint 'https://MyAzureCosmosDB.documents.azure.com'

$newCosmosDbContextParams  = @{
    Account      = 'MyAzureCosmosDB'
    EntraIdToken = $entraIdOAuthToken
}
$accountContext = New-CosmosDbContext @newCosmosDbContextParams
Get-CosmosDbCollection -Context $accountContext -Id MyNewCollection

An alternate method is to allow the New-CosmosDbContext cmdlet to retrieve the Entra ID token for you. This will require you to have already logged into Azure and will use the