Filtragem Avançada

Este documento detalha como usar o parâmetro de query string filter para realizar buscas avançadas no endpoint de listagem de documentos. A filtragem permite que você consulte:

1. Campos do modelo Document: created_at, updated_at, expires_at, version
2. Campos específicos dentro do objeto JSON data dos seus documentos

Endpoint Alvo: GET /api/v1/client/{client}/{env}/context/{context}/type/{type}

Tipos de Filtragem Disponíveis

1. Filtros em Campos do Modelo Document

Você pode filtrar diretamente pelos seguintes campos do modelo:

Exemplo: Documentos criados nas últimas 24 horas

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/.../users?filter[created_at_gte]=2024-01-20" \
-H "Authorization: Bearer {SEU_TOKEN}"

Exemplo: Documentos atualizados hoje

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/.../users?filter[updated_at_gte]=2024-01-20 00:00:00" \
-H "Authorization: Bearer {SEU_TOKEN}"

2. Filtros em Campos JSON (data)

Sintaxe Básica

A sintaxe geral para a filtragem é ?filter[<campo>]=<valor>.

• Para campos do modelo: aplica busca diretamente na coluna do banco
• Para campos JSON: aplica busca por igualdade exata no campo especificado dentro do objeto data

Exemplo: Busca por Igualdade

Vamos supor que você armazena documentos do tipo users com a seguinte estrutura de data:

{
  "name": "Alice",
  "city": "New York",
  "status": "active"
}

Para encontrar todos os usuários da cidade de "New York", a requisição seria:

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/.../users?filter[city]=New York" \
-H "Authorization: Bearer {SEU_TOKEN}"

Operadores de Comparação

Para buscas mais complexas, você pode adicionar um sufixo ao nome do campo para especificar o operador de comparação.

Operadores Disponíveis

Exemplos Detalhados

Considere os seguintes documentos do tipo users:

Documento 1:

{ "name": "Alice", "age": 30, "level": 15, "signup_date": "2024-03-15" }

Documento 2:

{ "name": "Bob", "age": 25, "level": 10, "signup_date": "2024-01-10" }

Documento 3:

{ "name": "Charlie", "age": 35, "level": 10, "signup_date": "2024-05-20" }

1. Filtragem Numérica

A API lida corretamente com comparações numéricas.

Encontrar usuários com level maior ou igual a 10: ?filter[level_gte]=10 Resultado: Bob, Charlie

Encontrar usuários com age estritamente menor que 30: ?filter[age_lt]=30 Resultado: Bob

2. Filtragem de Datas

Para que a comparação de datas funcione corretamente, armazene as datas no formato AAAA-MM-DD ou AAAA-MM-DD HH:MM:SS.

Encontrar usuários que se cadastraram antes de Março de 2024: ?filter[signup_date_lt]=2024-03-01 Resultado: Bob

3. Filtragem de Strings

Encontrar usuários cujo nome contém "li": ?filter[name_like]=li Resultado: Alice, Charlie

Combinando Múltiplos Filtros

Você pode combinar múltiplos filtros na mesma requisição para criar consultas mais refinadas. A API aplicará todos os filtros usando a lógica AND.

Exemplo: Encontrar usuários com level maior ou igual a 10 E que se cadastraram após 1º de Fevereiro de 2024.

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/.../users?filter[level_gte]=10&filter[signup_date_gt]=2024-02-01" \
-H "Authorization: Bearer {SEU_TOKEN}"

Resultado: Alice, Charlie

Combinando Filtros de Modelo e JSON

Você pode combinar filtros de campos do modelo com filtros de campos JSON na mesma requisição para criar consultas ainda mais refinadas.

Exemplo: Encontrar documentos criados hoje que tenham usuários ativos com level maior que 10

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/.../users?filter[created_at_gte]=2024-01-20&filter[status]=active&filter[level_gt]=10" \
-H "Authorization: Bearer {SEU_TOKEN}"

Exemplo: Documentos atualizados na última semana com usuários de uma cidade específica

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/.../users?filter[updated_at_gte]=2024-01-13&filter[city]=New York" \
-H "Authorization: Bearer {SEU_TOKEN}"

Exemplo: Versões específicas de documentos com dados contendo texto específico

curl -X GET "https://document-hub-api-xp.wake.tech/api/v1/client/.../users?filter[version_gte]=3&filter[name_like]=Alice" \
-H "Authorization: Bearer {SEU_TOKEN}"

Notas Importantes

• Performance: Filtros em campos do modelo (created_at, updated_at, etc.) são mais eficientes pois utilizam índices do banco de dados
• Formatos de Data: Para campos timestamp, aceite os formatos: YYYY-MM-DD, YYYY-MM-DD HH:MM:SS, ou timestamp Unix
• Retrocompatibilidade: Filtros existentes em campos JSON continuam funcionando normalmente