Implement similar document search

Author: philipproplesch

src/Meilisearch/Index.SimilarDocuments.cs

@@ -0,0 +1,33 @@
+using System.Net.Http.Json;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Meilisearch
+{
+    public partial class Index
+    {
+        /// <summary>
+        /// Search for similar documents.
+        /// </summary>
+        /// <param name="query">The query to search for similar documents.</param>
+        /// <param name="cancellationToken">The cancellation token for this call.</param>
+        /// <typeparam name="T">The type of the documents to return.</typeparam>
+        /// <returns>Returns the similar documents.</returns>
+        public async Task<SimilarDocumentsResult<T>> SearchSimilarDocumentsAsync<T>(
+            SimilarDocumentsQuery query,
+            CancellationToken cancellationToken = default)
+        {
+            var responseMessage = await _http
+                .PostAsJsonAsync(
+                    $"indexes/{Uid}/similar",
+                    query,
+                    Constants.JsonSerializerOptionsRemoveNulls,
+                    cancellationToken: cancellationToken)
+                .ConfigureAwait(false);
+
+            return await responseMessage.Content
+                .ReadFromJsonAsync<SimilarDocumentsResult<T>>(cancellationToken: cancellationToken)
+                .ConfigureAwait(false);
+        }
+    }
+}

src/Meilisearch/Meilisearch.csproj

@@ -86,5 +86,8 @@
         <Compile Update="Index.Embedders.cs">
           <DependentUpon>Index.cs</DependentUpon>
         </Compile>
+        <Compile Update="Index.SimilarDocuments.cs">
+          <DependentUpon>Index.cs</DependentUpon>
+        </Compile>
     </ItemGroup>
 </Project>

src/Meilisearch/SimilarDocumentsQuery.cs

@@ -0,0 +1,85 @@
+using System;
+using System.Text.Json.Serialization;
+
+namespace Meilisearch
+{
+    /// <summary>
+    /// Search query for similar documents.
+    /// </summary>
+    public class SimilarDocumentsQuery
+    {
+        /// <summary>
+        /// Creates a new instance of the <see cref="SimilarDocumentsQuery"/> class.
+        /// </summary>
+        /// <param name="id"></param>
+        public SimilarDocumentsQuery(string id)
+        {
+            if (string.IsNullOrEmpty(id))
+            {
+                throw new ArgumentNullException(nameof(id));
+            }
+
+            Id = id;
+        }
+
+        /// <summary>
+        /// Gets the document id.
+        /// </summary>
+        [JsonPropertyName("id")]
+        public string Id { get; }
+
+        /// <summary>
+        /// Gets or sets the embedder.
+        /// </summary>
+        [JsonPropertyName("embedder")]
+        public string Embedder { get; set; }
+
+        /// <summary>
+        /// Gets or sets the attributes to retrieve.
+        /// </summary>
+        [JsonPropertyName("attributesToRetrieve")]
+        public string[] AttributesToRetrieve { get; set; } = { "*" };
+
+        /// <summary>
+        /// Gets or sets the offset.
+        /// </summary>
+        [JsonPropertyName("offset")]
+        public int Offset { get; set; } = 0;
+
+        /// <summary>
+        /// Gets or sets the limit.
+        /// </summary>
+        [JsonPropertyName("limit")]
+        public int Limit { get; set; } = 20;
+
+        /// <summary>
+        /// Gets or sets the filter.
+        /// </summary>
+        [JsonPropertyName("filter")]
+        public string Filter { get; set; }
+
+        /// <summary>
+        /// Gets or sets whether to show the ranking score.
+        /// </summary>
+        [JsonPropertyName("showRankingScore")]
+        public bool ShowRankingScore { get; set; }
+
+        /// <summary>
+        /// Gets or sets whether to show the ranking score details.
+        /// </summary>
+        [JsonPropertyName("showRankingScoreDetails")]
+        public bool ShowRankingScoreDetails { get; set; }
+
+        /// <summary>
+        /// Gets or sets the ranking score threshold.
+        /// </summary>
+        [JsonPropertyName("rankingScoreThreshold")]
+        public int? RankingScoreThreshold { get; set; }
+
+        /// <summary>
+        /// Gets or sets whether to retrieve the vectors.
+        /// </summary>
+        [JsonPropertyName("retrieveVectors")]
+        public bool RetrieveVectors { get; set; }
+    }
+}

src/Meilisearch/SimilarDocumentsResult.cs

@@ -0,0 +1,72 @@
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace Meilisearch
+{
+    /// <summary>
+    /// Search result for similar documents.
+    /// </summary>
+    public class SimilarDocumentsResult<T>
+    {
+        /// <summary>
+        /// Creates a new instance of the <see cref="SimilarDocumentsResult{T}"/> class.
+        /// </summary>
+        /// <param name="hits"></param>
+        /// <param name="id"></param>
+        /// <param name="processingTimeMs"></param>
+        /// <param name="offset"></param>
+        /// <param name="limit"></param>
+        /// <param name="estimatedTotalHits"></param>
+        public SimilarDocumentsResult(
+            IReadOnlyCollection<T> hits,
+            string id,
+            int processingTimeMs,
+            int offset,
+            int limit,
+            int estimatedTotalHits)
+        {
+            Hits = hits;
+            Id = id;
+            ProcessingTimeMs = processingTimeMs;
+            Offset = offset;
+            Limit = limit;
+            EstimatedTotalHits = estimatedTotalHits;
+        }
+
+        /// <summary>
+        /// Gets the hits.
+        /// </summary>
+        [JsonPropertyName("hits")]
+        public IReadOnlyCollection<T> Hits { get; }
+
+        /// <summary>
+        /// Gets or sets the id.
+        /// </summary>
+        [JsonPropertyName("id")]
+        public string Id { get; }
+
+        /// <summary>
+        /// Gets or sets the processing time in milliseconds.
+        /// </summary>
+        [JsonPropertyName("processingTimeMs")]
+        public int ProcessingTimeMs { get; }
+
+        /// <summary>
+        /// Gets or sets the offset.
+        /// </summary>
+        [JsonPropertyName("offset")]
+        public int Offset { get; }
+
+        /// <summary>
+        /// Gets or sets the limit.
+        /// </summary>
+        [JsonPropertyName("limit")]
+        public int Limit { get; }
+
+        /// <summary>
+        /// Gets or sets the estimated total hits.
+        /// </summary>
+        [JsonPropertyName("estimatedTotalHits")]
+        public int EstimatedTotalHits { get; }
+    }
+}

tests/Meilisearch.Tests/SearchTests.cs

@@ -577,5 +577,23 @@ public async Task CustomSearchWithVector()
             Assert.Equal("522681", movies.Hits.First().Id);
             Assert.Equal("Escape Room", movies.Hits.First().Title);
         }
+
+        [Fact]
+        public async Task CustomSearchWithSimilarDocuments()
+        {
+            var query = new SimilarDocumentsQuery("143")
+            {
+                Embedder = "manual"
+            };
+
+            var movies = await _indexForVectorSearch.SearchSimilarDocumentsAsync<VectorMovie>(query);
+
+            Assert.Collection(movies.Hits,
+                m => Assert.Equal("Escape Room", m.Title),
+                m => Assert.Equal("Captain Marvel", m.Title),
+                m => Assert.Equal("How to Train Your Dragon: The Hidden World", m.Title),
+                m => Assert.Equal("Shazam!", m.Title)
+            );
+        }
     }
 }