Skip to main content
Version: Next

Semantic Search in Studio (Experimental)

caution

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

The bundle adds semantic (kNN) search to Studio's existing grid and search endpoints. A bpt.semanticSearch column filter travels inside the regular request body; a tagged Studio filter reads it and pushes the bundle's kNN search modifier onto the query. Because the kNN clause joins the same bool query as every other filter, semantic search is hybrid by construction: classic column filters, full-text search and workspace permissions all still apply.

Engine support is capability-gated. OpenSearch is always supported. Elasticsearch is supported from 8.12.2.

Covered endpoints (all POST):

  • /pimcore-studio/api/assets/grid
  • /pimcore-studio/api/data-objects/grid/{classId}
  • /pimcore-studio/api/search/assets
  • /pimcore-studio/api/search/data-objects

Request contract​

Add an entry to the ordinary filters.columnFilters array:

"filters": {
    "columnFilters": [
        {
            "key": "semanticSearch",
            "type": "bpt.semanticSearch",
            "filterValue": { "query": "red sports car", "orderByRelevance": true }
        }
    ]
}
  • query — the natural-language search text. Truncated at 1000 characters before embedding. A bare string filterValue is accepted as shorthand for { "query": ... }.
  • orderByRelevance — default true: the sort list is cleared so the engine orders by _score. Send false when the user explicitly picked a column sort.

Asset queries search the image_search usage; data object queries search semantic_text_search. Both are combined freely with other filters — e.g. a system.fulltext filter plus the semantic filter returns the intersection, relevance-ordered.

Result-set semantics​

  • With orderByRelevance: true the sort list is cleared — the engine defaults to _score descending, and GDI's OrderByPageNumber handler early-returns (no page inversion, no count round-trip). With orderByRelevance: false the explicit column sort is preserved and the set is still k-bounded; note that a non-empty sort list makes OrderByPageNumber issue a _count request that includes the kNN clause.

Degrade behaviour​

If the inference service cannot embed the query (outage, timeout), the semantic clause is silently skipped, and the request returns plain (non-semantic) results; the server logs Semantic search degraded: query embedding unavailable, clause skipped. at warning level. Query embeddings are cached for 24h, so a repeated query may keep working through a short outage.