Merge #643

643: Changes related to the next Meilisearch release (v1.9.0) r=curquiza a=meili-bot

Related to this issue: meilisearch/integration-guides#301

This PR:
- gathers the changes related to the next Meilisearch release (v1.9.0) so that this package is ready when the official release is out.
- should pass the tests against the [latest pre-release of Meilisearch](https://github.com/meilisearch/meilisearch/releases).
- might eventually contain test failures until the Meilisearch v1.9.0 is out.

⚠️ This PR should NOT be merged until the next release of Meilisearch (v1.9.0) is out.

_This PR is auto-generated for the [pre-release week](https://github.com/meilisearch/integration-guides/blob/main/resources/pre-release-week.md) purpose._


Co-authored-by: meili-bot <74670311+meili-bot@users.noreply.github.com>
Co-authored-by: Shalabh Agarwal <34604329+the-sinner@users.noreply.github.com>
Co-authored-by: Many the fish <many@meilisearch.com>
Co-authored-by: curquiza <clementine@meilisearch.com>
Co-authored-by: Clémentine <clementine@meilisearch.com>

.code-samples.meilisearch.yaml

@@ -718,3 +718,29 @@ negative_search_1: |-
   $client->index('movies')->search('-escape');
 negative_search_2: |-
   $client->index('movies')->search('-"escape"');
+search_parameter_reference_retrieve_vectors_1: |-
+  $client->index('INDEX_NAME')->search('kitchen utensils', [
+    'retrieveVectors' => true,
+    'hybrid' => [
+      'embedder': 'default'
+    ]
+  ]);
+search_parameter_reference_ranking_score_threshold_1: |-
+  $client->index('INDEX_NAME')->search('badman', [
+    'rankingScoreThreshold' => 0.2
+  ]);
+search_parameter_reference_distinct_1: |-
+  $client->index('INDEX_NAME')->search('QUERY TERMS', [
+    'distinct' => 'ATTRIBUTE_A'
+  ]);
+distinct_attribute_guide_filterable_1: |-
+  $client->index('products')->updateFilterableAttributes(['product_id', 'sku', 'url']);
+distinct_attribute_guide_distinct_parameter_1: |-
+  $client->index('products')->search('white shirt', [
+    'distinct' => 'sku'
+  ]);
+search_parameter_guide_matching_strategy_3: |-
+  $client->index('movies')->search('white shirt', ['matchingStrategy' => 'frequency']);
+get_similar_post_1: |-
+  $similarQuery = new SimilarDocumentsQuery('TARGET_DOCUMENT_ID');
+  $client->index('INDEX_NAME')->getSimilar($similarQuery);

src/Contracts/DocumentsQuery.php

@@ -10,6 +10,7 @@ class DocumentsQuery
     private int $limit;
     private array $fields;
     private array $filter;
+    private ?bool $retrieveVectors = null;
 
     public function setOffset(int $offset): DocumentsQuery
     {
@@ -46,6 +47,16 @@ public function setFilter(array $filter): DocumentsQuery
         return $this;
     }
 
+    /**
+     * @param bool|null $retrieveVectors boolean value to show _vector details
+     */
+    public function setRetrieveVectors(?bool $retrieveVectors): DocumentsQuery
+    {
+        $this->retrieveVectors = $retrieveVectors;
+
+        return $this;
+    }
+
     /**
      * Checks if the $filter attribute has been set.
      *
@@ -84,6 +95,7 @@ public function toArray(): array
             'limit' => $this->limit ?? null,
             'filter' => $this->filter ?? null,
             'fields' => $this->fields(),
-        ], function ($item) { return null != $item || is_numeric($item); });
+            'retrieveVectors' => (null !== $this->retrieveVectors ? ($this->retrieveVectors ? 'true' : 'false') : null),
+        ], function ($item) { return null !== $item; });
     }
 }

src/Contracts/SearchQuery.php

@@ -29,6 +29,8 @@ class SearchQuery
     private ?array $attributesToSearchOn = null;
     private ?bool $showRankingScore = null;
     private ?bool $showRankingScoreDetails = null;
+    private ?float $rankingScoreThreshold = null;
+    private ?string $distinct = null;
 
     public function setQuery(string $q): SearchQuery
     {
@@ -130,6 +132,23 @@ public function setShowRankingScoreDetails(?bool $showRankingScoreDetails): Sear
         return $this;
     }
 
+    public function setRankingScoreThreshold(?float $rankingScoreThreshold): SearchQuery
+    {
+        $this->rankingScoreThreshold = $rankingScoreThreshold;
+
+        return $this;
+    }
+
+    /**
+     * @param non-empty-string|null $distinct
+     */
+    public function setDistinct(?string $distinct): SearchQuery
+    {
+        $this->distinct = $distinct;
+
+        return $this;
+    }
+
     public function setSort(array $sort): SearchQuery
     {
         $this->sort = $sort;
@@ -230,6 +249,8 @@ public function toArray(): array
             'attributesToSearchOn' => $this->attributesToSearchOn,
             'showRankingScore' => $this->showRankingScore,
             'showRankingScoreDetails' => $this->showRankingScoreDetails,
+            'rankingScoreThreshold' => $this->rankingScoreThreshold,
+            'distinct' => $this->distinct,
         ], function ($item) { return null !== $item; });
     }
 }

