JSON Filter for Amazon Bedrock Knowledge Base - A JSON filter narrows an AI Skill query to a specific content segment within an Amazon Knowledge Base when using the Grounded by knowledge base Model connection . Filters are defined using key-value metadata attributes and support AND, OR, and comparison operators.

What a JSON filter does

When you add a filter to the Filter field in an AI Skill that uses the Grounded by knowledge base Model connection, the filter restricts the model's search to a specific content segment within a large document in the Amazon Knowledge Base. Filters use metadata attributes attached to each source document and are expressed in JSON format. Metadata must be configured on the data sources before filters can be applied.

Metadata file structure

For an Amazon S3 bucket source, each document must have a corresponding .metadata.json file with the same base name as the source document. For example, a document named articles.pdf requires a metadata file named articles.pdf.metadata.json.

The metadata file contains key-value attribute blocks. For example:

{
    "metadataAttributes": {
        "genre": "a360",
        "year": 2025
    }
}

Filter syntax

JSON filters use logical operators (orAll, andAll) to combine filter conditions. Each condition specifies a metadata key, a comparison operator, and a value.

OR condition — returns results matching any of the listed conditions:

AWS JSON filter with genre and year for an OR condition — Figure 1. OR condition filter configuration in Amazon Bedrock

{
  "orAll": [
    {
      "equals": {
        "key": "genre",
        "value": "a360"
      }
    },
    {
      "equals": {
        "key": "year",
        "value": 2025
      }
    }
  ]
}

AND condition — returns results matching all of the listed conditions:

AWS JSON filter with genre and year for an AND condition — Figure 2. AND condition filter configuration in Amazon Bedrock

{
  "andAll": [
    {
      "equals": {
        "key": "genre",
        "value": "a360"
      }
    },
    {
      "equals": {
        "key": "year",
        "value": 2025
      }
    }
  ]
}

Filter operators

Amazon Bedrock Knowledge Base supports the following filtering and logical operators. For the full reference, see Metadata and filtering in Amazon Bedrock Knowledge Base.

Table 1. Filtering operators
Operator	Console	API filter name	Supported attribute data types	Filtered results
Equals	`=`	`equals`	`string`, `number`, `boolean`	Attribute matches the value you provide
Not equals	`!=`	`notEquals`	`string`, `number`, `boolean`	Attribute doesn't match the value you provide
Greater than	`>`	`greaterThan`	`number`	Attribute is greater than the value you provide
Greater than or equals	`>=`	`greaterThanOrEquals`	`number`	Attribute is greater than or equal to the value you provide
Less than	`<`	`lessThan`	`number`	Attribute is less than the value you provide
Less than or equals	`<=`	`lessThanOrEquals`	`number`	Attribute is less than or equal to the value you provide
In	`:`	`in`	`string list`	Attribute is in the list you provide (currently best supported with Amazon OpenSearch Serverless and Neptune Analytics GraphRAG vector stores)
Not in	`!:`	`notIn`	`string list`	Attribute isn't in the list you provide (currently best supported with Amazon OpenSearch Serverless and Neptune Analytics GraphRAG vector stores)
String contains	Not available	`stringContains`	`string`	Attribute must be a string. Attribute name matches the key and whose value is a string that contains the value that you provided as a substring, or a list with a member that contains the value that you provided as a substring (currently best supported with Amazon OpenSearch Serverless vector store; the Neptune Analytics GraphRAG vector store supports the string variant but not the list variant of this filter)
List contains	Not available	`listContains`	`string`	Attribute must be a string list. Attribute name matches the key and whose value is a list that contains the value that you provided as one of its members (currently best supported with Amazon OpenSearch Serverless vector stores)

Combining filter groups

You can combine up to five filter groups by nesting them within a logical operator. The following example shows one level of embedding:

"retrievalConfiguration": {
    "vectorSearchConfiguration": {
        "filter": {
            "andAll | orAll": [
                "andAll | orAll": [
                    "<filter-type>": {
                        "key": "string",
                        "value": "string" | number | boolean | ["string", "string", ...]
                    }
                ],
                "andAll | orAll": [
                    "<filter-type>": {
                        "key": "string",
                        "value": "string" | number | boolean | ["string", "string", ...]
                    }
                ]
            ]
        }
    }
}

The following examples show single, one-group, and two-group filter combinations:

# genre = Strategy
single_filter = {
    "equals": {
        "key": "genre",
        "value": "Strategy"
    }
}
# genre = Strategy AND year >= 2023
one_group_filter = {
    "andAll": [
        {
            "equals": {
                "key": "genre",
                "value": "Strategy"
            }
        },
        {
            "greaterThanOrEquals": {
                "key": "year",
                "value": 2023
            }
        }
    ]
}
# (genre = Strategy AND year >= 2023) OR score >= 9
two_group_filter = {
    "orAll": [
        {
            "andAll": [
                {
                    "equals": {
                        "key": "genre",
                        "value": "Strategy"
                    }
                },
                {
                    "greaterThanOrEquals": {
                        "key": "year",
                        "value": 2023
                    }
                }
            ]
        },
        {
            "greaterThanOrEquals": {
                "key": "score",
                "value": 9
            }
        }
    ]
}