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

# Vector Search

> Rank knowledge documents by the distance between query and document embeddings.

Vector search compares an embedded query with the embeddings stored for knowledge documents.

```python theme={null}
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector, SearchType

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"

knowledge = Knowledge(
    vector_db=PgVector(
        table_name="docs",
        db_url=db_url,
        search_type=SearchType.vector,
    ),
)
```

## How It Works

1. The embedder converts the query to a vector.
2. The vector database compares it with stored document vectors.
3. The database orders results using its configured distance metric.

PgVector uses cosine distance by default. It also supports L2 distance and maximum inner product.

## When to Use Vector Search

| Query Pattern            | Why Test Vector Search                                    |
| ------------------------ | --------------------------------------------------------- |
| Conceptual questions     | Embedding similarity can retrieve related language        |
| Natural-language queries | The query and documents use the same embedding space      |
| Varied vocabulary        | Relevant documents may use different terms than the query |

Test hybrid or keyword search when specific tokens such as IDs and error codes affect relevance.

## Configuration

### Basic Setup

Set the API key used by `OpenAIEmbedder`:

```bash theme={null}
export OPENAI_API_KEY=your_openai_api_key_here
```

```python theme={null}
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.vectordb.pgvector import PgVector, SearchType

vector_db = PgVector(
    table_name="docs",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    search_type=SearchType.vector,
    embedder=OpenAIEmbedder(id="text-embedding-3-small"),
)
```

### With Reranking

Set the API keys used by the default OpenAI embedder and Cohere reranker:

```bash theme={null}
export OPENAI_API_KEY=your_openai_api_key_here
export COHERE_API_KEY=your_cohere_api_key_here
```

Apply `CohereReranker` to the vector-search candidates:

```python theme={null}
from agno.knowledge.reranker.cohere import CohereReranker
from agno.vectordb.pgvector import PgVector, SearchType

vector_db = PgVector(
    table_name="docs",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
    search_type=SearchType.vector,
    reranker=CohereReranker(),
)
```

## Example

<Steps>
  <Step title="Install dependencies">
    ```bash theme={null}
    uv pip install -U agno cohere openai pgvector psycopg pypdf sqlalchemy
    ```
  </Step>

  <Snippet file="run-pgvector-step.mdx" />

  <Step title="Export the OpenAI API key">
    ```bash theme={null}
    export OPENAI_API_KEY=your_openai_api_key_here
    ```
  </Step>
</Steps>

```python vector_search.py theme={null}
from agno.knowledge.embedder.openai import OpenAIEmbedder
from agno.knowledge.knowledge import Knowledge
from agno.vectordb.pgvector import PgVector, SearchType

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"

knowledge = Knowledge(
    vector_db=PgVector(
        table_name="recipes",
        db_url=db_url,
        search_type=SearchType.vector,
        embedder=OpenAIEmbedder(id="text-embedding-3-small"),
    ),
)

knowledge.insert(
    url="https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf",
)

results = knowledge.search("chicken coconut soup", max_results=5)
for doc in results:
    print(doc.content[:200])
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Hybrid Search" icon="magnifying-glass" href="/knowledge/concepts/search-and-retrieval/hybrid-search">
    Combine vector search with keyword matching
  </Card>

  <Card title="Embedders" icon="code" href="/knowledge/concepts/embedder/overview">
    Choose the right embedding model
  </Card>
</CardGroup>