[Internal] Query: Adds Index Metrics V2 Object Model

Microsoft.Azure.Cosmos/src/Handler/ResponseMessage.cs

@@ -251,21 +251,27 @@ private void CheckDisposed()
         /// Decode the Index Metrics from the response headers, if exists.
         /// </summary>
         /// <param name="responseMessageHeaders">The response headers</param>
-        /// <param name="isBse64Encoded">The encoding of the IndexMetrics response</param>
+        /// <param name="isBase64Encoded">The encoding of the IndexMetrics response</param>
         /// <returns>Lazy implementation of the pretty-printed IndexMetrics</returns>
-        static internal Lazy<string> DecodeIndexMetrics(Headers responseMessageHeaders, bool isBse64Encoded)
+        static internal Lazy<string> DecodeIndexMetrics(Headers responseMessageHeaders, bool isBase64Encoded)
         {
             if (responseMessageHeaders?.IndexUtilizationText != null)
             {
                 return new Lazy<string>(() =>
                     {
-                        IndexUtilizationInfo parsedIndexUtilizationInfo = IndexUtilizationInfo.CreateFromString(responseMessageHeaders.IndexUtilizationText, isBse64Encoded);
-
-                        StringBuilder stringBuilder = new StringBuilder();
-                        IndexMetricWriter indexMetricWriter = new IndexMetricWriter(stringBuilder);
-                        indexMetricWriter.WriteIndexMetrics(parsedIndexUtilizationInfo);
+                        if (isBase64Encoded)
+                        {
+                            IndexUtilizationInfo parsedIndexUtilizationInfo = IndexUtilizationInfo.CreateFromString(responseMessageHeaders.IndexUtilizationText);
 
-                        return stringBuilder.ToString();
+                            StringBuilder stringBuilder = new StringBuilder();
+                            IndexMetricsWriter indexMetricWriter = new IndexMetricsWriter(stringBuilder);
+                            indexMetricWriter.WriteIndexMetrics(parsedIndexUtilizationInfo);
+
+                            return stringBuilder.ToString();
+                        }
+
+                        // Return the JSON from the response header
+                        return responseMessageHeaders.IndexUtilizationText;
                     });
             }
 

Microsoft.Azure.Cosmos/src/Query/Core/Metrics/CompositeIndexIndexMetrics.cs

@@ -0,0 +1,48 @@
+//------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.  All rights reserved.
+//------------------------------------------------------------
+namespace Microsoft.Azure.Cosmos.Query.Core.Metrics
+{
+    using System;
+    using System.Collections.Generic;
+    using Newtonsoft.Json;
+
+    /// <summary>
+    /// Query index utilization data for composite indexes (sub-structure of the Index Metrics class) in the Azure Cosmos database service.
+    /// </summary>
+    #if INTERNAL
+#pragma warning disable SA1600
+#pragma warning disable CS1591
+    public
+#else
+    internal
+#endif
+    sealed class CompositeIndexIndexMetrics
+    {
+        /// <summary>
+        /// Initialized a new instance of an Index Metrics' Composite Index class.
+        /// </summary>
+        /// <param name="indexDocumentExpressions">The string list representation of the composite index.</param>
+        /// <param name="indexImpactScore">The index impact score.</param>
+        [JsonConstructor]
+        private CompositeIndexIndexMetrics(
+            IReadOnlyList<string> indexDocumentExpressions,
+            string indexImpactScore)
+        {
+            this.IndexSpecs = indexDocumentExpressions;
+            this.IndexImpactScore = indexImpactScore;
+        }
+
+        /// <summary>
+        /// String list representation of index paths of a composite index.
+        /// </summary>
+        [JsonProperty(PropertyName = "IndexSpecs")]
+        public IReadOnlyList<string> IndexSpecs { get; }
+
+        /// <summary>
+        /// The index impact score of the composite index.
+        /// </summary>
+        [JsonProperty(PropertyName = "IndexImpactScore")]
+        public string IndexImpactScore { get; }
+    }
+}

Microsoft.Azure.Cosmos/src/Query/Core/Metrics/IndexMetricsInfo.cs

@@ -0,0 +1,83 @@
+//------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.  All rights reserved.
+//------------------------------------------------------------
+namespace Microsoft.Azure.Cosmos.Query.Core.Metrics
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Linq;
+    using System.Text;
+    using Microsoft.Azure.Cosmos.Core;
+    using Microsoft.Azure.Cosmos.Core.Utf8;
+    using Newtonsoft.Json;
+
+    /// <summary>
+    /// Query index utilization data for composite indexes (sub-structure of the Index Metrics class) in the Azure Cosmos database service.
+    /// </summary>
+#if INTERNAL
+#pragma warning disable SA1600
+#pragma warning disable CS1591
+    public
+#else
+    internal
+#endif
+    sealed class IndexMetricsInfo
+    {
+        /// <summary>
+        /// Initializes a new instance of the Index Metrics class.
+        /// </summary>
+        /// <param name="utilizedEntity">The utilized indexes</param>
+        /// <param name="potentialEntity">The potential indexes</param>
+        [JsonConstructor]
+        public IndexMetricsInfo(
+             IndexMetricsInfoEntity utilizedEntity,
+             IndexMetricsInfoEntity potentialEntity)
+        {
+            this.UtilizedEntity = utilizedEntity;
+            this.PotentialEntity = potentialEntity;
+        }
+
+        [JsonProperty("Utilized")]
+        public IndexMetricsInfoEntity UtilizedEntity { get; }
+
+        [JsonProperty("Potential")]
+        public IndexMetricsInfoEntity PotentialEntity { get; }
+
+        /// <summary>
+        /// Creates a new IndexMetricsInfo from the backend delimited string.
+        /// </summary>
+        /// <param name="delimitedString">The backend delimited string to deserialize from.</param>
+        /// <param name="result">The parsed index utilization info</param>
+        /// <returns>A new IndexMetricsInfo from the backend delimited string.</returns>
+        public static bool TryCreateFromString(string delimitedString, out IndexMetricsInfo result)
+        {
+            if (delimitedString == null)
+            {
+                result = null;
+                return false;
+            }
+
+            try
+            {
+                // Decode and deserialize the response string
+                string decodedString = System.Web.HttpUtility.UrlDecode(delimitedString, Encoding.UTF8);
+
+                result = JsonConvert.DeserializeObject<IndexMetricsInfo>(decodedString, new JsonSerializerSettings()
+                    {
+                        // Allowing null values to be resilient to Json structure change
+                        MissingMemberHandling = MissingMemberHandling.Ignore,
+                        NullValueHandling = NullValueHandling.Ignore,
+                        // Ignore parsing error encountered in deserialization
+                        Error = (sender, parsingErrorEvent) => parsingErrorEvent.ErrorContext.Handled = true
+                    }) ?? null;
+
+                return true;
+            }
+            catch (JsonException)
+            {
+                result = null;
+                return false;
+            }
+        }
+    }
+}

