Self Query Retriever

Self Query Retriever pide a un modelo que lea la pregunta y la convierta en una búsqueda con filtros. Por ejemplo, «¿qué significa el error E07 en la Vellani?» se convierte en una búsqueda de «error E07» filtrada por marca igual a Vellani, siempre que tus documentos tengan ese dato.

Un buscador (retriever) recibe una pregunta y devuelve los fragmentos de documentos que mejor la responden, para que un agente o un modelo conteste con tu información.

Cuándo usarlo

Tus documentos tienen datos como marca, mes, ciudad, precio o categoría y las preguntas los mencionan.
Quieres que un agente filtre los resultados sin que nadie escriba los filtros.

Configuración

Campo	Qué hace
Search Query	La pregunta.
Metadata Schema	Los datos de los documentos por los que el modelo puede filtrar: nombre, tipo y qué significa cada campo. Es el mismo esquema que el de Metadata Tagger, así que puedes pegarlo tal cual.
Document Content Description	Una frase que describe qué contienen los documentos, por ejemplo «manuales técnicos e informes mensuales de incidencias».
Tool Name	El nombre de la salida Tool para el agente. Vacío: `search_documents_with_filters`.
Tool Description	Lo que lee el agente para saber cuándo usar la herramienta. Vacío: una descripción genérica.
Vector Store	La salida Vector Store de la base en la que buscar. Funciona con FAISS, Chroma DB, Qdrant, PGVector, Neo4j y otras bases con filtros.
Model	El modelo que escribe la búsqueda y su filtro.

Opciones avanzadas

Campo	Qué hace
Number of Results	Cuántos documentos devuelve. Por defecto, 20.
Search Type	`similarity` (por defecto), `similarity_score_threshold` (solo los resultados por encima de Search Score Threshold) o `mmr` (cercanos a la pregunta pero distintos entre sí).
Search Score Threshold	Puntuación mínima con `similarity_score_threshold`. Por defecto, 0,1.
Query Key Name	Junto con Query Key Description: el nombre y la descripción del argumento con la pregunta de la salida Tool. Por defecto, `query`.
Disable Streaming	Pide al modelo la respuesta completa de una vez, que es lo que necesita la búsqueda. Activado por defecto.

Valores permitidos

Si un campo solo admite algunos valores, enuméralos para que el modelo los escriba tal y como están guardados. En la descripción («Marca: Jaltec, Vellani o Molinar») o en enum:

[
  {"name": "marca", "type": "string", "description": "Marca de la máquina", "enum": ["Jaltec", "Vellani", "Molinar"]},
  {"name": "mes", "type": "string", "description": "Mes del informe, YYYY-MM"}
]

Un campo de tipo array (varios valores por documento, como lo escribe Metadata Tagger) coincide cuando coincide cualquiera de sus valores.

Cuando el filtro no sale bien

El componente nunca falla por el filtro: busca sin él y lo dice en el registro de la ejecución.

Si la respuesta del modelo no se puede leer como una búsqueda, busca la pregunta tal cual.
Si la base no puede aplicar el filtro (por ejemplo, un rango sobre un campo de texto en Qdrant), busca sin filtro.
Si nada cumple el filtro (un valor escrito distinto de como está guardado), vuelve a buscar sin él.

Resultado

Retriever: el buscador, para conectarlo a componentes que piden un buscador, como Local Rerank u otro de esta familia.
Search Results: los fragmentos encontrados para Search Query, que puedes pasar a un prompt o a un agente. El registro de cada ejecución muestra la búsqueda que escribió el modelo y su filtro, por ejemplo marca = "Vellani".
Tool: el buscador como herramienta, para conectarlo a Tools de un agente. El agente escribe la pregunta y, cuando los conoce, el valor de cada campo del esquema.

Ejemplo

Un servicio técnico de cafeteras guarda sus manuales e informes mensuales con los datos marca, tipo (tipo de documento) y mes.

Conecta la salida Vector Store de su base a Vector Store y un modelo a Model.
Pega el esquema en Metadata Schema y escribe «manuales técnicos, política de garantía e informes mensuales de incidencias» en Document Content Description.
Conecta la salida Tool a Tools del agente de soporte.

Cuando un técnico pregunta «¿qué significa el E07 en la Vellani?», el registro muestra la búsqueda error E07 con el filtro marca = "Vellani" y solo vuelven documentos de Vellani.

Cifras medidas

Medido el 17 de octubre de 2026 sobre una base de conocimiento de prueba (9 documentos de un servicio técnico ficticio, 40 preguntas; DeepSeek como modelo). Es un único conjunto sintético: muestra cómo se comporta la técnica, no una promesa para tus datos.

En las preguntas que necesitaban filtrar por marca, mes o tipo de documento, el resultado correcto estuvo entre los 5 primeros en el 83 % de los casos, frente al 33 % sin filtro. Igual con Qdrant que con FAISS.
En el resto de preguntas acertó lo mismo que la búsqueda normal.
Una llamada al modelo por pregunta: alrededor de 1 segundo.

Buenas prácticas

Enumera los valores permitidos de cada campo: el modelo escribirá filtros que coinciden con lo guardado.
Si el dato está dentro del texto y no en el documento, etiquétalo antes con Metadata Tagger usando el mismo esquema. Un campo que puede tener varios valores (los códigos de error de un párrafo) debe ser de tipo array.

Vídeo

Este vídeo muestra cómo Self Query Retriever convierte una pregunta por marca y mes en un filtro, y encuentra lo que la búsqueda normal se deja.

Lo que ves en el vídeo:

En el flujo de ingesta, el esquema de Metadata Tagger con los datos de cada fragmento: marca, tipo de documento, mes y códigos.
Self Query Retriever sobre Qdrant, con el mismo esquema en Metadata Schema y los valores permitidos de cada campo.
A «¿Qué incidencias tuvieron las Vellani en julio?», el modelo escribe el filtro and(eq("marca", "Vellani"), eq("mes", "2026-07")).
Con ese filtro vuelven los dos fragmentos de julio de Vellani, con las tres incidencias: Cafetería Triana, Cervecería Macarena y Cafetería San Bernardo.
La búsqueda sin filtro se deja alguna de ellas.

Componentes relacionados

Metadata Tagger: etiqueta los fragmentos con los datos por los que filtrar.
FAISS: una base vectorial sin servidor que este buscador puede filtrar.

Para ver cuándo compensa filtrar, consulta Técnicas de búsqueda en la guía de RAG.