src/Contracts/SimilarDocumentsQuery.php

@@ -0,0 +1,129 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Meilisearch\Contracts;
+
+class SimilarDocumentsQuery
+{
+    /**
+     * @var int|string
+     */
+    private $id;
+    private ?int $offset = null;
+    private ?int $limit = null;
+    private ?string $embedder = null;
+    private ?array $attributesToRetrieve = null;
+    private ?bool $showRankingScore = null;
+    private ?bool $showRankingScoreDetails = null;
+    private ?bool $retrieveVectors = null;
+    private ?array $filter = null;
+
+    /**
+     * @param int|string $id
+     */
+    public function __construct($id)
+    {
+        $this->id = $id;
+    }
+
+    /**
+     * @param non-negative-int $offset
+     */
+    public function setOffset(?int $offset): SimilarDocumentsQuery
+    {
+        $this->offset = $offset;
+
+        return $this;
+    }
+
+    /**
+     * @param positive-int $limit
+     */
+    public function setLimit(?int $limit): SimilarDocumentsQuery
+    {
+        $this->limit = $limit;
+
+        return $this;
+    }
+
+    /**
+     * @param array<int, array<int, string>|string> $filter an array of arrays representing filter conditions
+     */
+    public function setFilter(array $filter): SimilarDocumentsQuery
+    {
+        $this->filter = $filter;
+
+        return $this;
+    }
+
+    /**
+     * @param non-empty-string $embedder
+     */
+    public function setEmbedder(string $embedder): SimilarDocumentsQuery
+    {
+        $this->embedder = $embedder;
+
+        return $this;
+    }
+
+    /**
+     * @param list<non-empty-string> $attributesToRetrieve an array of attribute names to retrieve
+     */
+    public function setAttributesToRetrieve(array $attributesToRetrieve): SimilarDocumentsQuery
+    {
+        $this->attributesToRetrieve = $attributesToRetrieve;
+
+        return $this;
+    }
+
+    /**
+     * @param bool|null $showRankingScore boolean value to show ranking score
+     */
+    public function setShowRankingScore(?bool $showRankingScore): SimilarDocumentsQuery
+    {
+        $this->showRankingScore = $showRankingScore;
+
+        return $this;
+    }
+
+    /**
+     * @param bool|null $showRankingScoreDetails boolean value to show ranking score details
+     */
+    public function setShowRankingScoreDetails(?bool $showRankingScoreDetails): SimilarDocumentsQuery
+    {
+        $this->showRankingScoreDetails = $showRankingScoreDetails;
+
+        return $this;
+    }
+
+    /**
+     * @param bool|null $retrieveVectors boolean value to show _vector details
+     */
+    public function setRetrieveVectors(?bool $retrieveVectors): SimilarDocumentsQuery
+    {
+        $this->retrieveVectors = $retrieveVectors;
+
+        return $this;
+    }
+
+    /**
+     * @return array{id: int|string, offset: non-negative-int, limit: positive-int, filter: array<int, array<int, string>|string>, embedder: non-empty-string, attributesToRetrieve: list<non-empty-string>, showRankingScore: bool, showRankingScoreDetails: bool, retrieveVectors: bool} SimilarDocumentsQuery converted to an array with non null fields
+     */
+    public function toArray(): array
+    {
+        return array_filter([
+            'id' => $this->id,
+            'offset' => $this->offset,
+            'limit' => $this->limit,
+            'filter' => $this->filter,
+            'embedder' => $this->embedder,
+            'attributesToRetrieve' => $this->attributesToRetrieve,
+            'showRankingScore' => $this->showRankingScore,
+            'showRankingScoreDetails' => $this->showRankingScoreDetails,
+            'retrieveVectors' => $this->retrieveVectors,
+        ], function ($item) {
+            return null !== $item;
+        });
+    }
+}