Microsoft.Azure.Cosmos/src/Query/Core/Metrics/IndexMetricsInfoEntity.cs

@@ -0,0 +1,43 @@
+//------------------------------------------------------------
+// Copyright (c) Microsoft Corporation.  All rights reserved.
+//------------------------------------------------------------
+namespace Microsoft.Azure.Cosmos.Query.Core.Metrics
+{
+    using System;
+    using System.Collections.Generic;
+    using System.Linq;
+    using System.Text;
+    using Microsoft.Azure.Cosmos.Core;
+    using Microsoft.Azure.Cosmos.Core.Utf8;
+    using Newtonsoft.Json;
+
+    /// <summary>
+    /// Query index utilization metrics in the Azure Cosmos database service.
+    /// </summary>
+#if INTERNAL
+#pragma warning disable SA1600
+#pragma warning disable CS1591
+    public
+#else
+    internal
+#endif
+    sealed class IndexMetricsInfoEntity
+    {
+        /// <summary>
+        /// Initializes a new instance of the Index Utilization class. This is the legacy class of IndexMetricsInfoEntity.
+        /// </summary>
+        /// <param name="singleIndexes">The utilized single indexes list</param>
+        /// <param name="compositeIndexes">The potential single indexes list</param>
+        [JsonConstructor]
+        public IndexMetricsInfoEntity(
+             IReadOnlyList<SingleIndexIndexMetrics> singleIndexes,
+             IReadOnlyList<CompositeIndexIndexMetrics> compositeIndexes)
+        {
+            this.SingleIndexes = (singleIndexes ?? Enumerable.Empty<SingleIndexIndexMetrics>()).Where(item => item != null).ToList();
+            this.CompositeIndexes = (compositeIndexes ?? Enumerable.Empty<CompositeIndexIndexMetrics>()).Where(item => item != null).ToList();
+        }
+
+        public IReadOnlyList<SingleIndexIndexMetrics> SingleIndexes { get; }
+        public IReadOnlyList<CompositeIndexIndexMetrics> CompositeIndexes { get; }
+    }
+}

