# Filtering (/knowledge/concepts/filters/overview)



Filters restrict knowledge searches to documents matching specific criteria. Attach metadata when adding content, then filter by that metadata when searching.

These fragments use an initialized `knowledge` object and existing local documents. Follow [Knowledge Quickstart](/knowledge/quickstart) for setup.

```python
from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge

# Add content with metadata
knowledge.insert(
    path="resumes/",
    metadata={"candidate": "jordan_mitchell", "document_type": "cv", "year": 2025}
)

# Search with filters
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    knowledge_filters={"candidate": "jordan_mitchell"},
)
```

## Why Use Filters [#why-use-filters]

* **Personalization**: Retrieve documents for a specific candidate or group
* **Organization**: Select content by department or document type
* **Precision**: Reduce noise by narrowing results to relevant documents

## Manual Filtering [#manual-filtering]

Pass filters explicitly when creating the agent or searching:

```python
# Filter at agent level
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    knowledge_filters={"candidate": "jordan_mitchell"},
)

# Filter at query time
agent.print_response(
    "What are Jordan's skills?",
    knowledge_filters={"document_type": "cv"}
)

# Direct search with filters
results = knowledge.search(
    query="programming experience",
    filters={"candidate": "jordan_mitchell", "year": 2025}
)
```

Multiple filters are combined with AND logic. Run-level dictionary filters override agent-level values for the same key.

Metadata filters select retrieval results; they do not authenticate a requester or enforce ownership. Native content ownership uses `Knowledge.insert(user_id=...)` and the separate `user_id` search argument, supplied from a trusted identity. See [User Isolation](/agent-os/security/authorization/user-isolation) for the AgentOS boundary.

## Agentic Filtering [#agentic-filtering]

Let the agent extract filters automatically from the query. The agent analyzes the user's question and determines which filters to apply.

```python
agent = Agent(
    knowledge=knowledge,
    search_knowledge=True,
    enable_agentic_knowledge_filters=True,  # Agent infers filters from query
)

# Agent extracts "jordan_mitchell" as a candidate filter from the query
agent.print_response("What skills does Jordan Mitchell have?")
```

This requires a [Contents DB](/knowledge/concepts/contents-db) to track available filter keys.

## Manual vs Agentic Filtering [#manual-vs-agentic-filtering]

| Approach | When to Use                                   |
| -------- | --------------------------------------------- |
| Manual   | Automation, predictable filters, full control |
| Agentic  | User-facing apps, natural language queries    |

## Traditional vs Agentic RAG [#traditional-vs-agentic-rag]

Filters work with both RAG approaches:

<Tabs>
  <Tab title="Agentic RAG">
    ```python
    # Agent decides when to search (default)
    agent = Agent(
        knowledge=knowledge,
        search_knowledge=True,
        knowledge_filters={"candidate": "jordan_mitchell"},
    )
    ```
  </Tab>

  <Tab title="Traditional RAG">
    ```python
    # Always inject context into prompt
    agent = Agent(
        knowledge=knowledge,
        search_knowledge=False,
        add_knowledge_to_context=True,
        knowledge_filters={"candidate": "jordan_mitchell"},
    )
    ```
  </Tab>
</Tabs>

Use one approach at a time. Agentic RAG (`search_knowledge=True`) is recommended for most use cases.

## Metadata Design [#metadata-design]

Good metadata enables effective filtering:

```python
# Rich, filterable metadata
metadata = {
    "candidate": "jordan_mitchell",
    "document_type": "cv",
    "department": "engineering",
    "year": 2025,
    "access_level": "internal",
}

# Add with content
knowledge.insert(path="resume.pdf", metadata=metadata)
```

**Tips:**

* Use consistent values (always `"engineering"`, not sometimes `"eng"`)
* Include temporal data for time-based filtering
* Keep metadata categories separate from trusted authorization rules

## Supported Vector Databases [#supported-vector-databases]

Filtering is supported on:

* ChromaDB
* Couchbase
* Elasticsearch
* LanceDB
* Milvus
* MongoDB
* PgVector
* Pinecone
* Qdrant
* SurrealDB
* Upstash
* Weaviate

## Next Steps [#next-steps]

<CardGroup cols="2">
  <Card title="Advanced Filtering" icon="filter" href="/knowledge/concepts/filters/advanced-filtering">
    Complex filters with OR, NOT, and comparisons
  </Card>

  <Card title="Content DB" icon="database" href="/knowledge/concepts/contents-db">
    Required for agentic filtering
  </Card>

  <Card title="Search & Retrieval" icon="magnifying-glass" href="/knowledge/concepts/search-and-retrieval/overview">
    How filtering affects search
  </Card>
</CardGroup>