src/Endpoints/Indexes.php

@@ -10,6 +10,7 @@
 use Meilisearch\Contracts\Index\Settings;
 use Meilisearch\Contracts\IndexesQuery;
 use Meilisearch\Contracts\IndexesResults;
+use Meilisearch\Contracts\SimilarDocumentsQuery;
 use Meilisearch\Contracts\TasksQuery;
 use Meilisearch\Contracts\TasksResults;
 use Meilisearch\Endpoints\Delegates\HandlesDocuments;
@@ -18,6 +19,7 @@
 use Meilisearch\Exceptions\ApiException;
 use Meilisearch\Search\FacetSearchResult;
 use Meilisearch\Search\SearchResult;
+use Meilisearch\Search\SimilarDocumentsSearchResult;
 
 class Indexes extends Endpoint
 {
@@ -213,6 +215,13 @@ public function rawSearch(?string $query, array $searchParams = []): array
         return $result;
     }
 
+    public function searchSimilarDocuments(SimilarDocumentsQuery $parameters): SimilarDocumentsSearchResult
+    {
+        $result = $this->http->post(self::PATH.'/'.$this->uid.'/similar', $parameters->toArray());
+
+        return new SimilarDocumentsSearchResult($result);
+    }
+
     // Facet Search
 
     public function facetSearch(FacetSearchQuery $params): FacetSearchResult

src/Search/SimilarDocumentsSearchResult.php

@@ -0,0 +1,110 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Meilisearch\Search;
+
+class SimilarDocumentsSearchResult implements \Countable, \IteratorAggregate
+{
+    /**
+     * @var array<int, array<string, mixed>>
+     */
+    private array $hits;
+
+    /**
+     * `estimatedTotalHits` is the attributes returned by the Meilisearch server
+     * and its value will not be modified by the methods in this class.
+     * Please, use `hitsCount` if you want to know the real size of the `hits` array at any time.
+     */
+    private int $estimatedTotalHits;
+    private int $hitsCount;
+    private int $offset;
+    private int $limit;
+    private int $processingTimeMs;
+    private string $id;
+
+    public function __construct(array $body)
+    {
+        $this->id = $body['id'];
+        $this->hits = $body['hits'];
+        $this->hitsCount = \count($body['hits']);
+        $this->processingTimeMs = $body['processingTimeMs'];
+        $this->offset = $body['offset'];
+        $this->limit = $body['limit'];
+        $this->estimatedTotalHits = $body['estimatedTotalHits'];
+    }
+
+    /**
+     * @return array<string, mixed>|null
+     */
+    public function getHit(int $key): ?array
+    {
+        return $this->hits[$key];
+    }
+
+    /**
+     * @return array<int, array<string, mixed>>
+     */
+    public function getHits(): array
+    {
+        return $this->hits;
+    }
+
+    public function getOffset(): int
+    {
+        return $this->offset;
+    }
+
+    public function getLimit(): int
+    {
+        return $this->limit;
+    }
+
+    public function getEstimatedTotalHits(): int
+    {
+        return $this->estimatedTotalHits;
+    }
+
+    public function getProcessingTimeMs(): int
+    {
+        return $this->processingTimeMs;
+    }
+
+    public function getId(): string
+    {
+        return $this->id;
+    }
+
+    public function getHitsCount(): int
+    {
+        return $this->hitsCount;
+    }
+
+    /**
+     * Converts the SimilarDocumentsSearchResult to an array representation.
+     *
+     * @return array<string, mixed>
+     */
+    public function toArray(): array
+    {
+        return [
+            'id' => $this->id,
+            'hits' => $this->hits,
+            'hitsCount' => $this->hitsCount,
+            'processingTimeMs' => $this->processingTimeMs,
+            'offset' => $this->offset,
+            'limit' => $this->limit,
+            'estimatedTotalHits' => $this->estimatedTotalHits,
+        ];
+    }
+
+    public function getIterator(): \ArrayIterator
+    {
+        return new \ArrayIterator($this->hits);
+    }
+
+    public function count(): int
+    {
+        return $this->hitsCount;
+    }
+}