> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/metadata-filters.md).

# Metadata filters

Metadata filters limit retrieval to documents with matching properties. Use them to select content by attributes such as department, document type, or region.

{% embed url="<https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2F1tPGm5vYo9IgKi6Evw2H%2FG040.mp4?alt=media&token=b410bd8d-5fbf-4009-8196-4a332053b372>" %}

## Before you start

Have indexed documents and permission to edit their metadata. To apply a filter in a workflow, also have an editable workflow with a knowledge-base node connected to the base and a query supplied to that node. Start with [First input to output workflow](https://docs.stackai.com/guides-and-quickstarts/workflow-builder/first-input-to-output-workflow.md) if needed, then use [Inspect knowledge base references](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/inspect-knowledge-base-references.md) to locate an existing consuming project.

This guide starts in **Knowledge Bases** to tag documents, then moves to the consuming workflow to configure its search. A filter in that node applies to that workflow's retrieval; it does not change every other agent or workflow using the base. It is not an access-control rule.

## Add consistent metadata

Open a document's Metadata tab and add the property used for filtering.

![Document metadata property values](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/XRE3JA9nJMOeO4EMR2fS/assets/g040-g040-01-sales.png)

Choose a property you can apply consistently, such as `department`, and use the exact department value that describes each document. Keep a short list of agreed property names and values so collaborators do not introduce variants.

Apply the same property to the other relevant documents.

![Document metadata property values](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/j29aXhoM4feEQhv5qY5T/assets/g040-g040-02-engineering.png)

Keep spelling and value types consistent so a filter can match them reliably.

## Review retrieval without a filter

Open the consuming workflow and its knowledge-base node. Confirm it points to the base you just tagged, run a known query with **No filter**, and inspect the source passages returned.

![Retrieval results without metadata filters](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/DYvWoY8CWGybOb69zVsG/assets/g040-g040-03-baseline.png)

This shows the available results before you narrow retrieval with metadata.

## Configure a metadata filter

In the knowledge-base node's Search Parameters, choose Strict filter and add the condition.

![Metadata filter condition controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/wgnZwAiuJ4Qjl2F1Ns4n/assets/g040-g040-04-strict.png)

Select the metadata property, comparison operator, and value that define the required scope. For a department filter, choose the `department` property, the equality comparison, and an exact value already stored on the intended documents. Use the same value type as the metadata.

Optionally, open **JSON Editor** to inspect the equivalent rule if you are comfortable reading it. You can configure the condition with the visual property/operator/value controls without using JSON.

![Metadata filter condition controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/BY8aLWLnNTHSPLN2Hj06/assets/g040-g040-05-json.png)

Check the property name and value rather than assuming that the visible rule order determines its meaning.

## Use and change the filter

Run the query with the filter applied and inspect the returned filenames.

![Filtered retrieval condition and results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/2OcvuYQM1DKDO7F5GkjQ/assets/g040-g040-06-sales-result.png)

Confirm that the passages come from documents matching the metadata condition.

Change the condition value when you need a different document group.

![Filtered retrieval condition and results](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/WOW5b4hIXO5VEBTPW2Ja/assets/g040-g040-07-engineering-result.png)

Run again and check that retrieval follows the new scope.

## Remove a filter

Use Clear All and No filter to remove the metadata restriction.

![Metadata filter removal controls](https://content.gitbook.com/content/SQ1Sgy933krTyK0S4JpP/blobs/McfiQEWb9NCycQXbruaj/assets/g040-g040-08-restore.png)

Metadata filters narrow retrieval. They do not replace source-access permissions.

## If the filter returns no results

Return to a document you expect to match and inspect **Metadata**. Compare the property name, value, and value type with the condition. Clear the filter and rerun the same query: if the source is still absent, check indexing and permissions before changing the condition. Restore the intended filter after the comparison.

## Important behavior

Metadata filters narrow which documents retrieval considers. They do not replace source permissions.

A property name and value type must match the metadata stored on the documents.

## Continue

* [Source permissions](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/source-permissions.md)
* [Evaluate retrieval](https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/evaluate-retrieval.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/guides-and-quickstarts/knowledge-and-retrieval/metadata-filters.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
