.Net: [MEVD] Cosmos NoSQL provider work on keys, partition keys and point reads (#13550)

This is a sizable cleanup/redo of large chunks of the Cosmos NoSQL
provider; I've broken it down to three commits for easier reviewing.

* Cosmos NoSQL collections can now have either string/Guid as their key,
or CosmosNoSqlKey. In the former case, this configures the partition key
to be the same as the string/Guid document key - this is a sensible
default that's common (and encouraged) in Cosmos. All other scenarios
require CosmosNoSqlKey:
    * A single partition key that isn't the document ID
    * A hierarchical partition key (more than one property)
    * No partition key (legacy/discouraged)
* Note that CosmosNoSqlKey is only passed to GetAsync and DeleteAsync;
on the user's .NET record type, the properties are there as usual (e.g.
a string document Id property, an int partition key property). This
introduces a discrepancy for the first time between the collection's
TKey (CosmosNoSqlKey) and its actual key property on the .NET type (a
string); this made some things trickier, but is the correct way to do
things for composite key cases (we'd do the same if we implement
composite keys for relational providers).
* Added support for Cosmos hierarchical partition keys (2-3 properties
instead of just one).
* GetAsync no longer does a SQL query with a WHERE clause, but rather an
efficient point read via ReadItem. The multiple-key overload does
ReadManyItemsAsync, which again is far more efficient.
* UpdateAsync and DeleteAsync now correctly supply the partition key in
the call's request options, again making it much more efficient.
* Various other cleanup and fixes all around.

Author: roji

dotnet/samples/Demos/VectorStoreRAG/Program.cs

@@ -83,7 +83,7 @@
             appConfig.CosmosMongoConfig.DatabaseName);
         break;
     case "CosmosNoSql":
-        kernelBuilder.Services.AddCosmosNoSqlCollection<TextSnippet<string>>(
+        kernelBuilder.Services.AddCosmosNoSqlCollection<string, TextSnippet<string>>(
             appConfig.RagConfig.CollectionName,
             appConfig.CosmosNoSqlConfig.ConnectionString,
             appConfig.CosmosNoSqlConfig.DatabaseName);

dotnet/src/VectorData/CosmosNoSql/ByteArrayJsonConverter.cs

@@ -0,0 +1,96 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.SemanticKernel.Connectors.CosmosNoSql;
+
+/// <summary>
+/// A JSON converter for byte arrays that serializes them as JSON arrays of numbers
+/// instead of base64-encoded strings.
+/// </summary>
+/// <remarks>
+/// This is needed because Cosmos DB's VectorDistance function requires vectors to be arrays of numbers,
+/// not base64-encoded strings.
+/// </remarks>
+internal sealed class ByteArrayJsonConverter : JsonConverter<byte[]>
+{
+    /// <inheritdoc/>
+    public override byte[] Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        // Support reading both base64 strings (for backward compatibility) and number arrays
+        if (reader.TokenType == JsonTokenType.String)
+        {
+            return reader.GetBytesFromBase64();
+        }
+
+        if (reader.TokenType != JsonTokenType.StartArray)
+        {
+            throw new JsonException($"Expected StartArray or String token, got {reader.TokenType}");
+        }
+
+        var list = new List<byte>();
+        while (reader.Read() && reader.TokenType != JsonTokenType.EndArray)
+        {
+            list.Add(reader.GetByte());
+        }
+        return list.ToArray();
+    }
+
+    /// <inheritdoc/>
+    public override void Write(Utf8JsonWriter writer, byte[] value, JsonSerializerOptions options)
+    {
+        writer.WriteStartArray();
+        foreach (var b in value)
+        {
+            writer.WriteNumberValue(b);
+        }
+        writer.WriteEndArray();
+    }
+}
+
+/// <summary>
+/// A JSON converter for <see cref="ReadOnlyMemory{T}"/> of byte that serializes as JSON arrays of numbers
+/// instead of base64-encoded strings.
+/// </summary>
+/// <remarks>
+/// This is needed because Cosmos DB's VectorDistance function requires vectors to be arrays of numbers,
+/// not base64-encoded strings.
+/// </remarks>
+internal sealed class ReadOnlyMemoryByteJsonConverter : JsonConverter<ReadOnlyMemory<byte>>
+{
+    /// <inheritdoc/>
+    public override ReadOnlyMemory<byte> Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
+    {
+        // Support reading both base64 strings (for backward compatibility) and number arrays
+        if (reader.TokenType == JsonTokenType.String)
+        {
+            return new ReadOnlyMemory<byte>(reader.GetBytesFromBase64());
+        }
+
+        if (reader.TokenType != JsonTokenType.StartArray)
+        {
+            throw new JsonException($"Expected StartArray or String token, got {reader.TokenType}");
+        }
+
+        var list = new List<byte>();
+        while (reader.Read() && reader.TokenType != JsonTokenType.EndArray)
+        {
+            list.Add(reader.GetByte());
+        }
+        return new ReadOnlyMemory<byte>(list.ToArray());
+    }
+
+    /// <inheritdoc/>
+    public override void Write(Utf8JsonWriter writer, ReadOnlyMemory<byte> value, JsonSerializerOptions options)
+    {
+        writer.WriteStartArray();
+        foreach (var b in value.Span)
+        {
+            writer.WriteNumberValue(b);
+        }
+        writer.WriteEndArray();
+    }
+}