Improve Documentation by reducing focus on Non-Partitioned Collection…

…s - Fixes #342 (#345)

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

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,15 +34,17 @@
     - [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)
   - [Stored Procedures](#working-with-stored-procedures)
   - [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,51 +568,51 @@ $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
 
 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)

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'))
     {

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.