DDGSWebSearch

Search the web using the free, keyless ddgs metasearch library and return results as Haystack Documents.

Key Features

• Uses ddgs, a free and keyless metasearch library that aggregates results from multiple backends (DuckDuckGo, Google, Bing, Brave, Yahoo, Yandex, Mullvad, and more).
• Requires no API key — you can start searching immediately.
• Configurable search backend, region, and safe-search level.
• Supports per-run overrides for top_k, backend, region, and safesearch.

Configuration

1. Drag the DDGSWebSearch component onto the canvas from the Component Library.
2. Click on the component to open the configuration panel.
3. On the General tab:
   1. Set top_k to control the maximum number of results (default: 10).
   2. Optionally set backend to specify which search backends to use (for example, "duckduckgo, google, brave"), or leave it as "auto" to let the library choose.
   3. Optionally set region (for example, "us-en") and safesearch ("on", "moderate", or "off").

Connections

DDGSWebSearch receives a query string and returns a list of Document objects and a list of URLs. Connect its documents output to downstream components such as PromptBuilder for retrieval-augmented generation.

Source Code

To check this component's source code, open ddgs_websearch.py in the Haystack Core Integrations repository.

Usage Examples

Basic Configuration

  DDGSWebSearch:
    type: haystack_integrations.components.websearch.ddgs.ddgs_websearch.DDGSWebSearch
    init_parameters:
      top_k: 5
      backend: auto
      region: us-en
      safesearch: moderate

Using the Component in a Pipeline

# haystack-pipeline
components:
  websearch:
    type: haystack_integrations.components.websearch.ddgs.ddgs_websearch.DDGSWebSearch
    init_parameters:
      top_k: 5

  prompt_builder:
    type: haystack.components.builders.chat_prompt_builder.ChatPromptBuilder
    init_parameters:
      required_variables: "*"
      template:
      - role: user
        content: |
          Answer the question using the following search results:
          {% for doc in documents %}
          {{ doc.content }}
          {% endfor %}
          Question: {{ question }}

  llm:
    type: haystack.components.generators.chat.openai.OpenAIChatGenerator
    init_parameters:
      api_key:
        type: env_var
        env_vars:
        - OPENAI_API_KEY
        strict: false
      model: gpt-4o-mini

connections:
- sender: websearch.documents
  receiver: prompt_builder.documents
- sender: prompt_builder.prompt
  receiver: llm.messages

max_runs_per_component: 100

metadata: {}

inputs:
  query:
  - websearch.query
  - prompt_builder.question

outputs:
  replies: llm.replies

Parameters

Inputs

Parameter	Type	Description
query	str	The search query string.

Outputs

Parameter	Type	Description
documents	List[Document]	A list of documents containing search result content.
links	List[str]	A list of URLs from the search results.

Init Parameters

These are the parameters you can configure in Pipeline Builder:

Parameter	Type	Default	Description
top_k	int	10	Maximum number of results to return.
backend	str	auto	Comma-separated ddgs backends to query, or "auto" to let ddgs choose (for example, "duckduckgo, google, brave").
region	str	us-en	Region and locale for the search (for example, "us-en", "de-de", or "wt-wt" for no region).
safesearch	str	moderate	Safe-search level: "on", "moderate", or "off".
search_params	Optional[Dict[str, Any]]	None	Additional keyword arguments forwarded to DDGS().text(). Values here override backend, region, safesearch, and top_k on conflict.

Run Method Parameters

These are the parameters you can configure for the component's run() method. This means you can pass these parameters at query time through the API, in Playground, or when running a job. For details, see Modify Pipeline Parameters at Query Time.

Parameter	Type	Default	Description
query	str		The search query string.
top_k	Optional[int]	None	Per-run override of the maximum number of results.
backend	Optional[str]	None	Per-run override of the search backends.
region	Optional[str]	None	Per-run override of the region and locale.
safesearch	Optional[str]	None	Per-run override of the safe-search level.
search_params	Optional[Dict[str, Any]]	None	Per-run override of extra DDGS().text() arguments. If provided, fully replaces the init-time search_params.

Related Information

• Pipeline Components
• Integrations Overview