Skip to content
Componecat Docs

Search query reference

The catalog search box, saved searches, the REST q parameter, the GraphQL searchCatalog field, and the MCP search_catalog tool all take the same query syntax. The searching guide walks through it with examples; this page is the compact reference.

Syntax at a glance

Section titled “Syntax at a glance”
Form Meaning
payment gateway Bare words — search names, descriptions, tags, field values, and documentation
"payment gateway" A quoted phrase
field:value Field equals the value; field:~value contains it; field:!value doesn’t equal it
field:>=3, field:<now-90d Comparison on number and date fields
field:[a TO b] Inclusive range; * for an open end
field:null, field:* Field is absent / present
a AND b, a OR b, NOT a Booleans; a space means AND; -tag:x and !tag:x negate
( … ) Grouping
~"free text" Semantic clause — rank by meaning

Semantic clause

Section titled “Semantic clause”

A semantic clause ranks results by how close their meaning is to a piece of text, rather than by the words they share with it:

~"give money back to customers"
similar:"give money back to customers"
kind:component owner:payments ~"issues refunds"

~"…" and similar:"…" are the same clause; similar: also takes a single unquoted word (similar:refunds). A ~ that isn’t immediately followed by a quote is ordinary text.

How it combines with the rest of a query

Section titled “How it combines with the rest of a query”
  • Other clauses filter, the semantic clause ranks. kind:component ~"refunds" returns only components, ordered by how closely each one’s meaning matches “refunds”.
  • Bare words still filter, as they always do. When a query has both — refunds ~"money back to customers" — the results are ordered by blending two rankings, one by word match and one by meaning, with reciprocal-rank fusion: an entity that does well on both comes first, without either kind of score having to be weighed against the other.
  • An entity matches through its own name, description, tags, and fields or through any of its documentation sections, whichever is closer. When a section is what matched, the result shows it as the snippet.
  • The usual sort options still apply; relevance is the default.

Rules

Section titled “Rules”
  • One semantic clause per query.
  • It can’t be negated (NOT ~"…", -similar:…) or placed inside an OR — there would be nothing to rank the other branch by. Inside an AND group is fine.
  • It can’t be used in a dynamic collection query: a collection holds a filter, and the clause ranks. Saved searches can hold one.

Breaking a rule is a query error that points at the clause.

Scores and limits

Section titled “Scores and limits”

Each result carries a relevance — the cosine similarity between the clause text and the entity, from −1 to 1, higher meaning closer. The catalog page shows it as a percentage match. In the APIs it is relevance on each search result (GraphQL searchCatalog items, REST GET /catalog/search results); it is empty for a query without a semantic clause.

Three instance settings shape every semantic result, whichever model an organization uses:

Setting Default Effect
Embeddings__SearchMinSimilarity 0.3 Matches with a lower relevance are left out. What counts as “related” differs between embedding models, so this is worth revisiting after changing the model.
Embeddings__SearchMaxResults 100 The most entities one semantic query returns, nearest first (at most 500). The result count never exceeds it.
Embeddings__SearchQueryTimeoutSeconds 10 How long a search waits for the embedding model to read the clause text before giving up (1–120 seconds). Raise it for a self-hosted model that is slow to load on first use.

The clause text is read by the embedding model once and remembered for a few minutes, so changing the sort, adding a filter, or moving to the next page of the same search doesn’t ask the model again. Clause text longer than the model’s input limit (Embeddings__MaxInputCharacters) is cut to fit.

More like this

Section titled “More like this”

The GraphQL similarEntities(entityId, limit) query returns the entities closest in meaning to a given entity, never including the entity itself, under the same threshold and limit. See APIs. An entity’s page shows the same list as Similar entities.

Documentation by meaning

Section titled “Documentation by meaning”

The GraphQL relevantDocumentation(text, entityId, limit) query returns the documentation sections closest in meaning to a question — across the catalog, or within one entity — each with the entity it documents. See APIs.

For AI agents

Section titled “For AI agents”

The MCP search_catalog tool accepts the semantic clause like any other query. When the agent’s organization has search by meaning, the MCP server also offers find_relevant_entities and find_relevant_documentation, which take a plain-language description directly; without it, those two tools are not offered. See Connect AI agents.

Turning on search by meaning

Section titled “Turning on search by meaning”

Search by meaning works per organization. On the hosted app it is part of the Pro and Enterprise plans (see Plans and limits); on a plan without it, nothing below turns it on, and the AI Models page says which plan includes it. A self-hosted instance has no plans, so there it depends only on the model. With the plan, it is on when the organization has an embedding model, which comes from one of two places:

  • The organization’s own model. An organization admin opens Organization settings → AI Models, adds a model, sets its Kind to Embedding, and fills in the provider, model, vector size (Dimensions) and the provider’s endpoint or key. For a server that speaks the OpenAI API (a proxy, a gateway, or a self-hosted OpenAI-compatible server), pick the OpenAI provider and set its Endpoint; leave it blank for OpenAI’s own service. Dimensions must be a whole number above 0 and must match what the model returns — Test connection checks it. Above 2000 the form warns: such a model works, but its vectors cannot be indexed, so search by meaning is slower on large catalogs. If the organization has several embedding models, the one marked default is used. Removing that mark (or deleting or disabling the default) asks for confirmation first: the first enabled embedding model by name takes over, or the instance’s model if the organization has none left. The default chat model is set separately and never used for search. The catalog text is then read by that model, under that provider account.
  • A model for every organization. Whoever runs your Componecat can configure one under AIModels:Instances with Kind: Embedding — for example AIModels__Instances__embeddings__Kind=Embedding with __Provider, __ModelId, __Dimensions, __IsDefault=true and the provider’s __Properties__endpoint or __Secrets__apiKey. An organization that adds its own model uses that instead.

After a model is added or changed, the catalog and its documentation are read by the new model in the background; until that finishes, search by meaning returns fewer results or none. Changing the model again, its vector size, or its settings starts the same re-read. Removing the organization’s model falls back to the instance’s, if there is one.

When it isn’t available

Section titled “When it isn’t available”

Semantic search needs an embedding model for your organization. Without one, a query with a semantic clause doesn’t quietly fall back to something else — it fails with a message saying how to add one: in Organization settings → AI Models, or under AIModels:Instances for every organization. The error code is SEMANTIC_SEARCH_UNAVAILABLE in GraphQL (and on similarEntities and relevantDocumentation) and SemanticSearchUnavailable in the REST problem response. The GraphQL semanticSearchAvailable field answers true or false up front for the caller’s organization; the app uses it to leave every search-by-meaning control out for an organization without a model.

If the embedding model is set up but doesn’t answer — it is down, rate-limiting your instance, or slower than Embeddings__SearchQueryTimeoutSeconds — the search fails with a message saying so rather than an unexpected error. The code is SEMANTIC_SEARCH_FAILED in GraphQL and SemanticSearchFailed in REST, where the response status is 503 so clients know to retry. The same query usually works once the provider recovers.

New and edited entities are embedded in the background shortly after they change, so something saved a moment ago may not match by meaning yet.

Section titled “Related”