Skip to content
Nappai Documentation

SelfQueryRetriever

SelfQueryRetriever lets you ask a question in plain language and automatically turns that question into a search query that looks up the most relevant documents in your vector store. It can also create a structured tool that other parts of your workflow can call to perform the same search.

How it Works

  1. Input – You give the component a Search Query (the question you want answered) and optionally set how many results you want, what type of search to use, and any metadata schema that describes the documents in your vector store.
  2. LLM Query Generation – The component uses the Language Model you provide to rewrite the plain‑text query into a form that the vector store can understand. This step is called self‑query because the LLM generates the query itself.
  3. Vector Store Search – The rewritten query is sent to the vector store. Depending on the Search Type you chose, the store will return the most similar documents, documents above a similarity threshold, or a mix‑and‑match result.
  4. Output – The component returns the raw documents as Search Results, a retriever object that can be reused, and a structured Tool that other components can call.

The component works entirely inside Nappai; it does not call any external APIs beyond the LLM and the vector store you already have set up.

Inputs

  • Model: Language Model to be passed as input.
  • Parent document vectorstore: Parent document vectorstore
  • Disable Streaming: Disable streaming for the LLM.
  • Document Content Description: Document content description to be passed as input.
  • Metadata Schema: Metadata schema to use for the SelfQueryRetriever.
  • Number of Results: Number of results to return.
  • Query Key Description: Description of the key to use for query parameter.
  • Query Key Name: Name of the key to use for query parameter.
  • Search Query: The text you want to search for.
  • Search Score Threshold: Minimum similarity score threshold for search results. (when using ‘Similarity with score threshold’)
  • Search Type: Type of search to perform. Can be ‘similarity’, ‘similarity_score_threshold’ or ‘mmr’.
  • Tool Description: Tool description to be used for the SelfQueryRetriever.
  • Tool Name: Tool name to be used for the SelfQueryRetriever.

Outputs

  • Retriever: A retriever object that can be reused in other parts of your workflow. It contains the LLM and vector store configuration.
  • Search Results: A list of documents that match the query. Each document is returned as a Data object that can be passed to other components.
  • Tool: A structured tool that can be called by other components or by the LLM to perform the same search automatically.

Usage Example

  1. Add the component to your dashboard and connect a Language Model and a Vector Store to the Model and Parent document vectorstore inputs.
  2. Set the Search Query to something like “What are the latest trends in renewable energy?”.
  3. Choose a Search Type – for most cases, “similarity” is fine. If you want to filter out low‑confidence results, pick “similarity_score_threshold” and set a threshold such as 0.7.
  4. Run the component.
    • The Search Results output will show the top documents that answer your question.
    • The Retriever can be reused elsewhere.
    • The Tool can be added to a larger workflow so that the LLM can call it automatically when it needs to fetch information.
  • SelfQueryRetrieverTool – A helper that builds a tool from the retriever, useful when you want the LLM to call the search directly.
  • VectorStore – The component that stores your documents in a vector format.
  • LanguageModel – The LLM that generates the search query.

Tips and Best Practices

  • Keep the Metadata Schema up to date; it tells the retriever what fields to look for in each document.
  • If you only need a few documents, set Number of Results to a small number to speed up the search.
  • Use Disable Streaming when you want a single response instead of a stream of partial results.
  • For highly specific queries, try “similarity_score_threshold” with a higher threshold to avoid noisy results.
  • Test the component with a few sample queries before adding it to a production workflow.

Security Considerations

  • The component sends your query to the Language Model you provide. Make sure the model’s privacy settings match your data‑handling policies.
  • The vector store holds your documents; ensure it is stored in a secure, access‑controlled environment.
  • If you expose the Tool to external users, consider adding authentication or rate‑limiting to prevent abuse.