[Internal] Subpartitioning: Adds SDK changes to support subpartitioning.

Directory.Build.props

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <ClientOfficialVersion>3.11.0</ClientOfficialVersion>
     <ClientPreviewVersion>3.11.0</ClientPreviewVersion>
-    <DirectVersion>3.11.3</DirectVersion>
+    <DirectVersion>3.11.4</DirectVersion>
     <EncryptionVersion>1.0.0-preview4</EncryptionVersion>
     <HybridRowVersion>1.0.0-preview</HybridRowVersion>
     <AboveDirBuildProps>$([MSBuild]::GetPathOfFileAbove('Directory.Build.props', '$(MSBuildThisFileDirectory)../'))</AboveDirBuildProps>

Microsoft.Azure.Cosmos/src/PartitionKey.cs

@@ -95,6 +95,16 @@ internal PartitionKey(object value)
             this.IsNone = false;
         }
 
+        /// <summary>
+        /// Creates a new partition key value.
+        /// </summary>
+        /// <param name="partitionKeyInternal">The value to use as partition key.</param>
+        internal PartitionKey(PartitionKeyInternal partitionKeyInternal)
+        {
+            this.InternalKey = partitionKeyInternal;
+            this.IsNone = false;
+        }
+
         /// <summary>
         /// Creates a new partition key value.
         /// </summary>

Microsoft.Azure.Cosmos/src/PartitionKeyBuilder.cs

@@ -0,0 +1,130 @@
+//------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.  All rights reserved.
+//------------------------------------------------------------
+namespace Microsoft.Azure.Cosmos
+{
+    using System;
+    using System.Collections;
+    using System.Collections.Generic;
+    using Microsoft.Azure.Documents;
+    using Microsoft.Azure.Documents.Routing;
+
+    /// <summary>
+    /// Represents a partition key value list in the Azure Cosmos DB service.
+    /// </summary>
+#if INTERNAL || SUBPARTITIONING
+    public
+#else
+    internal
+#endif
+    sealed class PartitionKeyBuilder
+    {
+        private readonly List<object> partitionKeyValues;
+
+        /// <summary>
+        /// Creates a new partition key value list object.
+        /// </summary>
+        public PartitionKeyBuilder()
+        {
+            this.partitionKeyValues = new List<object>();
+        }
+
+        /// <summary>
+        /// Adds a partition key value of type string to the list.
+        /// </summary>
+        /// <param name="val">The value of type string to be used as partition key.</param>
+        /// <returns>An instance of <see cref="PartitionKeyBuilder"/> to use. </returns>
+        public PartitionKeyBuilder Add(string val)
+        {
+            this.partitionKeyValues.Add(val);
+            return this;
+        }
+
+        /// <summary>
+        /// Adds a partition key value of type double to the list.
+        /// </summary>
+        /// <param name="val">The value of type double to be used as partition key.</param>
+        /// <returns>An instance of <see cref="PartitionKeyBuilder"/> to use. </returns>
+        public PartitionKeyBuilder Add(double val)
+        {
+            this.partitionKeyValues.Add(val);
+            return this;
+        }
+
+        /// <summary>
+        /// Adds a partition key value of type bool to the list.
+        /// </summary>
+        /// <param name="val">The value of type bool to be used as partition key.</param>
+        /// <returns>An instance of <see cref="PartitionKeyBuilder"/> to use. </returns>
+        public PartitionKeyBuilder Add(bool val)
+        {
+            this.partitionKeyValues.Add(val);
+            return this;
+        }
+
+        /// <summary>
+        /// Adds a partition key value which is null
+        /// </summary>
+        /// <returns>An instance of <see cref="PartitionKeyBuilder"/> to use. </returns>
+        public PartitionKeyBuilder AddNullValue()
+        {
+            this.partitionKeyValues.Add(null);
+            return this;
+        }
+
+        /// <summary>
+        /// Adds a None partition key value.
+        /// </summary>
+        /// <returns>An instance of <see cref="PartitionKeyBuilder"/> to use. </returns>
+        public PartitionKeyBuilder AddNoneType()
+        {
+            this.partitionKeyValues.Add(PartitionKey.None);
+            return this;
+        }
+
+        /// <summary>
+        /// Builds a new instance of the <see cref="PartitionKey"/> with the specified Partition Key values.
+        /// </summary>
+        /// <returns>An instance of <see cref="PartitionKey"/> </returns>
+        public PartitionKey Build()
+        {
+            // Why these checks?
+            // These changes are being added for SDK to support multiple paths in a partition key.
+            //
+            // Currently, when a resource does not specify a value for the PartitionKey,
+            // we assign a temporary value `PartitionKey.None` and later discern whether
+            // it is a PartitionKey.Undefined or PartitionKey.Empty based on the Collection Type.
+            // We retain this behaviour for single path partition keys.
+            //
+            // For collections with multiple path keys, absence of a partition key values is
+            // always treated as a PartitionKey.Undefined.
+            if (this.partitionKeyValues.Count == 0)
+            {
+                throw new ArgumentException($"No partition key value has been specifed");
+            }
+
+            if (this.partitionKeyValues.Count == 1 && PartitionKey.None.Equals(this.partitionKeyValues[0]))
+            {
+                return PartitionKey.None;
+            }
+
+            PartitionKeyInternal partitionKeyInternal;
+            object[] valueArray = new object[this.partitionKeyValues.Count];
+            for (int i = 0; i < this.partitionKeyValues.Count; i++)
+            {
+                object val = this.partitionKeyValues[i];
+                if (PartitionKey.None.Equals(val))
+                {
+                    valueArray[i] = Undefined.Value;
+                }
+                else
+                {
+                    valueArray[i] = val;
+                }
+            }
+
+            partitionKeyInternal = new Documents.PartitionKey(valueArray).InternalKey;
+            return new PartitionKey(partitionKeyInternal);
+        }
+    }
+}