Microsoft.Azure.Cosmos/src/Query/Core/Metrics/IndexMetricWriter.cs → Microsoft.Azure.Cosmos/src/Query/Core/Metrics/IndexMetricsWriter.cs

@@ -9,7 +9,7 @@ namespace Microsoft.Azure.Cosmos.Query.Core.Metrics
     using System.Text;
 
     /// <summary>
-    /// Base class for visiting and serializing a <see cref="QueryMetrics"/>.
+    /// Base class for visiting and serializing a <see cref="IndexUtilizationInfo"/>.
     /// </summary>
 #if INTERNAL
 #pragma warning disable SA1600
@@ -18,7 +18,7 @@ namespace Microsoft.Azure.Cosmos.Query.Core.Metrics
 #else
     internal
 #endif
-    class IndexMetricWriter
+    class IndexMetricsWriter
     {
         private const string IndexUtilizationInfo = "Index Utilization Information";
         private const string UtilizedSingleIndexes = "Utilized Single Indexes";
@@ -32,7 +32,7 @@ class IndexMetricWriter
 
         private readonly StringBuilder stringBuilder;
 
-        public IndexMetricWriter(StringBuilder stringBuilder)
+        public IndexMetricsWriter(StringBuilder stringBuilder)
         {
             this.stringBuilder = stringBuilder ?? throw new ArgumentNullException($"{nameof(stringBuilder)} must not be null.");
         }
@@ -50,37 +50,37 @@ public void WriteIndexMetrics(IndexUtilizationInfo indexUtilizationInfo)
         #region IndexUtilizationInfo
         protected void WriteBeforeIndexUtilizationInfo()
         {
-            IndexMetricWriter.AppendNewlineToStringBuilder(this.stringBuilder);
-            IndexMetricWriter.AppendHeaderToStringBuilder(
+            IndexMetricsWriter.AppendNewlineToStringBuilder(this.stringBuilder);
+            IndexMetricsWriter.AppendHeaderToStringBuilder(
                 this.stringBuilder,
-                IndexMetricWriter.IndexUtilizationInfo,
+                IndexMetricsWriter.IndexUtilizationInfo,
                 indentLevel: 0);
         }
 
         protected void WriteIndexUtilizationInfo(IndexUtilizationInfo indexUtilizationInfo)
         {
-            IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricWriter.UtilizedSingleIndexes, indentLevel: 1);
+            IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricsWriter.UtilizedSingleIndexes, indentLevel: 1);
 
             foreach (SingleIndexUtilizationEntity indexUtilizationEntity in indexUtilizationInfo.UtilizedSingleIndexes)
             {
                 WriteSingleIndexUtilizationEntity(indexUtilizationEntity);
             }
 
-            IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricWriter.PotentialSingleIndexes, indentLevel: 1);
+            IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricsWriter.PotentialSingleIndexes, indentLevel: 1);
 
             foreach (SingleIndexUtilizationEntity indexUtilizationEntity in indexUtilizationInfo.PotentialSingleIndexes)
             {
                 WriteSingleIndexUtilizationEntity(indexUtilizationEntity);
             }
 
