Document Filters

A document filter restricts a RAG search to the documents that match a condition, such as a tag, a metadata value, or a date range. Only documents that pass the filter are ranked by semantic similarity, so results never include documents outside the filter.

Filters are evaluated before the search terms are embedded. When no document in the requested collections matches the filter, the request returns an empty result without generating embeddings or charging for the search.

tags has "finance" and createdAt >= now-30d

Where Filters Are Supported #

Send the filter in the filter field of these endpoints:

• Semantic search
• Answer generation

The field accepts a string or an array of strings. Array items are combined with and:

{
  "term": "How do I request a refund?",
  "collections": [ "<collection-id>" ],
  "filter": [
    "tags has \"billing\"",
    "metadata.region = \"latam\""
  ]
}

A missing or null field means no filter. The field name is filter; other names, such as filters, are ignored and the search runs without a filter.

Models can also send a filter string in the optional filter argument of these tools:

• The search tool of the Collections MCP.
• The query tool of AI gateways that use the QueryFunction query strategy.

Automatic gateway RAG, which searches before the model call, does not apply filters. An invalid filter in a tool call is returned to the model as a tool error with the same message as the API.

Syntax #

A filter is one or more conditions joined by and, or, and not. Each condition has the form field operator value:

name startswith "contract-"
metadata.pages > 10
not tags has "draft"
(tags has "finance" or tags has "legal") and updatedAt >= "2026-01-01"

• not binds tighter than and, and and binds tighter than or. Use parentheses to group explicitly.
• Keywords, operators, and field names are case-insensitive: AND, And, and and are equivalent.
• Strings use double or single quotes. Inside a string, escape the same quote with a backslash: "say \"hi\"", 'it\'s'. Supported escapes are \", \', \\, \/, \n, \r, \t, and \uXXXX.
• Numbers use a dot as the decimal separator and may use an exponent: 10, -2.5, 1e3.
• The other literals are true, false, null, and now (only in date conditions).

A value must be a literal. Functions, arithmetic, type conversions, and comparisons between two fields are not supported.

Fields #

See Collections for how these fields are set.

Operators #

• field in (a, b, c) is equivalent to field = a or field = b or field = c. For tags, it matches documents that have at least one of the listed tags.
• has checks whether a list contains a value: tags has "x", or metadata.<key> has value when the metadata value is a JSON array.
• exists checks whether a metadata path is present, including when its value is null.
• x != v is exactly not x = v.
• Any other combination, such as tags = "x" or name > "a", is rejected.

Text Comparison #

Text comparisons ignore letter case and accents: name = "relatorio" matches a document named Relatório.

• = and in ignore trailing spaces: "report " matches "report".
• contains, startswith, and endswith match literally, without wildcards. The characters % and _ match only themselves.
• contains requires at least 3 characters.

Text comparisons do not split words or match synonyms. Use the search terms for meaning and the filter for exact constraints.

Metadata #

Use a dot to read nested metadata. Keys that are not simple identifiers go in quotes:

metadata.author.name = "Ana"
metadata."file-path" startswith "/contracts/2026/"
metadata."a.b" = 1

The last example reads one key named a.b, not a nested path. Array indexes are not supported; use has to check whether an array contains a value.

The literal type selects the comparison, and types are never converted:

So metadata.year = 2026 does not match {"year": "2026"}, and metadata.public = true does not match {"public": "true"}. If your data mixes types, list both: metadata.year in (2026, "2026").

Ordering operators (>, >=, <, <=) work only on numbers in metadata. Dates stored in metadata cannot be compared as dates; use createdAt and updatedAt, or store a sortable number such as a Unix timestamp or 20260915.

A missing key never matches a positive condition, so metadata.lang != "en" also matches documents without lang. To exclude them, add metadata.lang exists.

Store metadata with consistent types per key, and prefer keys made of ASCII letters, digits, -, and _.

Dates #

createdAt and updatedAt accept absolute dates and relative times.

Absolute dates use ISO 8601:

createdAt >= "2026-09-01"
updatedAt < "2026-09-01T18:30"
createdAt >= "2026-09-01T00:00:00-03:00"
createdAt >= "2026-09-01T03:00:00Z"

• A date without a time means midnight.
• A value without Z or an offset is interpreted in the AIVAX service time zone, America/Sao_Paulo (UTC−03:00). Add Z or an offset when you need an exact instant.
• Other formats, such as 15/06/2025, are rejected.

Relative times use now, optionally followed by + or - and an amount with a unit:

createdAt >= now-7d
updatedAt >= now-12h and updatedAt < now

Limits #

A filter must finish within 10 seconds. Conditions on content, endswith, tags, and metadata examine every document in the requested collections, so they take longer in large collections. If a filter exceeds the time limit, the request fails and asks for more selective conditions. Prefer conditions on name (=, in, startswith), split very large corpora into smaller collections, and reserve content contains for collections where it stays fast.

Errors #

An invalid filter returns 400 Bad Request with a message that names the problem and the character position where it was found:

{
  "error": "Invalid filter: Unknown field 'author'. Expected name, content, tags, createdAt, updatedAt or metadata.<key>. (at 0)"
}

For an array, the message includes the index of the invalid item, such as Invalid filter at index 1: .... A filter that is not a string or an array of strings is also rejected.

Examples #

Common Mistakes #