Microsoft.Azure.Cosmos/src/Resource/Container/ContainerCore.Items.cs

@@ -627,6 +627,12 @@ private async Task<ResponseMessage> ExtractPartitionKeyAndProcessItemStreamAsync
             // User specified PK value, no need to extract it
             if (partitionKey.HasValue)
             {
+                PartitionKeyDefinition pKeyDefinition = await this.GetPartitionKeyDefinitionAsync();
+                if (partitionKey.HasValue && partitionKey.Value != PartitionKey.None && partitionKey.Value.InternalKey.Components.Count != pKeyDefinition.Paths.Count)
+                {
+                    throw new ArgumentException(RMResources.MissingPartitionKeyValue);
+                }
+
                 return await this.ProcessItemStreamAsync(
                         partitionKey,
                         itemId,
@@ -709,7 +715,7 @@ private async Task<ResponseMessage> ProcessItemStreamAsync(
 
             return responseMessage;
         }
-
+     
         public override async Task<PartitionKey> GetPartitionKeyValueFromStreamAsync(
             Stream stream,
             CancellationToken cancellation = default(CancellationToken))
@@ -734,21 +740,23 @@ public override async Task<PartitionKey> GetPartitionKeyValueFromStreamAsync(
                 IJsonNavigatorNode jsonNavigatorNode = jsonNavigator.GetRootNode();
                 CosmosObject pathTraversal = CosmosObject.Create(jsonNavigator, jsonNavigatorNode);
 
-                string[] tokens = await this.GetPartitionKeyPathTokensAsync(cancellation);
-                for (int i = 0; i < tokens.Length - 1; i++)
+                IReadOnlyList<IReadOnlyList<string>> tokenslist = await this.GetPartitionKeyPathTokensAsync(cancellation);
+                List<CosmosElement> cosmosElementList = new List<CosmosElement>(tokenslist.Count);
+
+                foreach (IReadOnlyList<string> tokenList in tokenslist)
                 {
-                    if (!pathTraversal.TryGetValue(tokens[i], out pathTraversal))
+                    CosmosElement element;
+                    if (ContainerCore.TryParseTokenListForElement(pathTraversal, tokenList, out element))
                     {
-                        return PartitionKey.None;
+                        cosmosElementList.Add(element);
+                    }
+                    else
+                    {
+                        cosmosElementList.Add(null);
                     }
                 }
 
-                if (!pathTraversal.TryGetValue(tokens[tokens.Length - 1], out CosmosElement partitionKeyValue))
-                {
-                    return PartitionKey.None;
-                }
-
-                return this.CosmosElementToPartitionKeyObject(partitionKeyValue);
+                return ContainerCore.CosmosElementToPartitionKeyObject(cosmosElementList);
             }
             finally
             {
@@ -757,18 +765,54 @@ public override async Task<PartitionKey> GetPartitionKeyValueFromStreamAsync(
             }
         }
 
-        private PartitionKey CosmosElementToPartitionKeyObject(CosmosElement cosmosElement) => cosmosElement switch
+        private static bool TryParseTokenListForElement(CosmosObject pathTraversal, IReadOnlyList<string> tokens, out CosmosElement result)
+        {
+            result = null;
+            for (int i = 0; i < tokens.Count - 1; i++)
+            {
+                if (!pathTraversal.TryGetValue(tokens[i], out pathTraversal))
+                {
+                    return false;
+                }
+            }
+
+            if (!pathTraversal.TryGetValue(tokens[tokens.Count - 1], out result))
+            {
+                return false;
+            }
+
+            return true;
+        }
+
+        private static PartitionKey CosmosElementToPartitionKeyObject(IReadOnlyList<CosmosElement> cosmosElementList) 
         {
-            CosmosString cosmosString => new PartitionKey(cosmosString.Value),
-            CosmosNumber cosmosNumber => new PartitionKey(Number64.ToDouble(cosmosNumber.Value)),
-            CosmosBoolean cosmosBoolean => new PartitionKey(cosmosBoolean.Value),
-            CosmosNull _ => PartitionKey.Null,
-            _ => throw new ArgumentException(
-                    string.Format(
-                        CultureInfo.InvariantCulture,
-                        RMResources.UnsupportedPartitionKeyComponentValue,
-                        cosmosElement)),
-        };
+            PartitionKeyBuilder partitionKeyBuilder = new PartitionKeyBuilder();
+
+            foreach (CosmosElement cosmosElement in cosmosElementList)
+            {
+                if (cosmosElement == null)
+                {
+                    partitionKeyBuilder.AddNoneType();
+                }
+                else
+                {
+                    _ = cosmosElement switch
+                    {
+                        CosmosString cosmosString => partitionKeyBuilder.Add(cosmosString.Value),
+                        CosmosNumber cosmosNumber => partitionKeyBuilder.Add(Number64.ToDouble(cosmosNumber.Value)),
+                        CosmosBoolean cosmosBoolean => partitionKeyBuilder.Add(cosmosBoolean.Value),
+                        CosmosNull _ => partitionKeyBuilder.AddNullValue(),
+                        _ => throw new ArgumentException(
+                               string.Format(
+                                   CultureInfo.InvariantCulture,
+                                   RMResources.UnsupportedPartitionKeyComponentValue,
+                                   cosmosElement)),
+                    };
+                }
+            }
+
+            return partitionKeyBuilder.Build();
+        }
 
         private string GetResourceUri(RequestOptions requestOptions, OperationType operationType, string itemId)
         {

Microsoft.Azure.Cosmos/src/Resource/Container/ContainerCore.cs

@@ -347,7 +347,7 @@ public override async Task<string> GetRIDAsync(CancellationToken cancellationTok
         /// </summary>
         /// <param name="cancellationToken"></param>
         /// <returns>Returns the partition key path</returns>
-        public override async Task<string[]> GetPartitionKeyPathTokensAsync(CancellationToken cancellationToken = default(CancellationToken))
+        public override async Task<IReadOnlyList<IReadOnlyList<string>>> GetPartitionKeyPathTokensAsync(CancellationToken cancellationToken = default(CancellationToken))
         {
             ContainerProperties containerProperties = await this.GetCachedContainerPropertiesAsync(cancellationToken);
             if (containerProperties == null)

Microsoft.Azure.Cosmos/src/Resource/Container/ContainerInternal.cs

@@ -40,7 +40,8 @@ public abstract Task<ThroughputResponse> ReplaceThroughputIfExistsAsync(
         public abstract Task<ContainerProperties> GetCachedContainerPropertiesAsync(
             CancellationToken cancellationToken = default(CancellationToken));
 
-        public abstract Task<string[]> GetPartitionKeyPathTokensAsync(CancellationToken cancellationToken = default(CancellationToken));
+        public abstract Task<IReadOnlyList<IReadOnlyList<string>>> GetPartitionKeyPathTokensAsync(
+            CancellationToken cancellationToken = default(CancellationToken));
 
         public abstract Task<Documents.Routing.PartitionKeyInternal> GetNonePartitionKeyValueAsync(
             CancellationToken cancellationToken);