Self Query Retriever

Self Query Retriever asks a model to read the question and turn it into a search with filters. For example, “what does error E07 mean on the Vellani?” becomes a search for “error E07” filtered by brand equal to Vellani, as long as your documents carry that data.

A retriever receives a question and returns the document pieces that best answer it, so an agent or model can reply with your information.

When to use it

Your documents have data such as brand, month, city, price or category, and questions mention them.
You want an agent to filter results without anyone writing the filters.

Configuration

Field	What it does
Search Query	The question.
Metadata Schema	The document data the model can filter on: name, type and what each field means. It is the same schema as Metadata Tagger, so you can paste it as it is.
Document Content Description	A sentence describing what the documents contain, for example “technical manuals and monthly incident reports”.
Tool Name	The name of the Tool output for the agent. Empty: `search_documents_with_filters`.
Tool Description	What the agent reads to know when to use the tool. Empty: a generic description.
Vector Store	The Vector Store output of the database to search. It works with FAISS, Chroma DB, Qdrant, PGVector, Neo4j and other databases with filters.
Model	The model that writes the search and its filter.

Advanced options

Field	What it does
Number of Results	How many documents are returned. Default: 20.
Search Type	`similarity` (default), `similarity_score_threshold` (only results above Search Score Threshold) or `mmr` (close to the question but different from each other).
Search Score Threshold	Minimum score with `similarity_score_threshold`. Default: 0.1.
Query Key Name	Together with Query Key Description: the name and description of the question argument of the Tool output. Default: `query`.
Disable Streaming	Asks the model for its whole answer at once, which the search needs. On by default.

Allowed values

If a field only takes some values, list them so the model writes them exactly as they are stored. Either in the description (“Brand: Jaltec, Vellani or Molinar”) or under enum:

[
  {"name": "brand", "type": "string", "description": "Brand of the machine", "enum": ["Jaltec", "Vellani", "Molinar"]},
  {"name": "mes", "type": "string", "description": "Month of the report, YYYY-MM"}
]

A field of type array (several values per document, as Metadata Tagger writes it) matches when any of its values does.

When the filter does not work out

The component never fails because of the filter; it searches without it and says so in the run’s log:

If the model’s answer cannot be read as a search, it searches the question as written.
If the database cannot apply the filter (for example a range on a text field in Qdrant), it searches without the filter.
If nothing matches the filter (a value written differently from how it is stored), it searches again without it.

Output

Retriever: the search engine, to connect to components that ask for one, such as Local Rerank or another in this family.
Search Results: the pieces found for Search Query, which you can pass to a prompt or an agent. Each run’s log shows the search the model wrote and its filter, for example marca = "Vellani".
Tool: the retriever as a tool, to connect to an agent’s Tools. The agent writes the question and, when it knows them, the value of each field of the schema.

Example

A coffee machine repair service keeps its manuals and monthly reports with the data brand, type (document type) and month (month).

Connect the Vector Store output of its database to Vector Store and a model to Model.
Paste the schema in Metadata Schema and type “technical manuals, warranty policy and monthly incident reports” in Document Content Description.
Connect the Tool output to the support agent’s Tools.

When a technician asks “what does E07 mean on the Vellani?”, the log shows the search error E07 with the filter marca = "Vellani", and only Vellani documents come back.

Measured figures

Measured on 17 October 2026 on a test knowledge base (9 documents of a fictional repair service, 40 questions; DeepSeek as the model). It is a single synthetic set: it shows how the technique behaves, not a promise for your data.

On questions that needed a filter by brand, month or document type, the right result was in the top 5 in 83 % of cases, against 33 % without a filter. The same with Qdrant and with FAISS.
On the other questions it did as well as plain search.
One model call per question: about 1 second.

Good practices

List the allowed values of each field: the model writes filters that match what is stored.
If the data is inside the text and not in the document, tag it first with Metadata Tagger, using the same schema. A field that can hold several values (the error codes of a paragraph) should be of type array.

Video

This video shows how Self Query Retriever turns a question about a brand and a month into a filter, and finds what plain search misses.

What you see in the video:

In the ingestion flow, the Metadata Tagger schema with each chunk’s data: brand, document type, month and codes.
Self Query Retriever over Qdrant, with the same schema in Metadata Schema and the allowed values of each field.
Asked “Which incidents did the Vellani machines have in July?”, the model writes the filter and(eq("brand", "Vellani"), eq("month", "2026-07")).
With that filter, the two July Vellani chunks come back, with all three incidents: Cafetería Triana, Cervecería Macarena and Cafetería San Bernardo.
Plain search misses some of them.

Metadata Tagger: tags the pieces with the data to filter by.
FAISS: a vector database without a server that this retriever can filter.

To see when filtering pays off, see Search techniques in the RAG guide.