Skip to main content
Version: Next

Semantic Search (Experimental)

caution

This is an experimental feature, built on the experimental Embeddings feature. The request contract, behaviour and APIs may still change in breaking ways between releases.

Semantic search matches by meaning instead of by words. "british roadster" finds a Triumph TR 3 and a Jaguar XK140 even though neither text contains the phrase, and "red sports car" finds red sports cars by what the picture looks like, with no tagging involved.

Searching images for "red sports car"Searching images for "red sports car"Searching images for "red sports car"

It appears as an extra search mode next to Studio's existing full-text search. Which modes are offered depends on what is embedded:

SurfaceModes
AssetsFull text search, Smart search: Text, Smart search: Image
Data objectsFull text search, Smart search: Text
DocumentsFull text search only — documents carry no embeddings

The same modes are available in two places: the quick search dialog and the Search & Filter panel of any grid. See Search Modes.

Features​

  • Hybrid by construction. The semantic clause joins the same bool query as everything else, so column filters, full-text search and workspace permissions all still apply.
  • Available everywhere a listing is. Quick search, asset grids and data object grids, through one registered search mode rather than a separate screen.
  • Relevance you can see and cut. While a smart mode is applied the grid shows a Score column, and a score threshold hides weak matches — per request, or by a configured default per target.
  • Fails visibly, never silently. If the inference service cannot embed the query, the request fails with a translated, user-facing message instead of returning non-semantic results.
  • Scriptable. The same search is reachable as a column filter inside the ordinary grid request, and as a standalone endpoint.

Requirements​

  • Embeddings enabled, with a semantic_text_search usage for text search and an image_search usage for image search.
  • OpenSearch, or Elasticsearch where every asset and data object index was created on 8.12.1 or newer. Older Elasticsearch indices cannot combine a kNN clause with the workspace query, so the feature is switched off rather than returning wrong results.
  • The bptb_semantic_search_permission user permission, see User Permissions.

Where any of these is missing, the smart modes are simply not offered — there is nothing to switch off.

Configuration​

The candidate caps and the default score threshold per target are a separate configuration record, edited under System > Semantic Search Configuration (admin-only). The options, their defaults and the YAML override are documented in Embeddings Configuration.

Configuration API​

Admin-only (IsGranted admin), like the duplicates configuration:

MethodPathoperationId
GET/pimcore-studio/api/bundle/backend-power-tools/semantic-search-configuration/configurations/{configurationId}bundle_backend_power_tools_semantic_search_configuration_get
PUTsamebundle_backend_power_tools_semantic_search_configuration_update

configurationId is default_semantic_search. Response (BundleBackendPowerToolsSemanticSearchConfiguration):

{
"id": "default_semantic_search",
"isWriteable": true,
"candidateCap": 10000,
"globalSearchCandidateCap": 150,
"text": { "defaultMinScore": null, "builtInMinScore": 20, "usage": "semantic_text_search", "model": "nomic-text-v2", "queryModel": null },
"image": { "defaultMinScore": 12, "builtInMinScore": 8, "usage": "image_search", "model": "siglip2-vision", "queryModel": "siglip2-text" }
}
  • defaultMinScore is the configured value (null = the built-in default applies); builtInMinScore, usage, model and queryModel are read-only (model/query model of the usage in the embeddings config).
  • isWriteable is false when a YAML semantic_search node shadows the store or the write target is disabled (same rules as the embeddings configuration).
  • PUT body (BundleBackendPowerToolsUpdateSemanticSearchConfiguration): { "candidateCap"?: int, "globalSearchCandidateCap"?: int, "text"?: { "defaultMinScore": number|null }, "image"?: { "defaultMinScore": number|null } }. Merge-safe: an omitted member keeps its stored value, a sent target replaces its threshold, null clears it. defaultMinScore is required in a sent target: an empty or malformed target is a 422; omit the target to keep it. Returns the full configuration.
  • GET reports the values as applied at search time: the caps clamped to 1..10000, a stored threshold outside 0..100 as null. A PUT merges those sanitized values, so a hand-edited row does not fail it.
  • Status codes: 404 unknown configurationId; 422 out-of-range or non-finite values; not writeable (isWriteable false, including a YAML-shadowed record) → NotWriteableException, nothing is written.

Pages in this chapter​

  • Search Modes: the modes in Studio, what each one matches, and where they appear.
  • Grid and Search Filter: the bpt.semanticSearch column filter, result ordering, the relevance score column and threshold, and the behaviour when the inference service is down.
  • Global Endpoint: the standalone search endpoint, and the availability data the UI reads.