From 8cb362230fc5e4e458f659c087ebf917d4bd3c33 Mon Sep 17 00:00:00 2001 From: Daniel Scott-Raynsford Date: Sat, 21 Mar 2020 12:20:04 +1300 Subject: [PATCH] Improve Documentation by reducing focus on Non-Partitioned Collections - Fixes #342 (#345) --- CHANGELOG.md | 7 + README.md | 169 +++++++++++------- .../collections/New-CosmosDbCollection.ps1 | 4 + source/en-US/CosmosDB.strings.psd1 | 1 + 4 files changed, 119 insertions(+), 62 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index f5d7fe34..2b553ca9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Changed + +- Add warning to `New-CosmosDbCollection` to show when creating a collection + without a partition key. +- Updated `README.MD` to documentation to reduce focus on collections without + partition keys - fixes [Issue #342](https://github.com/PlagueHO/CosmosDB/issues/342). + ## [3.6.1] - 2020-03-19 ### Changed diff --git a/README.md b/README.md index 7d1f4243..5b7eb6d9 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,8 @@ - [Introduction](#introduction) - [Requirements](#requirements) +- [Recommended Knowledge](#recommended-knowledge) - [Installation](#installation) -- [Compatibility and Testing](#compatibility-and-testing) - [Getting Started](#getting-started) - [Working with Contexts](#working-with-contexts) - [Create a Context specifying the Key Manually](#create-a-context-specifying-the-key-manually) @@ -34,8 +34,9 @@ - [Update an existing Collection with a new Indexing Policy](#update-an-existing-collection-with-a-new-indexing-policy) - [Creating a Collection with a custom Unique Key Policy](#creating-a-collection-with-a-custom-unique-key-policy) - [Update an existing Collection with a new Unique Key Policy](#update-an-existing-collection-with-a-new-unique-key-policy) + - [Creating a Collection without a Partition Key](#creating-a-collection-without-a-partition-key) - [Working with Documents](#working-with-documents) - - [Working with Documents in a Partitioned Collection](#working-with-documents-in-a-partitioned-collection) + - [Working with Documents in a non-partitioned Collection](#working-with-documents-in-a-non-partitioned-collection) - [Using Resource Authorization Tokens](#using-resource-authorization-tokens) - [Working with Attachments](#working-with-attachments) - [Working with Users](#working-with-users) @@ -43,6 +44,7 @@ - [Working with Triggers](#working-with-triggers) - [Working with User Defined Functions](#working-with-user-defined-functions) - [How to Handle Exceeding Provisioned Throughput](#how-to-handle-exceeding-provisioned-throughput) +- [Compatibility and Testing](#compatibility-and-testing) - [Contributing](#contributing) - [Cmdlets](#cmdlets) - [Change Log](#change-log) @@ -84,6 +86,22 @@ This module requires the following: > or **AzureRm.NetCore** modules are used then you will need to remain on > CosmosDB module 2.x. +## 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 practice. + +Users new to Cosmos DB should familiarize themselves with the following +concepts: + +- [Overview of Cosmos DB](https://docs.microsoft.com/bs-cyrl-ba/azure/cosmos-db/introduction) +- [NoSQL vs. Relational Databases](https://docs.microsoft.com/bs-cyrl-ba/azure/cosmos-db/relational-nosql) +- [Partitioning](https://docs.microsoft.com/bs-cyrl-ba/azure/cosmos-db/partitioning-overview) + +It is also recommended to watch [this Ignite video](https://myignite.techcommunity.microsoft.com/sessions/79932) +on data modelling and partitioning in Cosmos DB. + ## Installation To install the module from PowerShell Gallery, use the PowerShell Cmdlet: @@ -92,25 +110,6 @@ To install the module from PowerShell Gallery, use the PowerShell Cmdlet: Install-Module -Name CosmosDB ``` -## Compatibility and Testing - -This PowerShell module is automatically tested and validated to run -on the following systems: - -- Windows Server (using Windows PowerShell 5.1): - - Windows Server 2016: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). - - Windows Server 2019: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). -- Linux (using PowerShell Core 6.x): - - Ubuntu Trusty 16.04: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). -- Linux (using PowerShell 7.x): - - Ubuntu Trusty 16.04: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). - - Ubuntu Xenial 18.04: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). -- macOS (using PowerShell Core 6.x): - - macOS 10.14: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). - -This module should function correctly on other systems and configurations -but is not automatically tested with them in every change. - ## Getting Started The easiest way to use this module is to first create a context @@ -246,17 +245,18 @@ Remove-CosmosDbAccount -Name 'MyAzureCosmosDB' -ResourceGroupName 'MyCosmosDbRes ### Working with Databases -Create a new database in the Cosmos DB account: +Create a new database in the Cosmos DB account with database throughput +provisioned at 1200 RU/s: ```powershell -New-CosmosDbDatabase -Context $cosmosDbContext -Id 'AnotherDatabase' +New-CosmosDbDatabase -Context $cosmosDbContext -Id 'MyDatabase' -OfferThrougput 1200 ``` -Create a new database in the Cosmos DB account with a -custom offer throughput of 1200 RU/s: +Create a new database in the Cosmos DB account that will have throughput +provisioned at the collection rather than the database: ```powershell -New-CosmosDbDatabase -Context $cosmosDbContext -Id 'DatabaseWithOffer' -OfferThrougput 1200 +New-CosmosDbDatabase -Context $cosmosDbContext -Id 'DatabaseWithCollectionThroughput' ``` Get a list of databases in the Cosmos DB account: @@ -307,17 +307,11 @@ Get a list of collections in a database: Get-CosmosDbCollection -Context $cosmosDbContext ``` -Create a collection in the database with the offer throughput of 2500 RU/s: - -```powershell -New-CosmosDbCollection -Context $cosmosDbContext -Id 'MyNewCollection' -OfferThroughput 2500 -``` - -Create a collection in the database with the partition key 'account' and +Create a collection in the database with the partition key 'id' and the offer throughput of 50000 RU/s: ```powershell -New-CosmosDbCollection -Context $cosmosDbContext -Id 'PartitionedCollection' -PartitionKey 'account' -OfferThroughput 50000 +New-CosmosDbCollection -Context $cosmosDbContext -Id 'MyNewCollection' -PartitionKey 'id' -OfferThroughput 50000 ``` Get a specified collection from a database: @@ -367,7 +361,7 @@ $indexNumberRange = New-CosmosDbCollectionIncludedPathIndex -Kind Range -DataTyp $indexPointSpatial = New-CosmosDbCollectionIncludedPathIndex -Kind Spatial -DataType Point $indexIncludedPath = New-CosmosDbCollectionIncludedPath -Path '/*' -Index $indexStringRange, $indexNumberRange, $indexPointSpatial $indexingPolicy = New-CosmosDbCollectionIndexingPolicy -Automatic $true -IndexingMode Consistent -IncludedPath $indexIncludedPath -New-CosmosDbCollection -Context $cosmosDbContext -Id 'MyNewCollection' -PartitionKey 'account' -IndexingPolicy $indexingPolicy +New-CosmosDbCollection -Context $cosmosDbContext -Id 'MyNewCollection' -PartitionKey 'id' -IndexingPolicy $indexingPolicy ``` > **Important Index Notes** @@ -422,7 +416,7 @@ unique key is set to '/email'. $uniqueKeyNameAddress = New-CosmosDbCollectionUniqueKey -Path '/name', '/address' $uniqueKeyEmail = New-CosmosDbCollectionUniqueKey -Path '/email' $uniqueKeyPolicy = New-CosmosDbCollectionUniqueKeyPolicy -UniqueKey $uniqueKeyNameAddress, $uniqueKeyEmail -New-CosmosDbCollection -Context $cosmosDbContext -Id 'MyNewCollection' -PartitionKey 'account' -UniqueKeyPolicy $uniqueKeyPolicy +New-CosmosDbCollection -Context $cosmosDbContext -Id 'MyNewCollection' -PartitionKey 'id' -UniqueKeyPolicy $uniqueKeyPolicy ``` For more information on how Cosmos DB indexes documents, see [this page](https://docs.microsoft.com/en-us/azure/cosmos-db/unique-keys). @@ -440,37 +434,65 @@ $uniqueKeyPolicy = New-CosmosDbCollectionUniqueKeyPolicy -UniqueKey $uniqueKeyNa Set-CosmosDbCollection -Context $cosmosDbContext -Id 'MyExistingCollection' -IndexingPolicy $indexingPolicy ``` +#### Creating a Collection without a Partition Key + +> **Warning:** It is not recommended to create a collection without a partition +key. It may result in reduced performance and increased cost. This +functionality is included for backwards compatibility only. + +It is only possible to create non-partitioned collection in a database that has +not got provisioned throughput at the database level enabled. + +Create a collection in the database with the offer throughput of 2500 RU/s +and without a partition key: + +```powershell +New-CosmosDbCollection -Context $cosmosDbContext -Id 'NonPartitionedCollection' -OfferThroughput 2500 +``` + ### Working with Documents -Create 10 new documents in a collection in the database: +Create 10 new documents in a collection in the database using the `id` as +the partition key: ```powershell 0..9 | Foreach-Object { + $id = $([Guid]::NewGuid().ToString()) $document = @" { - `"id`": `"$([Guid]::NewGuid().ToString())`", + `"id`": `"$id`", `"content`": `"Some string`", `"more`": `"Some other string`" } "@ -New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentBody $document + New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentBody $document -PartitionKey $id } ``` Create a new document containing non-ASCII characters in a collection in the -database: +database using the `id` as the partition key: ```powershell +$id = $([Guid]::NewGuid().ToString()) $document = @" { - `"id`": `"$([Guid]::NewGuid().ToString())`", + `"id`": `"$id`", `"content`": `"杉本 司`" } "@ -New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentBody $document -Encoding 'UTF-8' -} +New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentBody $document -Encoding 'UTF-8' -PartitionKey $id ``` +Return a document with a specific Id from a collection in the database using +the document ID as the partition key: + +```powershell +Get-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id $documents[0].id -PartitionKey $documents[0].id +``` + +> **Note:** Because this is a partitioned collection, if you don't specify a partition +key you will receive a `(400) Bad Request` exception. + Get the first 5 documents from the collection in the database: ```powershell @@ -479,6 +501,10 @@ $documents = Get-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNew $continuationToken = [String] $ResponseHeader.'x-ms-continuation' ``` +> **Note:** You don't need to specify the partition key here because you are just +getting the first 5 documents in whatever order they are available so going to +a specific partition is not required. + Get the next 5 documents from a collection in the database using the continuation token found in the headers from the previous request: @@ -497,14 +523,7 @@ $newDocument = @" `"more`": `"Another new string`" } "@ -Set-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id $documents[0].id -DocumentBody $newDocument -``` - -Return a document with a specific Id from a collection in -the database: - -```powershell -Get-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id $documents[0].id +Set-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id $documents[0].id -DocumentBody $newDocument -PartitionKey $documents[0].id ``` Querying a collection in a database: @@ -527,12 +546,19 @@ Get-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' - Delete a document from a collection in the database: ```powershell -Remove-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id $documents[0].id +Remove-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id $documents[0].id -PartitionKey $documents[0].id ``` -#### Working with Documents in a Partitioned Collection +> **Note:** Because this is a partitioned collection, if you don't specify a partition +key you will receive a `(400) Bad Request` exception. -Creating a document in a collection that has a Partition Key requires the +#### Working with Documents in a non-partitioned Collection + +> **Warning:** It is not recommended to use a collection without a partition +key. It may result in reduced performance and increased cost. This +functionality is included for backwards compatibility only. +> +> Creating a document in a collection that has a Partition Key requires the `PartitionKey` parameter to be specified for the document: ```powershell @@ -542,19 +568,19 @@ $document = @" `"locale`": `"English (US)`" } "@ -New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'PartitionedCollection' -DocumentBody $document -PartitionKey 'en-us' +New-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'NonPartitionedCollection' -DocumentBody $document ``` Get a document from a partitioned collection with a specific Id: ```powershell -$document = Get-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'PartitionedCollection' -Id 'en-us' -PartitionKey 'en-us' +Get-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'NonPartitionedCollection' -Id 'en-us' ``` Delete a document from a partitioned collection in the database: ```powershell -Remove-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'PartitionedCollection' -Id 'en-us' -PartitionKey 'en-us' +Remove-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'NonPartitionedCollection' -Id 'en-us' ``` ### Working with Attachments @@ -562,31 +588,31 @@ Remove-CosmosDbDocument -Context $cosmosDbContext -CollectionId 'PartitionedColl Create an attachment on a document in a collection: ```powershell -New-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id -Id 'image_1' -ContentType 'image/jpg' -Media 'www.bing.com' +New-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id -PartitionKey $documents[0].id -Id 'image_1' -ContentType 'image/jpg' -Media 'www.bing.com' ``` Get _all_ attachments for a document in a collection: ```powershell -Get-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id +Get-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id -PartitionKey $documents[0].id ``` Get an attachment by Id for a document in a collection: ```powershell -Get-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id -Id 'image_1' +Get-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id -PartitionKey $documents[0].id -Id 'image_1' ``` Rename an attachment for a document in a collection: ```powershell -Set-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id -Id 'image_1' -NewId 'Image_2' +Set-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id -PartitionKey $documents[0].id -Id 'image_1' -NewId 'image_2' ``` Delete an attachment from a document in collection: ```powershell -Remove-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -Id $documents[0].id -Id 'Image_2' +Remove-CosmosDbAttachment -Context $cosmosDbContext -CollectionId 'MyNewCollection' -DocumentId $documents[0].id -PartitionKey $documents[0].id -Id 'image_2' ``` ### Working with Users @@ -965,6 +991,25 @@ A policy that adds or subtracts up to 50% of the delay period to the base delay each time can also be applied. For example, the first delay might be 850ms, with the second delay being 1424ms and final delay being 983ms. +## Compatibility and Testing + +This PowerShell module is automatically tested and validated to run +on the following systems: + +- Windows Server (using Windows PowerShell 5.1): + - Windows Server 2016: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). + - Windows Server 2019: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). +- Linux (using PowerShell Core 6.x): + - Ubuntu Trusty 16.04: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). +- Linux (using PowerShell 7.x): + - Ubuntu Trusty 16.04: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). + - Ubuntu Xenial 18.04: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). +- macOS (using PowerShell Core 6.x): + - macOS 10.14: Using [Azure Pipelines](https://dev.azure.com/dscottraynsford/GitHub/_build?definitionId=4). + +This module should function correctly on other systems and configurations +but is not automatically tested with them in every change. + ## Contributing If you wish to contribute to this project, please read the [Contributing.md](/.github/CONTRIBUTING.md) diff --git a/source/Public/collections/New-CosmosDbCollection.ps1 b/source/Public/collections/New-CosmosDbCollection.ps1 index 2c44d412..51ef5d03 100644 --- a/source/Public/collections/New-CosmosDbCollection.ps1 +++ b/source/Public/collections/New-CosmosDbCollection.ps1 @@ -112,6 +112,10 @@ function New-CosmosDbCollection } $null = $PSBoundParameters.Remove('PartitionKey') } + else + { + Write-Warning -Message $($LocalizedData.NonPartitionedCollectionWarning) + } if ($PSBoundParameters.ContainsKey('IndexingPolicy')) { diff --git a/source/en-US/CosmosDB.strings.psd1 b/source/en-US/CosmosDB.strings.psd1 index c4b4a076..e6771e7a 100644 --- a/source/en-US/CosmosDB.strings.psd1 +++ b/source/en-US/CosmosDB.strings.psd1 @@ -19,6 +19,7 @@ ConvertFrom-StringData -StringData @' RemovingAzureCosmosDBAccount = Removing Azure Cosmos DB account '{0}' in resource group '{1}'. StoredProcedureScriptLogResults = Stored Procedure '{0}' script log results:\n{1} RequestChargeResults = Request charge for {0} to '{1}' was {2} RUs. + NonPartitionedCollectionWarning = It is not recommended to create a collection without a partition key. It may result in reduced performance and increased cost. This functionality is included for backwards compatibility only. CollectionProvisionedThroughputExceededWithBackoffPolicy = The collection has exceeded the provisioned throughput limit but a back-off policy is specified. CollectionProvisionedThroughputExceededNoBackoffPolicy = The collection has exceeded the provisioned throughput limit but there is no back-off policy. CollectionProvisionedThroughputExceededMaxRetriesHit = The maximum back-off policy retries {0} has been exceeded.