-            IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricWriter.UtilizedCompositeIndexes, indentLevel: 1);
+            IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricsWriter.UtilizedCompositeIndexes, indentLevel: 1);
 
             foreach (CompositeIndexUtilizationEntity indexUtilizationEntity in indexUtilizationInfo.UtilizedCompositeIndexes)
             {
                 WriteCompositeIndexUtilizationEntity(indexUtilizationEntity);
             }
 
-            IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricWriter.PotentialCompositeIndexes, indentLevel: 1);
+            IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricsWriter.PotentialCompositeIndexes, indentLevel: 1);
 
             foreach (CompositeIndexUtilizationEntity indexUtilizationEntity in indexUtilizationInfo.PotentialCompositeIndexes)
             {
@@ -89,16 +89,16 @@ protected void WriteIndexUtilizationInfo(IndexUtilizationInfo indexUtilizationIn
 
             void WriteSingleIndexUtilizationEntity(SingleIndexUtilizationEntity indexUtilizationEntity)
             {
-                IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, $"{IndexMetricWriter.IndexExpression}: {indexUtilizationEntity.IndexDocumentExpression}", indentLevel: 2);
-                IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, $"{IndexMetricWriter.IndexImpactScore}: {indexUtilizationEntity.IndexImpactScore}", indentLevel: 2);
-                IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricWriter.IndexUtilizationSeparator, indentLevel: 2);
+                IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, $"{IndexMetricsWriter.IndexExpression}: {indexUtilizationEntity.IndexDocumentExpression}", indentLevel: 2);
+                IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, $"{IndexMetricsWriter.IndexImpactScore}: {indexUtilizationEntity.IndexImpactScore}", indentLevel: 2);
+                IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricsWriter.IndexUtilizationSeparator, indentLevel: 2);
             }
 
             void WriteCompositeIndexUtilizationEntity(CompositeIndexUtilizationEntity indexUtilizationEntity)
             {
-                IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, $"{IndexMetricWriter.IndexExpression}: {String.Join(", ", indexUtilizationEntity.IndexDocumentExpressions)}", indentLevel: 2);
-                IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, $"{IndexMetricWriter.IndexImpactScore}: {indexUtilizationEntity.IndexImpactScore}", indentLevel: 2);
-                IndexMetricWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricWriter.IndexUtilizationSeparator, indentLevel: 2);
+                IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, $"{IndexMetricsWriter.IndexExpression}: {String.Join(", ", indexUtilizationEntity.IndexDocumentExpressions)}", indentLevel: 2);
+                IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, $"{IndexMetricsWriter.IndexImpactScore}: {indexUtilizationEntity.IndexImpactScore}", indentLevel: 2);
+                IndexMetricsWriter.AppendHeaderToStringBuilder(this.stringBuilder, IndexMetricsWriter.IndexUtilizationSeparator, indentLevel: 2);
             }
         }
 
