> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypertic.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Retriever

Retrievers connect agents to your documents stored in vector databases. When you ask a question, the retriever searches your indexed documents for relevant content and automatically includes it in the agent's context. This lets agents answer questions about your specific documents, even if that information wasn't in their training data.

To use a retriever, you first index your documents in a vector database, then pass the retriever to your agent. The agent automatically uses retrieved documents to enhance its responses.

## Supported Vector Databases

Hypertic supports multiple vector database providers. Click on a provider to see setup and usage examples:

<Columns cols={3}>
  <Card title="ChromaDB" icon="https://www.trychroma.com/favicon.ico" href="/retriever/chromadb">
    View guide >
  </Card>

  <Card title="MongoDB Atlas" icon="https://www.mongodb.com/favicon.ico" href="/retriever/mongodb">
    View guide >
  </Card>

  <Card title="Pinecone" icon="https://www.pinecone.io/favicon.ico" href="/retriever/pinecone">
    View guide >
  </Card>

  <Card title="PgVector" icon="https://www.postgresql.org/favicon.ico" href="/retriever/pgvector">
    View guide >
  </Card>

  <Card title="Qdrant" icon="https://qdrant.tech/favicon.ico" href="/retriever/qdrant">
    View guide >
  </Card>
</Columns>

## Supported Embedders

Hypertic supports multiple embedding providers. Click on a provider to see setup and usage examples:

<Columns cols={3}>
  <Card title="Cohere" icon="https://cohere.com/favicon.ico" href="/embedders/cohere">
    View guide >
  </Card>

  <Card title="Google" icon="https://www.google.com/favicon.ico" href="/embedders/google">
    View guide >
  </Card>

  <Card title="Mistral" icon="https://mistral.ai/favicon.ico" href="/embedders/mistral">
    View guide >
  </Card>

  <Card title="OpenAI" icon="openai" href="/embedders/openai">
    View guide >
  </Card>

  <Card title="Sentence Transformers" icon="database" href="/embedders/sentence-transformers">
    View guide >
  </Card>
</Columns>

## Setup

Create a vector database with an embedder. Hypertic supports multiple vector database providers:

```python theme={null} theme={null}
import os
from hypertic.vectordb import ChromaDB
from hypertic.embedders import OpenAIEmbedder

# Create embedder
embedder = OpenAIEmbedder(
    api_key=os.getenv("OPENAI_API_KEY"),
    model="text-embedding-3-small"
)

# Create vector DB
vector_db = ChromaDB(
    collection="my_collection",
    embedder=embedder,
    path="./chromadb_data"
)
```

## Adding Documents

Add documents from local files or URLs:

<CodeGroup>
  ```python Sync theme={null} theme={null}
  # Add documents with metadata
  vector_db.add(
    files=["data/index.pdf", "data/sample.txt"],
    metadatas=[
        {"source": "invoice.pdf", "type": "invoice", "category": "financial"},
        {"source": "sample.txt", "type": "text", "category": "general"}
    ]
  )

  # Add from URL
  vector_db.add(
    files=["https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"],
    metadatas=[{"source": "url_test.pdf", "type": "url", "category": "test"}]
  )

  # Check document count
  count = vector_db.count()
  print(f"Document count: {count}")
  ```

  ```python Async theme={null} theme={null}
  # Add documents with metadata
  await vector_db.async_add(
      files=["data/index.pdf", "data/sample.txt"],
      metadatas=[
          {"source": "invoice.pdf", "type": "invoice", "category": "financial"},
          {"source": "sample.txt", "type": "text", "category": "general"}
      ]
  )

  # Add from URL
  await vector_db.async_add(
      files=["https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf"],
      metadatas=[{"source": "url_test.pdf", "type": "url", "category": "test"}]
  )

  # Check document count
  count = await vector_db.async_count()
  print(f"Document count: {count}")
  ```
</CodeGroup>

## Searching Documents

Search for relevant documents:

<CodeGroup>
  ```python Sync theme={null} theme={null}
  # Create retriever
  retriever = vector_db.as_retriever(k=3)

  # Search for relevant content
  docs = retriever.search("invoice payment")
  print(docs)
  ```

  ```python Async theme={null} theme={null}
  # Create retriever
  retriever = vector_db.as_retriever(k=3)

  # Search for relevant content
  docs = await retriever.async_search("invoice payment")
  print(docs)
  ```
