Filtros Avançados

Um filtro avançado, também chamado de filtro de documento, restringe uma busca RAG aos documentos que atendem a uma condição, como uma tag, um valor de metadado ou um intervalo de datas. Apenas os documentos que passam pelo filtro são classificados por similaridade semântica, portanto os resultados nunca incluem documentos fora do filtro. Para um tutorial orientado a tarefas, veja How to filter RAG results by metadata, tags and date.

Os filtros são avaliados antes de os termos de busca serem incorporados. Quando nenhum documento nas coleções solicitadas corresponde ao filtro, a solicitação retorna um resultado vazio sem gerar embeddings ou cobrar pela busca.

tags has "finance"
metadata.department = "finance" and createdAt >= now-30d
(tags has "finance" or tags has "legal") and not tags has "draft"

Anatomia de um Filtro #

Um filtro é uma ou mais condições unidas por and, or e not. Cada condição tem três partes:

metadata.pages   >   10
└── field ──┘   └op┘ └value┘

• Field — o que observar: name, content, tags, createdAt, updatedAt ou metadata.<key>. Veja Fields.
• Operator — como comparar: =, >, contains, in, has, exists e outros. Veja Operators.
• Value — um literal para comparar: uma string entre aspas, um número, true, false, null, uma data ou uma lista entre parênteses. Veja Values.

O valor deve ser sempre um literal. Funções, aritmética, conversões de tipo e comparações entre dois campos não são suportados. Palavras‑chave, operadores e nomes de campos não diferenciam maiúsculas de minúsculas: AND, And e and são equivalentes.

Campos #

Veja Documents para saber como esses campos são definidos.

Operadores #

Cada operador funciona apenas com campos e tipos de valor específicos. Qualquer outra combinação, como tags = "x" ou name > "a", é rejeitada.

Igualdade #

Para metadata.<key>, o valor pode ser texto, número, true, false ou null. A comparação de texto ignora maiúsculas/minúsculas e acentos; veja Strings.

Ordenação #

A ordenação funciona em datas para createdAt e updatedAt, e apenas em números para metadados. Datas ou texto armazenados em metadados não podem ser ordenados; veja Metadata.

Texto #

Esses operadores correspondem literalmente, sem curingas: % e _ correspondem apenas a si mesmos. Eles não dividem palavras nem correspondem a sinônimos. Use os termos de busca para significado e o filtro para restrições exatas.

Listas #

field in (a, b, c) é equivalente a field = a or field = b or field = c. Para tags, in corresponde a documentos que tenham ao menos uma das tags listadas. has é o único operador de estilo de igualdade para tags; tags = "x" é rejeitado.

Existência #

exists não recebe valor. Para exigir um valor não‑null, combine com !=: metadata.reviewer exists and metadata.reviewer != null.

Valores #

Strings #

As strings utilizam aspas duplas ou simples. Dentro de uma string, escape a mesma as com barra invertida: \"say \\\"hi\\\"\", 'it\\'s'. Os escapes suportados são \", \', \\, \/, \n, \r, \t e \uXXXX.

As comparações de texto ignoram maiúsculas/minúsculas e acentos: name = "relatorio" corresponde a um documento chamado Relatório. = e in também ignoram espaços finais: \"report \" corresponde a \"report\".

Números #

Números usam ponto como separador decimal e podem usar expoente: 10, -2.5, 1e3. Números nunca são colocados entre aspas; \"100\" é uma string.

Booleanos e null #

true, false e null são literals, escritos sem aspas. São válidos apenas para metadata.<key>.

Datas #

createdAt e updatedAt aceitam datas absolutas e tempos relativos.

Datas absolutas usam ISO 8601 dentro de aspas:

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

• Uma data sem horário significa meia‑noite.
• Um valor sem Z ou offset é interpretado no fuso horário do serviço AIVAX, America/Sao_Paulo (UTC−03:00). Adicione Z ou um offset quando precisar de um instante exato.
• Outros formatos, como 15/06/2025, são rejeitados.

Tempos relativos usam now, opcionalmente seguidos por + ou - e uma quantidade com unidade, sem aspas:

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

now é válido apenas em condições de data.

Listas #

Uma lista é um ou mais valores separados por vírgulas dentro de parênteses: (\"finance\", \"legal\"), (2026, \"2026\"). Listas são usadas com in.

Combinando Condições #

Una condições com and, or e not:

not tags has "draft"
tags has "finance" and createdAt >= now-30d
(tags has "finance" or tags has "legal") and updatedAt >= "2026-01-01"

not tem precedência maior que and, e and tem precedência maior que or. Portanto, a or b and c significa a or (b and c). Use parênteses para agrupar explicitamente.

Metadados #

Use um ponto para ler metadados aninhados. Chaves que não são identificadores simples vão entre aspas:

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

O último exemplo lê uma chave chamada a.b, não um caminho aninhado. Índices de array não são suportados; use has para verificar se um array contém um valor.

Tipos nunca são convertidos. O tipo literal determina quais valores armazenados podem corresponder:

Portanto, metadata.year = 2026 não corresponde a {"year": "2026"}, e metadata.public = true não corresponde a {"public": "true"}. Se seus dados misturam tipos, liste ambos: metadata.year in (2026, "2026").

Operadores de ordenação funcionam apenas em números nos metadados. Datas armazenadas nos metadados não podem ser comparadas como datas; use createdAt e updatedAt, ou armazene um número ordenável como um timestamp Unix ou 20260915.

Uma chave ausente nunca corresponde a uma condição positiva, portanto metadata.lang != "en" também corresponde a documentos sem lang. Para excluí‑los, adicione metadata.lang exists.

Armazene metadados com tipos consistentes por chave e prefira chaves compostas por letras ASCII, dígitos, - e _.

Exemplos #

Erros Comuns #

Onde os Filtros São Suportados #

Envie o filtro no campo filter desses endpoints:

• Semantic search
• Geração de respostas

O campo aceita uma string ou um array de strings. Itens do array são combinados com and:

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

Um campo ausente ou null significa sem filtro. O nome do campo é filter; outros nomes, como filters, são ignorados e a busca ocorre sem filtro.

Modelos também podem enviar uma string de filtro no argumento opcional filter dessas ferramentas:

• A ferramenta de busca do Collections MCP.
• A ferramenta query de gateways de IA que usam a estratégia de consulta QueryFunction.

A ferramenta memory_search também aceita uma string de filtro, mas requer exatamente um de query ou filter, não ambos. Seu modo apenas filtro retorna até 10 memórias correspondentes para o usuário atual, as mais recentes primeiro, sem embeddings de consulta.

O RAG automático de gateway, que busca antes da chamada ao modelo, não aplica filtros. Um filtro inválido em uma chamada de ferramenta é retornado ao modelo como erro de ferramenta com a mesma mensagem da API.

Limites #

Esses limites se aplicam a cada filtro, incluindo filtros usados pela busca de memória e pelo Collections MCP.

Condições em content, endswith, tags e metadados examinam cada documento nas coleções solicitadas, portanto demoram mais em coleções grandes. Se um filtro exceder o limite de tempo, a solicitação falha e pede condições mais seletivas. Prefira condições em name (=, in, startswith), divida corpora muito grandes em coleções menores e reserve content contains para coleções onde ele permanece rápido.

Erros #

Um filtro inválido retorna 400 Bad Request com uma mensagem que indica o problema e a posição do caractere onde foi encontrado:

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

Para um array, a mensagem inclui o índice do item inválido, como Invalid filter at index 1: .... Um filter que não seja uma string ou um array de strings também é rejeitado.