IBX-9846: Describe Embeddings search API

[dabrt]

Question	Answer
JIRA Ticket	IBX-9846
Versions	4.6, 5.0
Edition	All

Describe Embeddings search API

Checklist

• Text renders correctly
• Text has been checked with vale
• Description metadata is up to date
• PHP code samples have been fixed with PHP CS fixer
• Added link to this PR in relevant JIRA ticket or code PR

[github-actions]

Preview of modified files

Preview of modified Markdown:

• docs/content_management/content_api/managing_content.md
• docs/release_notes/ez_platform_v3.1.md
• docs/search/embeddings_reference/embeddings_reference.md
• docs/search/search_api.md
• docs/search/search_criteria_and_sort_clauses.md
• docs/search/search_in_trash_reference.md

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[mikadamczyk]

Suggested change

	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.

[mikadamczyk]

Suggested change

	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.
	Provider/model configuration and vector compatibility are resolved at runtime by the configured embedding and search engine components.

[mikadamczyk]

Suggested change

	- [`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.

[mikadamczyk]

Suggested change

	Embedding providers generate vector representations for inputs.
	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".

[mikadamczyk]

Suggested change

	use Ibexa\Contracts\Core\Repository\Values\Content\EmbeddingQueryBuilder;
	use Ibexa\Contracts\Core\Repository\Values\Content\Query\Embedding;
	// Example embedding vector (float[])
	$vector = [
	0.0123,
	-0.9876,
	0.4567,
	// ...
	];
	// Create an Embedding instance with a float[] vector
	$embedding = new Embedding($vector);
	// Build the embedding query with the fluent builder
	$embeddingQuery = EmbeddingQueryBuilder::create()
	->withEmbedding($embedding)
	->setLimit(10) // maximum number of results
	->setOffset(0) // result offset for pagination
	->setPerformCount(true) // optionally count total matching items
	->build();
	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;
	$vector = [
	0.0123,
	-0.9876,
	0.4567,
	...
	];
	$embedding = new TaxonomyEmbedding($vector);
	$embeddingQuery = EmbeddingQueryBuilder::create()
	->withEmbedding($embedding)
	->setFilter(new ContentTypeIdentifier('article'))
	->setLimit(10)
	->setOffset(0)
	->setPerformCount(true)
	->build();

[mikadamczyk]

Suggested change

	$results = $repository->findContent($embeddingQuery);
	use Ibexa\Contracts\Core\Repository\Repository;
	use Ibexa\Contracts\Core\Repository\SearchService;
	use Ibexa\Contracts\Core\Repository\Values\Content\EmbeddingQueryBuilder;
	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) {
	// ...
	}
	}
	}