Implemented reviewer comments

Author: dabrt

docs/search/embeddings_reference/embeddings_reference.md

@@ -16,12 +16,17 @@ Embedding queries do not support criteria, Sort Clauses, facet builders, or spel
 
 ## Embedding
 
-- [`Ibexa\Contracts\Core\Repository\Values\Content\Query\Embedding`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-Content-Query-Embedding.html): Represents the semantic input used for similarity search.
-Depending on the embedding provider, it can encapsulate text or vector data
+- [`Ibexa\Contracts\Core\Repository\Values\Content\Query\Embedding`](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-Content-Query-Embedding.html): Represents the vector input used
+for similarity search.
+It stores embedding values as float arrays, while providers generate those vectors from text input
 
 ## Embedding providers
 
 Embedding providers generate vector representations for inputs.
+Out of the box, embedding search integration is provided for TaxonomyEmbedding.
+If you use a custom embedding value type, implement matching embedding
+visitors for your search engine (Solr/Elasticsearch).
+Otherwise, query execution may fail with "No visitor available".
 
 ### Provider contracts
 

docs/search/search_api.md

@@ -371,7 +371,9 @@ Instead of comparing keywords, the system compares vectors that represent the se
 
 !!! note "Taxonomy suggestions"
 
-    Embedding queries have been introduced primarily to support the [Taxonomy suggestions](taxonomy.md#taxonomy-suggestions) feature but you can use them in other scenarios.
+    Embedding queries have been introduced primarily to support the [Taxonomy suggestions](taxonomy.md#taxonomy-suggestions) feature, therefore embedding search integration is provided for `TaxonomyEmbedding`.
+    To use them in other scenarios that use a custom embedding value type, implement matching embedding
+visitors for your search engine.
 
 Searching with embeddings can be combined with filtering, which allows the semantic search results to be constrained by content type, location, permissions, or other criteria.
 
@@ -387,71 +389,99 @@ The following components are used to build and validate embedding-based queries:
 
 - [EmbeddingQueryBuilder](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-Content-EmbeddingQueryBuilder.html):
     A fluent builder for constructing `EmbeddingQuery` instances.
-    It enforces required parameters and integrates embedding queries with the search query pipeline
+    It helps construct queries consistently and integrates embedding queries with the search query pipeline, but you must still provide the required embedding value
 
 - [QueryValidatorInterface](/api/php_api/php_api_reference/classes/Ibexa-Contracts-Core-Repository-Values-Content-QueryValidatorInterface.html):
-    Validates embedding queries before they are passed to the search engine.
-    Implementations ensure that the embedding model exists and that vector dimensions match the configured embedding field
+    Validates embedding query structure before execution.
+    The provider/model configuration and vector compatibility are resolved at runtime by the configured embedding and search engine component
 
 ### Use embedding queries in search
 
 Embedding queries are executed through the search API in the same way as other search requests.
 You build an `EmbeddingQuery` instance by using a builder and pass it to the search service.
 Embedding queries can also be combined with filters to narrow down results, such as by content type, location, or permissions.
 
+This example shows a minimal embedding query executed directly through the search service:
+
 ``` php
+<?php
+
+declare(strict_types=1);
+
+use Ibexa\Contracts\Core\Repository\Repository;
 use Ibexa\Contracts\Core\Repository\Values\Content\EmbeddingQueryBuilder;
 use Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\ContentTypeIdentifier;
 use Ibexa\Contracts\Taxonomy\Search\Query\Value\TaxonomyEmbedding;
 
+/** @var Repository $repository */
+$searchService = $repository->getSearchService();
+
+// Example of a vector generated by an embedding provider
 $vector = [
-  0.0123,
-  -0.9876,
-  0.4567,
-  ...
+    0.0123,
+    -0.9876,
+    0.4567,
+    // ...
 ];
 
-$embedding = new TaxonomyEmbedding($vector);
+$query = EmbeddingQueryBuilder::create()
+    ->withEmbedding(new TaxonomyEmbedding($vector))
+    ->setFilter(new ContentTypeIdentifier('article'))
+    ->setLimit(10)
+    ->setOffset(0)
+    ->setPerformCount(true)
+    ->build();
+
+$result = $searchService->findContent($query);
+
+foreach ($result->searchHits as $hit) {
+    // Handle result
+}
+```
+
+This example shows how to encapsulate an embedding query inside a reusable service class:
+
+``` php
+<?php
+
+declare(strict_types=1);
 
-$embeddingQuery = EmbeddingQueryBuilder::create()
-  ->withEmbedding($embedding)
-  ->setFilter(new ContentTypeIdentifier('article'))
-  ->setLimit(10)
-  ->setOffset(0)
-  ->setPerformCount(true)
-  ->build();
+namespace App\Service;
 
-// Execute the query via the repository
 use Ibexa\Contracts\Core\Repository\Repository;
 use Ibexa\Contracts\Core\Repository\SearchService;
 use Ibexa\Contracts\Core\Repository\Values\Content\EmbeddingQueryBuilder;
+use Ibexa\Contracts\Core\Repository\Values\Content\Query\Criterion\ContentTypeIdentifier;
 use Ibexa\Contracts\Taxonomy\Search\Query\Value\TaxonomyEmbedding;
 
 final class ExampleService
-  {
-      private SearchService $searchService;
-
-      public function __construct(Repository $repository)
-      {
-          $this->searchService = $repository->getSearchService();
-      }
-
-      public function searchByEmbedding(array $vector): void
-      {
-          $query = EmbeddingQueryBuilder::create()
-              ->withEmbedding(new TaxonomyEmbedding($vector))
-              ->setLimit(10)
-              ->setOffset(0)
-              ->build();
-
-          $result = $this->searchService->findContent($query);
-
-          foreach ($result->searchHits as $hit) {
-              // ...
-          }
-      }
-  }
-
+{
+    private SearchService $searchService;
+
+    public function __construct(Repository $repository)
+    {
+        $this->searchService = $repository->getSearchService();
+    }
+
+    /**
+     * @param float[] $vector
+     */
+    public function searchByEmbedding(array $vector): void
+    {
+        $query = EmbeddingQueryBuilder::create()
+            ->withEmbedding(new TaxonomyEmbedding($vector))
+            ->setFilter(new ContentTypeIdentifier('article'))
+            ->setLimit(10)
+            ->setOffset(0)
+            ->build();
+
+        $result = $this->searchService->findContent($query);
+
+        foreach ($result->searchHits as $hit) {
+            // Handle result
+        }
+    }
+}
 ```
 
 The `EmbeddingQueryBuilder` ensures that the query is correctly configured before execution.