</CodeGroup>

## Updating Documents

Update document content or metadata:

<CodeGroup>
  ```python Sync theme={null} theme={null}
  # Get document ID
  all_docs = vector_db.get(limit=1)
  if all_docs['ids']:
    doc_id = all_docs['ids'][0]
    
    # Update metadata only
    vector_db.update(
        ids=[doc_id],
        metadatas=[{"source": "updated_invoice.pdf", "type": "invoice", "status": "processed"}]
    )
    
    # Update document content and metadata
    vector_db.update(
        ids=[doc_id],
        documents=["Updated invoice content with new payment terms"],
        metadatas=[{"source": "updated_invoice.pdf", "status": "content_updated"}]
    )
  ```

  ```python Async theme={null} theme={null}
  # Get document ID
  all_docs = await vector_db.async_get(limit=1)
  if all_docs['ids']:
      doc_id = all_docs['ids'][0]
      
      # Update metadata only
      await vector_db.async_update(
          ids=[doc_id],
          metadatas=[{"source": "updated_invoice.pdf", "type": "invoice", "status": "processed"}]
      )
      
      # Update document content and metadata
      await vector_db.async_update(
          ids=[doc_id],
          documents=["Updated invoice content with new payment terms"],
          metadatas=[{"source": "updated_invoice.pdf", "status": "content_updated"}]
      )
  ```
</CodeGroup>

## Upsert Operations

Upsert documents (insert or update if exists):

<CodeGroup>
  ```python Sync theme={null} theme={null}
  vector_db.upsert(
    ids=["doc_123"],
    documents=["This is a new document created via upsert"],
    metadatas=[{"source": "upsert_test.txt", "type": "test"}]
  )
  ```

  ```python Async theme={null} theme={null}
  await vector_db.async_upsert(
      ids=["doc_123"],
      documents=["This is a new document created via upsert"],
      metadatas=[{"source": "upsert_test.txt", "type": "test"}]
  )
  ```
</CodeGroup>

## Querying by Metadata

Query documents using metadata filters:

<CodeGroup>
  ```python Sync theme={null} theme={null}
  # Get documents by metadata
  financial_docs = vector_db.get(
    where={"category": "financial"},
    limit=5,
    include=['embeddings', 'metadatas', 'documents']
  )
  print(f"Financial documents: {financial_docs}")
  ```

  ```python Async theme={null} theme={null}
  # Get documents by metadata
  financial_docs = await vector_db.async_get(
      where={"category": "financial"},
      limit=5,
      include=['embeddings', 'metadatas', 'documents']
  )
  print(f"Financial documents: {financial_docs}")
  ```
</CodeGroup>

## Deleting Documents

Delete documents by ID or metadata filter:

<CodeGroup>
  ```python Sync theme={null} theme={null}
  # Delete by ID
  vector_db.delete(ids=["doc_123"])

  # Delete by metadata filter
  vector_db.delete(where={"category": "test"})

  # Check count after deletion
  count = vector_db.count()
  print(f"Documents after delete: {count}")
  ```

  ```python Async theme={null} theme={null}
  # Delete by ID
  await vector_db.async_delete(ids=["doc_123"])

  # Delete by metadata filter
  await vector_db.async_delete(where={"category": "test"})

  # Check count after deletion
  count = await vector_db.async_count()
  print(f"Documents after delete: {count}")
  ```
</CodeGroup>

## Using with an Agent

Connect the retriever to your agent. The agent automatically uses retrieved documents to enhance its responses:

```python theme={null} theme={null}
from hypertic.agents import Agent
from hypertic.models import OpenAIChat

model = OpenAIChat(model="gpt-5.2")

# Create retriever from vector DB
retriever = vector_db.as_retriever(k=3)  # Retrieve top 3 most relevant documents

# Add retriever to agent
agent = Agent(
    model=model,
    retriever=retriever,
)

# Agent automatically uses retriever when relevant
response = agent.run("What does the documentation say about invoices?")
print(response.content)
# Response includes information from your indexed documents
```