@@ -123,7 +123,7 @@ private static void AppendHeaderToStringBuilder(StringBuilder stringBuilder, str
 
         private static void AppendNewlineToStringBuilder(StringBuilder stringBuilder)
         {
-            IndexMetricWriter.AppendHeaderToStringBuilder(
+            IndexMetricsWriter.AppendHeaderToStringBuilder(
                 stringBuilder,
                 string.Empty,
                 indentLevel: 0);

Microsoft.Azure.Cosmos/src/Query/Core/Metrics/IndexUtilizationInfo.cs

@@ -8,6 +8,7 @@ namespace Microsoft.Azure.Cosmos.Query.Core.Metrics
     using System.Linq;
     using System.Text;
     using Microsoft.Azure.Cosmos.Core;
+    using Microsoft.Azure.Cosmos.Core.Utf8;
     using Newtonsoft.Json;
 
     /// <summary>
@@ -29,7 +30,7 @@ sealed class IndexUtilizationInfo
             potentialCompositeIndexes: new List<CompositeIndexUtilizationEntity>());
 
         /// <summary>
-        /// Initializes a new instance of the Index Utilization class.
+        /// Initializes a new instance of the Index Utilization class. This is the legacy class of IndexMetricsInfo.
         /// </summary>
         /// <param name="utilizedSingleIndexes">The utilized single indexes list</param>
         /// <param name="potentialSingleIndexes">The potential single indexes list</param>
@@ -60,33 +61,22 @@ public IndexUtilizationInfo(
         /// <param name="result">The parsed index utilization info</param>
         /// <returns>A new IndexUtilizationInfo from the backend delimited string.</returns>
         internal static bool TryCreateFromDelimitedBase64String(string delimitedString, out IndexUtilizationInfo result)
-        {
-            if (delimitedString == null)
-            {
-                result = IndexUtilizationInfo.Empty;
-                return true;
-            }
-
-            return TryCreateFromDelimitedString(System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(delimitedString)), out result);
-        }
-
-        /// <summary>
-        /// Creates a new IndexUtilizationInfo from the backend delimited string.
-        /// </summary>
-        /// <param name="delimitedString">The backend delimited string to deserialize from.</param>
-        /// <param name="result">The parsed index utilization info</param>
-        /// <returns>A new IndexUtilizationInfo from the backend delimited string.</returns>
-        internal static bool TryCreateFromDelimitedString(string delimitedString, out IndexUtilizationInfo result)
         {
             if (delimitedString == null)
             {
                 result = IndexUtilizationInfo.Empty;
                 return true;
             }
 
+            // Even though this parsing is resilient, older version of the SDK doesn't have such lenient parsing.
+            // As such, it is right not not possible to remove some of the field in the IndexUtilizationInfo class.
+            // However, in newer version of the SDKs, the code base is going to start returning IndexMetricsInfo, 
+            // so this class exists solely for legacy support.
             try
             {
-                result = JsonConvert.DeserializeObject<IndexUtilizationInfo>(delimitedString, new JsonSerializerSettings()
+                string decodedString = System.Text.Encoding.UTF8.GetString(Convert.FromBase64String(delimitedString));
+
+                result = JsonConvert.DeserializeObject<IndexUtilizationInfo>(decodedString, new JsonSerializerSettings()
                 {
                     // Allowing null values to be resilient to Json structure change
                     MissingMemberHandling = MissingMemberHandling.Ignore,
@@ -108,20 +98,10 @@ internal static bool TryCreateFromDelimitedString(string delimitedString, out In
         /// Materialize the Index Utilization String into Concrete objects.
         /// </summary>
         /// <param name="delimitedString">The index utilization response string as sent by the back end.</param>
-        /// <param name="isBse64Encoded">The encoding of the string.</param>
         /// <returns>Cpncrete Index utilization object.</returns>
-        public static IndexUtilizationInfo CreateFromString(string delimitedString, bool isBse64Encoded)
+        public static IndexUtilizationInfo CreateFromString(string delimitedString)
         {
-            IndexUtilizationInfo indexUtilizationInfo;
-
-            if (isBse64Encoded)
-            {
-                TryCreateFromDelimitedBase64String(delimitedString, out indexUtilizationInfo);
-            }
-            else
-            {
-                TryCreateFromDelimitedString(delimitedString, out indexUtilizationInfo);
-            }
+            TryCreateFromDelimitedBase64String(delimitedString, out IndexUtilizationInfo indexUtilizationInfo);
 
             return indexUtilizationInfo;
         }