.Net: Switch to using interfaces for search instead of query objects. (…

…#8690)

### Motivation and Context

As part of the vector search adr, we have agreed to switch to a
different design for exposing different search experiences.

### Description

- Switch to individual interfaces for search.
- Making vector search part of the collection interface

### Contribution Checklist

<!-- Before submitting this PR, please make sure: -->

- [x] The code builds clean without any errors or warnings
- [x] The PR follows the [SK Contribution
Guidelines](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md)
and the [pre-submission formatting
script](https://github.com/microsoft/semantic-kernel/blob/main/CONTRIBUTING.md#development-scripts)
raises no violations
- [x] All unit tests pass, and I have added new tests where possible
- [x] I didn't break anyone 😄

docs/decisions/00NN-vector-search-design.md

@@ -371,3 +371,7 @@ class AzureAISearchVectorStoreRecordCollection<TRecord>: IVectorStoreRecordColle
 ```
 
 ## Decision Outcome
+
+Chosen option: 4
+
+The consensus is that option 4 is easier to understand for users, where only functionality that works for all vector stores are exposed by default.

dotnet/samples/Concepts/Memory/VectorSearch_Simple.cs

@@ -0,0 +1,137 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.SemanticKernel.Connectors.AzureOpenAI;
+using Microsoft.SemanticKernel.Data;
+using Microsoft.SemanticKernel.Embeddings;
+
+namespace Memory;
+
+/// <summary>
+/// A simple example showing how to ingest data into a vector store and then use vector search to find related records to a given string.
+///
+/// The example shows the following steps:
+/// 1. Create an embedding generator.
+/// 2. Create a Volatile Vector Store.
+/// 3. Ingest some data into the vector store.
+/// 4. Search the vector store with various text and filtering options.
+/// </summary>
+public class VectorSearch_Simple(ITestOutputHelper output) : BaseTest(output)
+{
+    [Fact]
+    public async Task ExampleAsync()
+    {
+        // Create an embedding generation service.
+        var textEmbeddingGenerationService = new AzureOpenAITextEmbeddingGenerationService(
+                TestConfiguration.AzureOpenAIEmbeddings.DeploymentName,
+                TestConfiguration.AzureOpenAIEmbeddings.Endpoint,
+                TestConfiguration.AzureOpenAIEmbeddings.ApiKey);
+
+        // Initiate the docker container and construct the vector store.
+        var vectorStore = new VolatileVectorStore();
+
+        // Get and create collection if it doesn't exist.
+        var collection = vectorStore.GetCollection<ulong, Glossary>("skglossary");
+        await collection.CreateCollectionIfNotExistsAsync();
+
+        // Create glossary entries and generate embeddings for them.
+        var glossaryEntries = CreateGlossaryEntries().ToList();
+        var tasks = glossaryEntries.Select(entry => Task.Run(async () =>
+        {
+            entry.DefinitionEmbedding = await textEmbeddingGenerationService.GenerateEmbeddingAsync(entry.Definition);
+        }));
+        await Task.WhenAll(tasks);
+
+        // Upsert the glossary entries into the collection and return their keys.
+        var upsertedKeysTasks = glossaryEntries.Select(x => collection.UpsertAsync(x));
+        var upsertedKeys = await Task.WhenAll(upsertedKeysTasks);
+
+        var vectorSearch = collection as IVectorizedSearch<Glossary>;
+
+        // Search the collection using a vector search.
+        var searchString = "What is an Application Programming Interface";
+        var searchVector = await textEmbeddingGenerationService.GenerateEmbeddingAsync(searchString);
+        var searchResult = await vectorSearch!.VectorizedSearchAsync(searchVector, new() { Limit = 1 }).ToListAsync();
+
+        Console.WriteLine("Search string: " + searchString);
+        Console.WriteLine("Result: " + searchResult.First().Record.Definition);
+        Console.WriteLine();
+
+        // Search the collection using a vector search.
+        searchString = "What is Retrieval Augmented Generation";
+        searchVector = await textEmbeddingGenerationService.GenerateEmbeddingAsync(searchString);
+        searchResult = await vectorSearch!.VectorizedSearchAsync(searchVector, new() { Limit = 1 }).ToListAsync();
+
+        Console.WriteLine("Search string: " + searchString);
+        Console.WriteLine("Result: " + searchResult.First().Record.Definition);
+        Console.WriteLine();
+
+        // Search the collection using a vector search with pre-filtering.
+        searchString = "What is Retrieval Augmented Generation";
+        searchVector = await textEmbeddingGenerationService.GenerateEmbeddingAsync(searchString);
+        var filter = new VectorSearchFilter().EqualTo(nameof(Glossary.Category), "External Definitions");
+        searchResult = await vectorSearch!.VectorizedSearchAsync(searchVector, new() { Limit = 3, Filter = filter }).ToListAsync();
+
+        Console.WriteLine("Search string: " + searchString);
+        Console.WriteLine("Number of results: " + searchResult.Count);
+        Console.WriteLine("Result 1 Score: " + searchResult[0].Score);
+        Console.WriteLine("Result 1: " + searchResult[0].Record.Definition);
+        Console.WriteLine("Result 2 Score: " + searchResult[1].Score);
+        Console.WriteLine("Result 2: " + searchResult[1].Record.Definition);
+    }
+
+    /// <summary>
+    /// Sample model class that represents a glossary entry.
+    /// </summary>
+    /// <remarks>
+    /// Note that each property is decorated with an attribute that specifies how the property should be treated by the vector store.
+    /// This allows us to create a collection in the vector store and upsert and retrieve instances of this class without any further configuration.
+    /// </remarks>
+    private sealed class Glossary
+    {
+        [VectorStoreRecordKey]
+        public ulong Key { get; set; }
+
+        [VectorStoreRecordData(IsFilterable = true)]
+        public string Category { get; set; }
+
+        [VectorStoreRecordData]
+        public string Term { get; set; }
+
+        [VectorStoreRecordData]
+        public string Definition { get; set; }
+
+        [VectorStoreRecordVector(1536)]
+        public ReadOnlyMemory<float> DefinitionEmbedding { get; set; }
+    }
+
+    /// <summary>
+    /// Create some sample glossary entries.
+    /// </summary>
+    /// <returns>A list of sample glossary entries.</returns>
+    private static IEnumerable<Glossary> CreateGlossaryEntries()
+    {
+        yield return new Glossary
+        {
+            Key = 1,
+            Category = "External Definitions",
+            Term = "API",
+            Definition = "Application Programming Interface. A set of rules and specifications that allow software components to communicate and exchange data."
+        };
+
+        yield return new Glossary
+        {
+            Key = 2,
+            Category = "Core Definitions",
+            Term = "Connectors",
+            Definition = "Connectors allow you to integrate with various services provide AI capabilities, including LLM, AudioToText, TextToAudio, Embedding generation, etc."
+        };
+
+        yield return new Glossary
+        {
+            Key = 3,
+            Category = "External Definitions",
+            Term = "RAG",
+            Definition = "Retrieval Augmented Generation - a term that refers to the process of retrieving additional data to provide as context to an LLM to use when generating a response (completion) to a user’s question (prompt)."
+        };
+    }
+}

dotnet/src/Connectors/Connectors.AzureAISearch.UnitTests/AzureAISearchVectorStoreRecordCollectionTests.cs

@@ -567,16 +567,15 @@ public async Task CanSearchWithVectorAndFilterAsync()
         var filter = new VectorSearchFilter().EqualTo(nameof(MultiPropsModel.Data1), "Data1FilterValue");
 
         // Act.
-        var searchResults = await sut.SearchAsync(
-            VectorSearchQuery.CreateQuery(
-                new ReadOnlyMemory<float>(new float[4]),
-                new()
-                {
-                    Limit = 5,
-                    Offset = 3,
-                    Filter = filter,
-                    VectorFieldName = nameof(MultiPropsModel.Vector1)
-                }),
+        var searchResults = await sut.VectorizedSearchAsync(
+            new ReadOnlyMemory<float>(new float[4]),
+            new()
+            {
+                Limit = 5,
+                Offset = 3,
+                Filter = filter,
+                VectorFieldName = nameof(MultiPropsModel.Vector1)
+            },
             this._testCancellationToken).ToListAsync();
 
         // Assert.
@@ -608,16 +607,15 @@ public async Task CanSearchWithTextAndFilterAsync()
         var filter = new VectorSearchFilter().EqualTo(nameof(MultiPropsModel.Data1), "Data1FilterValue");
 
         // Act.
-        var searchResults = await sut.SearchAsync(
-            VectorSearchQuery.CreateQuery(
-                "search string",
-                new()
-                {
-                    Limit = 5,
-                    Offset = 3,
-                    Filter = filter,
-                    VectorFieldName = nameof(MultiPropsModel.Vector1)
-                }),
+        var searchResults = await sut.VectorizableTextSearchAsync(
+            "search string",
+            new()
+            {
+                Limit = 5,
+                Offset = 3,
+                Filter = filter,
+                VectorFieldName = nameof(MultiPropsModel.Vector1)
+            },
             this._testCancellationToken).ToListAsync();
 
         // Assert.

dotnet/src/Connectors/Connectors.Memory.AzureAISearch/AzureAISearchVectorStoreRecordCollection.cs

@@ -22,7 +22,7 @@ namespace Microsoft.SemanticKernel.Connectors.AzureAISearch;
 /// </summary>
 /// <typeparam name="TRecord">The data model to use for adding, updating and retrieving data from storage.</typeparam>
 #pragma warning disable CA1711 // Identifiers should not have incorrect suffix
-public sealed class AzureAISearchVectorStoreRecordCollection<TRecord> : IVectorStoreRecordCollection<string, TRecord>, IVectorSearch<TRecord>
+public sealed class AzureAISearchVectorStoreRecordCollection<TRecord> : IVectorStoreRecordCollection<string, TRecord>, IVectorizableTextSearch<TRecord>
 #pragma warning restore CA1711 // Identifiers should not have incorrect suffix
     where TRecord : class
 {
@@ -342,72 +342,84 @@ public async IAsyncEnumerable<string> UpsertBatchAsync(IEnumerable<TRecord> reco
     }
 
     /// <inheritdoc />
-    public IAsyncEnumerable<VectorSearchResult<TRecord>> SearchAsync(VectorSearchQuery vectorQuery, CancellationToken cancellationToken = default)
+    public IAsyncEnumerable<VectorSearchResult<TRecord>> VectorizedSearchAsync<TVector>(TVector vector, Data.VectorSearchOptions? options = null, CancellationToken cancellationToken = default)
     {
-        Verify.NotNull(vectorQuery);
+        Verify.NotNull(vector);
 
         if (this._firstVectorPropertyName is null)
         {
             throw new InvalidOperationException("The collection does not have any vector fields, so vector search is not possible.");
         }
 
-        string? queryText = null;
-        string? filterString = null;
-        var searchFields = new List<string>();
+        if (vector is not ReadOnlyMemory<float> floatVector)
+        {
+            throw new NotSupportedException($"The provided vector type {vector.GetType().Name} is not supported by the Azure AI Search connector.");
+        }
+
+        // Resolve options.
+        var internalOptions = options ?? Data.VectorSearchOptions.Default;
+        string? vectorFieldName = this.ResolveVectorFieldName(internalOptions.VectorFieldName);
+
+        // Configure search settings.
         var vectorQueries = new List<VectorQuery>();
-        int limit = 3;
-        int offset = 0;
-        bool includeVectors = false;
+        vectorQueries.Add(new VectorizedQuery(floatVector) { KNearestNeighborsCount = internalOptions.Limit, Fields = { vectorFieldName } });
+        var filterString = AzureAISearchVectorStoreCollectionSearchMapping.BuildFilterString(internalOptions.Filter, this._storagePropertyNames);
 
-        if (vectorQuery is VectorizedSearchQuery<ReadOnlyMemory<float>> floatVectorQuery)
+        // Build search options.
+        var searchOptions = new SearchOptions
         {
-            // Resolve options.
-            var internalOptions = floatVectorQuery.SearchOptions ?? Data.VectorSearchOptions.Default;
-            string? vectorFieldName = this.ResolveVectorFieldName(internalOptions.VectorFieldName);
-
-            // Configure search settings.
-            filterString = AzureAISearchVectorStoreCollectionSearchMapping.BuildFilterString(internalOptions.Filter, this._storagePropertyNames);
-            vectorQueries.Add(new VectorizedQuery(floatVectorQuery.Vector) { KNearestNeighborsCount = internalOptions.Limit, Fields = { vectorFieldName } });
-            limit = internalOptions.Limit;
-            offset = internalOptions.Offset;
-            includeVectors = internalOptions.IncludeVectors;
-        }
-        else if (vectorQuery is VectorizableTextSearchQuery vectorizableTextQuery)
+            VectorSearch = new(),
+            Size = internalOptions.Limit,
+            Skip = internalOptions.Offset,
+            Filter = filterString,
+        };
+        searchOptions.VectorSearch.Queries.AddRange(vectorQueries);
+
+        // Filter out vector fields if requested.
+        if (!internalOptions.IncludeVectors)
         {
-            // Resolve options.
-            var internalOptions = vectorizableTextQuery.SearchOptions ?? Data.VectorSearchOptions.Default;
-            string? vectorFieldName = this.ResolveVectorFieldName(internalOptions.VectorFieldName);
-
-            // Configure search settings.
-            filterString = AzureAISearchVectorStoreCollectionSearchMapping.BuildFilterString(internalOptions.Filter, this._storagePropertyNames);
-            vectorQueries.Add(new VectorizableTextQuery(vectorizableTextQuery.QueryText) { KNearestNeighborsCount = internalOptions.Limit, Fields = { vectorFieldName } });
-            limit = internalOptions.Limit;
-            offset = internalOptions.Offset;
-            includeVectors = internalOptions.IncludeVectors;
+            searchOptions.Select.AddRange(this._nonVectorStoragePropertyNames);
         }
-        else
+
+        return this.SearchAndMapToDataModelAsync(null, searchOptions, internalOptions.IncludeVectors, cancellationToken);
+    }
+
+    /// <inheritdoc />
+    public IAsyncEnumerable<VectorSearchResult<TRecord>> VectorizableTextSearchAsync(string searchText, Data.VectorSearchOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        Verify.NotNull(searchText);
+
+        if (this._firstVectorPropertyName is null)
         {
-            throw new NotSupportedException($"A {nameof(VectorSearchQuery)} of type {vectorQuery.QueryType} is not supported by the Azure AI Search connector.");
+            throw new InvalidOperationException("The collection does not have any vector fields, so vector search is not possible.");
         }
 
+        // Resolve options.
+        var internalOptions = options ?? Data.VectorSearchOptions.Default;
+        string? vectorFieldName = this.ResolveVectorFieldName(internalOptions.VectorFieldName);
+
+        // Configure search settings.
+        var vectorQueries = new List<VectorQuery>();
+        vectorQueries.Add(new VectorizableTextQuery(searchText) { KNearestNeighborsCount = internalOptions.Limit, Fields = { vectorFieldName } });
+        var filterString = AzureAISearchVectorStoreCollectionSearchMapping.BuildFilterString(internalOptions.Filter, this._storagePropertyNames);
+
         // Build search options.
         var searchOptions = new SearchOptions
         {
             VectorSearch = new(),
-            Size = limit,
-            Skip = offset,
+            Size = internalOptions.Limit,
+            Skip = internalOptions.Offset,
             Filter = filterString,
         };
-        searchOptions.SearchFields.AddRange(searchFields);
         searchOptions.VectorSearch.Queries.AddRange(vectorQueries);
 
         // Filter out vector fields if requested.
-        if (!includeVectors)
+        if (!internalOptions.IncludeVectors)
         {
             searchOptions.Select.AddRange(this._nonVectorStoragePropertyNames);
         }
 
-        return this.SearchAndMapToDataModelAsync(queryText, searchOptions, includeVectors, cancellationToken);
+        return this.SearchAndMapToDataModelAsync(null, searchOptions, internalOptions.IncludeVectors, cancellationToken);
     }
 
     /// <summary>

dotnet/src/Connectors/Connectors.Memory.AzureCosmosDBMongoDB/AzureCosmosDBMongoDBVectorStoreRecordCollection.cs

@@ -237,6 +237,12 @@ public async IAsyncEnumerable<string> UpsertBatchAsync(
         }
     }
 
+    /// <inheritdoc />
+    public IAsyncEnumerable<VectorSearchResult<TRecord>> VectorizedSearchAsync<TVector>(TVector vector, VectorSearchOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        throw new NotImplementedException();
+    }
+
     #region private
 
     private async Task CreateIndexAsync(string collectionName, CancellationToken cancellationToken)

dotnet/src/Connectors/Connectors.Memory.AzureCosmosDBNoSQL/AzureCosmosDBNoSQLVectorStoreRecordCollection.cs

@@ -360,6 +360,12 @@ async IAsyncEnumerable<AzureCosmosDBNoSQLCompositeKey> IVectorStoreRecordCollect
         }
     }
 
+    /// <inheritdoc />
+    public IAsyncEnumerable<VectorSearchResult<TRecord>> VectorizedSearchAsync<TVector>(TVector vector, VectorSearchOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        throw new NotImplementedException();
+    }
+
     #endregion
 
     #region private

dotnet/src/Connectors/Connectors.Memory.Pinecone/PineconeVectorStoreRecordCollection.cs

@@ -227,6 +227,12 @@ await this.RunOperationAsync(
         }
     }
 
+    /// <inheritdoc />
+    public IAsyncEnumerable<VectorSearchResult<TRecord>> VectorizedSearchAsync<TVector>(TVector vector, VectorSearchOptions? options = null, CancellationToken cancellationToken = default)
+    {
+        throw new NotImplementedException();
+    }
+
     private async Task<T> RunOperationAsync<T>(string operationName, Func<Task<T>> operation)
     {
         try